Skip to content

Adding session recording encryption key rotation to tctl#57780

Merged
eriktate merged 1 commit intomasterfrom
eriktate/tctl-encryption-key-rotation
Aug 26, 2025
Merged

Adding session recording encryption key rotation to tctl#57780
eriktate merged 1 commit intomasterfrom
eriktate/tctl-encryption-key-rotation

Conversation

@eriktate
Copy link
Copy Markdown
Contributor

@eriktate eriktate commented Aug 11, 2025

This PR adds subcommands for rotating session recording encryption keys under tctl recordings encryption. They are rotate, status, complete-rotation, and rollback-rotation.

  • rotate will start a rotation by provisioning a new key and adding it to the active set of encryption keys.
  • status will print the state of each key along with its fingerprint.
  • 'complete-rotation' will move the rotated key of an in-progress rotation into a RotatedKeys resource which makes it usable for replays
  • 'rollback-rotation' will remove the new key in an in-progress rotation and reinstate the original key. Running rotate and rollback should ultimately result in no changes being applied.

There's also a fix for using manual_key_management from the fileconfig included.

$ tctl recordings encryption --help
usage: tctl recordings encryption <command> [<args> ...]

Manage encryption properties of session recordings.

Flags:
  -d, --[no-]debug     Enable verbose logging to stderr
  -c, --config         Path to a configuration file [/etc/teleport.yaml] for an Auth Service instance. Can also be set via
                       the TELEPORT_CONFIG_FILE environment variable. Ignored if the auth_service is disabled.
      --auth-server    Attempts to connect to specific auth/proxy address(es) instead of local auth [127.0.0.1:3025]
  -i, --identity       Path to an identity file. Must be provided to make remote connections to auth. An identity file can be
                       exported with 'tctl auth sign'
      --[no-]insecure  When specifying a proxy address in --auth-server, do not verify its TLS certificate. Danger: any data
                       you send can be intercepted or modified by an attacker.

Commands:
  recordings encryption rotate            Rotate encryption keys used for encrypting session recordings.
  recordings encryption status            Show current rotation status
  recordings encryption complete-rotation Completes an in-progress encryption key rotation.
  recordings encryption rollback-rotation Rolls back an in-progress encryption key rotation.

@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from 9975ad2 to dfcb23e Compare August 12, 2025 16:09
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 896e8b5 to 21eba68 Compare August 12, 2025 16:10
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from dfcb23e to 08205b8 Compare August 12, 2025 19:47
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch 2 times, most recently from 10f19bc to 61774dc Compare August 12, 2025 19:58
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from 08205b8 to 0bbff95 Compare August 12, 2025 20:08
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 61774dc to 03399fb Compare August 12, 2025 20:08
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from 0bbff95 to cfd8a0d Compare August 13, 2025 19:05
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 03399fb to 9851d3e Compare August 13, 2025 19:06
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch 3 times, most recently from 07e70f4 to feb25d0 Compare August 14, 2025 18:24
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 9851d3e to 793694f Compare August 14, 2025 18:24
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch 2 times, most recently from 616902e to c061345 Compare August 15, 2025 18:52
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 793694f to 6c9d34c Compare August 15, 2025 19:01
@eriktate eriktate marked this pull request as ready for review August 15, 2025 19:01
@github-actions github-actions Bot added size/md tctl tctl - Teleport admin tool labels Aug 15, 2025
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch 2 times, most recently from c66edd3 to 2590df4 Compare August 15, 2025 19:06
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from facc111 to a3a55f4 Compare August 15, 2025 21:36
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch 4 times, most recently from fd07f4f to 9c37f95 Compare August 19, 2025 19:40
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from 031a470 to 9a4027f Compare August 19, 2025 20:02
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 9c37f95 to 0f3ecd9 Compare August 19, 2025 20:04
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 5e29b99 to 51248d7 Compare August 21, 2025 16:17
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from 94498db to 775f225 Compare August 22, 2025 19:35
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from b552e2d to e10692f Compare August 22, 2025 19:35
Comment thread lib/auth/init.go
Comment thread tool/tctl/common/recordings_encryption_command.go Outdated
Comment thread lib/config/fileconf.go
Comment on lines +2933 to +2950
// SessionRecordingEncryptionConfig is the session_recording_config.encryption
// section of the Teleport config file. It maps directly to [types.SessionRecordingEncryptionConfig]
type SessionRecordingEncryptionConfig struct {
Enabled bool `yaml:"enabled,omitempty"`
ManualKeyManagement *struct {
Enabled bool `yaml:"enabled,omitempty"`
ActiveKeys []*types.KeyLabel `yaml:"active_keys,omitempty"`
RotatedKeys []*types.KeyLabel `yaml:"rotated_keys,omitempty"`
} `yaml:"manual_key_management,omitempty"`
}

