Skip to content

pg_hardstorage_kms_verify.md

Latest commit

 

History

History
88 lines (70 loc) · 4.95 KB

pg_hardstorage_kms_verify.md

File metadata and controls

88 lines (70 loc) · 4.95 KB
Raw
title pg hardstorage kms verify
description CLI reference for the pg hardstorage kms verify command.
tags
cli
reference

pg_hardstorage kms verify

Verify the encryption envelope on every backup manifest in the repo

Synopsis

kms verify walks every committed (non-tombstoned) backup manifest in the repo and asks the only question that matters for at-rest encryption health: "would the operator's current keyring decrypt this backup if we had to restore it right now?".

For each manifest, kms verify:

  1. Validates the manifest's Ed25519 signature against the local public key (manifests that don't verify get the loudest classification: signature_failed).
  2. Reads the encryption block. Manifests with no encryption block are counted as 'unencrypted' (NOT a failure — that's the operator's policy call).
  3. Resolves the KEK by KEKRef. By default the resolver is the local keystore, which knows the "local:default" ref. With --kek-ref + --kek-file the operator points at an explicit KEK file for one ref (post-rotation or per-tenant audits).
  4. Tries to unwrap the wrapped_dek with the resolved KEK. A successful unwrap is "ok"; a tag-failure is "unwrap_failed".

Chunks are NOT fetched, decrypted, or hashed. For per-chunk integrity verification of one specific backup, use pg_hardstorage verify <deployment> [backup-id]. The fleet-wide envelope check this command runs is O(manifest count); per-chunk verification is O(unique chunks per backup) and orders of magnitude more expensive.

Read-only by construction — safe to run against a read-only repo, a WORM-locked repo, or production at any cadence.

Exit code is 0 when every encrypted manifest unwraps cleanly (or every manifest is unencrypted). Exit code 9 (verify failed) is returned when at least one encrypted manifest can't be decrypted with the resolved KEK, or any manifest signature failed.

pg_hardstorage kms verify [flags]

Options

      --deployment string   restrict the walk to one deployment (default: all deployments)
  -h, --help                help for verify
      --kek-file string     path to KEK bytes for --kek-ref (32 bytes raw); required when --kek-ref is set, not the local-keystore ref, and the local keyring can't resolve the ref
      --kek-ref string      restrict to manifests whose KEKRef matches this string (default: all kek_refs)
      --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