Raw ECDH keyrings
Important
The Raw ECDH keyring is only available with version 4.x of the AWS Encryption SDK for .NET and version 3.x of the AWS Encryption SDK for Java. The Raw ECDH keyring is introduced in version 1.5.0 of the Material Providers Library.
The Raw ECDH keyring uses the elliptic curve publicprivate key pairs that you
provide to derive a shared wrapping key between two parties. First, the keyring
derives a shared secret using the sender's private key, the recipient's public key,
and the Elliptic Curve DiffieHellman (ECDH) key agreement algorithm. Then, the
keyring uses the shared secret to derive the shared wrapping key that protects your
data encryption keys. The key derivation function that the AWS Encryption SDK uses
(KDF_CTR_HMAC_SHA384
) to derive the shared wrapping key conforms to
NIST recommendations for key derivation
The key derivation function returns 64 bytes of key material. To ensure that both parties use the correct key material, the AWS Encryption SDK uses the first 32 bytes as a commitment key and the last 32 bytes as the shared wrapping key. On decrypt, if the keyring cannot reproduce the same commitment key and shared wrapping key that is stored on the message header ciphertext, the operation fails. For example, if you encrypt data with a keyring configured with Alice's private key and Bob's public key, a keyring configured with Bob's private key and Alice's public key will reproduce the same commitment key and shared wrapping key and be able to decrypt the data. If Bob's public key is from an AWS KMS key pair, then Bob can create an AWS KMS ECDH keyring to decrypt the data.
The Raw ECDH keyring encrypts data with a symmetric key using AESGCM. The data key is then envelope encrypted with the derived shared wrapping key using AESGCM. Each Raw ECDH keyring can have only one shared wrapping key, but you can include multiple Raw ECDH keyrings, alone or with other keyrings, in a multikeyring.
You are responsible for generating, storing, and protecting your private keys, preferably in a hardware security module (HSM) or key management system. The sender and recipient's key pairs much be on the same elliptic curve. The AWS Encryption SDK supports the following elliptic cuve specifications:

ECC_NIST_P256

ECC_NIST_P384

ECC_NIST_P512
Creating a Raw ECDH keyring
The Raw ECDH keyring supports three key agreement schemas:
RawPrivateKeyToStaticPublicKey
,
EphemeralPrivateKeyToStaticPublicKey
, and
PublicKeyDiscovery
. The key agreement schema that you select
determines which cryptographic operations you can perform and how the keying
materials are assembled.
RawPrivateKeyToStaticPublicKey
Use the RawPrivateKeyToStaticPublicKey
key agreement schema
to statically configure the sender's private key and the recipient's public
key in the keyring. This key agreement schema can encrypt and decrypt
data.
To initialize a Raw ECDH keyring with the
RawPrivateKeyToStaticPublicKey
key agreement schema,
provide the following values:

Sender's private key
You must provide the sender's PEMencoded private key (PKCS #8 PrivateKeyInfo structures), as defined in RFC 5958
. 
Recipient's public key
You must provide the recipient's DERencoded X.509 public key, also known as
SubjectPublicKeyInfo
(SPKI), as defined in RFC 5280. You can specify the public key of an asymmetric key agreement KMS key pair or the public key from a key pair generated outside of AWS.

Curve specification
Identifies the elliptic curve specification in the specified key pairs. Both the sender and recipient's key pairs must have the same curve specification.
Valid values:
ECC_NIST_P256
,ECC_NIS_P384
,ECC_NIST_P512
EphemeralPrivateKeyToStaticPublicKey
Keyrings configured with the
EphemeralPrivateKeyToStaticPublicKey
key agreement schema
create a new key pair locally and derive a unique shared wrapping key for
each encrypt call.
This key agreement schema can only encrypt messages. To decrypt messages
encrypted with the EphemeralPrivateKeyToStaticPublicKey
key
agreement schema, you must use a discovery key agreement schema configured
with the same recipient's public key. To decrypt, you can use a Raw ECDH
keyring with the PublicKeyDiscovery key agreement algorithm, or,
if the recipient's public key is from an asymmetric key agreement KMS key
pair, you can use an AWS KMS ECDH keyring with the KmsPublicKeyDiscovery key agreement
schema.
To initialize a Raw ECDH keyring with the
EphemeralPrivateKeyToStaticPublicKey
key agreement schema,
provide the following values:

Recipient's public key
You must provide the recipient's DERencoded X.509 public key, also known as
SubjectPublicKeyInfo
(SPKI), as defined in RFC 5280. You can specify the public key of an asymmetric key agreement KMS key pair or the public key from a key pair generated outside of AWS.

Curve specification
Identifies the elliptic curve specification in the specified public key.
On encrypt, the keyring creates a new key pair on the specified curve and uses the new private key and specified public key to derive a shared wrapping key.
Valid values:
ECC_NIST_P256
,ECC_NIS_P384
,ECC_NIST_P512
PublicKeyDiscovery
When decrypting, it's a best practice to specify the wrapping keys that the AWS Encryption SDK can use. To follow this best practice, use an ECDH keyring that specifies both a sender's private key and recipient's public key. However, you can also create a Raw ECDH discovery keyring, that is, a Raw ECDH keyring that can decrypt any message where the specified key's public key matches the recipient's public key stored on the message ciphertext. This key agreement schema can only decrypt messages.
Important
When you decrypt messages using the PublicKeyDiscovery
key agreement schema, you accept all public keys, regardless of who owns
it.
To initialize a Raw ECDH keyring with the PublicKeyDiscovery
key agreement schema, provide the following values:

Recipient's static private key
You must provide the recipient's PEMencoded private key (PKCS #8 PrivateKeyInfo structures), as defined in RFC 5958
. 
Curve specification
Identifies the elliptic curve specification in the specified private key. Both the sender and recipient's key pairs must have the same curve specification.
Valid values:
ECC_NIST_P256
,ECC_NIS_P384
,ECC_NIST_P512