// SessionRecordingConfig is the session_recording_config section of the Teleport config file.
// It maps directly to [types.SessionRecordingConfigSpecV2]
type SessionRecordingConfig struct {
Mode string `yaml:"mode"`
ProxyChecksHostKeys *types.BoolOption `yaml:"proxy_checks_host_keys,omitempty"`
Encryption *SessionRecordingEncryptionConfig `yaml:"encryption,omitempty"`
}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like it could cause problems if we forget to update this in response to any changes made to the types.SessionRecordingEncryptionConfig resource. Why is this needed?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fields with underscores were broken before I added this, so manual_key_management and proxy_checks_host_keys. If there's a way to get the yaml parser to use the json tags during unmarshaling, that would definitely be better

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@atburke any thoughts here regarding the yaml parser and json tags with _?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The yaml parser isn't seeing the json tags at all and is assuming camel case instead of snake case. I don't think any of our current yaml packages can handle mixed yaml and json tags within the same object; we'll have to either do what you're doing here or get goccy just for ReadConfig.

@eriktate eriktate requested a review from rosstimothy August 22, 2025 21:48
@public-teleport-github-review-bot public-teleport-github-review-bot Bot removed the request for review from fspmarshall August 25, 2025 12:18
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from 775f225 to 9c09e0e Compare August 25, 2025 15:19
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from d1d5594 to 8efaa74 Compare August 25, 2025 15:20
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch 3 times, most recently from c164220 to e34ceba Compare August 26, 2025 14:00
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from 8efaa74 to 837bb3a Compare August 26, 2025 14:33
@eriktate eriktate force-pushed the eriktate/rotating-encryption-keys branch from e34ceba to e125ded Compare August 26, 2025 20:44
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch 2 times, most recently from e5ff62d to d3ad732 Compare August 26, 2025 21:11
Base automatically changed from eriktate/rotating-encryption-keys to master August 26, 2025 21:30
@eriktate eriktate added this pull request to the merge queue Aug 26, 2025
broken session_recording_config when using fileconf
@eriktate eriktate removed this pull request from the merge queue due to a manual request Aug 26, 2025
@eriktate eriktate force-pushed the eriktate/tctl-encryption-key-rotation branch from d3ad732 to aa0a7c9 Compare August 26, 2025 21:41
@eriktate eriktate enabled auto-merge August 26, 2025 21:41
@eriktate eriktate added this pull request to the merge queue Aug 26, 2025
Merged via the queue into master with commit c987490 Aug 26, 2025
41 checks passed
@eriktate eriktate deleted the eriktate/tctl-encryption-key-rotation branch August 26, 2025 22:27
eriktate added a commit that referenced this pull request Aug 27, 2025
eriktate added a commit that referenced this pull request Aug 27, 2025
eriktate added a commit that referenced this pull request Sep 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

hold-for-18.2 no-changelog Indicates that a PR does not require a changelog entry size/md tctl tctl - Teleport admin tool

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants