CloudHSM Credentials Rotation¶

Context¶

The CI pipeline accesses AWS CloudHSM via credentials stored in HashiCorp Vault at kv/data/ci/cloudhsm. These credentials must be rotated periodically (recommended: every 90 days).

Prerequisites¶

• Vault token with write access to kv/data/ci/cloudhsm
• AWS IAM access to create/rotate access keys for the CloudHSM service account
• The seed-cloudhsm.sh script (scripts/vault/seed-cloudhsm.sh)

Steps¶

1. Generate new AWS credentials¶

# In AWS Console or via CLI:
aws iam create-access-key --user-name probatiovault-cloudhsm-ci
# Note the new AccessKeyId and SecretAccessKey

2. Update Vault secret¶

# Option A: Interactive
export VAULT_ADDR="https://vault.dev.probatiovault.com"
export VAULT_TOKEN="hvs...."
./scripts/vault/seed-cloudhsm.sh seed

# Option B: From environment variables
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
./scripts/vault/seed-cloudhsm.sh seed --from-env

3. Verify the new credentials¶

./scripts/vault/seed-cloudhsm.sh verify

4. Validate CI pipeline¶

# Trigger a pipeline to verify CloudHSM access works
git commit --allow-empty -m "chore: trigger pipeline after CloudHSM credential rotation"
git push

5. Delete old AWS credentials¶

# Only after confirming the pipeline works with new credentials
aws iam delete-access-key --user-name probatiovault-cloudhsm-ci --access-key-id AKIA_OLD_KEY

Rollback¶

If the new credentials don't work:

1. Re-seed Vault with the old credentials:

   export AWS_ACCESS_KEY_ID="AKIA_OLD..."
   export AWS_SECRET_ACCESS_KEY="..."
   ./scripts/vault/seed-cloudhsm.sh seed --from-env
   

2. Verify: ./scripts/vault/seed-cloudhsm.sh verify
3. Delete the broken new key in AWS IAM

Verification¶

Run the full config validation:

export VAULT_ADDR="https://vault.dev.probatiovault.com"
export VAULT_TOKEN="hvs...."
./ansible/scripts/validate-config-fail-closed.sh --aws

Expected output:

[AWS credentials (from Vault kv/data/ci/cloudhsm)]
  OK: aws_access_key_id is present
  OK: aws_access_key_id format
  OK: aws_secret_access_key is present
  OK: aws_secret_access_key format

Vault Policy¶

The GitLab CI JWT role gitlab-ci-dev has read access via policy gitlab-ci-cloudhsm:

path "kv/data/ci/cloudhsm" {
  capabilities = ["read"]
}

Policy file: vault/policies/gitlab-ci-cloudhsm.hcl

Schedule¶