feat(framework): add support for ECDH Keyring (#88) (#274)

Co-authored-by: seebees <ryanemer@amazon.com>
Co-authored-by: Lucas McDonald <lucasmcdonald3@gmail.com>

changes/2024-03-12_ecdh-keyring/background.md

@@ -0,0 +1,155 @@
+[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
+[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
+
+# Interacting with AWS KMS ECDH API using the AWS Cryptographic Material Providers Library (MPL) (Background)
+
+## Definitions
+
+### ECDH
+
+ECDH (Elliptic-curve Diffie–Hellman) is a key agreement protocol that
+allows two parties, each having an elliptic-curve public–private key
+pair, to establish a shared secret over an insecure channel.
+
+This shared secret may be directly used as a key, or to derive another key.
+
+### Conventions used in this document
+
+The key words
+"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
+in this document are to be interpreted as described in
+[RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+## Issues and Alternatives
+
+## Why is the MPL adding support for the ECDH API?
+
+The ECDH API will produce the cryptographic primitive shared secret
+that is calculated from the ECDH exchange between the sender's
+private key and the recipient's public key.
+
+Customers need an out of box solution that will "just work"
+with AWS Crypto Tools products such as the AWS Encryption SDK
+and the AWS Database Encryption SDK, without having to worry
+about using the shared secret correctly.
+
+## How is the MPL going to support this new ECDH operation?
+
+By introducing a new keyring that will accept a sender's
+private key and a recipient's public key, the keyring will
+be able to calculate the ECDH shared secret or delegate the
+operation to AWS KMS.
+
+Once a shared secret has been established, a plaintext
+shared wrapping key will be derived from the shared secret such that
+it can be used in hybrid encryption workflows.
+
+It is a common use case to derive a shared wrapping key
+from the shared secret. The derivation of a shared
+data key from a shared secret established by ECDH
+is specified by [NIST 800-56A 4.2](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf)
+
+## How many Keyrings does this feature require?
+
+Two keyrings will be introduced.
+
+- [Raw ECDH Keyring](../../framework/raw-ecdh-keyring.md)
+- [AWS KMS ECDH Keyring](../../framework/aws-kms/aws-kms-ecdh-keyring.md)
+
+## What kind of configurations can we expect if we plan on using an AWS KMS ECDH Keyring?
+
+The ECDH Keyrings have [schemas](../../framework/key-agreement-schemas.md) as part of their configurations.
+These schemas tell the keyring how the parties' ECC keys are presented.
+
+See each keyring's specification for their supported schemas.
+
+- [AWS KMS ECDH Keyring](../../framework/aws-kms/aws-kms-ecdh-keyring.md)
+- [Raw ECDH Keyring](../../framework/raw-ecdh-keyring.md)
+
+## How can customers know they are using the correct shared wrapping key for envelope encryption?
+
+In order to confirm that customers are using the correct shared wrapping key,
+we will provide a commitment key.
+
+Adding a commitment key allows the decrypting party to verify they
+are in possession of correct keying material.
+
+This also provides for future compatibility with other systems that
+also provide a commitment key. This key may be used
+as a key for key commitment, symmetric signature, key confirmation,
+or other protocol specific applications.
+
+As is, the keyring implementation cannot support key confirmation.
+In key confirmation you compare a MAC message as opposed to a commitment key.
+However; the cryptographic primitives exist in the library
+such that it is easy to add functionality to perform key confirmation.
+
+## How much entropy is used for the Key Derivation and for the data key wrapping?
+
+The keyrings will use a 32 byte random nonce
+every time a shared wrapping key is derived.
+Using a new 32 byte random value every time
+pretty much guarantees a unique shared wrapping key
+on every encrypt operation.
+
+This key is only ever used once in the keyrings.
+Due to this, we do need need to add an additional
+distinct random IV in the AES-GCM wrapping operation.
+This effectively means that there is no "built-in"
+support for a rotation. If you were to use the shared
+wrapping key for more than one encrypt operation, the IV
+in the AES GCM operation allows us to extend the "life" of the
+shared wrapping key by generating a unique random IV every time
+while the shared wrapping key is the same.
+
+We believe that our use case only needs to use the shared wrapping
+key once. However; if we ever need to support doing
+additional encryption operations with the shared wrapping key,
+we can distinguish that through the version value serialized
+in the key provider information.
+
+## Other Considerations
+
+1. Public Key Validation
+
+   1. Which Crypto Provider should do this? Is it in the threat model
+      to validate the correct construction of the public key such that its
+      parameters matches those of the sender's private key?
+
+1. Which Key Derivation Function should be supported?
+
+   1. KDF-CTR?
+      1. We will support KDF in Counter Mode as it is a KDF that is supported
+         by both Crypto Tools and AWS KMS.
+
+1. Which Key Derivation Methods (KDM) should be supported?
+   With any KDM, we MUST keep in mind that adding new support should be easy for customers.
+
+   1. Hash: Supporting a Hash based KDM is straightforward and most customers expect an easy default.
+   1. HMAC: HMAC may also be a suitable choice. We would have to keep in mind that not only do you need
+      HMAC functionality but you also need to support an approved hashing function.
+   1. KMAC: Crypto Tools hasn't had requests to support this method, so we can leave it off
+      the table; however it should be trivial and non-breaking to add in the future.
+
+1. How many Keyrings does this feature require?
+
+   1. This feature _could_ fit all in one keyring. Following the
+      team's precedent, splitting them into a "Raw" and a "AwsKMS" Keyring makes
+      the most sense.
+
+1. ECDH Hierarchy Keyring
+   1. Crypto Tools has introduced the AWS KMS Hierarchical Keyring as an option
+      to reduce KMS network calls every encrypt and decrypt to every "x" minutes.
+      This plays nicely with customers that want KMS security without having to
+      call KMS every time. The hierarchy keyring does this by creating a key hierarchy
+      where one KMS key sits at the top and customers protect data under that key by
+      deriving data keys from the KMS key.
+   1. For customer that want to go even faster having an ECDH Hierarchy Keyring can
+      be an attractive option. Consider the following; you have "n" hosts, each call KMS
+      to get an ECC KeyPair. Out of those "n" hosts, there is one admin host that is going
+      to be the admin. This admin host can establish a keystore with the other hosts by using
+      their public keys. Now, this becomes an interesting use case because each host can establish
+      the same hierarchy by establishing the shared secret, once established the hosts can go off
+      and rotate their "branch keys" by introducing new raw ECC public keys or ephemeral ECC keys.
+   1. This hierarchy feature is out of scope for these new keyrings but it is worth keeping it in mind.

changes/2024-03-12_ecdh-keyring/change.md

@@ -0,0 +1,192 @@
+[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
+[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
+
+# Elliptic Curve Diffie-Hellman (ECDH) Keyring
+
+## Affected Specifications
+
+N/A
+
+## Definitions
+
+- **AWS ECC KMS Key** :
+  A KMS key with an elliptic curve key pair.
+
+- **Ephemeral ECC Key** :
+  A short lived ECC Key that lives only for the duration
+  of the operation.
+
+### Conventions used in this document
+
+The key words
+"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
+in this document are to be interpreted as described in
+[RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+## Summary
+
+AWS KMS supports elliptic curve Diffie-Hellman (ECDH) key agreement protocol
+on elliptic curve (ECC) KMS key. This allows two parties to establish
+a secure communication channel using a shared secret.
+
+Customers do not want to worry about how to correctly use the
+shared secret.
+Instead, they can rely on the ECDH Keyring to use the shared secret to derive
+a shared wrapping key and perform envelope encryption.
+
+This keyring will use a Key Derivation Function with a Psuedo Random Function
+to derive a shared wrapping key. This shared wrapping key will be used to encrypt the data key
+that performs the data encryption for the customer.
+
+Using the shared wrapping key in this way allows customers to be
+able to execute hybrid encryption workflows, where
+their data is encrypted by a symmetric key
+and the symmetric key is protected by asymmetric keys.
+
+When using a KMS ECDH Keyring, at a minimum a KMS Key ID and the
+recipient's public key are needed.
+But the recipient public key could be a kms key.
+
+When using a Raw ECDH Keyring, at a minimum you need the sender's private key
+and the recipient's public key.
+
+This construction does not adhere to the specification of an
+[AWS KMS multikeyring](../../framework/aws-kms/aws-kms-multi-keyrings.md).
+In a KMS multikeyring the generator and the children MUST be created with
+[aws-kms-keyrings](../../framework/aws-kms/aws-kms-keyring.md).
+Since the KMS ECDH Keyring has a different construction,
+it MUST NOT be used in a KMS multikeyring.
+However; it can be used in a [multikeyring](../../framework/multi-keyring.md).
+
+## Configuration
+
+There are three different configuration settings
+
+1. [Key Agreement Schemes](#key-agreement-schemes)
+1. [AWS KMS ECDH Keyring Configuration](#aws-kms-ecdh-keyring-configuration)
+1. [Raw ECDH Keyring Configuration](#raw-ecdh-keyring-configuration)
+
+### Key Agreement Schemes
+
+From [NIST 800-56](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3),
+the supported schemes involve a combination of ephemeral and static ECC Keys. These are:
+
+- [FullUnifiedModel](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf#page=81)
+- [EphemeralUnifiedModel](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf#page=89)
+- [OnePassUnifiedModel](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf#page=97)
+- [OnePassDiffieHellman](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf#page=110)
+- [StaticUnifiedModel](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf#page=117)
+
+The keyrings will _ONLY_ support the StaticUnifiedModel Key Agreement Scheme.
+We can make this assumption because on configuration we don't have a way of knowing whether
+the public key supplied by the recipient is actually an ephemeral key.
+Additionally, for the AWS ECDH Keyring the `DeriveSharedSecret` API
+has no way of knowing if the public key is an ephemeral key.
+
+### AWS KMS ECDH Keyring Configuration
+
+The ECDH Protocol is executed between two parties.
+One is the sender, the other the recipient.
+
+ECDH uses the sender's
+private key and the recipient's public key to
+calculate the shared secret.
+
+However; when configured with an AWS KMS ECDH Keyring the parties
+either have an AWS KMS ECC Key Pair OR they have raw keys.
+The "sender" party MUST be AWS KMS, whereas the recipient MAY BE
+AWS KMS or a raw key.
+
+| Sender (Private) Keys |
+| --------------------- |
+| AWS ECC KMS Key       |
+
+| Recipient (Public) Keys |
+| ----------------------- |
+| AWS ECC KMS Key         |
+| Raw ECC Key             |
+
+### Raw ECDH Keyring Configuration
+
+The ECDH Protocol is executed between two parties.
+One is the sender, the other the recipient.
+
+ECDH uses the sender's
+private key and the recipient's public key to
+calculate the shared secret.
+
+However; when using the Raw ECDH Keyring you can
+have multiple key configurations.
+
+| Sender (Private) Keys |
+| --------------------- |
+| Raw ECC Key           |
+| Ephemeral ECC Key     |
+
+| Recipient (Public) Keys |
+| ----------------------- |
+| Raw ECC Key             |
+| Ephemeral ECC Key       |
+
+### KDF Configuration
+
+Once a shared secret has been established between
+the sender's private key and the recipient's public key,
+the shared secret will be used to derive a shared wrapping key
+that can be used in hybrid encryption workflows.
+
+The only available option for key derivation is:
+
+- KDF_CTR_HMAC_SHA384:
+  [Key Derivation Function in Counter Mode](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf)
+  with HMAC using Hashing Algorithm SHA 384
+
+## Key Commitment
+
+To confirm that the correct keying material is being used we will
+supply a commitment key.
+This commitment key will be verified by
+the decrypting party by calculating its own commitment key.
+
+If the sender's commitment key and the recipient's key match then
+the decrypting party can assert that it is in possession of the
+shared wrapping key the sender used.
+
+## Additional Information
+
+The keyring will use the encryption and decryption materials' encryption
+context as input to the Key Derivation function as additional information; however,
+it will be used in two places.
+
+1. Derivation information as part of the KDF
+   - This ensures that the shared wrapping key is cryptographically
+     bound to the context of what it will be used for.
+1. AAD as part of the data key wrapping
+   - As with the other keyrings, the ECDH keyring will use
+     the supplied encryption context to also cryptographically bind
+     the shared wrapping key to the data key.
+
+Using additional information in this way allows
+customers to have authenticated encryption
+because the additional information
+will have to match in the derivation step
+and the data key wrapping/unwrapping step in order to
+produce the data key.
+
+## Additional Information vs Encryption Context:
+
+There will be no changes to the public facing API.
+So how will customers differentiate between Additional Information
+and Encryption Context? Which is used where?
+
+Before wrapping the plaintext data key with the derived shared wrapping key,
+the ECDH Keyrings will use the input encryption context and canonicalize it
+and use it as additional information into the KDF.
+
+If the keyring succeeds at deriving the shared wrapping key and is ready to wrap the
+plaintext data key, it will use the input encryption context as additional
+authenticated data (AAD) into the AES-GCM Encrypt operation.
+
+Using the encryption context as both AAD and Additional Information for the KDF
+allows us to save message-header space.