awskms
seal
The AWS KMS seal configures OpenBao to use AWS KMS as the seal wrapping mechanism. The AWS KMS seal is activated by one of the following:
- The presence of a
seal "awskms"
block in OpenBao's configuration file - The presence of the environment variable
VAULT_SEAL_TYPE
set toawskms
. If enabling via environment variable, all other required values specific to AWS KMS (i.e.VAULT_AWSKMS_SEAL_KEY_ID
) must be also supplied, as well as all other AWS-related environment variables that lends to successful authentication (i.e.AWS_ACCESS_KEY_ID
, etc.).
awskms
example
This example shows configuring AWS KMS seal through the OpenBao configuration file by providing all the required values:
seal "awskms" {
region = "us-east-1"
access_key = "AKIAIOSFODNN7EXAMPLE"
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}
awskms
parameters
These parameters apply to the seal
stanza in the OpenBao configuration file:
-
region
(string: "us-east-1")
: The AWS region where the encryption key lives. If not provided, may be populated from theAWS_REGION
orAWS_DEFAULT_REGION
environment variables, from your~/.aws/config
file, or from instance metadata. -
access_key
(string: <required>)
: The AWS access key ID to use. May also be specified by theAWS_ACCESS_KEY_ID
environment variable or as part of the AWS profile from the AWS CLI or instance profile. -
session_token
(string: "")
: Specifies the AWS session token. This can also be provided via the environment variableAWS_SESSION_TOKEN
. -
secret_key
(string: <required>)
: The AWS secret access key to use. May also be specified by theAWS_SECRET_ACCESS_KEY
environment variable or as part of the AWS profile from the AWS CLI or instance profile. -
kms_key_id
(string: <required>)
: The AWS KMS key ID or ARN to use for encryption and decryption. May also be specified by theVAULT_AWSKMS_SEAL_KEY_ID
environment variable. An alias in the formatalias/key-alias-name
may also be used here. -
disabled
(string: "")
: Set this totrue
if OpenBao is migrating from an auto seal configuration. Otherwise, set tofalse
. -
endpoint
(string: "")
: The KMS API endpoint to be used to make AWS KMS requests. May also be specified by theAWS_KMS_ENDPOINT
environment variable. This is useful, for example, when connecting to KMS over a VPC Endpoint. If not set, OpenBao will use the default API endpoint for your region.
Refer to the Seal Migration documentation for more information about the seal migration process.
Authentication
Authentication-related values must be provided, either as environment variables or as configuration parameters.
Note: Although the configuration file allows you to pass in
AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
as part of the seal's parameters, it
is strongly recommended to set these values via environment variables.
AWS authentication values:
AWS_REGION
orAWS_DEFAULT_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
Note: The client uses the official AWS SDK and will use the specified credentials, environment credentials, shared file credentials, or IAM role/ECS task credentials in that order, if the above AWS specific values are not provided.
OpenBao needs the following permissions on the KMS key:
kms:Encrypt
kms:Decrypt
kms:DescribeKey
These can be granted via IAM permissions on the principal that OpenBao uses, on the KMS key policy for the KMS key, or via KMS Grants on the key.
awskms
environment variables
Alternatively, the AWS KMS seal can be activated by providing the following environment variables.
OpenBao Seal specific values:
VAULT_SEAL_TYPE
VAULT_AWSKMS_SEAL_KEY_ID
Key rotation
This seal supports rotating the root keys defined in AWS KMS doc. Both automatic rotation and manual rotation is supported for KMS since the key information is stored with the encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data. Any new or updated data will be encrypted with the current key defined in the seal configuration or set to current under a key alias.