Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(Examples): discovery filter #246

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions examples/templates/configuration/discovery-filter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
[//]: # "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

```
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

```
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

```
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

```
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

```
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
Loading