CA rotation

[klizhentas]

Description

Currently it is only possible to "hard-revoke" teleport CA authority by wiping out data. There should be a way to gracefully rotate user and host certificate authorities.

Proposal

Automatic rotation

The most simple way to rotate certificate authorities, both user and host should be as easy as:

tctl auth rotate

This will trigger 48 hour rotation process - new user and host CA will be effective immediately and old user and host CA will be deprecated in 48 hours.

The ttl can be adjusted by using --grace-period flag, and type of authority to rotate can be selected using --type flag:

tctl auth rotate --type=user --grace-period=200h

This rotation will be respected by trusted clusters as well.

Manual rotation

Start manual rotation:

tctl auth rotate --manual --phase=update_clients

Make sure all components have updated to update_clients phase by looking at the rotation status:

$tctl get auth
kind: auth_server
metadata:
  expires: 2018-05-01T17:24:23.230193591Z
  name: 2f814269-2d8c-4ac7-928b-41213d3b254a
spec:
  addr: 192.168.122.1:3025
  hostname: planet
  rotation:
    current_id: 33933c76-b8b4-45c9-becc-3f077f950c86
    grace_period: 30h0m0s
    last_rotated: 0001-01-01T00:00:00Z
    mode: manual
    phase: update_servers
    schedule:
      standby: 2018-05-02T23:22:33.016692123Z
      update_servers: 2018-05-02T08:22:33.01669192Z
    started: 2018-05-01T17:22:33.523546431Z
    state: in_progress

# repeat procedure for nodes
tctl get proxy
tctl get node

Move to the next phase:

tctl auth rotate --manual --phase=update_servers
# check status of the components again

Wrap up the phase:

tctl auth rotate --manual --phase=standby
# check status of the components again

Rolling back:

In case if something went wrong, rollback is possible from phases update_clients and update_servers

In this mode, old CA and new CA are both trusted, but all components will re-register with old CA credentials

tctl auth rotate --manual --phase=rollback
# check status of the components again

From rollback phase, it is possible to go to standby to revert to old cert authority

tctl auth rotate --manual --phase=standbyu
# check status of the components again

Forced rotation

Sometimes it is necessary to force-rotate user or host CA

tctl auth rotate --grace-period=0h --type=user

Rotation status

Rotation status can be queried at:

$ tctl status
No rotation is in progress.

$ tctl status

* User Certificate Authority rotation in progress, old CA will be bsolete in 3 hours

With debug flag, status will print status of remote clusters as well:

tctl status -d

More low-level docs are here:

https://github.com/gravitational/teleport/blob/master/lib/auth/rotate.go#L126

[klizhentas]

@kontsevoy I converted this to doc ticket and moved it out of 2.6.0 milestone, so you can take care of it on your own schedule.

[kontsevoy]

@klizhentas I have documented the high-level commands but we're leaving "phases" undocumented for now.