docs: add keyring examples #221

mattsb42-aws · 2020-03-12T23:04:29Z

Issue #, if available: #156 #146

Description of changes:

This adds several examples that show how to use keyrings to solve some common problems.

These new examples all follow the format set in #219.

Who reviews what

Everyone is of course welcome to review anything else, but these are the things that I'm specifically looking for from each tagged person.

@SalusaSecondus : The example scenario description and framing for the multi-keyring escrow example.
@WesleyRosenblum : Keyring use and any additional example use-cases you can think of. We'll also be translating these examples to Java once these are merged.
@acioc : Python good-ness and any thoughts on example use-cases.
@juneb : Descriptions of example use-cases and the in-line comments where they diverge from the template.

What this is not

Things I intentionally left out of this PR:

Master key providers : Once this batch of keyring examples is merged, I'll go through and translate all that can be to use MKPs.
Cryptographic materials managers : To avoid an even larger PR, I did not include any examples of CMMs. I'll be adding several such examples in a later PR.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Check any applicable:

Were any files moved? Moving files changes their URL, which breaks all hyperlinks to the files.

mattsb42-aws · 2020-03-12T23:12:42Z

doh; looks like I need to seed the environment with a default AWS region :/

acioc

Looks good! Just had a few questions/ np's below

examples/src/keyring/aws_kms/custom_client_supplier.py

examples/src/keyring/aws_kms/custom_kms_client_config.py

examples/src/keyring/aws_kms/discovery_decrypt.py

examples/src/keyring/aws_kms/discovery_decrypt_in_region_only.py

examples/src/keyring/aws_kms/discovery_decrypt_with_preferred_regions.py

examples/src/keyring/raw_rsa/private_key_only_from_pem.py

examples/src/keyring/raw_rsa/public_private_key_separate.py

WesleyRosenblum · 2020-03-13T17:42:25Z

Once this batch of keyring examples is merged, I'll go through and translate all that can be to use MKPs.

What is the value of doing that? The way I see it, all current customers are already using MKPs and don't really need example code to follow for doing something with MKPs, and if they want to try out a new use case they should just use Keyrings anyway? I could see an argument to do it for completeness, but it still seems like the lowest priority to me.

examples/README.md

examples/src/keyring/aws_kms/custom_kms_client_config.py

examples/src/keyring/aws_kms/discovery_decrypt.py

examples/src/keyring/aws_kms/discovery_decrypt_with_preferred_regions.py

examples/src/keyring/aws_kms/multiple_regions.py

examples/src/keyring/multi/aws_kms_with_escrow.py

examples/src/keyring/raw_rsa/public_private_key_separate.py

juneb

Review in progress (back later).

examples/README.md

…an "KMS keyring in discovery mode"

acioc

Looked over all diffs since my last review. Looks good! Would be great to also get an example of how to handle errors/ failing to encrypt/decrypt, but that can be out of scope for this PR.

examples/README.md

examples/src/keyring/aws_kms/custom_client_supplier.py

examples/README.md

examples/src/keyring/aws_kms/discovery_decrypt_in_region_only.py

juneb · 2020-03-25T00:47:24Z

examples/src/keyring/aws_kms/discovery_decrypt_in_region_only.py

+    }
+
+    # Create the keyring that determines how your data keys are protected.
+    encrypt_keyring = KmsKeyring(generator_key_id=aws_kms_cmk)


examples/src/keyring/aws_kms/discovery_decrypt_in_region_only.py

Co-Authored-By: June Blender <[email protected]>

…iguration

juneb

A couple of general comments.

