From 5ca3e6e61f5537fa637de9436881402a929bea77 Mon Sep 17 00:00:00 2001 From: Charles Smith Date: Fri, 2 Sep 2016 14:52:41 -0700 Subject: [PATCH] add how pki works topic Signed-off-by: Charles Smith --- docs/swarm/how-swarm-mode-works/nodes.md | 3 +- docs/swarm/how-swarm-mode-works/pki.md | 72 ++++++++++++++++++++ docs/swarm/how-swarm-mode-works/services.md | 5 ++ docs/swarm/images/src/tls.svg | 1 + docs/swarm/images/tls.png | Bin 0 -> 69747 bytes 5 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 docs/swarm/how-swarm-mode-works/pki.md create mode 100644 docs/swarm/images/src/tls.svg create mode 100644 docs/swarm/images/tls.png diff --git a/docs/swarm/how-swarm-mode-works/nodes.md b/docs/swarm/how-swarm-mode-works/nodes.md index 825939e5b8..ac8dc76b3f 100644 --- a/docs/swarm/how-swarm-mode-works/nodes.md +++ b/docs/swarm/how-swarm-mode-works/nodes.md @@ -86,6 +86,7 @@ You can also demote a manager node to a worker node. See [node demote](../../reference/commandline/node_demote.md). -## What's Next +## Learn More * Read about how swarm mode [services](services.md) work. +* Learn how [PKI](pki.md) works in swarm mode diff --git a/docs/swarm/how-swarm-mode-works/pki.md b/docs/swarm/how-swarm-mode-works/pki.md new file mode 100644 index 0000000000..6f2698c3f7 --- /dev/null +++ b/docs/swarm/how-swarm-mode-works/pki.md @@ -0,0 +1,72 @@ + + +# How PKI works in swarm mode + +The swarm mode public key infrastructure (PKI) system built into Docker Engine +makes it simple to securely deploy a container orchestration system. The nodes +in a swarm use mutual Transport Layer Security (TLS) to authenticate, authorize, +and encrypt the communications between themselves and other nodes in the swarm. + +When you create a swarm by running `docker swarm init`, the Docker Engine +designates istself as a manager node. By default, the manager node generates +itself a new root Certificate Authority (CA) along with a key pair to secure +communications with other nodes that join the swarm. If you prefer, you can pass +the `--external-ca` flag to specify a root CA external to the swarm. Refer to +the [docker swarm init](../../reference/commandline/swarm_init.md) CLI +reference. + +The manager node also generates two tokens to use when you join additional nodes +to the swarm: one worker token and one manager token. Each token includes the +digest of the root CA's certificate and a randomly generated secret. When a node +joins the swarm, it uses the digest to validate the root CA certificate from the +remote manager. It uses the secret to ensure the node is an approved node. + +Each time a new node joins the swarm, the manager issues a certificate to the +node that contains a randomly generated node id to identify the node under the +certificate common name (CN) and the role under the organizational unit (OU). +The node id serves as the cryptographically secure node identity for the +lifetime of the node in the current swarm. + +The diagram below illustrates how worker manager nodes and worker nodes encrypt +communications using a minimum of TLS 1.2. + +![tls diagram](../images/tls.png) + + +The example below shows the information from a certificate from a worker node: + +```bash +Certificate: + Data: + Version: 3 (0x2) + Serial Number: + 3b:1c:06:91:73:fb:16:ff:69:c3:f7:a2:fe:96:c1:73:e2:80:97:3b + Signature Algorithm: ecdsa-with-SHA256 + Issuer: CN=swarm-ca + Validity + Not Before: Aug 30 02:39:00 2016 GMT + Not After : Nov 28 03:39:00 2016 GMT + Subject: O=ec2adilxf4ngv7ev8fwsi61i7, OU=swarm-worker, CN=dw02poa4vqvzxi5c10gm4pq2g +...snip... +``` + +By default, each node in the swarm renews its certificate every three months. +You can run `docker swarm update --cert-expiry