docs: clarify GetObject stream ContentLength is not plaintext length - #211
Open
reginaldalfret wants to merge 1 commit into
Open
reginaldalfret wants to merge 1 commit into
reginaldalfret wants to merge 1 commit into
Conversation
Fixes aws#164 Clarify in the README, Sphinx documentation (docs/index.rst), and API docstrings (S3EncryptionClient.get_object, on_get_object_after_call, and GetEncryptedObjectPipeline.decrypt) that the ContentLength in the response dictionary returned by get_object corresponds to the ciphertext stream length stored in S3 (which includes the cryptographic authentication tag or CBC padding), rather than the decrypted plaintext length. Callers must read the entire stream (e.g. via response['Body'].read()) to ensure complete decryption and authentication verification.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #164
Summary
Clarifies in documentation and docstrings that the
ContentLengthin the response returned byget_objectreflects the length of the ciphertext stream stored in S3 (which includes the cryptographic authentication tag, e.g. 16 bytes for AES-GCM, or cipher padding for CBC mode), rather than the decrypted plaintext length.Customers and callers should always read the entire stream (
response["Body"].read()) to ensure complete decryption and cryptographic authentication verification rather than relying onContentLengthas the plaintext length.Changes
README.md: Added a note under Getting Started detailing the distinction between stream length (ContentLength) and decrypted plaintext length.docs/index.rst: Added a Sphinx note block covering stream length vs plaintext length and the requirement to read the full stream.src/s3_encryption/__init__.py:Note:section toS3EncryptionClient.get_objectdocstring explaining theContentLengthsemantics.on_get_object_after_calldocstring.src/s3_encryption/pipelines.py: UpdatedGetEncryptedObjectPipeline.decryptdocstring to document that the surrounding response'sContentLengthis the ciphertext stream length.Verification
ruff check srcpassed clean (including docstring style rules).ruff format --check srcpassed clean.pytest test --ignore test/integration --ignore test/performance): 324 passed.git diff --checkpassed clean with zero whitespace issues.