//= aws-encryption-sdk-specification/framework/master-key-provider-interface.md#legacy
//= type=exception
//# This is a legacy specification.
//# Master key providers SHOULD NOT be included in any additional implementations.
//# Any new implementations MUST include [Keyrings](./keyring-interface.md) instead.

//= aws-encryption-sdk-specification/framework/master-key-provider-interface.md#consistency
//= type=exception
//# This specification defines the common behavior between the two implementations
//# that determine the REQUIRED functionality.

//= aws-encryption-sdk-specification/framework/master-key-provider-interface.md#terms
//= type=exception
//#- Provider ID: A value that identifies a master key provider.
//#  This concept is equivalent to "key namespace" for Keyrings.
//#- Key ID: A value that identifies a master key
//#  within the context of a master key provider.
//#  This concept is equivalent to "key name" for Keyrings.
//#- Provider Info: The value that is written to a serialized encrypted data key
//#  that identifies a master key within the context of a master key provider.
//#  This MUST always be equal to the master key's key ID
//#  with the exception of the raw AES master key.
//#  For a detailed description of this exception,
//#  see the [Raw AES Keyring specification](./raw-aes-keyring.md).

//= aws-encryption-sdk-specification/framework/master-key-provider-interface.md#get-master-key
//= type=exception
//# This interface provides a way for a master key provider to return master keys.
//# 
//# An implementation MUST support master key selection by key ID.
//# 
//# An implementation MAY support master key selection by provider info or provider ID.
//# 
//# The output of this interface MUST be a master key.
//# 
//# If the master key provider cannot locate an appropriate master key,
//# the call MUST result in an error.

//= aws-encryption-sdk-specification/framework/master-key-provider-interface.md#get-master-keys-for-encryption
//= type=exception
//# This interface provides a way for a master key provider to indicate which master keys
//# SHOULD be used for encryption.
//# 
//# Inputs to this interface MUST include the encryption context.
//# 
//# Inputs MAY include the plaintext body and plaintext size.
//# 
//# The output of this interface MUST include a list of all master keys that
//# SHOULD be used for encryption.
//# 
//# The output of this interface MUST indicate which one of those master keys
//# MUST be used to generate the data key.

//= aws-encryption-sdk-specification/framework/master-key-provider-interface.md#decrypt-data-key
//= type=exception
//# This interface is used to decrypt a data key.
//# 
//# The master key provider SHOULD attempt to decrypt the data key
//# by passing the request to any master keys that it has access to
//# until it has either exhausted available master keys
//# or obtained a plaintext data key.
//# 
//# Inputs to this interface MUST include
//# the algorithm suite,
//# the encryption context,
//# and a list of encrypted data keys.
//# 
//# The output of this interface MUST include
//# the decrypted data key
//# and information that can identify which master key
//# decrypted the data key.
//# 
//# If the master key provider cannot decrypt the data key,
//# the call MUST result in an error.