From 4a3243aaf5603a8b73e7a1ba0af37811cdfff089 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Thu, 10 Nov 2016 16:58:53 -0800 Subject: [PATCH 1/3] Add docs for generating example certificates --- helper/tlsutil/testdata/README.md | 2 +- .../docs/agent/configuration/tls.html.md | 12 --- website/source/docs/agent/encryption.html.md | 91 +++++++++++++++++-- 3 files changed, 84 insertions(+), 21 deletions(-) diff --git a/helper/tlsutil/testdata/README.md b/helper/tlsutil/testdata/README.md index 234500c7f..5a951a007 100644 --- a/helper/tlsutil/testdata/README.md +++ b/helper/tlsutil/testdata/README.md @@ -17,7 +17,7 @@ Using [cfssl 1.2.0](https://github.com/cloudflare/cfssl) ```sh # Write defaults and update cfssl print-defaults csr > ca-csr.json -cfssl print-defaults config > ca.config.json +cfssl print-defaults config > ca-config.json # Generate CA certificate and key cfssl gencert -config ca-config.json -initca ca-csr.json | cfssljson -bare ca - diff --git a/website/source/docs/agent/configuration/tls.html.md b/website/source/docs/agent/configuration/tls.html.md index d3071a460..80c3042d5 100644 --- a/website/source/docs/agent/configuration/tls.html.md +++ b/website/source/docs/agent/configuration/tls.html.md @@ -68,18 +68,6 @@ This example shows enabling TLS configuration. This enables TLS communication between all servers and clients using the default system CA bundle and certificates. -```hcl -tls { - http = true - rpc = true -} -``` - -### Custom Certificates - -This example shows configuring Nomad to communicate via TLS over HTTP and RPC -using a custom certificate and CA bundle. - ```hcl tls { http = true diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md index 45fc7b7c8..fb8d1c895 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -3,14 +3,14 @@ layout: "docs" page_title: "Gossip and RPC Encryption" sidebar_current: "docs-agent-encryption" description: |- - Learn how to configure Nomad to encrypt both its gossip traffic and its RPC - traffic. + Learn how to configure Nomad to encrypt all of its traffic. --- # Encryption The Nomad agent supports encrypting all of its network traffic. There are -two separate encryption systems, one for gossip traffic, and one for RPC. +two separate encryption systems, one for gossip traffic, and one for HTTP and +RPC. ## Gossip @@ -30,7 +30,7 @@ cg8StVXbQJ0gPvMd9o7yrg== With that key, you can enable gossip encryption on the agent. -## RPC and Raft Encryption with TLS +## HTTP, RPC, and Raft Encryption with TLS Nomad supports using TLS to verify the authenticity of servers and clients. To enable this, Nomad requires that all clients and servers have key pairs that are @@ -42,13 +42,88 @@ a certificate is provided that is signed by the Certificate Authority from the [`ca_file`][tls] for TLS connections. If `verify_server_hostname` is set, then outgoing connections perform -hostname verification. All servers must have a certificate valid for -`server..nomad` or the client will reject the handshake. It is also -recommended for the certificate to sign `localhost` such that the CLI can -validate the server name. +hostname verification. Unlike traditional HTTPS browser validation, all servers +must have a certificate valid for `server..nomad` or the client will +reject the handshake. It is also recommended for the certificate to sign +`localhost` such that the CLI can validate the server name. TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP and is secured using a symmetric key. See above for enabling gossip encryption. [tls]: /docs/agent/configuration/tls.html "Nomad TLS Configuration" + +### Example TLS Configuration using cfssl + +While [Vault's PKI backend][vault] is an ideal solution for managing +certificates and other secrets in a production environment, it's useful to use +simpler command line tools when learning how to configure TLS and your [PKI]. + +[`cfssl`][cfssl] is a tool for working with TLS certificates and certificate +authorities similar to [OpenSSL's][openssl] `x509` command line tool. + +Once you have the `cfssl` command line tool installed create, the first step to +setting up TLS is to create a Certificate Authority (CA) certificate. The +following command will generate a suitable example CA CSR, certificate, and +key: + +```sh +# Run in the directory where you want to store certificates + +cfssl print-defaults csr | cfssl gencert -initca - | cfssljson -bare ca +``` + +Next create a `nomad-csr.json` which contains the configuration for the actual +certificate you'll be using in Nomad: + +```json +{ + "CN": "regionglobal.nomad", + "hosts": [ + "server.regionglobal.nomad", + "client.regionglobal.nomad" + ] +} +``` + +This will create a certificate suitable for both clients and servers in the +`global` (default) region. + +In production Nomad agents should have a certificate valid for the name +`${ROLE}.region${REGION}.nomad` where role is either `client` or `server` +depending on the node's role. + +Create a certificate signed by your CA: + +```sh +cfssl gencert -ca ca.pem -ca-key ca-key.pem nomad-csr.json | cfssljson -bare nomad +``` + +You've now successfully generated self-signed certificates! You should see the +following files: + +| File | Description | Usage | +|-----------------|------------------------------|---------------------------| +| `ca.pem` | CA certificate | `ca_file` setting | +| `ca-key.pem` | CA private key | Signing CSRs | +| `nomad.pem` | Nomad cert for global region | `cert_file` setting | +| `nomad-key.pem` | Nomad key for foo region | `key_file` setting | +| `*.csr` | Certificate Signing Requests | Generating certs (temporary) | + +In your Nomad configuration add the `tls` stanza: + +```hcl +tls { + http = true + rpc = true + verify_server_hostname = true + ca_file = "ca.pem" + cert_file = "nomad.pem" + key_file = "nomad-key.pem" +} +``` + +[vault]: https://www.vaultproject.io/docs/secrets/pki/ +[PKI]: https://en.wikipedia.org/wiki/Public_key_infrastructure +[cfssl]: https://cfssl.org/ +[openssl]: https://www.openssl.org/ From df1305d3265da0c829925fd8961bda4f6dc0da89 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Tue, 15 Nov 2016 17:21:15 -0800 Subject: [PATCH 2/3] Don't forget localhost! --- website/source/docs/agent/encryption.html.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md index fb8d1c895..9e28d16c0 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -81,7 +81,8 @@ certificate you'll be using in Nomad: "CN": "regionglobal.nomad", "hosts": [ "server.regionglobal.nomad", - "client.regionglobal.nomad" + "client.regionglobal.nomad", + "localhost" ] } ``` From 5754a3ebf468ff1dce23add1e313d90d82b43bb3 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Wed, 16 Nov 2016 14:49:29 -0800 Subject: [PATCH 3/3] Fix review comments --- website/source/docs/agent/encryption.html.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md index 9e28d16c0..275b834b2 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -3,7 +3,7 @@ layout: "docs" page_title: "Gossip and RPC Encryption" sidebar_current: "docs-agent-encryption" description: |- - Learn how to configure Nomad to encrypt all of its traffic. + Learn how to configure Nomad to encrypt HTTP, RPC, and Serf traffic. --- # Encryption @@ -62,14 +62,13 @@ simpler command line tools when learning how to configure TLS and your [PKI]. [`cfssl`][cfssl] is a tool for working with TLS certificates and certificate authorities similar to [OpenSSL's][openssl] `x509` command line tool. -Once you have the `cfssl` command line tool installed create, the first step to +Once you have the `cfssl` command line tool installed, the first step to setting up TLS is to create a Certificate Authority (CA) certificate. The following command will generate a suitable example CA CSR, certificate, and key: ```sh # Run in the directory where you want to store certificates - cfssl print-defaults csr | cfssl gencert -initca - | cfssljson -bare ca ``` @@ -78,10 +77,10 @@ certificate you'll be using in Nomad: ```json { - "CN": "regionglobal.nomad", + "CN": "global.nomad", "hosts": [ - "server.regionglobal.nomad", - "client.regionglobal.nomad", + "server.global.nomad", + "client.global.nomad", "localhost" ] } @@ -91,8 +90,8 @@ This will create a certificate suitable for both clients and servers in the `global` (default) region. In production Nomad agents should have a certificate valid for the name -`${ROLE}.region${REGION}.nomad` where role is either `client` or `server` -depending on the node's role. +`${ROLE}.${REGION}.nomad` where role is either `client` or `server` depending +on the node's role. Create a certificate signed by your CA: