github.com/ncodes/nomad@v0.5.7-0.20170403112158-97adf4a74fb3/website/source/docs/agent/encryption.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Gossip and RPC Encryption"
     4  sidebar_current: "docs-agent-encryption"
     5  description: |-
     6    Learn how to configure Nomad to encrypt HTTP, RPC, and Serf traffic.
     7  ---
     8  
     9  # Encryption
    10  
    11  The Nomad agent supports encrypting all of its network traffic. There are
    12  two separate encryption systems, one for gossip traffic, and one for HTTP and
    13  RPC.
    14  
    15  ## Gossip
    16  
    17  Enabling gossip encryption only requires that you set an encryption key when
    18  starting the Nomad server. The key can be set via the
    19  [`encrypt`](/docs/agent/configuration/server.html#encrypt) parameter: the value
    20  of this setting is a server configuration file containing the encryption key.
    21  
    22  The key must be 16-bytes, base64 encoded. As a convenience, Nomad provides the
    23  [`nomad keygen`](/docs/commands/keygen.html) command to generate a cryptographically suitable key:
    24  
    25  ```sh
    26  $ nomad keygen
    27  cg8StVXbQJ0gPvMd9o7yrg==
    28  ```
    29  
    30  With that key, you can enable gossip encryption on the agent.
    31  
    32  
    33  ## HTTP, RPC, and Raft Encryption with TLS
    34  
    35  Nomad supports using TLS to verify the authenticity of servers and clients. To
    36  enable this, Nomad requires that all clients and servers have key pairs that are
    37  generated and signed by a Certificate Authority. This can be a private CA.
    38  
    39  TLS can be used to verify the authenticity of the servers and clients. The
    40  configuration option [`verify_server_hostname`][tls] causes Nomad to verify that
    41  a certificate is provided that is signed by the Certificate Authority from the
    42  [`ca_file`][tls] for TLS connections.
    43  
    44  If `verify_server_hostname` is set, then outgoing connections perform
    45  hostname verification. Unlike traditional HTTPS browser validation, all servers
    46  must have a certificate valid for `server.<region>.nomad` or the client will
    47  reject the handshake. It is also recommended for the certificate to sign
    48  `localhost` such that the CLI can validate the server name.
    49  
    50  TLS is used to secure the RPC calls between agents, but gossip between nodes is
    51  done over UDP and is secured using a symmetric key. See above for enabling
    52  gossip encryption.
    53  
    54  ## Encryption Examples
    55  
    56  ### TLS Configuration using `cfssl`
    57  
    58  While [Vault's PKI backend][vault] is an ideal solution for managing
    59  certificates and other secrets in a production environment, it's useful to use
    60  simpler command line tools when learning how to configure TLS and your [PKI].
    61  
    62  [`cfssl`][cfssl] is a tool for working with TLS certificates and certificate
    63  authorities similar to [OpenSSL's][openssl] `x509` command line tool.
    64  
    65  Once you have the `cfssl` command line tool installed, the first step to
    66  setting up TLS is to create a Certificate Authority (CA) certificate.  The
    67  following command will generate a suitable example CA CSR, certificate, and
    68  key:
    69  
    70  ```shell
    71  # Run in the directory where you want to store certificates
    72  $ cfssl print-defaults csr | cfssl gencert -initca - | cfssljson -bare ca
    73  ```
    74  
    75  Next create a `nomad-csr.json` which contains the configuration for the actual
    76  certificate you'll be using in Nomad:
    77  
    78  ```json
    79  {
    80    "CN": "global.nomad",
    81    "hosts": [
    82      "server.global.nomad",
    83      "client.global.nomad",
    84      "localhost"
    85    ]
    86  }
    87  ```
    88  
    89  This will create a certificate suitable for both clients and servers in the
    90  `global` (default) region.
    91  
    92  In production Nomad agents should have a certificate valid for the name
    93  `${ROLE}.${REGION}.nomad` where role is either `client` or `server` depending
    94  on the node's role.
    95  
    96  Create a certificate signed by your CA:
    97  
    98  ```shell
    99  $ cfssl gencert -ca ca.pem -ca-key ca-key.pem nomad-csr.json | cfssljson -bare nomad
   100  ```
   101  
   102  You've now successfully generated self-signed certificates! You should see the
   103  following files:
   104  
   105  - `ca.pem` - the CA certificate. This corresponds to the Nomad `ca_file`
   106    parameter in the Nomad [`tls` stanza][tls].
   107  
   108  - `ca-key.pem` - the CA private key. This is used to sign CSRs and should
   109    **not** be included in the Nomad [`tls` stanza][tls].
   110  
   111  - `nomad.pem` - the Nomad certificate for the region. This corresponds to the
   112    `cert_file` parameter in the Nomad [`tls` stanza][tls].
   113  
   114  - `nomad-key.pem` - the Nomad private key. This corresponds to the `key_file`
   115    parameter in the Nomad [`tls` stanza][tls].
   116  
   117  - `*.csr` - the certificate signing request. This is temporary for generating
   118    certificates and should **not** be included in the Nomad [`tls` stanza][tls].
   119  
   120  In your Nomad configuration add the `tls` stanza:
   121  
   122  ```hcl
   123  tls {
   124    http = true
   125    rpc  = true
   126  
   127    ca_file   = "ca.pem"
   128    cert_file = "nomad.pem"
   129    key_file  = "nomad-key.pem"
   130  
   131    verify_server_hostname = true
   132  }
   133  ```
   134  
   135  [vault]: https://www.vaultproject.io/docs/secrets/pki/
   136  [PKI]: https://en.wikipedia.org/wiki/Public_key_infrastructure
   137  [cfssl]: https://cfssl.org/
   138  [openssl]: https://www.openssl.org/
   139  [tls]: /docs/agent/configuration/tls.html "Nomad TLS Configuration"