Skip to content

Readme: Update KMSMasterKeyProvider credentials configuration for bet… #251

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.

Sign up for GitHub

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

Merged
merged 6 commits into from
Apr 23, 2020
Merged

Readme: Update KMSMasterKeyProvider credentials configuration for bet… #251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
043011d
Readme: Update KMSMasterKeyProvider credentials configuration for bet…
nraval1729 Apr 15, 2020
09ea03e
Readme: Move KMSMasterKeyProvider usage information into its docstring
nraval1729 Apr 20, 2020
7599b0e
Merge branch 'master' into master
nraval1729 Apr 20, 2020
64fcd9a
Format KMSMasterKeyProvider docstring
nraval1729 Apr 20, 2020
c69237b
Fix pylint max character error in kms.py
nraval1729 Apr 20, 2020
a839503
docs: copyedit, rst formatting, and rearranging
mattsb42-aws Apr 21, 2020
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
3 changes: 0 additions & 3 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,6 @@ to your use-case in order to obtain peak performance.
.. _GitHub: https://github.com/aws/aws-encryption-sdk-python/
.. _AWS KMS: https://docs.aws.amazon.com/kms/latest/developerguide/overview.html
.. _KMS customer master key (CMK): https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys
.. _boto3 SDK: https://boto3.readthedocs.io/en/latest/
.. _standard means by which boto3 locates credentials: https://boto3.readthedocs.io/en/latest/guide/configuration.html
.. _final message: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html
.. _encryption context: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context
.. _examples: https://github.com/aws/aws-encryption-sdk-python/tree/master/examples
.. _Security issue notifications: https://github.com/aws/aws-encryption-sdk-python/tree/master/CONTRIBUTING.md#security-issue-notifications
58 changes: 47 additions & 11 deletions src/aws_encryption_sdk/key_providers/kms.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,22 +82,58 @@ class KMSMasterKeyProvider(MasterKeyProvider):
Master key providers are deprecated.
Use :class:`aws_encryption_sdk.keyrings.aws_kms.AwsKmsKeyring` instead.

>>> import aws_encryption_sdk
>>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(key_ids=[
... 'arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222',
... 'arn:aws:kms:us-east-1:3333333333333:key/33333333-3333-3333-3333-333333333333'
To encrypt data, you must configure :class:`KMSMasterKeyProvider` with at least one CMK.
If you configure :class:`KMSMasterKeyProvider` with multiple CMKs,
it generates the data key using the first CMK and encrypts that data key using the rest,
so that the `encrypted message`_ includes a copy of the data key encrypted under each configured CMK.

.. _encrypted message: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html

>>> from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider
>>> kms_key_provider = KMSMasterKeyProvider(key_ids=[
... "arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222",
... "arn:aws:kms:us-east-1:3333333333333:key/33333333-3333-3333-3333-333333333333",
... ])

You can also configure :class:`KMSMasterKeyProvider` with CMKs in multiple regions:

>>> from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider
>>> kms_key_provider = KMSMasterKeyProvider(key_ids=[
... "arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222",
... "arn:aws:kms:us-west-2:3333333333333:key/33333333-3333-3333-3333-333333333333",
... "arn:aws:kms:ap-northeast-1:4444444444444:key/44444444-4444-4444-4444-444444444444",
... ])
>>> kms_key_provider.add_master_key('arn:aws:kms:ap-northeast-1:4444444444444:alias/another-key')

.. note::
If no botocore_session is provided, the default botocore session will be used.
:class:`KMSMasterKeyProvider` needs AWS credentials in order to interact with `AWS KMS`_.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we move the credentials related information towards the top of the docstring (above line #85 (To encrypt data, you must configure ...) or is it okay either way? I am asking because conventionally information about how to set credentials appears before other information.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put the CMK configuration first because I expect more users to need to know the affect of CMK configuration than will need to know how to configure credentials. In the happy-path of "I'm running in AWS in an environment where the credentials magic in (EC2, ECS, Lambda, etc)", you usually don't need to think about the credentials at all; the default behavior will Just Work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. Makes sense 👍

There are two ways that you can provide these credentials:

.. _AWS KMS: https://docs.aws.amazon.com/kms/latest/developerguide/overview.html

1. Provide your AWS credentials in one of the standard `AWS credential discovery locations`_
and the :class:`KMSMasterKeyProvider` instance automatically discovers those credentials.

.. _AWS credential discovery locations:
https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuring-credentials

>>> from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider
>>> import botocore.session
>>> kms_key_provider = KMSMasterKeyProvider()

.. note::
If multiple AWS Identities are needed, one of two options are available:
2. Provide an existing botocore session to :class:`KMSMasterKeyProvider`.
This option can be useful if you want to use specific credentials
or if you want to reuse an existing botocore session instance to decrease startup costs.

* Additional KMSMasterKeyProvider instances may be added to the primary MasterKeyProvider.
>>> from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider
>>> import botocore.session
>>> existing_botocore_session = botocore.session.Session(profile="custom")
>>> kms_key_provider = KMSMasterKeyProvider(botocore_session=existing_botocore_session)

* KMSMasterKey instances may be manually created and added to this KMSMasterKeyProvider.
If you need different credentials to use different CMKs,
you can combine multiple :class:`KMSMasterKeyProvider` or :class:`KMSMasterKey` instances,
each with their own credentials.
However, we recommend that you use
:class:`aws_encryption_sdk.keyrings.aws_kms.AwsKmsKeyring` and client suppliers
for a simpler user experience.

:param config: Configuration object (optional)
:type config: aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig
Expand Down