From aa510ff395a6abf7f4faa002bc69deb42f5ba19a Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Tue, 10 May 2022 13:03:49 -0700 Subject: [PATCH 1/3] feat(Examples): discovery filter --- .../configuration/discovery-filter.md | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 examples/templates/configuration/discovery-filter.md diff --git a/examples/templates/configuration/discovery-filter.md b/examples/templates/configuration/discovery-filter.md new file mode 100644 index 00000000..7236290f --- /dev/null +++ b/examples/templates/configuration/discovery-filter.md @@ -0,0 +1,104 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Discovery Filter example + +Implementations of this example MUST follow the rules defined in +[Example Templates](../../../examples.md#example-templates). + +## Implementations + +- [JavaScript Node](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts) +- [NET](https://github.com/aws/aws-encryption-sdk-dafny/blob/mainline/aws-encryption-sdk-net/Examples/DiscoveryFilterExample.cs) + +## Definitions + +### 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). + +## Header + +```c# +/// Discovery Filters are used to restrict Discovery Keyrings +/// to trusted AWS Accounts. +/// The Accounts are specified by their Account Ids +/// and the partition they are in. +/// +/// It's always a best practice to specify your wrapping keys explicitly. +/// This practice assures that you only use the keys that you intend. +/// It also improves performance by preventing you from +/// inadvertently using keys in a different AWS account or Region, +/// or attempting to decrypt with keys that you don't have permission to use. +/// +/// However, when decrypting with AWS KMS keyrings, +/// you are not required to specify wrapping keys. +/// The AWS Encryption SDK can get the key identifier +/// from the metadata of the encrypted data key. +/// +/// When specifying AWS KMS wrapping keys for decrypting is impractical +/// (such as when encrypting using AWS KMS Aliases), +/// you can use discovery keyrings. +/// +/// When you can not specify your wrapping keys explicitly, +/// using a Discovery Filter is a best practice. +/// +/// Particularly if an application is decrypting messages from multiple sources, +/// adding trusted AWS accounts to the discovery filter allows it to +/// protect itself from decrypting messages from untrusted sources. +``` + +## Summary + +```c# +/// Demonstrate using Discovery Filters. +``` + +## Inputs + +- **plaintext** : + Plaintext that is/will be encrypted + +- **trustedAccountIds** : + List of AWS Account Ids that are trusted. + +- **awsPartition** : + AWS Partition that contains all the members of "trustedAccountIds". + +## Steps + +1. Instantiate the Material Providers and Encryption SDK + +```C# +// Instantiate the Encryption SDK such that it limits the number of +// Encrypted Data Keys a ciphertext may contain. +// Discovery Keyrings are an excellent tool +// for handling encrypted messages from multiple sources. +// Limiting the number of encrypted data keys is a best practice, +// particularly when decrypting messages from multiple sources. +// See the LimitEncryptedDataKeysExample for details. +``` + +2. Create a Discovery Keyring with a Discovery Filter +```c# +// We create a Discovery keyring to use for decryption. +// We'll add a discovery filter so that we limit the set of Encrypted Data Keys +// we are willing to decrypt to only ones created by KMS keys from +// trusted accounts. +``` + +3. Retrieve or create an encrypted message to decrypt. + +4. Decrypt the encrypted data. + +5. Verify the encryption context + +6. Verify the decrypted plaintext is the original plaintext + +7. Create a discovery filter that excludes the encrypted data key + +8. Validate the excluding discovery filter fails to decrypt the ciphertext From e7496b9241c9865607f58753b4fed900a7cc2fdc Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Tue, 10 May 2022 13:28:05 -0700 Subject: [PATCH 2/3] fix(Example): discovery filter --- examples/templates/configuration/discovery-filter.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/examples/templates/configuration/discovery-filter.md b/examples/templates/configuration/discovery-filter.md index 7236290f..20efdfc0 100644 --- a/examples/templates/configuration/discovery-filter.md +++ b/examples/templates/configuration/discovery-filter.md @@ -62,13 +62,11 @@ in this document are to be interpreted as described in - **plaintext** : Plaintext that is/will be encrypted - - **trustedAccountIds** : List of AWS Account Ids that are trusted. - - **awsPartition** : AWS Partition that contains all the members of "trustedAccountIds". - + ## Steps 1. Instantiate the Material Providers and Encryption SDK @@ -84,6 +82,7 @@ in this document are to be interpreted as described in ``` 2. Create a Discovery Keyring with a Discovery Filter + ```c# // We create a Discovery keyring to use for decryption. // We'll add a discovery filter so that we limit the set of Encrypted Data Keys From abe459959e587de9d1955d42606d1ff5e1cd8061 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 15 Jun 2022 16:48:22 -0700 Subject: [PATCH 3/3] fix(example): remove comment syntax --- .../configuration/discovery-filter.md | 92 ++++++++++--------- 1 file changed, 49 insertions(+), 43 deletions(-) diff --git a/examples/templates/configuration/discovery-filter.md b/examples/templates/configuration/discovery-filter.md index 20efdfc0..dd382a98 100644 --- a/examples/templates/configuration/discovery-filter.md +++ b/examples/templates/configuration/discovery-filter.md @@ -23,39 +23,39 @@ in this document are to be interpreted as described in ## Header -```c# -/// Discovery Filters are used to restrict Discovery Keyrings -/// to trusted AWS Accounts. -/// The Accounts are specified by their Account Ids -/// and the partition they are in. -/// -/// It's always a best practice to specify your wrapping keys explicitly. -/// This practice assures that you only use the keys that you intend. -/// It also improves performance by preventing you from -/// inadvertently using keys in a different AWS account or Region, -/// or attempting to decrypt with keys that you don't have permission to use. -/// -/// However, when decrypting with AWS KMS keyrings, -/// you are not required to specify wrapping keys. -/// The AWS Encryption SDK can get the key identifier -/// from the metadata of the encrypted data key. -/// -/// When specifying AWS KMS wrapping keys for decrypting is impractical -/// (such as when encrypting using AWS KMS Aliases), -/// you can use discovery keyrings. -/// -/// When you can not specify your wrapping keys explicitly, -/// using a Discovery Filter is a best practice. -/// -/// Particularly if an application is decrypting messages from multiple sources, -/// adding trusted AWS accounts to the discovery filter allows it to -/// protect itself from decrypting messages from untrusted sources. +``` +Discovery Filters are used to restrict Discovery Keyrings +to trusted AWS Accounts. +The Accounts are specified by their Account Ids +and the partition they are in. + +It's always a best practice to specify your wrapping keys explicitly. +This practice assures that you only use the keys that you intend. +It also improves performance by preventing you from +inadvertently using keys in a different AWS account or Region, +or attempting to decrypt with keys that you don't have permission to use. + +However, when decrypting with AWS KMS keyrings, +you are not required to specify wrapping keys. +The AWS Encryption SDK can get the key identifier +from the metadata of the encrypted data key. + +When specifying AWS KMS wrapping keys for decrypting is impractical +(such as when encrypting using AWS KMS Aliases), +you can use discovery keyrings. + +When you can not specify your wrapping keys explicitly, +using a Discovery Filter is a best practice. + +Particularly if an application is decrypting messages from multiple sources, +adding trusted AWS accounts to the discovery filter allows it to +protect itself from decrypting messages from untrusted sources. ``` ## Summary -```c# -/// Demonstrate using Discovery Filters. +``` +Demonstrate using Discovery Filters. ``` ## Inputs @@ -71,23 +71,23 @@ in this document are to be interpreted as described in 1. Instantiate the Material Providers and Encryption SDK -```C# -// Instantiate the Encryption SDK such that it limits the number of -// Encrypted Data Keys a ciphertext may contain. -// Discovery Keyrings are an excellent tool -// for handling encrypted messages from multiple sources. -// Limiting the number of encrypted data keys is a best practice, -// particularly when decrypting messages from multiple sources. -// See the LimitEncryptedDataKeysExample for details. +``` +Instantiate the Encryption SDK such that it limits the number of +Encrypted Data Keys a ciphertext may contain. +Discovery Keyrings are an excellent tool +for handling encrypted messages from multiple sources. +Limiting the number of encrypted data keys is a best practice, +particularly when decrypting messages from multiple sources. +See the LimitEncryptedDataKeysExample for details. ``` 2. Create a Discovery Keyring with a Discovery Filter -```c# -// We create a Discovery keyring to use for decryption. -// We'll add a discovery filter so that we limit the set of Encrypted Data Keys -// we are willing to decrypt to only ones created by KMS keys from -// trusted accounts. +``` +We create a Discovery keyring to use for decryption. +We'll add a discovery filter so that we limit the set of Encrypted Data Keys +we are willing to decrypt to only ones created by KMS keys from +trusted accounts. ``` 3. Retrieve or create an encrypted message to decrypt. @@ -100,4 +100,10 @@ in this document are to be interpreted as described in 7. Create a discovery filter that excludes the encrypted data key -8. Validate the excluding discovery filter fails to decrypt the ciphertext +``` +If we create a Discovery Filter that excludes +all the accounts the ciphertext was encrypted with, +the decryption will fail. +``` + +8. Validate that excluding discovery filter fails to decrypt the ciphertext