kms

# StackIT RMK provider

`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

```elixir
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:

```text
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

```elixir
: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:

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

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

```elixir
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.