-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(framework): add support for ECDH Keyring (#88)
Co-authored-by: seebees <ryanemer@amazon.com> Co-authored-by: Lucas McDonald <lucasmcdonald3@gmail.com>
- Loading branch information
1 parent
82911ea
commit 8f4afff
Showing
5 changed files
with
1,284 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.