The example readme is a nice description of the ESDK. But it needs a table with the name and description of each example.
The examples all use (one?) CMK that's passed to the function. Please show at least one example with multiple CMKs (generator, additional) and different keyrings for encrypt and decrypt.
Show examples for discovery keyring and client supplier variants. (I suspect that's coming.)

mattsb42-aws · 2020-03-31T01:58:21Z

The example readme is a nice description of the ESDK. But it needs a table with the name and description of each example.

Let's look at that separately from this PR. I opened #232 to track this.

The examples all use (one?) CMK that's passed to the function. Please show at least one example with multiple CMKs (generator, additional) and different keyrings for encrypt and decrypt.

https://github.com/aws/aws-encryption-sdk-python/pull/221/files#diff-473fcd9a070a3379cefee9a26242b882

Show examples for discovery keyring and client supplier variants. (I suspect that's coming.)

discovery : https://github.com/aws/aws-encryption-sdk-python/pull/221/files#diff-a4dea98c86c59ae161e1f625dcb6a2d0
custom client configuration: https://github.com/aws/aws-encryption-sdk-python/pull/221/files#diff-cd79402ed659c40a343272f2060b1162
custom client supplier: https://github.com/aws/aws-encryption-sdk-python/pull/221/files#diff-a8445a2278d4f801582801e1fa2c0789
single-region discovery: https://github.com/aws/aws-encryption-sdk-python/pull/221/files#diff-4c3bda50e3a6c02973cd75f35a2dbaa8
discovery with preferred region: https://github.com/aws/aws-encryption-sdk-python/pull/221/files#diff-d4ff831b36b165c2a4444aeee400912c

mattsb42-aws added 19 commits March 12, 2020 12:05

docs: add raw RSA keyring examples

558563f

fix: fix type signatures in raw RSA keyring

7b6b920

docs: add raw AES keyring example

05266a8

chore: move single-CMK example to new location

f368f09

docs: update single-CMK example to match new template

4709409

fix: fix docstring in raw AES keyring example

5fb2d3e

chore: move multi-region KMS example to new location

f6af7ee

chore: update multi-region AWS keyring example to new format

52f8312

docs: add multi-keyring example

0047ddf

docs: add custom KMS client config keyring example

5925b77

docs: add multi-partition client supplier example

a6519d2

docs: clarify custom client supplier example intro

2fb99d0

docs: add reference to in-region-discovery example

154ce5d

docs: add basic KMS discovery keyring example

3fc892a

docs: add examples showing region-scoped discovery keyrings

47351a7

docs: add listing of keyring examples

7770186

chore: remove reminder to write more because I already did

0186e61

docs: clean up multikeyring description

23c3766

docs: rearrange examples readme

59b09df

mattsb42-aws requested review from juneb, acioc, WesleyRosenblum, a team and SalusaSecondus March 12, 2020 23:04

fix: set AWS_DEFAULT_REGION to region of primary CMK for examples tets

9234c01

acioc reviewed Mar 13, 2020

View reviewed changes

WesleyRosenblum reviewed Mar 13, 2020

View reviewed changes

juneb reviewed Mar 13, 2020

View reviewed changes

mattsb42-aws requested review from SalusaSecondus, juneb, WesleyRosenblum and acioc March 19, 2020 19:56

mattsb42-aws added 3 commits March 23, 2020 13:32

Merge branch 'keyring' into moar-examples

810eff2

docs: change examples to talk about "KMS discovery keyring" rather th…

9acd33d

…an "KMS keyring in discovery mode"

docs: add link to NIST docs explaining RSA key size and fix typos

b8fdf96

WesleyRosenblum previously approved these changes Mar 24, 2020

View reviewed changes

SalusaSecondus previously approved these changes Mar 24, 2020

View reviewed changes

acioc previously approved these changes Mar 24, 2020

View reviewed changes

juneb reviewed Mar 25, 2020

View reviewed changes

docs: apply suggestions from code review

dd59a36

Co-Authored-By: June Blender <[email protected]>

mattsb42-aws dismissed stale reviews from acioc, SalusaSecondus, and WesleyRosenblum via dd59a36 March 25, 2020 04:52

mattsb42-aws added 3 commits March 24, 2020 21:59

docs: carrying over copyedits

739ed47

Merge branch 'keyring' into moar-examples

5ea4e81

feat: update KMS discovery keyring examples to use new discovery conf…

8b28bee

…iguration

juneb reviewed Mar 29, 2020

View reviewed changes

mattsb42-aws added 2 commits March 30, 2020 18:47

Merge branch 'keyring' into moar-examples

18007ed

docs: fix typo

c4aeaf7

docs: remove trailing whitespace

dd63564

juneb approved these changes Mar 31, 2020

View reviewed changes

mattsb42-aws merged commit 8d84ff5 into aws:keyring Mar 31, 2020

mattsb42-aws deleted the moar-examples branch March 31, 2020 18:48

ttjsu-aws mentioned this pull request Apr 7, 2020

Revise Examples #156

Closed

15 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add keyring examples #221

docs: add keyring examples #221

mattsb42-aws commented Mar 12, 2020 •

edited

Loading

mattsb42-aws commented Mar 12, 2020

acioc left a comment

WesleyRosenblum commented Mar 13, 2020

juneb left a comment

acioc left a comment

juneb Mar 25, 2020

juneb left a comment

mattsb42-aws commented Mar 31, 2020

docs: add keyring examples #221

docs: add keyring examples #221

Conversation

mattsb42-aws commented Mar 12, 2020 • edited Loading

Check any applicable:

mattsb42-aws commented Mar 12, 2020

acioc left a comment

Choose a reason for hiding this comment

WesleyRosenblum commented Mar 13, 2020

juneb left a comment

Choose a reason for hiding this comment

acioc left a comment

Choose a reason for hiding this comment

juneb Mar 25, 2020

Choose a reason for hiding this comment

juneb left a comment

Choose a reason for hiding this comment

mattsb42-aws commented Mar 31, 2020

mattsb42-aws commented Mar 12, 2020 •

edited

Loading