#include <kms_keyring.h>

Public Member Functions
Builder &	WithGrantToken (const Aws::String &grant_token)

Builder &	WithGrantTokens (const Aws::Vector< Aws::String > &grant_tokens)

Builder &	WithClientSupplier (const std::shared_ptr< ClientSupplier > &client_supplier)

Builder &	WithKmsClient (const std::shared_ptr< KMS::KMSClient > &kms_client)

aws_cryptosdk_keyring *	Build (const Aws::String &generator_key_id, const Aws::Vector< Aws::String > &additional_key_ids={}) const

aws_cryptosdk_keyring *	BuildDiscovery () const

aws_cryptosdk_keyring *	BuildDiscovery (std::shared_ptr< KmsKeyring::DiscoveryFilter > discovery_filter) const

Detailed Description

Helper class for building a new KmsKeyring object. You cannot construct a KmsKeyring directly and must use this class instead. This class is the only API you need to interact with KmsKeyrings. You will set all of the configuration of the KmsKeyring with this class before calling Build, and once the keyring is built, its configuration cannot be changed.

After the KmsKeyring is constructed, the only ways you should interact with the (aws_cryptosdk_keyring *) are to pass it to a CMM or another keyring (such as the multi-keyring) and to release the pointer with aws_cryptosdk_keyring_release.

For general documentation about keyrings see include/aws/cryptosdk/materials.h. This header will only document what is specific to the KmsKeyring.

Definition at line 64 of file kms_keyring.h.

Member Function Documentation

◆ Build()

aws_cryptosdk_keyring * Aws::Cryptosdk::KmsKeyring::Builder::Build	(	const Aws::String &	generator_key_id,
		const Aws::Vector< Aws::String > &	additional_key_ids = {} ) const

Creates a new KmsKeyring object or returns NULL if parameters are invalid.

You must specify at least one KMS CMK to use as a master key for encryption and decryption as the generator CMK. This CMK is the first one that will be used in all encryption and decryption attempts, and it is the only key for which you need to have KMS GenerateDataKey permissions in order to do encryption.

If this keyring is called for encryption after another keyring has already generated the data key (for example, in a multi-keyring) then the generator CMK will encrypt an existing data key. In that case, you will need KMS Encrypt permissions on this CMK.

Optionally, you may specify a list of additional CMKs to encrypt the data key with. Encrypting with multiple CMKs gives users who have KMS Decrypt access with any one of those CMKs the ability to decrypt the data. For encryption you will only need KMS Encrypt permission on the additional CMKs. You will NEVER need KMS GenerateDataKey permission on them.

Providing multiple CMKs for decryption allows the decryption of data that was encrypted using any of those keys. You will need KMS Decrypt permission on the generator CMK and all other CMKs.

Key IDs for encryption may be specified in two different ways:

(1) key ARN: arn:aws:kms:us-east-1:999999999999:key/01234567-89ab-cdef-fedc-ba9876543210 (2) alias ARN: arn:aws:kms:us-east-1:999999999999:alias/MyCryptoKey

Key IDs for decryption must be specified as key ARNs only, i.e., format (1) above. Format (2) will not work for decryption. The AWS Encryption SDK will allow you to attempt decrypts with a KmsKeyring configured with keys in format (2) without errors, but it will only succeed in decrypting data that was encrypted with keys that were specified in key ARN format. This is a limitation of the message format of encryption and of the KMS APIs, not of this library.

◆ BuildDiscovery() [1/2]

aws_cryptosdk_keyring * Aws::Cryptosdk::KmsKeyring::Builder::BuildDiscovery ( ) const

Creates a new KmsKeyring object with no KMS keys configured, i.e., in "discovery" mode. This means the following:

(1) This KmsKeyring will not do anything on encryption attempts. If you attempt encryption with this as your only keyring, it will fail. If you include this keyring as part of a multi-keyring and attempt encryption, the results will be the same as if this keyring was not included.

(2) On attempts to decrypt, the AWS Encryption SDK will attempt KMS DecryptDataKey calls for every KMS key that was used to encrypt the data until it finds one that you have permission to use. This may include calls to any region and to KMS keys that are outside of your account, unless prevented by policies on the IAM user or role.

◆ BuildDiscovery() [2/2]

aws_cryptosdk_keyring * Aws::Cryptosdk::KmsKeyring::Builder::BuildDiscovery ( std::shared_ptr< KmsKeyring::DiscoveryFilter > discovery_filter ) const

Creates a new KmsKeyring object in discovery mode (i.e., no KMS keys configured) but with a DiscoveryFilter. This means the following:

(1) As in discovery mode without a DiscoveryFilter, this KmsKeyring will not do anything on encryption attempts.

(2) On attempts to decrypt, the AWS Encryption SDK will attempt KMS DecryptDataKey calls for every KMS key that was used to encrypt the data until it finds one that:

(a) you have permission to use, and (b) that is in an account specified by the DiscoveryFilter.

This may include calls to any region, unless prevented by policies on the IAM user or role.

The discovery_filter argument must not be nullptr, or else this function fails and returns nullptr.

◆ WithClientSupplier()

Builder & Aws::Cryptosdk::KmsKeyring::Builder::WithClientSupplier ( const std::shared_ptr< ClientSupplier > & client_supplier )

Sets the object that supplies and caches KMSClient instances. This allows sharing of a client cache among multiple KMS keyrings. A client supplier which caches KMS clients only within this KMS keyring will be created by default if one is not provided.

◆ WithGrantToken()

Builder & Aws::Cryptosdk::KmsKeyring::Builder::WithGrantToken ( const Aws::String & grant_token )

Adds a single grant token. For more information, see http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token

May be called multiple times, adding additional grant tokens to the list that the keyring is configured with. Once a grant token is added to the builder, it is not removable. To build a KmsKeyring with a different set of grant tokens, use a different builder.

◆ WithGrantTokens()

Builder & Aws::Cryptosdk::KmsKeyring::Builder::WithGrantTokens ( const Aws::Vector< Aws::String > & grant_tokens )

Adds multiple grant tokens. For more information, see http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token

May be called multiple times, adding additional grant tokens to the list that the keyring is configured with. Once a grant token is added to the builder, it is not removable. To build a KmsKeyring with a different set of grant tokens, use a different builder.

◆ WithKmsClient()

Builder & Aws::Cryptosdk::KmsKeyring::Builder::WithKmsClient ( const std::shared_ptr< KMS::KMSClient > & kms_client )

KmsKeyring will use only this KMS Client. Note that this is only suitable if all KMS keys are in one region. If this is set then the client supplier parameter is ignored.

The documentation for this class was generated from the following file:

kms_keyring.h

Public Member Functions