Configuration¶
VaultSDK(...) constructor¶
VaultSDK(
server_url: str = "https://cps-vault.commandcentral.com",
aws_profile: str | None = None,
aws_access_key_id: str | None = None,
aws_secret_access_key: str | None = None,
region: str = "us-east-1",
kms_key_alias: str | None = None,
timeout: float = 10.0,
max_retries: int = 2,
sts_region: str = "us-east-1",
)
| Parameter | Type | Default | Description |
|---|---|---|---|
server_url |
str |
"https://cps-vault.commandcentral.com" |
Base URL of the CPS-Vault server to talk to (the API Gateway custom domain). |
aws_profile |
str \| None |
None |
Named AWS CLI profile to sign requests and perform KMS operations with. If omitted, falls back to the default boto3 credential resolution chain (environment variables, instance/task role, SSO, etc). |
aws_access_key_id |
str \| None |
None |
Explicit AWS access key, if not using a profile or the default chain. |
aws_secret_access_key |
str \| None |
None |
Explicit AWS secret key, paired with aws_access_key_id. |
region |
str |
"us-east-1" |
AWS region used for KMS operations. |
kms_key_alias |
str \| None |
"alias/cps-vault-key" |
KMS key alias used for client-side envelope encryption. The alias/ prefix is added automatically if omitted. If no key with this alias exists yet in the caller's account, one is created automatically on first use. |
timeout |
float |
10.0 |
Per-request HTTP timeout (seconds) for calls to the server. |
max_retries |
int |
2 |
Automatic retries for transient HTTP failures (connection errors, 429/502/503/504). Applies to all request methods; only raise this if a retried write being re-applied (in case the original request succeeded but its response was lost) is acceptable for your use case. |
sts_region |
str |
"us-east-1" |
Region whose STS endpoint the identity proof is signed for. This must be the region of the server's STS endpoint, so you normally never change it. Your own profile/session region is ignored for proofs, which is why callers in any AWS region (and any account) work without extra setup. |
Credential resolution order
Internally, the SDK always constructs a boto3.Session(profile_name=aws_profile,
aws_access_key_id=aws_access_key_id, aws_secret_access_key=aws_secret_access_key). If you pass
none of these three, this is equivalent to boto3.Session() and boto3's normal default
credential chain applies.
KMS key lifecycle¶
- The SDK resolves its KMS key lazily — nothing is created at construction time, only on the
first
create/put/fetchcall. - Resolution looks up an existing key by the configured alias in the caller's own AWS account
(
kms:DescribeKeyequivalent). If none exists, the SDK creates a new key and alias (kms:CreateKey+kms:CreateAlias). - Every
VaultSDKinstance using the samekms_key_alias(and the same underlying AWS account) shares the same physical key, so secrets encrypted by one instance/process can be decrypted by another with the same alias and sufficient IAM permissions. - Automatic rotation. When the SDK creates a new key, it also enables automatic annual key
rotation on it (
kms:EnableKeyRotationequivalent) — no action needed from you, and no impact on existing ciphertext, which continues to decrypt correctly against prior key material.
Choosing a kms_key_alias¶
Use a distinct alias per application/team if you want to scope KMS key policies (who can
decrypt) more narrowly than "everyone who can assume a role in this account." If omitted, all
callers in the same AWS account share the default alias/cps-vault-key.
Logging¶
The SDK logs under the cps_vault_sdk logger name (standard library logging). Enable debug
logging to see request timing (including KMS encrypt/decrypt duration):