Subchapter 72.3
references/byok-kms.mdMarkdown7 KBView on GitHub
Source:
04-db2-client/bring-your-own-key/bring-your-own-kms-key-for-rds-for-db2.md(blog DBBLOG-5188). Commands and option names are reproduced from that source; no secret values, credentials, or customer IDs are included — replace every .
<placeholder>RDS for Db2 encrypts at rest with AWS KMS. BYOK lets you import your own key material into a customer-managed KMS key so you control the key, meet key-management compliance, keep a CloudTrail audit trail, and reuse the same key material across Regions for disaster recovery. Always create the instance encrypted (encryption at rest cannot be added in place — see migration below).
Prerequisites: AWS CLI, OpenSSL, jq, and a valid IBM Customer ID + Site ID for BYOL.
export HOME_REGION=<region>
export DR_REGION=<dr-region>
export KEY_ALIAS=alias/byok-db2
export DB_INSTANCE_ID=<db-instance-id>
export SUBNET_GROUP=<subnet-group>
export SG_ID=<sg-id>
export IBM_CUSTOMER_ID=<IBM_CUSTOMER_ID> # rds.ibm_customer_id
export IBM_SITE_ID=<IBM_SITE_ID> # rds.ibm_site_idA multi-region key (MRK) keeps the same key ID/material when replicated to a DR Region.
aws kms create-key --region $HOME_REGION \
--origin EXTERNAL --key-usage ENCRYPT_DECRYPT --key-spec SYMMETRIC_DEFAULT \
--multi-region --description "BYOK for RDS Db2" \
--query KeyMetadata.KeyId --output text | tee KEY_ID.txt
export KEY_ID=$(cat KEY_ID.txt)
aws kms create-alias --region $HOME_REGION \
--alias-name $KEY_ALIAS --target-key-id $KEY_IDaws kms get-parameters-for-import --region $HOME_REGION --key-id $KEY_ID \
--wrapping-algorithm RSAES_OAEP_SHA_256 --wrapping-key-spec RSA_2048 \
--query '{PublicKey:PublicKey,ImportToken:ImportToken}' --output json > import-params.json
jq -r .PublicKey import-params.json | base64 --decode > wrappingKey.der
jq -r .ImportToken import-params.json | base64 --decode > importToken.bin
openssl pkey -inform DER -pubin -in wrappingKey.der -out wrappingKey.pemopenssl rand -out keyMaterial.bin 32 # your own 256-bit key material
openssl pkeyutl -encrypt -inkey wrappingKey.pem -pubin \
-in keyMaterial.bin -out encryptedKeyMaterial.bin \
-pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256
aws kms import-key-material --region $HOME_REGION --key-id $KEY_ID \
--encrypted-key-material fileb://encryptedKeyMaterial.bin \
--import-token fileb://importToken.bin \
--expiration-model KEY_MATERIAL_DOES_NOT_EXPIREImport tokens expire after 24 hours. If import fails, re-run
get-parameters-for-import.
aws kms replicate-key --region $HOME_REGION --key-id $KEY_ID \
--replica-region $DR_REGION \
--query ReplicaKeyMetadata.Arn --output text | tee REPLICA_ARN.txt
export REPLICA_ARN=$(cat REPLICA_ARN.txt)
aws kms create-alias --region $DR_REGION \
--alias-name $KEY_ALIAS --target-key-id $REPLICA_ARNThe principal creating the instance needs, on the key:
kms:CreateGrant — lets RDS create a grant to use the keykms:DescribeKey — lets RDS read key metadataUse a least-privilege IAM policy (no *FullAccess); trust the account root in the key policy and
let RDS use the grant created at instance creation. Inspect grants with
aws kms list-grants --key-id $KEY_ID --region $HOME_REGION.
export PG_FAMILY=<db2-se-x.y|db2-ae-x.y>
export PG_NAME=db2-se-byol-params
aws rds create-db-parameter-group --region $HOME_REGION \
--db-parameter-group-name $PG_NAME --db-parameter-group-family $PG_FAMILY \
--description "BYOL: IBM IDs for RDS Db2"
aws rds modify-db-parameter-group --region $HOME_REGION \
--db-parameter-group-name $PG_NAME --parameters \
"ParameterName=rds.ibm_customer_id,ParameterValue=$IBM_CUSTOMER_ID,ApplyMethod=pending-reboot" \
"ParameterName=rds.ibm_site_id,ParameterValue=$IBM_SITE_ID,ApplyMethod=pending-reboot"Encryption at rest is set at creation with the customer-managed KMS key. Use
--manage-master-user-password (RDS stores and rotates the credential in Secrets Manager)
rather than an inline plaintext password.
aws rds create-db-instance --region $HOME_REGION \
--db-instance-identifier $DB_INSTANCE_ID \
--engine db2-se --engine-version <engine-version> \
--db-instance-class db.r7i.xlarge --allocated-storage 100 --storage-type gp3 \
--master-username db2inst1 --manage-master-user-password \
--vpc-security-group-ids $SG_ID --db-subnet-group-name $SUBNET_GROUP \
--storage-encrypted --kms-key-id $KEY_ALIAS \
--license-model bring-your-own-license \
--db-parameter-group-name $PG_NAME--storage-encrypted --kms-key-id binds the instance to your KMS key. BYOL requires the parameter
group with IBM IDs.
Encryption cannot be toggled in place — re-encrypt through a snapshot:
# 1) snapshot the unencrypted DB
aws rds create-db-snapshot --region $HOME_REGION \
--db-instance-identifier $DB_INSTANCE_ID \
--db-snapshot-identifier ${DB_INSTANCE_ID}-plain-snap
# 2) copy the snapshot, encrypting with your key
aws rds copy-db-snapshot --region $HOME_REGION \
--source-db-snapshot-identifier ${DB_INSTANCE_ID}-plain-snap \
--target-db-snapshot-identifier ${DB_INSTANCE_ID}-enc-snap \
--kms-key-id $KEY_ALIAS
# 3) restore a new encrypted DB
aws rds restore-db-instance-from-db-snapshot --region $HOME_REGION \
--db-instance-identifier ${DB_INSTANCE_ID}-enc \
--db-snapshot-identifier ${DB_INSTANCE_ID}-enc-snap \
--db-subnet-group-name $SUBNET_GROUP --vpc-security-group-ids $SG_IDUse the DR replica key as the target --kms-key-id:
aws rds copy-db-snapshot \
--source-region $HOME_REGION --region $DR_REGION \
--source-db-snapshot-identifier \
arn:aws:rds:$HOME_REGION:<account-id>:snapshot:${DB_INSTANCE_ID}-enc-snap \
--target-db-snapshot-identifier ${DB_INSTANCE_ID}-enc-snap-dr \
--kms-key-id <alias|arn>| Symptom | Cause / fix |
|---|---|
import-key-material fails | Import token expired (24h). Re-run get-parameters-for-import and re-wrap. |
| Permission errors at create | Role lacks kms:CreateGrant / kms:DescribeKey, or key policy blocks the action. |
| Cross-region copy fails | Replica key missing in target Region, or wrong --kms-key-id alias/ARN. |
Considerations: multi-region keys bill per Region; enable CloudTrail on KMS operations; store your original key material securely for recovery.