Skip to content

pg_hardstorage_kms_rotate.md

Latest commit

 

History

History
86 lines (68 loc) · 4.61 KB

pg_hardstorage_kms_rotate.md

File metadata and controls

86 lines (68 loc) · 4.61 KB
Raw
title pg hardstorage kms rotate
description CLI reference for the pg hardstorage kms rotate command.
tags
cli
reference

pg_hardstorage kms rotate

Re-wrap every encrypted backup's DEK with a new KEK

Synopsis

Walk every committed (non-tombstoned) backup manifest in the repo. For each manifest wrapped with --old-kek-ref:

  1. Decrypt the wrapped DEK using the bytes at --old-kek-file.
  2. Re-wrap the DEK using the bytes at --new-kek-file.
  3. Mutate the manifest's encryption block to record --new-kek-ref and the new wrapped_dek; everything else stays bit-identical.
  4. Re-sign the manifest (the operator's signing keypair is unchanged).
  5. Atomically rewrite the manifest at its repo key (and the replica copy if present).

Chunks are NOT re-encrypted. Per-chunk keys are derived via HKDF from the (unchanged) BDEK; rewrapping the DEK leaves every chunk's bytes untouched. KEK rotation is O(manifest count), not O(chunk count).

Multi-tenant safety: only manifests with --old-kek-ref are touched. Manifests wrapped under different KEK refs (other tenants) are skipped, not failed. Operators rotating per-tenant KEKs run this command once per tenant.

Resumability: a rotation interrupted partway through is safely re-runnable with the same args. Manifests that were already rotated (their KEKRef == --new-kek-ref) are counted as 'already_rotated' and skipped.

Default mode is dry-run; pass --apply to actually rewrite. With --apply, one kms.rotate audit event is emitted per rotated manifest.

pg_hardstorage kms rotate [flags]

Options

      --apply                 actually rewrite the manifests (default: dry-run)
  -h, --help                  help for rotate
      --new-kek-file string   path to the NEW KEK bytes (32 bytes raw); required
      --new-kek-ref string    the kek_ref to record on rotated manifests (required)
      --old-kek-file string   path to the OLD KEK bytes (32 bytes raw); required
      --old-kek-ref string    the kek_ref currently on the manifests to rotate (required)
      --repo string           repository URL (required)

Options inherited from parent commands

      --airgapped airgapped: strict                                                       refuse outbound endpoints (LLM providers, sinks, OTLP collectors) outside loopback / RFC1918 / explicit airgap.allowlist. Also enabled by PG_HARDSTORAGE_AIRGAPPED=1 or airgapped: strict in the config file.
  -c, --config string                                                                     path to config file (default: XDG/FHS lookup)
      --cpu-profile go tool pprof <path>                                                  write a pprof CPU profile to this path for the duration of the command (go tool pprof <path> to analyse). Off when empty.
      --mem-profile string                                                                write a pprof heap profile to this path at command exit. Off when empty.
      --no-color                                                                          disable ANSI color in text output
      --on-error-llm                                                                      on a structured-error failure, drop into the matching LLM helper skill (auto_on_error trigger). Also enabled by PG_HARDSTORAGE_ON_ERROR_LLM=1.
      --otel-endpoint string                                                              OpenTelemetry OTLP/HTTP endpoint (e.g. http://otel-collector:4318); empty disables tracing
      --otel-stdout                                                                       also export OpenTelemetry traces to stderr (useful for dev)
  -o, --output string                                                                     output format: text|json|ndjson|yaml|template|csv|markdown|html|tap|junit|pdf (default: text on TTY, json off-TTY)
      --profile-port go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30   if non-zero, expose net/http/pprof on 127.0.0.1:<port> for live profiling of long-running commands (e.g. go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30). Off when zero.
  -q, --quiet                                                                             suppress non-essential output
      --template string                                                                   Go text/template applied when --output template (or implied if --template is set without --output)

SEE ALSO