From 043011d4b53603e31064bf1e33095bfcb559c2ab Mon Sep 17 00:00:00 2001 From: Nisarg Raval Date: Wed, 15 Apr 2020 13:01:50 +0530 Subject: [PATCH 1/5] Readme: Update KMSMasterKeyProvider credentials configuration for better understanding --- README.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 7bc8038ea..7970341d0 100644 --- a/README.rst +++ b/README.rst @@ -97,11 +97,12 @@ or a CMM. The examples in this readme use the ``KMSMasterKeyProvider`` class. KMSMasterKeyProvider ==================== -Because the ``KMSMasterKeyProvider`` uses the `boto3 SDK`_ to interact with `AWS KMS`_, it requires AWS Credentials. -To provide these credentials, use the `standard means by which boto3 locates credentials`_ or provide a -pre-existing instance of a ``botocore session`` to the ``KMSMasterKeyProvider``. -This latter option can be useful if you have an alternate way to store your AWS credentials or -you want to reuse an existing instance of a botocore session in order to decrease startup costs. +The ``KMSMasterKeyProvider`` uses the `boto3 SDK`_ to interact with `AWS KMS`_, and thus requires AWS credentials in the form of a ``botocore +session``. There are two ways to provide this: + +1. `Provide your AWS credentials per the boto3 documentation`_, and a ``botocore session`` will be created internally using the `standard means by which boto3 locates credentials`_. + +2. Provide a pre-existing instance of a ``botocore session`` to the ``KMSMasterKeyProvider``. This option can be useful if you have an alternate way of storing your AWS credentials or you want to reuse an existing instance of a botocore session in order to decrease startup costs. This can be done like so: .. code:: python @@ -258,7 +259,8 @@ to your use-case in order to obtain peak performance. .. _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 +.. _Provide your AWS credentials per the boto3 documentation: https://boto3.readthedocs.io/en/latest/guide/configuration.html#credentials +.. _standard means by which boto3 locates credentials: https://boto3.readthedocs.io/en/latest/guide/configuration.html#configuring-credentials .. _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 .. _Security issue notifications: ./CONTRIBUTING.md#security-issue-notifications From 09ea03e145ca6a96ed0025780867a1f9e3d954b4 Mon Sep 17 00:00:00 2001 From: Nisarg Raval Date: Mon, 20 Apr 2020 19:46:30 +0530 Subject: [PATCH 2/5] Readme: Move KMSMasterKeyProvider usage information into its docstring --- README.rst | 51 ------------------ src/aws_encryption_sdk/key_providers/kms.py | 57 ++++++++++++++++++--- 2 files changed, 50 insertions(+), 58 deletions(-) diff --git a/README.rst b/README.rst index 7970341d0..c3e80086e 100644 --- a/README.rst +++ b/README.rst @@ -95,53 +95,6 @@ Usage To use this client, you (the caller) must provide an instance of either a master key provider or a CMM. The examples in this readme use the ``KMSMasterKeyProvider`` class. -KMSMasterKeyProvider -==================== -The ``KMSMasterKeyProvider`` uses the `boto3 SDK`_ to interact with `AWS KMS`_, and thus requires AWS credentials in the form of a ``botocore -session``. There are two ways to provide this: - -1. `Provide your AWS credentials per the boto3 documentation`_, and a ``botocore session`` will be created internally using the `standard means by which boto3 locates credentials`_. - -2. Provide a pre-existing instance of a ``botocore session`` to the ``KMSMasterKeyProvider``. This option can be useful if you have an alternate way of storing your AWS credentials or you want to reuse an existing instance of a botocore session in order to decrease startup costs. This can be done like so: - -.. code:: python - - import aws_encryption_sdk - import botocore.session - - kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider() - - existing_botocore_session = botocore.session.Session() - kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(botocore_session=existing_botocore_session) - - -You can pre-load the ``KMSMasterKeyProvider`` with one or more CMKs. -To encrypt data, you must configure the ``KMSMasterKeyProvider`` with as least one CMK. -If you configure the the ``KMSMasterKeyProvider`` with multiple CMKs, the `final message`_ -will include a copy of the data key encrypted by each configured CMK. - -.. code:: python - - 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' - ]) - -You can add CMKs from multiple regions to the ``KMSMasterKeyProvider``. - -.. code:: python - - 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-west-2:3333333333333:key/33333333-3333-3333-3333-333333333333', - 'arn:aws:kms:ap-northeast-1:4444444444444:key/44444444-4444-4444-4444-444444444444' - ]) - - Encryption and Decryption ========================= After you create an instance of a ``MasterKeyProvider``, you can use either of the two @@ -258,9 +211,5 @@ 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/ -.. _Provide your AWS credentials per the boto3 documentation: https://boto3.readthedocs.io/en/latest/guide/configuration.html#credentials -.. _standard means by which boto3 locates credentials: https://boto3.readthedocs.io/en/latest/guide/configuration.html#configuring-credentials -.. _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 .. _Security issue notifications: ./CONTRIBUTING.md#security-issue-notifications diff --git a/src/aws_encryption_sdk/key_providers/kms.py b/src/aws_encryption_sdk/key_providers/kms.py index c0a2dc46e..5c1c22a46 100644 --- a/src/aws_encryption_sdk/key_providers/kms.py +++ b/src/aws_encryption_sdk/key_providers/kms.py @@ -78,15 +78,50 @@ class KMSMasterKeyProviderConfig(MasterKeyProviderConfig): class KMSMasterKeyProvider(MasterKeyProvider): """Master Key Provider for KMS. - >>> 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' - ... ]) - >>> kms_key_provider.add_master_key('arn:aws:kms:ap-northeast-1:4444444444444:alias/another-key') + .. note:: + The KMSMasterKeyProvider uses the boto3 SDK[1] to interact with AWS KMS[2], + and thus requires AWS credentials in the form of a botocore session. + + There are two ways to provide this: + 1. Provide your AWS credentials per the boto3 documentation[3], + and a botocore session will be created internally using the standard means by which boto3 locates credentials[4]. + 2. Provide a pre-existing instance of a botocore session to the KMSMasterKeyProvider. + This option can be useful if you have an alternate way of storing your AWS credentials, + or if you want to reuse an existing instance of a botocore session in order to decrease startup costs. + This can be done like so: + + >>> import aws_encryption_sdk + >>> import botocore.session + + >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider() + + >>> existing_botocore_session = botocore.session.Session() + >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(botocore_session=existing_botocore_session) + + .. note:: + You can pre-load the KMSMasterKeyProvider with one or more CMKs. + To encrypt data, you must configure the KMSMasterKeyProvider with at least one CMK. + If you configure the the KMSMasterKeyProvider with multiple CMKs, + the final message[5] will include a copy of the data key encrypted by each configured CMK. + + >>> 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' + >>> ]) .. note:: - If no botocore_session is provided, the default botocore session will be used. + You can add CMKs from multiple regions to the KMSMasterKeyProvider. + + >>> 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-west-2:3333333333333:key/33333333-3333-3333-3333-333333333333', + >>> 'arn:aws:kms:ap-northeast-1:4444444444444:key/44444444-4444-4444-4444-444444444444' + >>> ]) + .. note:: If multiple AWS Identities are needed, one of two options are available: @@ -95,6 +130,14 @@ class KMSMasterKeyProvider(MasterKeyProvider): * KMSMasterKey instances may be manually created and added to this KMSMasterKeyProvider. + .. note:: + References: + [1] https://boto3.readthedocs.io/en/latest/ + [2] https://docs.aws.amazon.com/kms/latest/developerguide/overview.html + [3] https://boto3.readthedocs.io/en/latest/guide/configuration.html#credentials + [4] https://boto3.readthedocs.io/en/latest/guide/configuration.html#configuring-credentials + [5] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html + :param config: Configuration object (optional) :type config: aws_encryption_sdk.key_providers.kms.KMSMasterKeyProviderConfig :param botocore_session: botocore session object (optional) From 64fcd9a3f7e1b30000d8ef08ebd8e1066e8a566e Mon Sep 17 00:00:00 2001 From: Nisarg Raval Date: Mon, 20 Apr 2020 19:58:27 +0530 Subject: [PATCH 3/5] Format KMSMasterKeyProvider docstring --- src/aws_encryption_sdk/key_providers/kms.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/aws_encryption_sdk/key_providers/kms.py b/src/aws_encryption_sdk/key_providers/kms.py index f3a39e251..e6061aba4 100644 --- a/src/aws_encryption_sdk/key_providers/kms.py +++ b/src/aws_encryption_sdk/key_providers/kms.py @@ -79,8 +79,8 @@ class KMSMasterKeyProvider(MasterKeyProvider): """Master Key Provider for KMS. .. versionadded:: 1.5.0 - Master key providers are deprecated. - Use :class:`aws_encryption_sdk.keyrings.aws_kms.AwsKmsKeyring` instead. + Master key providers are deprecated. + Use :class:`aws_encryption_sdk.keyrings.aws_kms.AwsKmsKeyring` instead. .. note:: From c69237b717c2380e2cbb303bc86c1b0801d3ab19 Mon Sep 17 00:00:00 2001 From: Nisarg Raval Date: Mon, 20 Apr 2020 20:12:40 +0530 Subject: [PATCH 4/5] Fix pylint max character error in kms.py --- src/aws_encryption_sdk/key_providers/kms.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/aws_encryption_sdk/key_providers/kms.py b/src/aws_encryption_sdk/key_providers/kms.py index e6061aba4..eed5abb26 100644 --- a/src/aws_encryption_sdk/key_providers/kms.py +++ b/src/aws_encryption_sdk/key_providers/kms.py @@ -89,7 +89,8 @@ class KMSMasterKeyProvider(MasterKeyProvider): There are two ways to provide this: 1. Provide your AWS credentials per the boto3 documentation[3], - and a botocore session will be created internally using the standard means by which boto3 locates credentials[4]. + and a botocore session will be created internally + using the standard means by which boto3 locates credentials[4]. 2. Provide a pre-existing instance of a botocore session to the KMSMasterKeyProvider. This option can be useful if you have an alternate way of storing your AWS credentials, or if you want to reuse an existing instance of a botocore session in order to decrease startup costs. From a839503db54d4fc7f2d42975d45f8c5b01dc469e Mon Sep 17 00:00:00 2001 From: Matt Bullock Date: Tue, 21 Apr 2020 15:14:49 -0700 Subject: [PATCH 5/5] docs: copyedit, rst formatting, and rearranging --- src/aws_encryption_sdk/key_providers/kms.py | 113 +++++++++----------- 1 file changed, 52 insertions(+), 61 deletions(-) diff --git a/src/aws_encryption_sdk/key_providers/kms.py b/src/aws_encryption_sdk/key_providers/kms.py index eed5abb26..917819fdb 100644 --- a/src/aws_encryption_sdk/key_providers/kms.py +++ b/src/aws_encryption_sdk/key_providers/kms.py @@ -82,67 +82,58 @@ class KMSMasterKeyProvider(MasterKeyProvider): Master key providers are deprecated. Use :class:`aws_encryption_sdk.keyrings.aws_kms.AwsKmsKeyring` instead. - - .. note:: - The KMSMasterKeyProvider uses the boto3 SDK[1] to interact with AWS KMS[2], - and thus requires AWS credentials in the form of a botocore session. - - There are two ways to provide this: - 1. Provide your AWS credentials per the boto3 documentation[3], - and a botocore session will be created internally - using the standard means by which boto3 locates credentials[4]. - 2. Provide a pre-existing instance of a botocore session to the KMSMasterKeyProvider. - This option can be useful if you have an alternate way of storing your AWS credentials, - or if you want to reuse an existing instance of a botocore session in order to decrease startup costs. - This can be done like so: - - >>> import aws_encryption_sdk - >>> import botocore.session - - >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider() - - >>> existing_botocore_session = botocore.session.Session() - >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(botocore_session=existing_botocore_session) - - .. note:: - You can pre-load the KMSMasterKeyProvider with one or more CMKs. - To encrypt data, you must configure the KMSMasterKeyProvider with at least one CMK. - If you configure the the KMSMasterKeyProvider with multiple CMKs, - the final message[5] will include a copy of the data key encrypted by each configured CMK. - - >>> 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' - >>> ]) - - .. note:: - You can add CMKs from multiple regions to the KMSMasterKeyProvider. - - >>> 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-west-2:3333333333333:key/33333333-3333-3333-3333-333333333333', - >>> 'arn:aws:kms:ap-northeast-1:4444444444444:key/44444444-4444-4444-4444-444444444444' - >>> ]) - - - .. note:: - If multiple AWS Identities are needed, one of two options are available: - - * Additional KMSMasterKeyProvider instances may be added to the primary MasterKeyProvider. - - * KMSMasterKey instances may be manually created and added to this KMSMasterKeyProvider. - - .. note:: - References: - [1] https://boto3.readthedocs.io/en/latest/ - [2] https://docs.aws.amazon.com/kms/latest/developerguide/overview.html - [3] https://boto3.readthedocs.io/en/latest/guide/configuration.html#credentials - [4] https://boto3.readthedocs.io/en/latest/guide/configuration.html#configuring-credentials - [5] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html + 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", + ... ]) + + :class:`KMSMasterKeyProvider` needs AWS credentials in order to interact with `AWS KMS`_. + 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() + + 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. + + >>> 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) + + 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