docs: add example to replicate AWS KMS MKP behavior with AWS KMS keyring #255

mattsb42-aws · 2020-04-16T22:01:44Z

Issue #, if available:

resolves: #248

Description of changes:

In addition to using the configured AWS KMS CMKs, the AWS KMS master key provider attempts to decrypt any data keys that were encrypted under an AWS KMS CMK. This behavior is not always obvious, and when we designed the AWS KMS keyring, we decided that it was best to separate these behaviors, but as customers migrate from master key providers to keyrings, it will be helpful to have an example of how to replicate the exact behavior of the AWS KMS master key provider using keyrings.

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.

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

WesleyRosenblum · 2020-04-16T22:41:07Z

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

+We have found that separating these two behaviors out,
+as we did in the AWS KMS keyring,


how about "We have found that separating these two behaviors into the AWS KMS Keyring and the AWS KMS discovery keyring"

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

…_provider.py Co-Authored-By: Wesley Rosenblum <55108558+WesleyRosenblum@users.noreply.github.com>

…_provider.py

juneb · 2020-04-17T22:07:06Z

examples/README.md

@@ -44,6 +44,8 @@ We start with AWS KMS examples, then show how to use other wrapping keys.
        * [with keyrings](./src/keyring/aws_kms/discovery_decrypt_in_region_only.py)
    * How to decrypt with a preferred region but failover to others
        * [with keyrings](./src/keyring/aws_kms/discovery_decrypt_with_preferred_regions.py)
+    * How to replicate the behavior of an AWS KMS master key provider


Can we use "reproduce" instead of "replicate?" The KMS is using "replicate" and "replica" for other purposes. Although most people won't notice, I can envisions someone with limited English language skills googling this and becoming hopelessly confused.

juneb · 2020-04-17T22:07:33Z

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Before there were keyrings, there were master key providers.


Once upon a time ... :)

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

juneb · 2020-04-17T22:17:18Z

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

+the AWS KMS master key provider always attempts to decrypt
+*any* data keys that were encrypted under an AWS KMS CMK.


Suggested change

the AWS KMS master key provider always attempts to decrypt

*any* data keys that were encrypted under an AWS KMS CMK.

the AWS KMS master key provider can decrypt

*any* data key that was encrypted under an AWS KMS CMK.

-or-

the AWS KMS master key provider can use any AWS KMS CMK that encrypted a data key to decrypt it.

That's not quite what I was getting at. Whether or not it can decrypt depends on the KMS/IAM permissions. Just like the discovery keyring, the point I was trying to make is that it does in fact reach out to the KMS service for every KMS-encrypted EDK whether or not it succeeds.

The difficulty here is the combination of "always" and "any." Does the ESDK always attempt to decrypt all of the encrypted data keys in an encrypted message? Or, it can attempt to decrypt any of them?

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

Co-Authored-By: June Blender <juneb@users.noreply.github.com>

juneb · 2020-04-21T17:11:53Z

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

+In earlier versions of the AWS Encryption SDK,
+you used master key providers to determine how your data keys are protected.


Suggested change

In earlier versions of the AWS Encryption SDK,

you used master key providers to determine how your data keys are protected.

You might have used master key providers to protect your data keys in an earlier versions of the AWS Encryption SDK. This example shows how to replace a master key provider with a keyring that behaves the same way.

I might never have used the ESDK before.

juneb · 2020-04-21T17:21:55Z

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

+the AWS KMS master key provider always attempts to decrypt
+*any* data keys that were encrypted under an AWS KMS CMK.


The difficulty here is the combination of "always" and "any." Does the ESDK always attempt to decrypt all of the encrypted data keys in an encrypted message? Or, it can attempt to decrypt any of them?

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

* show using multiple CMKs * demonstrate how the generating CMK is defined in both * explain that it does not matter if the CMK keyring fails

WesleyRosenblum · 2020-04-22T20:40:33Z

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

+    # This also means that it does not matter if the CMK keyring fails on decrypt,
+    # for example if you configured it with aliases which would work on encrypt
+    # but fail to match any encrypted data keys on decrypt,
+    # because the discovery keyring attempts to decrypt any AWS KMS-encrypted
+    # data keys that it finds.


This sentence is really long, can you break it up?

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py

…_provider.py Co-Authored-By: Wesley Rosenblum <55108558+WesleyRosenblum@users.noreply.github.com>

docs: add example to replicate AWS KMS MKP behavior with AWS KMS keyring

314323e

mattsb42-aws added this to the keyrings milestone Apr 16, 2020

mattsb42-aws requested review from juneb and WesleyRosenblum April 16, 2020 22:01

docs: thanks, grazie; fixing grammar

356083d

mattsb42-aws mentioned this pull request Apr 16, 2020

KMSMasterKeyProvider with 2 keys from same region #254

Closed

WesleyRosenblum reviewed Apr 16, 2020

View reviewed changes

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py Outdated Show resolved Hide resolved

mattsb42-aws and others added 3 commits April 17, 2020 11:21

docs: update examples/src/keyring/aws_kms/act_like_aws_kms_master_key…

3c71661

…_provider.py Co-Authored-By: Wesley Rosenblum <55108558+WesleyRosenblum@users.noreply.github.com>

