Skip to content
Verbitas Docs

Bring Your Own KMS

Bring Your Own KMS

BYOK (Bring Your Own Key) lets you use your own AWS KMS key for Verbitas signing operations. Your private key never leaves your AWS account. Verbitas’s signer service uses your key via an IAM role you grant access to.

BYOK requires the Enterprise BYOK plan. Contact [email protected] to enable it.

How BYOK works

In the standard configuration, Verbitas manages the signing key in its own AWS KMS account (eu-central-1). With BYOK:

  1. You create an asymmetric KMS key in your AWS account.
  2. You grant Verbitas’s signer IAM role kms:Sign and kms:GetPublicKey on that key.
  3. You configure your recipe with kms_mode: byok and provide the key ARN.
  4. All subsequent sign calls using that recipe use your key.

Your key is used only for its intended cryptographic operation: signing canonical C2PA claim digests. The signer validates the digest structure before calling KMS. It is not a generic signing oracle.

Step 1: Create an asymmetric KMS key

In your AWS account:

Terminal window
aws kms create-key \
  --key-usage SIGN_VERIFY \
  --key-spec ECC_NIST_P256 \
  --description "Verbitas BYOK signing key" \
  --region eu-central-1

Note the KeyArn from the output:

arn:aws:kms:eu-central-1:123456789012:key/mrk-1234abcd...

For multi-region key resilience, use --multi-region to create an MRK.

Step 2: Grant Verbitas signer role access

Get the Verbitas signer IAM role ARN from the admin console at https://verbitas.io/admin/settings/byok.

Create a KMS key policy granting the signer role access:

{
  "Sid": "AllowVerbitasSigner",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::VERBITAS_AWS_ACCOUNT:role/verbitas-signer-prod"
  },
  "Action": [
    "kms:Sign",
    "kms:GetPublicKey"
  ],
  "Resource": "*"
}

Apply the policy:

Terminal window
aws kms put-key-policy \
  --key-id arn:aws:kms:eu-central-1:123456789012:key/mrk-1234abcd... \
  --policy-name default \
  --policy file://key-policy.json \
  --region eu-central-1

Grant only kms:Sign and kms:GetPublicKey. Do not grant kms:GenerateDataKey, kms:Decrypt, or any other permission.

Step 3: Register the key ARN in Verbitas

Terminal window
curl -X POST https://api.verbitas.io/v1/keys \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "byok_aws_kms",
    "key_arn": "arn:aws:kms:eu-central-1:123456789012:key/mrk-1234abcd...",
    "description": "My BYOK signing key"
  }'

Response:

{
  "key_id": "vbk_01j...",
  "type": "byok_aws_kms",
  "key_arn": "arn:aws:kms:eu-central-1:123456789012:key/mrk-1234abcd...",
  "status": "validating"
}

Verbitas calls kms:GetPublicKey to verify the grant works. The status changes to active within a few seconds.

Step 4: Create a recipe with kms_mode byok

id: my-byok-recipe-v1
version: 1
extends: enterprise-strict-v1@1
media_type: image
description: Enterprise signing with BYOK KMS
c2pa:
  enabled: true
  assertions: [ai_generated, generator, model, created_at, legal_entity]
watermark:
  enabled: true
  engine: trustmark
soft_binding:
  enabled: true
  methods: [exact_watermark, perceptual_hash]
anchoring:
  enabled: true
  methods: [opentimestamps, arbitrum]
kms_mode: byok
retention:
  manifest_days: 2555
billing:
  meter: image_sign
  unit: asset
Terminal window
curl -X POST https://api.verbitas.io/v1/recipes \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @my-byok-recipe-v1.yaml

Step 5: Sign with your BYOK recipe

result = client.sign(
    "document.jpg",
    recipe="my-byok-recipe-v1",
    metadata={"legal_entity": "ACME Corp", "generator": "my-pipeline"}
)
print(result.verifier_url)

The C2PA manifest will contain the X.509 certificate from your KMS key. Verifiers see your organisation’s certificate.

Key rotation

When you rotate your KMS key, Verbitas automatically picks up the new key version. KMS key versioning is transparent to the signer. No action is required in Verbitas.

To use a completely different key ARN, register the new ARN via POST /v1/keys and update your recipe. Existing assets signed with the old key continue to verify against that key version.

Revoking access

To revoke Verbitas’s access, remove the key policy statement granting the signer role access. New sign calls using the BYOK recipe will fail with 503 verbitas.signer.unavailable.

Existing manifests remain verifiable. The signature is stored in the manifest and does not require re-contacting KMS to verify.

To deactivate a BYOK key in Verbitas without removing the AWS policy:

Terminal window
curl -X POST https://api.verbitas.io/v1/keys/vbk_01j.../deactivate \
  -H "Authorization: Bearer $VERBITAS_API_KEY"

Security constraints

  • apps/signer is the only Verbitas service that calls AWS KMS. No other service has AWS credentials.
  • The signer validates the digest is a canonical C2PA claim hash (32 bytes, correct structure) before calling KMS.
  • Your key policy is a customer-controlled layer on top of Verbitas’s own IAM policy.

Audit

All BYOK sign operations are recorded in the Verbitas audit log. AWS CloudTrail also logs every kms:Sign call made by the Verbitas signer role on your key.