Raw ECDH keyrings
Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the DynamoDB Encryption Client. |
Important
The Raw ECDH keyring is only available with version 1.5.0 of the Material Providers Library.
The Raw ECDH keyring uses the elliptic curve public-private 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 Diffie-Hellman (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 Database 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 keying material. To ensure that both parties use the correct keying material, the AWS Database 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 in the material description field of the encrypted record, the operation fails. For example, if you encrypt a record 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 record. If Bob's public key is from an AWS KMS key pair, then Bob can create an AWS KMS ECDH keyring to decrypt the record.
The Raw ECDH keyring encrypts records with a symmetric key using AES-GCM. The data key is then envelope encrypted with the derived shared wrapping key using AES-GCM. 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 multi-keyring.
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 Database 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 records.
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 PEM-encoded private key (PKCS #8 PrivateKeyInfo structures), as defined in RFC 5958
. -
Recipient's public key
You must provide the recipient's DER-encoded 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 records. To decrypt records 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 DER-encoded 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 Database 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 record where the specified key's public key matches the recipient's public key stored in the material description field of the encrypted record. This key agreement schema can only decrypt records.
Important
When you decrypt records 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 PEM-encoded 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