From a20a00060100ce98ef2c95b2a1e7b21e4365a497 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Lipt=C3=A1k?= Date: Thu, 16 Feb 2023 19:03:10 -0500 Subject: [PATCH 1/5] docs: Add Thread safety section to README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Gábor Lipták --- README.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.rst b/README.rst index b9acc3edc..db2407427 100644 --- a/README.rst +++ b/README.rst @@ -307,6 +307,11 @@ Processing each frame in a framed message involves a certain amount of overhead. increasing the frame size can offer potentially significant performance gains. We recommend that you tune these values to your use-case in order to obtain peak performance. +Thread safety +========================== +The clients are all thread safe, yes, with one minor qualifier. Instances of `KMSMasterKeyProvider` should not be shared between threads, for the reasons outlined in the `boto3 docs `_ . We do create `new boto3 sessions `_ for each `KMSMasterKeyProvider` instance regional client, so you don't need to worry about issues below that level. As long as you create a new `KMSMasterKeyProvider` for each thread, you should be fine. + +If you are using data key caching, however, caches can be shared across threads without issue, though if you want to share entries in that cache across threads you will need to be careful (see explanation about `partition name `_ ). .. _AWS Encryption SDK: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html .. _cryptography: https://cryptography.io/en/latest/ From 3c73f4d77931bc7348f1251523bf1bf8bb7ed117 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Lipt=C3=A1k?= Date: Tue, 21 Feb 2023 20:41:59 -0500 Subject: [PATCH 2/5] Update README.rst Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- README.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index db2407427..38f6b76ec 100644 --- a/README.rst +++ b/README.rst @@ -309,7 +309,15 @@ to your use-case in order to obtain peak performance. Thread safety ========================== -The clients are all thread safe, yes, with one minor qualifier. Instances of `KMSMasterKeyProvider` should not be shared between threads, for the reasons outlined in the `boto3 docs `_ . We do create `new boto3 sessions `_ for each `KMSMasterKeyProvider` instance regional client, so you don't need to worry about issues below that level. As long as you create a new `KMSMasterKeyProvider` for each thread, you should be fine. +The `EncryptionSDKClient` and all provided`CryptoMaterialsManager` are thread safe. +But instances of `BaseKMSMasterKeyProvider` MUST not be shared between threads, +for the reasons outlined in (the boto3 docs)[https://boto3.amazonaws.com/v1/documentation/api/latest/guide/resources.html#multithreading-or-multiprocessing-with-resources]. + +Because the `BaseKMSMaterKeyProvider` creates a [new boto3 sessions](https://github.com/aws/aws-encryption-sdk-python/blob/08f305a9b7b5fc897d9cafac55fb98f3f2a6fe13/src/aws_encryption_sdk/key_providers/kms.py#L665-L674) per region, +users do not need to create a client for every region in every thread; +a new `BaseKMSMasterKeyProvider` per thread is sufficient. + +(The `BaseKMSMasterKeyProvider` is the internal parent class of all the KMS Providers.) If you are using data key caching, however, caches can be shared across threads without issue, though if you want to share entries in that cache across threads you will need to be careful (see explanation about `partition name `_ ). From 1e159ba56c69a0a500cf8b775e168318595dbc3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Lipt=C3=A1k?= Date: Tue, 21 Feb 2023 20:42:35 -0500 Subject: [PATCH 3/5] Update README.rst Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- README.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 38f6b76ec..53db3b19a 100644 --- a/README.rst +++ b/README.rst @@ -319,7 +319,9 @@ a new `BaseKMSMasterKeyProvider` per thread is sufficient. (The `BaseKMSMasterKeyProvider` is the internal parent class of all the KMS Providers.) -If you are using data key caching, however, caches can be shared across threads without issue, though if you want to share entries in that cache across threads you will need to be careful (see explanation about `partition name `_ ). +Finally, while the `CryptoMaterialsCache` is thread safe, +sharing entries in that cache across threads needs to be done carefully +(see the !Note about partition name [in the API Docs](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.materials_managers.caching.html#aws_encryption_sdk.materials_managers.caching.CachingCryptoMaterialsManager)). .. _AWS Encryption SDK: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html .. _cryptography: https://cryptography.io/en/latest/ From f76ce66ca55785fd7c083d4587f2ed1cd2851595 Mon Sep 17 00:00:00 2001 From: Tony Knapp <5892063+texastony@users.noreply.github.com> Date: Thu, 23 Feb 2023 09:57:16 -0800 Subject: [PATCH 4/5] fix: README is rst, not md --- README.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 53db3b19a..903a81b2a 100644 --- a/README.rst +++ b/README.rst @@ -309,19 +309,19 @@ to your use-case in order to obtain peak performance. Thread safety ========================== -The `EncryptionSDKClient` and all provided`CryptoMaterialsManager` are thread safe. -But instances of `BaseKMSMasterKeyProvider` MUST not be shared between threads, -for the reasons outlined in (the boto3 docs)[https://boto3.amazonaws.com/v1/documentation/api/latest/guide/resources.html#multithreading-or-multiprocessing-with-resources]. +The ``EncryptionSDKClient`` and all provided ``CryptoMaterialsManager`` are thread safe. +But instances of ``BaseKMSMasterKeyProvider`` MUST not be shared between threads, +for the reasons outlined in `the boto3 docs `_. -Because the `BaseKMSMaterKeyProvider` creates a [new boto3 sessions](https://github.com/aws/aws-encryption-sdk-python/blob/08f305a9b7b5fc897d9cafac55fb98f3f2a6fe13/src/aws_encryption_sdk/key_providers/kms.py#L665-L674) per region, +Because the ``BaseKMSMaterKeyProvider`` creates a `new boto3 sessions `_ per region, users do not need to create a client for every region in every thread; -a new `BaseKMSMasterKeyProvider` per thread is sufficient. +a new ``BaseKMSMasterKeyProvider`` per thread is sufficient. -(The `BaseKMSMasterKeyProvider` is the internal parent class of all the KMS Providers.) +(The ``BaseKMSMasterKeyProvider`` is the internal parent class of all the KMS Providers.) -Finally, while the `CryptoMaterialsCache` is thread safe, +Finally, while the ``CryptoMaterialsCache`` is thread safe, sharing entries in that cache across threads needs to be done carefully -(see the !Note about partition name [in the API Docs](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.materials_managers.caching.html#aws_encryption_sdk.materials_managers.caching.CachingCryptoMaterialsManager)). +(see the !Note about partition name `in the API Docs `_). .. _AWS Encryption SDK: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html .. _cryptography: https://cryptography.io/en/latest/ From aba6bcedaaea769bdf294f474215e41e4b39ce78 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Thu, 23 Feb 2023 10:05:21 -0800 Subject: [PATCH 5/5] fix: README.rst must pass doc8 --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 903a81b2a..f526f2727 100644 --- a/README.rst +++ b/README.rst @@ -310,7 +310,7 @@ to your use-case in order to obtain peak performance. Thread safety ========================== The ``EncryptionSDKClient`` and all provided ``CryptoMaterialsManager`` are thread safe. -But instances of ``BaseKMSMasterKeyProvider`` MUST not be shared between threads, +But instances of ``BaseKMSMasterKeyProvider`` MUST not be shared between threads, for the reasons outlined in `the boto3 docs `_. Because the ``BaseKMSMaterKeyProvider`` creates a `new boto3 sessions `_ per region, @@ -319,7 +319,7 @@ a new ``BaseKMSMasterKeyProvider`` per thread is sufficient. (The ``BaseKMSMasterKeyProvider`` is the internal parent class of all the KMS Providers.) -Finally, while the ``CryptoMaterialsCache`` is thread safe, +Finally, while the ``CryptoMaterialsCache`` is thread safe, sharing entries in that cache across threads needs to be done carefully (see the !Note about partition name `in the API Docs `_).