Skip to content

Sealing and unsealing

TKeeper seals local sensitive material using envelope encryption.

  • DEK (Data Encryption Key): a local master key used to encrypt TKeeper storage data (RocksDB records).
  • KEK (Key Encryption Key): a provider-backed key used to wrap/unwrap the DEK.

The seal provider defines how KEK is managed and whether unsealing is automatic or requires manual operator input.

Seal mechanisms

TKeeper supports the following seal providers:

  • shamir
  • aws
  • google

The active provider is selected via:

keeper {
  providers {
    selected = "shamir" # or "aws" / "google"
  }
}

For provider-specific configuration fields, see config.md.

Startup behavior

On startup, TKeeper attempts to make the local key share available for use.

Provider Startup behavior Operator input required
aws Automatic unseal using AWS KMS. No
google Automatic unseal using Google Cloud KMS (via ADC). No
shamir Manual unseal required; protected operations remain locked until completed. Yes

Provider overview

shamir

  • TKeeper generates a local DEK during initialization.
  • The KEK is derived from Shamir shares and is used to wrap/unwrap the DEK.
  • Unseal shares are generated during initialization (/v1/keeper/system/init) and returned to the operator.
  • Manual unsealing is required after every restart.

Note

Operational notes:
Shamir supports distribution of unseal responsibility across multiple operators (for example, by distributing shares to separate team members).
Shamir avoids reliance on external KMS providers and reduces vendor lock-in.

aws

  • TKeeper uses AWS KMS as a KEK to wrap/unwrap the local DEK.
  • By default, TKeeper unseals automatically on startup.
  • Automatic unseal can be disabled via -Dkeeper.auto.unseal=false. In this mode, the operator must call GET /v1/keeper/unseal after startup.
  • No manual unseal shares are required.

TKeeper uses official amazon sdk. Set credentials via env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optionally AWS_SESSION_TOKEN) or configure an AWS profile with AWS CLI. The SDK uses the default credential and region provider chains.

google

  • TKeeper uses Google Cloud KMS as a KEK to wrap/unwrap the local DEK.
  • By default, TKeeper unseals automatically on startup (using Application Default Credentials).
  • Automatic unseal can be disabled via -Dkeeper.auto.unseal=false. In this mode, the operator must call GET /v1/keeper/unseal after startup.
  • No manual unseal shares are required.

TKeeper authenticates to Google Cloud KMS using Application Default Credentials (ADC). When ADC is used, the Google authentication libraries automatically discover credentials based on the runtime environment.

Manual Unseal (Shamir)

Tip

You can unseal TKeeper via the control plane at /ui.
This section describes how to unseal via the API.

When keeper.providers.selected = "shamir", a keeper must reconstruct its local unseal key using a threshold of unseal shares.

Unsealing can be performed: - incrementally (one share at a time), or - in a single request (multiple shares at once)

Endpoint

  • POST /v1/keeper/system/unseal

Request body

{
  "payload64": "<index>:<sealed_share>:<salt>",
  "payloads64": [
    "<index>:<sealed_share>:<salt>",
    "..."
  ],
  "reset": false
}

Request fields:

Field Type Meaning
payload64 string Single share payload (optional).
payloads64 array[string] Multiple share payloads (optional).
reset boolean If true, clears prior progress before applying submitted shares.

Requirements:

  • A request should include either payload64 or payloads64.

Response

{
  "threshold": 3,
  "total": 5,
  "progress": 2,
  "ready": false
}

Response fields:

Field Meaning
threshold Number of shares required to complete unsealing.
total Total configured shares available for the keeper.
progress Number of valid shares accepted so far.
ready true when unsealing completed and the keeper is operational.

When ready = true, protected operations can proceed.

Manual Unseal (google/aws)

If you sealed storage via /v1/keeper/system/seal endpoint, or -Dkeeper.auto.unseal=false is specified, call:

  • GET /v1/keeper/system/unseal

After authorization check, it will allow to keeper use specified KEK.

Operational guidance

For deployments that require shared operational responsibility and provider independence, shamir is recommended:

  • Unseal access can be distributed across multiple trusted operators by splitting shares among team members.
  • It avoids reliance on external KMS providers and reduces vendor lock-in.

Share handling

  • Shamir unseal shares are high-value material. Store them under the same controls used for recovery credentials.
  • Loss of shares may prevent unsealing, depending on threshold and how many shares remain available.
  • Distributing shares reduces single-operator authority and aligns with multi-person control requirements.

Security properties

  • Sealed key material is encrypted at rest before storage.
  • Decrypted key share material is held only in locked memory during runtime.