Materials providers

Functions
struct aws_cryptosdk_cmm *	aws_cryptosdk_default_cmm_new (struct aws_allocator *alloc, struct aws_cryptosdk_keyring *kr)
int	aws_cryptosdk_default_cmm_set_alg_id (struct aws_cryptosdk_cmm *cmm, enum aws_cryptosdk_alg_id alg_id)
void	aws_cryptosdk_cmm_release (struct aws_cryptosdk_cmm *cmm)
struct aws_cryptosdk_cmm *	aws_cryptosdk_cmm_retain (struct aws_cryptosdk_cmm *cmm)
void	aws_cryptosdk_keyring_release (struct aws_cryptosdk_keyring *keyring)
struct aws_cryptosdk_keyring *	aws_cryptosdk_keyring_retain (struct aws_cryptosdk_keyring *keyring)
struct aws_cryptosdk_keyring *	aws_cryptosdk_multi_keyring_new (struct aws_allocator *alloc, struct aws_cryptosdk_keyring *generator)
int	aws_cryptosdk_multi_keyring_add_child (struct aws_cryptosdk_keyring *multi, struct aws_cryptosdk_keyring *child)
bool	aws_cryptosdk_multi_keyring_is_valid (struct aws_cryptosdk_keyring *multi)

Detailed Description

The behavior of the encryption SDK is largely defined by two types of materials providers - the Crypto Materials Managers (CMMs) and Keyrings. In order to perform an encryption or decryption operation, the Session APIs must be given a CMM, which will typically be configured to delegate to one or more keyrings to perform the key wrapping or unwrapping operation.

Broadly speaking, you can think of a keyring as defining the underlying keys used to encrypt and decrypt (and therefore, who has access to the final message), while CMMs can perform higher-level manipulations on the overall encrypt/decrypt operation (such as caching the results of invoking the keyring).

CMM and keyring objects are reference counted to make it easier to construct higher-level CMMs or keyrings out of other primitives; in general, functions in the encryption SDK which take a CMM or keyring as an argument will appropriately increment the reference count (and decrement it when they no longer have a reference). When this reference count reaches zero, the CMM or keyring will be destroyed.

All CMMs and keyrings provided as built-ins are thread-safe with respect to the API they expose to the session; however, any configuration APIs that are specific to the type of CMM or keyring in question may not be thread safe (that is, you can't safely change the configuration while using the CMM or keyring on another thread's session object).

Function Documentation

aws_cryptosdk_cmm_release()

void aws_cryptosdk_cmm_release

(

struct aws_cryptosdk_cmm *

cmm

)

Decrements the reference count on the CMM. If the new reference count is zero, the CMM is destroyed.

Definition at line 449 of file materials.h.

aws_cryptosdk_cmm_retain()

struct aws_cryptosdk_cmm * aws_cryptosdk_cmm_retain

(

struct aws_cryptosdk_cmm *

cmm

)

Increments the reference count on the CMM.

Definition at line 460 of file materials.h.

aws_cryptosdk_default_cmm_new()

struct aws_cryptosdk_cmm * aws_cryptosdk_default_cmm_new	(	struct aws_allocator *	alloc,
		struct aws_cryptosdk_keyring *	kr )

Instantiate the default (non-caching) implementation of the Crypto Materials Manager (CMM). A Keyring must have already been instantiated and a pointer to it passed in. This CMM implements all of the CMM virtual functions.

On each call to Generate Encryption Materials, it makes a call to the keyring's On Encrypt function to generate and encrypt a data key. If an algorithm suite that does not include signing is used, this is the only thing that the Generate Encryption Materials does. If an algorithm suite that does include signing is used, then the call additionally begins the calculation of the trailing signature, which will be completed by the session.

On each call to Decrypt Materials, it passes the full list of EDKs to the keyring and asks it to find one to decrypt, via the keyring's On Decrypt function. If an algorithm suite that does not include signing is used, this is the only thing that the Decrypt Materials call does. If an algorithm suite that does include signing is used, then the call additionally begins the verification of the trailing signature, which will be completed by the session.

If a CMM that delegates to the default CMM selects an algorithm suite, that algorithm suite will be used. Otherwise, the default CMM will select a default algorithm suite. This is initially ALG_AES256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 or ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384, depending on the session's configured key commitment policy, but can be overridden using aws_cryptosdk_default_cmm_set_alg_id.

