From e98be9a48d35ce98ae5c3643f3bb18b387e262fb Mon Sep 17 00:00:00 2001 From: Jaykumar Gosar Date: Mon, 16 Sep 2024 16:38:06 -0700 Subject: [PATCH] Update the httpChecksum trait spec --- docs/source-2.0/aws/aws-core.rst | 84 ++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 30 deletions(-) diff --git a/docs/source-2.0/aws/aws-core.rst b/docs/source-2.0/aws/aws-core.rst index 44b5ea64470..fb961d89023 100644 --- a/docs/source-2.0/aws/aws-core.rst +++ b/docs/source-2.0/aws/aws-core.rst @@ -932,23 +932,21 @@ The ``httpChecksum`` trait is a structure that contains the following members: * - requestAlgorithmMember - ``string`` - Defines a top-level operation input member that is used to configure - request checksum behavior. The input member MUST target a string shape - marked with the :ref:`enum-trait`. Each value in the enum represents a - supported checksum algorithm. Algorithms MUST be one of the following - supported values: "CRC64NVME", "CRC32C", "CRC32", "SHA1", or "SHA256". + request checksum behavior. The input member MUST target an :ref:`enum` + shape. Each value in the enum represents a supported checksum + algorithm. Algorithms MUST be one of the following supported values: + "CRC64NVME", "CRC32C", "CRC32", "SHA1", or "SHA256". * - requestChecksumRequired - ``boolean`` - - Indicates an operation requires a checksum in its HTTP request. By - default, the checksum used for a service is an MD5 checksum passed - in the Content-MD5 header. When the input member represented by the - ``requestAlgorithmMember`` property is set, the default behavior is - disabled. + - Indicates an operation requires a checksum in its HTTP request. If the + input member represented by``requestAlgorithmMember`` property is not + set, the client uses its default algorithm. * - requestValidationModeMember - ``string`` - - Defines a top-level operation input member used to opt-in to - best-effort validation of a checksum returned in the HTTP response of - the operation. The input member MUST target a string shape marked with - the :ref:`enum-trait` that contains the value "ENABLED". + - Defines a top-level operation input member used to opt-in to validation + of a checksum returned in the HTTP response of the operation. The input + member MUST target an :ref:`enum` shape that contains the value + "ENABLED". * - responseAlgorithms - ``set`` - Defines the checksum algorithms clients SHOULD look for when validating @@ -1027,18 +1025,33 @@ behavior, will fail validation. Client behavior =============== +Supported checksum algorithms +----------------------------- +The following checksum algorithms MUST be supported by clients. + * CRC32 + * SHA1 + * SHA256 + +Additionally, the following checksum algorithms SHOULD be supported by clients. + * CRC64NVME + * CRC32C + HTTP request checksums ---------------------- -When a client calls an operation which has the ``httpChecksum`` trait where -``requestChecksumRequired`` is set to ``true``, the client MUST include a -checksum in the HTTP request. +By default, when a client calls an operation which has the ``httpChecksum`` +trait, the client MUST include a checksum in the HTTP request, unless the +client is configured to only include checksum when ``requestChecksumRequired`` +is set to ``true``. When a client calls an operation which has the ``httpChecksum`` trait where ``requestAlgorithmMember`` is set, the client MUST look up the input member represented by ``requestAlgorithmMember`` property. The value of this member is the checksum algorithm that the client MUST use to compute the request payload -checksum. +checksum. If the client does not support that algorithm, it MUST fail the +request. If the user did not set a value for the input member represented by +``requestAlgorithmMember``, the client MUST use its default algorithm and +implicitly set that value in ``requestAlgorithmMember``. The computed checksum MUST be supplied at a resolved location as per the :ref:`resolving checksum location ` @@ -1049,29 +1062,35 @@ of the body. The header or trailer name to use with an algorithm is resolved as per the :ref:`resolving checksum name ` section. -If no ``requestAlgorithmMember`` property is set, the client MUST compute an -MD5 checksum of the request payload and place it in the ``Content-MD5`` header. +If no ``requestAlgorithmMember`` property is set in the trait and +``requestChecksumRequired`` is set to ``true``, the client MUST compute an MD5 +checksum of the request payload and place it in the ``Content-MD5`` header. If the HTTP header corresponding to a checksum is set explicitly, the client MUST use the explicitly set header and skip computing the payload checksum. -.. seealso:: See :ref:`client behavior` - for more details. - HTTP response checksums ----------------------- +When a client calls an operation which has the ``httpChecksum`` trait, the +client MUST look up the input member represented by the +``requestValidationModeMember`` property. If the user did not set a value for +this member, by default the client MUST implicitly set it to ``ENABLED``, +unless the client is configured to opt-out of this default behavior. + When a client receives a response for an operation which has the ``httpChecksum`` trait where the ``requestValidationModeMember`` property is set, the client MUST look up the input member represented by the property's value. If the input -member is set to ``ENABLED``, the client MUST perform best-effort validation of -checksum values returned in the HTTP response. +member is set to ``ENABLED``, the client MUST perform validation of checksum +returned in the HTTP response. A client MUST use the list of supported algorithms modeled in the -``responseAlgorithms`` property to look up the checksum(s) for which validation -MUST be performed. The client MUST look for the HTTP header in the response as -per the :ref:`resolving checksum name ` -section. +``responseAlgorithms`` property and filter it for the algorithms supported by +the client to look up the checksum(s) for which validation MUST be performed. +The client MUST look for the HTTP header in the response as per the +:ref:`resolving checksum name ` +section. From the available headers in the response, the client MUST pick only +one checksum to validate. A client MUST raise an error if the response checksum to validate does not match computed checksum of the response payload for the same checksum algorithm. @@ -1098,7 +1117,12 @@ property are set, the service MUST validate an HTTP request checksum. When a service receives a request where the ``requestAlgorithmMember`` is set, the service MUST look up the input member represented by the checksum ``requestAlgorithmMember`` property. The value of this member is the checksum -algorithm that the service MUST use to compute a checksum of the request payload. +algorithm that the service MUST use to compute a checksum of the request +payload. If the value of this member is not set, the service MUST look for the +HTTP headers in the request as per the +:ref:`resolving checksum name ` +section. From the available headers in the request, the service MUST pick only +one checksum to validate. The computed checksum MUST be validated against the checksum supplied at a resolved location as per the :ref:`resolving checksum location @@ -1114,7 +1138,7 @@ header. When using the ``httpChecksum`` trait, services MUST always accept checksum values in HTTP headers. For operations with streaming payload input, services MUST additionally accept checksum values sent in the `chunked trailer part`_ of -the request body. Service MUST only send response checksums in HTTP headers. +the request body. HTTP response checksums -----------------------