CA Pinning

[russjones]

When a node joins a cluster, both sides need to verify the identity of the other before a successful join can occur. The cluster needs to ensure that the node joining was issued a token that itself generated and the node connecting needs to verify the Auth Server it is connecting to is the one that issued the token.

The current approach is for nodes to look for a file on disk at /var/lib/teleport/ca.cert which contains the CA certificate and use this to verify the certificate presented by the Auth Server. If no CA certificate exists at that path, then the Auth Server is not validated.

This proposal adds a user friendly way for nodes to verify the identity of the Auth Server by using CA pins. Similar to the approach used by Kubernetes, when an Auth Server issues a join token, it also takes the SHA256 hash of the CA Subject Public Key Info (SPKI) of it's CA. This is sent along with the token and used by the node to join the cluster.

Now when creating a join token:

$ tctl nodes add
The invite token: 1ac590d36493acdaa2387bc1c492db1a
This token will expire in 30 minutes

Run this on the new node to join the cluster:

$ teleport start \
   --roles=node \
   --token=1ac590d36493acdaa2387bc1c492db1a \
   --ca-pin=sha256:68517d9f8591d29d0b1fdbd157389db3ef92ea101c4867d45b8719049a6ac8f5 \
   --auth-server=10.12.0.6:3025

Please note:

  - This invitation token will expire in 30 minutes.
  - 10.12.0.6:3025 must be reachable from the new node.

Teleport can be started with the above CA pin either using command line flags or using Teleport file configuration.

$ teleport start \
   --roles=node \
   --token=1ac590d36493acdaa2387bc1c492db1a \
   --ca-pin=sha256:68517d9f8591d29d0b1fdbd157389db3ef92ea101c4867d45b8719049a6ac8f5 \
   --auth-server=10.12.0.6:3025

teleport:
  nodename: "node"

  auth_token: "1ac590d36493acdaa2387bc1c492db1a"
  ca_pin: "sha256:68517d9f8591d29d0b1fdbd157389db3ef92ea101c4867d45b8719049a6ac8f5"

  auth_servers:
    - "10.12.0.6:3025"

[kontsevoy]

@russjones @klizhentas

Currently there's no elegant way for a user to get the CA pin of a cluster. For example if I am using statically defined tokens (as most do), I will not be calling tctl nodes add.

In the docs, I am adding the following:

$ tctl status
Cluster  staging.example.com           
User CA  never updated 
Host CA  never updated 
CA pin   sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1

... and telling users to execute tctl status to get the value of a CA pin. Happy to chage if you have a better idea, but we need to add this line to the output before 3.1 gets out the door.

[kontsevoy]

@russjones feel free to close the ticket when tctl status is updated. The docs are done.

[jeroenvermeulen]

Could you add JSON output to tctl status? I would like to parse the output.