On success allocates a CMM and returns a pointer to it. Be sure to call aws_cryptosdk_cmm_release when you are done using the pointer so that the memory is properly deallocated.

On failure returns NULL and sets an internal AWS error code.

aws_cryptosdk_default_cmm_set_alg_id()

int aws_cryptosdk_default_cmm_set_alg_id	(	struct aws_cryptosdk_cmm *	cmm,
		enum aws_cryptosdk_alg_id	alg_id )

Selects the algorithm suite ID to use for encryption. If not called, a reasonable default will be selected. Raises AWS_CRYPTOSDK_ERR_UNSUPPORTED_FORMAT if the algorithm suite ID is unknown.

aws_cryptosdk_keyring_release()

void aws_cryptosdk_keyring_release

(

struct aws_cryptosdk_keyring *

keyring

)

Decrements the reference count on the keyring; if the new reference count is zero, the keyring is destroyed.

Definition at line 602 of file materials.h.

aws_cryptosdk_keyring_retain()

struct aws_cryptosdk_keyring * aws_cryptosdk_keyring_retain

(

struct aws_cryptosdk_keyring *

keyring

)

Increments the reference count on the keyring.

Definition at line 613 of file materials.h.

aws_cryptosdk_multi_keyring_add_child()

int aws_cryptosdk_multi_keyring_add_child	(	struct aws_cryptosdk_keyring *	multi,
		struct aws_cryptosdk_keyring *	child )

Adds a new child keyring to this multi-keyring. Child keyrings are only used to encrypt or decrypt a data key, not to generate new data keys. Do not add the generator keyring as a child keyring. This will result in generated data keys getting encrypted twice by that keyring, which is useless.

This operation is not threadsafe. If this is called at the same time as the multi-keyring is used for encrypt or decrypt, it results in undefined behavior.

It is not possible to remove a keyring from the multi-keyring at this time.

aws_cryptosdk_multi_keyring_is_valid()

bool aws_cryptosdk_multi_keyring_is_valid

(

struct aws_cryptosdk_keyring *

multi

)

Constant time check of data-structure invariants for struct multi_keyring.

aws_cryptosdk_multi_keyring_new()

struct aws_cryptosdk_keyring * aws_cryptosdk_multi_keyring_new	(	struct aws_allocator *	alloc,
		struct aws_cryptosdk_keyring *	generator )

Creates a new multi-keyring. This keyring allows you to combine keyrings into a single keyring. When used for encryption, the resulting document can be decrypted by any of the included keyrings. When used for decryption, the multi- keyring will attempt to decrypt using each of the included keyrings.

The second argument provided to the constructor is this multi-keyring's generator keyring, which is the first keyring it will call on encryption and decryption attempts, when it is set.

You may create a multi-keyring with no generator by setting the argument to NULL. If a generator is not set, the multi-keyring may be used for decryption or for encryption after another keyring has already generated a data key, (for example, as a child keyring of another multi-keyring.) However, a multi-keyring with no generator is not usable for encryption on its own.

Calling the multi-keyring's On Encrypt method does the following:

(1) Call the generator's On Encrypt method, if a generator has been set. If the generator's On Encrypt method fails, the multi-keyring's On Encrypt fails immediately, and the error code will be set by the generator keyring.

(2) Verify that an unencrypted data key has been generated, setting an error code of AWS_CRYPTOSDK_ERR_BAD_STATE and failing if it has not.

(3) Call the child keyrings' On Encrypt methods, producing a list of EDKs that are all encrypted versions of the data key verified in step (2). If any of the child keyring's On Encrypt methods fail, the multi-keyring's On Encrypt method will fail immediately, and the error code will be set by the failing child keyring.

(4) If all previous calls have succeeded, return the unencrypted data key and append all EDKs to the list provided by the caller.

The multi-keyring's On Decrypt call will attempt to decrypt an EDK with the generator (if one is set) and then each child keyring until it succeeds. Errors from any keyrings will not stop it from proceeding to the rest. If it succeeds in decrypting an EDK, it will return AWS_OP_SUCCESS, even if one or more of the keyrings failed. If it does not succeed in decrypting an EDK, it will return AWS_OP_SUCCESS if there were no errors, and AWS_OP_ERR if there were errors. As with all On Decrypt calls, check unencrypted_data_key.buffer to see whether an EDK was decrypted.