StackIT RMK provider

Copy Markdown View Source

KMS.RMK.StackIT uses StackIT KMS as the RMK provider. It is useful when KMS database contents must remain protected by a separate key service.

Use this provider when StackIT is your operational cloud boundary or when you need StackIT KMS audit and IAM controls around RMK decrypt operations.

Configuration

config :kms, :rmk_provider, KMS.RMK.StackIT

config :kms, KMS.RMK.StackIT,
  service_account_token: System.get_env("STACKIT_SERVICE_ACCOUNT_TOKEN"),
  service_account_key: System.get_env("STACKIT_SERVICE_ACCOUNT_KEY"),
  project_id: System.fetch_env!("STACKIT_PROJECT_ID"),
  region_id: System.get_env("STACKIT_REGION_ID") || "eu01",
  key_ring_id: System.fetch_env!("STACKIT_KEY_RING_ID"),
  key_id: System.fetch_env!("STACKIT_KEY_ID"),
  version_number: String.to_integer(System.fetch_env!("STACKIT_KEY_VERSION"))

Required:

  • STACKIT_PROJECT_ID
  • STACKIT_REGION_ID unless app config supplies a default
  • STACKIT_KEY_RING_ID
  • STACKIT_KEY_ID
  • STACKIT_KEY_VERSION
  • one auth source:
    • STACKIT_SERVICE_ACCOUNT_TOKEN, or
    • STACKIT_SERVICE_ACCOUNT_KEY

Optional:

  • STACKIT_KMS_BASE_URL
  • STACKIT_SERVICE_ACCOUNT_TOKEN_URL

Authentication

Supported auth:

  • static bearer token via STACKIT_SERVICE_ACCOUNT_TOKEN;
  • service account key JSON via STACKIT_SERVICE_ACCOUNT_KEY.

Service account key JSON is used to mint access tokens. Tokens are cached in memory until near expiry.

Only the KMS authority process should receive StackIT credentials. Do not configure them in remote-client-only applications.

Key reference and ciphertext

New ciphertexts are stored as:

kms-rmk:v1:stackit:<key_ref_b64url>:<ciphertext_b64url>

key_ref includes project, region, key ring, key id, and key version. This matters because StackIT encrypt/decrypt operations are versioned.

Legacy raw ciphertext is still passed to the configured StackIT provider for compatibility.

BYOK / offline key material

If provider migration matters, prefer StackIT key material that your organization controls offline when StackIT supports that workflow for your key type.

If StackIT owns non-exportable key material, migration requires the old StackIT key/version to stay available until data is re-encrypted under a new RMK provider.

Keep offline key material outside the KMS database and outside KMS hosts.

Readiness

:ok = KMS.RMK.ensure_ready()

StackIT readiness calls the key endpoint. Failure returns provider errors such as :unauthorized, :not_found, :rate_limited, or :unavailable.

Caching

External RMK decrypt calls should normally be cached:

config :kms, :rmk_cache_ttl_ms, :timer.minutes(5)

Use shorter TTLs when host-memory exposure matters more than provider call volume:

KMS.decrypt_alias(encrypted, "alias", rmk_cache_ttl_ms: :timer.seconds(30))

Use rmk_cache_ttl_ms: 0 for one call when no RMK decrypt cache should be used.

Security notes

  • Do not log service account key JSON, bearer tokens, plaintext, ciphertext, or request bodies.
  • Use least-privilege StackIT credentials for encrypt/decrypt/get-key operations required by KMS.
  • Monitor StackIT KMS audit logs for unexpected decrypt volume.