Bring your own AWS key

BYOK (AWS KMS) PAID

Bring your own key (BYOK) adds an extra encryption layer to supported stored vault records, using a key you control in Amazon Web Services Key Management Service (AWS KMS). Available under an Enterprise contract.

Your client encrypts the content first. BYOK then wraps those encrypted bytes on the server with a per-record AES-256-GCM data encryption key (DEK); your AWS KMS customer-managed key (CMK) protects the DEK. A copy of the database alone does not expose the unwrapped vault content. Revoking KMS access blocks future unwrapping, not copies already obtained.

Storage scope:

• vault_items.encrypted_data: standard vault records, including writes through the API and dashboard. The separate Managed Vault API above does not apply this wrapping.

The encrypt/decrypt API surface (/api/encrypt, /api/decrypt) is unaffected because nothing on those paths is server-stored.

For your engineers: an ARN (Amazon Resource Name) identifies an AWS resource. IAM (Identity and Access Management) defines the role and permissions. STS (Security Token Service) lets deny.sh assume that role temporarily.

Setup walkthrough

Full step-by-step at /byok-walkthrough. Four steps in summary:

1. Create a symmetric AES-256 CMK in AWS KMS in the region you want.
2. Create an IAM role in your account with a trust policy naming deny.sh's account as principal, an sts:ExternalId condition with the external ID shown in your BYOK dashboard, and permissions kms:GenerateDataKey + kms:Decrypt scoped to your CMK ARN. Mirror the same allow in the CMK's key policy.
3. Paste both ARNs plus the region into /dashboard/byok.
4. Click Register. We immediately STS AssumeRole and roundtrip a verify call. On success, your state flips to active.

IAM trust policy template

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AllowDenyShAssumeRole",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<DENY_SH_AWS_ACCOUNT_ID>:root" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "<YOUR_EXTERNAL_ID>" }
    }
  }]
}

IAM role inline permission policy

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "DenyShEnvelopeOps",
    "Effect": "Allow",
    "Action": [ "kms:GenerateDataKey", "kms:Decrypt" ],
    "Resource": "<YOUR_CMK_ARN>"
  }]
}

KMS key policy addition

{
  "Sid": "AllowDenyShRoleToUseKey",
  "Effect": "Allow",
  "Principal": { "AWS": "<YOUR_ROLE_ARN>" },
  "Action": [ "kms:GenerateDataKey", "kms:Decrypt", "kms:DescribeKey" ],
  "Resource": "*"
}

Config states

Failure-mode reference

Routes

All BYOK routes require a signed-in consumer session (cs_*) from /login, sent in the Bearer header, and BYOK-enabled account access. Only the account owner can register, verify, rotate or revoke the configuration. Cookies are not accepted for this authentication.

POST Register BYOK config

POST /v1/byok/config
Authorization: Bearer cs_your_session_token

{
  "cmkArn": "arn:aws:kms:us-east-1:<12-digit-account-id>:key/<uuid>",
  "iamRoleArn": "arn:aws:iam::<12-digit-account-id>:role/deny-sh-byok-role",
  "region": "us-east-1"
}

201
{
  "config": {
    "state": "active",
    "cmk_arn": "<...>",
    "iam_role_arn": "<...>",
    "region": "us-east-1",
    "verified_at": 1764000000
  }
}

GET Read BYOK config

GET /v1/byok/config

200
{ "config": { "cmk_arn": "...", "state": "active", "verified_at": ..., ... } }

POST Re-verify BYOK config

Forces a fresh STS AssumeRole + KMS roundtrip. Useful after rotating the IAM role or updating the key policy. State updates to active or failed on completion.

POST /v1/byok/verify

200
{ "config": { "state": "active", "verified_at": ..., ... } }

DELETE Revoke BYOK config

Sets state to revoked. New writes requiring BYOK are blocked; reads of historical wrapped rows return BYOK_UNAVAILABLE. Restore the same key configuration and permissions to regain access. Copies already obtained cannot be recalled.

DELETE /v1/byok/config

200
{ "config": { "state": "revoked", ... } }

Responses above show selected fields. GET /v1/byok/config returns { "config": null } if no configuration exists. An active configuration cannot be overwritten through registration; use POST /v1/byok/rotate to change its key, role or region. See the BYOK walkthrough.

Audit-chain op vocabulary

Every BYOK lifecycle event lands in the hash-chained audit log. Filter /dashboard/audit by op_type prefix byok. to see just BYOK ops. ARN suffixes only (last 12 chars) appear in payloads; never the full ARN.

You also see our calls on your side: every kms:GenerateDataKey and kms:Decrypt shows in your AWS CloudTrail under the IAM role you provisioned, with our STS session name as deny-sh-byok-<tenant-prefix>. Cross-reference our hash-chained audit and your CloudTrail any time.