Encryption keys (AWS KMS)

Everything ByoTalk keeps for an environment (the delivery buffer of recent messages, conversation metadata, credentials) is encrypted with that environment's own data key, using AES-256-GCM. By default ByoTalk wraps the data key with its own master key. You can wrap it with your AWS KMS key instead.

What changes

  • The data key is encrypted by your KMS key, and ByoTalk deletes its own wrapped copy. From then on, ByoTalk can only use the data key while your key allows it.
  • Disable, delete or restrict the key in AWS and, within 10 minutes, nobody can read this environment's data, including us. Requests that need it answer 503 storage_unavailable, and messages stop flowing for that environment until the key works again.
  • The data key itself does not change, so switching is instant and nothing is re-encrypted.
  • Every KMS request carries the encryption context {"byotalk:env": "<environment id>"}, which you can see and restrict in CloudTrail and in the key policy.
  • Your permanent record already lives in your own database and bucket; this covers what ByoTalk holds on its side.

Set it up

  1. In AWS KMS, create a symmetric key (or pick one) in any region.

  2. Create an IAM user with an access key and this policy (replace the ARN):

    {
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": ["kms:Encrypt", "kms:Decrypt"],
        "Resource": "arn:aws:kms:eu-central-1:123456789012:key/1234abcd-…",
        "Condition": { "StringLike": { "kms:EncryptionContext:byotalk:env": "env_*" } }
      }]
    }
    
  3. In the dashboard, open the environment's Settings → Encryption key, enter the key ARN, region and access key, and choose Use my KMS key. ByoTalk encrypts and decrypts the data key once to prove the key works before switching. You may be asked to sign in again: changing the key needs a recent sign-in.

Over the API (dashboard session):

PUT /v1/storage/kms
{ "provider": "aws", "keyId": "arn:aws:kms:…", "region": "eu-central-1", "accessKeyId": "AKIA…", "secretAccessKey": "…" }

Switch back

Switch back to a ByoTalk-managed key in the same card (or DELETE /v1/storage/kms). Your key has to work one last time so the data key can be unwrapped and wrapped with ours again.

Good to know

  • Each environment has its own key setting; production and development are configured separately.
  • Rotating the key in AWS (automatic key rotation) needs nothing from you.
  • To change access keys, switch back and set the key again, or save the same key ARN with new credentials.
  • Only AWS KMS is supported today.