Rotating Manual Session Recording Encryption Keys

Report an Issue

Is this page helpful?

How can we improve this page?

View as Markdown

In the manual approach to rotating keys for session recordings, you configure the encryption keys that the Teleport Auth Service uses for encrypted session recordings.

In this guide, you will perform a single key rotation by configuring the Teleport Auth Service.

For instructions on using the automatic approach, see Rotating Session Recording Encryption Keys.

How it works

In the manual approach to session recording key management, a user provides the Auth Service with the types and labels of keys used to encrypt Teleport session recordings. In this way, the user has control over the keys the Auth Service uses to encrypt session recordings, as well as rotated keys that the Auth Service no longer uses for encryption, but that are available for decrypting stored session recordings.

Prerequisites

This guide assumes that you have followed the setup instructions in Encrypted Session Recordings.

Although Manual Key Management leaves key rotation entirely up to the administrator, the manual_key_management configuration can be leveraged to help facilitate rotations.

As an example, we will assume an existing Teleport Auth Service configured to use a PKCS#11 compatible HSM with an active key identified by the label session_recordings_001.

While this guide shows you how to perform a manual session recording key rotation using the session_recording_config resource, you can also make the same changes to the Teleport Auth Service configuration directly. To do so, edit the auth_service.session_recording_config.encryption configuration block instead of the spec.encryption block, e.g.:

auth_service:
  session_recording_config:
    encryption:
      enabled: yes
      manual_key_management:
        enabled: yes
        active_keys:
          - type: pkcs11
            label: 'session_recordings_001'

Step 1/2. Add the new key

A new key can be added to the list of active keys. Run the following command to edit the session recording config in your cluster:

tctl edit session_recording_config

Include the following:

  kind: session_recording_config
  version: v2
  metadata:
    name: session-recording-config
  spec:
    encryption:
      enabled: yes
+     manual_key_management:
+       enabled: yes
+       active_keys:
+         - type: pkcs11
+           label: 'session_recordings_002'
+         - type: pkcs11
+           label: 'session_recordings_001'

Save the file and close your editor to apply the changes.

This configuration expects a second key to be accessible using the session_recordings_002 label. Teleport maintains a cache of references to accessible keys that is periodically updated, but it is best practice to ensure the key exists prior to updating the manual_key_management configuration.

Step 2/2. Rotate the old key

The old key can be moved out of the active set of encryption keys and into the set of rotated keys. Run the following command to edit the session recording config in your cluster:

tctl edit session_recording_config

Include the following:

  kind: session_recording_config
  version: v2
  metadata:
    name: session-recording-config
  spec:
    encryption:
      enabled: yes
      manual_key_management:
        enabled: yes
-       active_keys:
-         - type: pkcs11
-           label: 'session_recordings_002'
-         - type: pkcs11
-           label: 'session_recordings_001'
+       active_keys:
+         - type: pkcs11
+           label: 'session_recordings_002'
+       rotated_keys:
+         - type: pkcs11
+           label: 'session_recordings_001'

Save the file and close your editor to apply the changes.

All new recordings will now be encrypted using the key labeled by session_recordings_002, and historical recordings encrypted using session_recordings_001 will remain replayable.