Encryption & Secrets Management

Quick Navigation

1. AWS KMS - Key Management Service

KMS is the cryptographic backbone of AWS. It creates, stores, and controls access to customer managed keys (CMKs) backed by hardware security modules (HSMs). The key material never leaves the KMS service in plaintext. When you enable encryption on an S3 bucket, an EBS volume, or an RDS database, KMS is doing the key management work underneath every service call.

Envelope Encryption

KMS never encrypts large payloads directly. Instead it uses envelope encryption: KMS generates a short-lived data key, your application uses that key to encrypt the actual payload locally (fast, no size limit), and the data key itself is encrypted by the CMK and stored alongside the ciphertext. To decrypt, the process reverses. The CMK never leaves KMS, only the data key travels to your application, briefly.

Key Types

Create a CMK and an Alias

# Create a customer managed key (CMK)
aws kms create-key \
  --description "MyApp production encryption key" \
  --key-usage ENCRYPT_DECRYPT \
  --query 'KeyMetadata.{KeyId:KeyId,Arn:Arn}' \
  --output json

# Create a human-readable alias for the key
aws kms create-alias \
  --alias-name alias/myapp-prod \
  --target-key-id 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

{
    "KeyId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "Arn": "arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

Encrypt and Decrypt with boto3

import boto3, base64

kms = boto3.client("kms", region_name="us-east-1")
KEY_ID = "alias/myapp-prod"

# Encrypt a plaintext value
plaintext = "super-secret-value"
response = kms.encrypt(
    KeyId=KEY_ID,
    Plaintext=plaintext.encode(),
)
ciphertext_blob = response["CiphertextBlob"]
encoded = base64.b64encode(ciphertext_blob).decode()
print("Encrypted:", encoded[:40], "...")

# Decrypt - KMS infers the key from the ciphertext metadata
response = kms.decrypt(CiphertextBlob=ciphertext_blob)
recovered = response["Plaintext"].decode()
print("Decrypted:", recovered)

Encrypted: AQICAHh5...base64... ...
Decrypted: super-secret-value

Upload to S3 with SSE-KMS

import boto3

s3 = boto3.client("s3")
KEY_ARN = "arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-..."

# Upload an object with server-side encryption using your CMK
s3.put_object(
    Bucket="my-secure-bucket",
    Key="sensitive/report.json",
    Body=b'{"revenue": 1234567}',
    ServerSideEncryption="aws:kms",
    SSEKMSKeyId=KEY_ARN,
)

# Bucket-level default encryption (applied to all new objects)
s3.put_bucket_encryption(
    Bucket="my-secure-bucket",
    ServerSideEncryptionConfiguration={
        "Rules": [{
            "ApplyServerSideEncryptionByDefault": {
                "SSEAlgorithm": "aws:kms",
                "KMSMasterKeyID": KEY_ARN,
            }
        }]
    },
)

2. SSM Parameter Store

SSM Parameter Store is a hierarchical key-value store for application configuration and secrets. It organizes values in a path-based hierarchy such as /myapp/prod/db_host, which makes it easy to fetch an entire environment's config in a single API call and to enforce IAM access at the path level rather than per-parameter.

Parameter Types

Standard vs Advanced

Store Parameters

# Store a plaintext config value (free, Standard tier)
aws ssm put-parameter \
  --name "/myapp/prod/log_level" \
  --value "INFO" \
  --type String

# Store an encrypted secret (KMS-backed SecureString)
aws ssm put-parameter \
  --name "/myapp/prod/db_password" \
  --value "hunter2" \
  --type SecureString \
  --key-id "alias/myapp-prod"

# Overwrite an existing parameter with a new value
aws ssm put-parameter \
  --name "/myapp/prod/db_password" \
  --value "newpassword123" \
  --type SecureString \
  --key-id "alias/myapp-prod" \
  --overwrite

Retrieve Parameters in Python

import boto3

ssm = boto3.client("ssm", region_name="us-east-1")

# Fetch a single SecureString parameter (decrypted)
response = ssm.get_parameter(
    Name="/myapp/prod/db_password",
    WithDecryption=True,
)
password = response["Parameter"]["Value"]
print(password)

# Fetch every parameter under /myapp/prod/ in one call
response = ssm.get_parameters_by_path(
    Path="/myapp/prod/",
    WithDecryption=True,
    Recursive=True,
)
config = {
    p["Name"].split("/")[-1]: p["Value"]
    for p in response["Parameters"]
}
print(config)

hunter2
{'db_password': 'hunter2', 'log_level': 'INFO'}

3. AWS Secrets Manager

Secrets Manager is purpose-built for credential lifecycle management. It stores secrets as JSON blobs, encrypts them with KMS, and can automatically rotate credentials on a schedule by invoking a Lambda function that talks to the backing service (RDS, Redshift, DocumentDB, etc.) and updates the secret without requiring a redeployment of your application.

Automatic Rotation Flow

Rotation is a four-step Lambda lifecycle that Secrets Manager orchestrates. AWS provides built-in rotation Lambda templates for RDS MySQL, PostgreSQL, Redshift, and DocumentDB. You can write a custom Lambda for any other service following the same four-step interface.

Create a Secret

# Create a JSON secret for an RDS database
aws secretsmanager create-secret \
  --name "myapp/prod/rds-creds" \
  --description "RDS master credentials" \
  --secret-string '{
    "username": "admin",
    "password": "hunter2",
    "host": "db.cluster-abc.us-east-1.rds.amazonaws.com",
    "port": 5432,
    "dbname": "myapp"
  }'

Retrieve and Use a Secret in Python

import boto3, json

sm = boto3.client("secretsmanager", region_name="us-east-1")

# Retrieve the current secret value
response = sm.get_secret_value(SecretId="myapp/prod/rds-creds")
secret = json.loads(response["SecretString"])

# Use directly in your database connection
import psycopg2
conn = psycopg2.connect(
    host=secret["host"],
    port=secret["port"],
    dbname=secret["dbname"],
    user=secret["username"],
    password=secret["password"],
)
print("Connected to:", secret["host"])

Enable Automatic Rotation

# Enable automatic rotation every 30 days
# For RDS secrets, pass --rotation-lambda-arn with the ARN of the
# rotation Lambda AWS created when you set up the secret via the console,
# or use managed rotation (supported for RDS clusters and single-instance RDS).
aws secretsmanager rotate-secret \
  --secret-id "myapp/prod/rds-creds" \
  --rotation-lambda-arn "arn:aws:lambda:us-east-1:123456789012:function:SecretsManagerMyAppRDSRotation" \
  --rotation-rules '{"AutomaticallyAfterDays": 30}' \
  --rotate-immediately

# Check the current rotation status
aws secretsmanager describe-secret \
  --secret-id "myapp/prod/rds-creds" \
  --query 'RotationEnabled'

true

4. SSM Parameter Store vs Secrets Manager

Both services store KMS-encrypted secrets and integrate with IAM. The right choice depends on whether you need automatic rotation and how many secrets you manage.