docs: update examples/src/keyring/aws_kms/act_like_aws_kms_master_key…

b0c0cc0

…_provider.py

docs: reword behavior separation statement

93a1371

mattsb42-aws requested a review from WesleyRosenblum April 17, 2020 18:58

docs: linting fix

70134b1

WesleyRosenblum previously approved these changes Apr 17, 2020

View reviewed changes

juneb reviewed Apr 17, 2020

View reviewed changes

Merge branch 'master' into mkp-keyring-example

dc8dd2f

mattsb42-aws mentioned this pull request Apr 20, 2020

Readme: Update KMSMasterKeyProvider credentials configuration for bet… #251

Merged

1 task

mattsb42-aws commented Apr 20, 2020

View reviewed changes

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py Outdated Show resolved Hide resolved

docs: apply suggestions from code review

0181431

Co-Authored-By: June Blender <juneb@users.noreply.github.com>

mattsb42-aws dismissed WesleyRosenblum’s stale review via 0181431 April 20, 2020 20:19

mattsb42-aws added 2 commits April 20, 2020 13:30

docs: s/replicate/reproduce/

2aed0c8

docs: keep naming consistent

bbb24ef

mattsb42-aws requested review from WesleyRosenblum and juneb April 20, 2020 20:31

WesleyRosenblum previously approved these changes Apr 20, 2020

View reviewed changes

docs: fix line length issue in docstring

b7ced3d

mattsb42-aws dismissed WesleyRosenblum’s stale review via b7ced3d April 21, 2020 16:58

juneb reviewed Apr 21, 2020

View reviewed changes

mattsb42-aws added 2 commits April 22, 2020 11:00

docs: revise description of AWS KMS discovery decrypt behavior

6239257

docs: remove duplicate typo

52d6277

mattsb42-aws added 2 commits April 22, 2020 12:04

docs: refine wording on discovery descriptions

8837284

docs: revise AWS KMS keyring-as-mkp example

b3598d3

* show using multiple CMKs * demonstrate how the generating CMK is defined in both * explain that it does not matter if the CMK keyring fails

mattsb42-aws requested review from juneb and WesleyRosenblum April 22, 2020 19:54

WesleyRosenblum reviewed Apr 22, 2020

View reviewed changes

mattsb42-aws added 2 commits April 23, 2020 14:17

docs: break up long sentence

86f618b

Merge branch 'master' into mkp-keyring-example

52cbca6

mattsb42-aws requested a review from WesleyRosenblum April 23, 2020 21:18

WesleyRosenblum reviewed Apr 23, 2020

View reviewed changes

examples/src/keyring/aws_kms/act_like_aws_kms_master_key_provider.py Outdated Show resolved Hide resolved

docs: update examples/src/keyring/aws_kms/act_like_aws_kms_master_key…

a57c379

…_provider.py Co-Authored-By: Wesley Rosenblum <55108558+WesleyRosenblum@users.noreply.github.com>

mattsb42-aws requested a review from WesleyRosenblum April 24, 2020 06:21

WesleyRosenblum approved these changes Apr 24, 2020

View reviewed changes

mattsb42-aws merged commit 027b127 into aws:master Apr 24, 2020

mattsb42-aws deleted the mkp-keyring-example branch April 24, 2020 16:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add example to replicate AWS KMS MKP behavior with AWS KMS keyring #255

docs: add example to replicate AWS KMS MKP behavior with AWS KMS keyring #255

Uh oh!

mattsb42-aws commented Apr 16, 2020

Uh oh!

Uh oh!

WesleyRosenblum Apr 16, 2020

Uh oh!

Uh oh!

juneb Apr 17, 2020 •

edited by mattsb42-aws

Loading

Uh oh!

juneb Apr 17, 2020

Uh oh!

Uh oh!

Uh oh!

juneb Apr 17, 2020

Uh oh!

mattsb42-aws Apr 20, 2020

Uh oh!

juneb Apr 21, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

juneb Apr 21, 2020

Uh oh!

juneb Apr 21, 2020

Uh oh!

Uh oh!

WesleyRosenblum Apr 22, 2020

Uh oh!

Uh oh!

Uh oh!

		We have found that separating these two behaviors out,
		as we did in the AWS KMS keyring,

		the AWS KMS master key provider always attempts to decrypt
		any data keys that were encrypted under an AWS KMS CMK.

		In earlier versions of the AWS Encryption SDK,
		you used master key providers to determine how your data keys are protected.

	In earlier versions of the AWS Encryption SDK,
	you used master key providers to determine how your data keys are protected.
	You might have used master key providers to protect your data keys in an earlier versions of the AWS Encryption SDK. This example shows how to replace a master key provider with a keyring that behaves the same way.

docs: add example to replicate AWS KMS MKP behavior with AWS KMS keyring #255

docs: add example to replicate AWS KMS MKP behavior with AWS KMS keyring #255

Uh oh!

Conversation

mattsb42-aws commented Apr 16, 2020

Check any applicable:

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

juneb Apr 17, 2020 • edited by mattsb42-aws Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

juneb Apr 17, 2020 •

edited by mattsb42-aws

Loading