docs: clarify KMSMasterKeyProvider credentials configuration (#251)

* Readme: Update KMSMasterKeyProvider credentials configuration for better understanding

* Readme: Move KMSMasterKeyProvider usage information into its docstring

* Format KMSMasterKeyProvider docstring

* Fix pylint max character error in kms.py

* docs: copyedit, rst formatting, and rearranging

Co-authored-by: Matt Bullock <bullocm@amazon.com>

Author: nraval1729

README.rst

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

src/aws_encryption_sdk/key_providers/kms.py

@@ -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`_.
+    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