From f856f389f21b576163fafe6a8f21b5bb7692af29 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Fri, 19 Apr 2024 09:36:40 -0400 Subject: [PATCH 1/4] update for mrk support in keystore --- framework/branch-key-store.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index cd379305..640a5169 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -89,6 +89,23 @@ The table name of the DynamoDb table that backs this Keystore. A valid [AWS KMS Key ARN](./aws-kms/aws-kms-key-arn.md#a-valid-aws-kms-arn) that wraps and unwraps keys stored in Amazon DynamoDB. +The KMS Configuration MUST distinguish between strict ARN compatibility and MRK ARN compatibility. + +Both compatibility modes are allowed with both mrk ARN's and non-mrk ARNs. + +#### AWS Key Compatibility + +For two ARNs to be compatible : + +If the [AWS KMS Configuration](#aws-kms-configuration) designates strict ARN compatibility, +then two ARNs are compatible if they are exactly equal. + +If the [AWS KMS Configuration](#aws-kms-configuration) designates MRK ARN compatibility, +then two ARNs are compatible if they are equal in all parts other than the region. +That is, they are compatible if [AWS KMS MRK Match for Decrypt](aws-kms/aws-kms-mrk-match-for-decrypt.md#implementation) returns true. + + + ### Logical KeyStore Name This name is cryptographically bound to all data stored in this table, @@ -206,7 +223,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [encryption context for beacon keys](#beacon-key-encryption-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -222,7 +239,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). - GenerateDataKeyWithoutPlaintext `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -235,10 +252,10 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). -- `SourceKeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `SourceKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `CiphertextBlob` MUST be the wrapped DECRYPT_ONLY Branch Key. - ReEncrypt `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `DestinationKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `DestinationEncryptionContext` MUST be the [ACTIVE encryption context for branch keys](#active-encryption-context). If the call to AWS KMS ReEncrypt succeeds, @@ -361,10 +378,10 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above -- `SourceKeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `SourceKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `DestinationKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above ### GetActiveBranchKey @@ -503,7 +520,7 @@ The key `enc` MUST NOT exist in the constructed [encryption context](#encryption When calling [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), the keystore operation MUST call with a request constructed as follows: -- `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `EncryptionContext` MUST be the [encryption context](#encryption-context) constructed above - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). From 03c05db1b0d886263664f558b201d25b25b29e08 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Fri, 19 Apr 2024 09:41:14 -0400 Subject: [PATCH 2/4] reformat --- framework/branch-key-store.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 640a5169..f5a84a40 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -104,8 +104,6 @@ If the [AWS KMS Configuration](#aws-kms-configuration) designates MRK ARN compat then two ARNs are compatible if they are equal in all parts other than the region. That is, they are compatible if [AWS KMS MRK Match for Decrypt](aws-kms/aws-kms-mrk-match-for-decrypt.md#implementation) returns true. - - ### Logical KeyStore Name This name is cryptographically bound to all data stored in this table, From 707db1ab018c36e4ac3868afc2ad11a1506b3adc Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Fri, 19 Apr 2024 12:06:48 -0400 Subject: [PATCH 3/4] feedback --- framework/branch-key-store.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index f5a84a40..87cbe425 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -89,15 +89,15 @@ The table name of the DynamoDb table that backs this Keystore. A valid [AWS KMS Key ARN](./aws-kms/aws-kms-key-arn.md#a-valid-aws-kms-arn) that wraps and unwraps keys stored in Amazon DynamoDB. -The KMS Configuration MUST distinguish between strict ARN compatibility and MRK ARN compatibility. +The KMS Configuration MUST distinguish between single region ARN compatibility and MRK ARN compatibility. -Both compatibility modes are allowed with both mrk ARN's and non-mrk ARNs. +Both compatibility modes are allowed with both mrk ARN's and single region ARNs. -#### AWS Key Compatibility +#### AWS Key ARN Compatibility For two ARNs to be compatible : -If the [AWS KMS Configuration](#aws-kms-configuration) designates strict ARN compatibility, +If the [AWS KMS Configuration](#aws-kms-configuration) designates single region ARN compatibility, then two ARNs are compatible if they are exactly equal. If the [AWS KMS Configuration](#aws-kms-configuration) designates MRK ARN compatibility, @@ -221,7 +221,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [encryption context for beacon keys](#beacon-key-encryption-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -237,7 +237,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). - GenerateDataKeyWithoutPlaintext `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -250,10 +250,10 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). -- `SourceKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `CiphertextBlob` MUST be the wrapped DECRYPT_ONLY Branch Key. - ReEncrypt `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `DestinationEncryptionContext` MUST be the [ACTIVE encryption context for branch keys](#active-encryption-context). If the call to AWS KMS ReEncrypt succeeds, @@ -376,10 +376,10 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above -- `SourceKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above ### GetActiveBranchKey @@ -518,7 +518,7 @@ The key `enc` MUST NOT exist in the constructed [encryption context](#encryption When calling [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), the keystore operation MUST call with a request constructed as follows: -- `KeyId` MUST be [compatible with](#aws-key-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `EncryptionContext` MUST be the [encryption context](#encryption-context) constructed above - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). From ccd9db34e9760c512132519a46274c86062f4e35 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Fri, 19 Apr 2024 13:39:25 -0400 Subject: [PATCH 4/4] more PR feedback --- framework/branch-key-store.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 87cbe425..02cbacb0 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -95,7 +95,7 @@ Both compatibility modes are allowed with both mrk ARN's and single region ARNs. #### AWS Key ARN Compatibility -For two ARNs to be compatible : +For two ARNs to be compatible: If the [AWS KMS Configuration](#aws-kms-configuration) designates single region ARN compatibility, then two ARNs are compatible if they are exactly equal. @@ -221,7 +221,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [encryption context for beacon keys](#beacon-key-encryption-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -237,7 +237,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). - GenerateDataKeyWithoutPlaintext `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -250,10 +250,10 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). -- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `CiphertextBlob` MUST be the wrapped DECRYPT_ONLY Branch Key. - ReEncrypt `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `DestinationEncryptionContext` MUST be the [ACTIVE encryption context for branch keys](#active-encryption-context). If the call to AWS KMS ReEncrypt succeeds, @@ -376,10 +376,10 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above -- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above ### GetActiveBranchKey @@ -518,7 +518,7 @@ The key `enc` MUST NOT exist in the constructed [encryption context](#encryption When calling [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), the keystore operation MUST call with a request constructed as follows: -- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore +- `KeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `EncryptionContext` MUST be the [encryption context](#encryption-context) constructed above - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token).