.. index:: single: s3_signing .. _s3_signing/0: .. rst-class:: right **object** ``s3_signing`` ============== AWS Signature Version 4 helpers specialized for S3. | **Availability:** | ``logtalk_load(s3(loader))`` | **Author:** Paulo Moura | **Version:** 1:0:0 | **Date:** 2026-07-09 | **Compilation flags:** | ``static, context_switching_calls`` | **Imports:** | ``public`` :ref:`options ` | **Uses:** | :ref:`date ` | :ref:`hmac ` | :ref:`http_core ` | :ref:`list ` | :ref:`os ` | :ref:`sha256 ` | :ref:`term_io ` | :ref:`user ` | **Remarks:** | (none) | **Inherited public predicates:** |  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`   .. contents:: :local: :backlinks: top Public predicates ----------------- .. index:: payload_hash/2 .. _s3_signing/0::payload_hash/2: ``payload_hash/2`` ^^^^^^^^^^^^^^^^^^ Returns the hexadecimal SHA-256 payload hash for a normalized HTTP body term. | **Compilation flags:** | ``static`` | **Template:** | ``payload_hash(Body,Hash)`` | **Mode and number of proofs:** | ``payload_hash(+compound,-atom)`` - ``one_or_error`` | **Exceptions:** | ``Body`` is not a valid normalized HTTP body term: | ``domain_error(http_body,Body)`` | No registered HTTP body codec exists for the body media type when codec-based encoding is required: | ``existence_error(http_body_codec,MediaType)`` ------------ .. index:: canonical_query/2 .. _s3_signing/0::canonical_query/2: ``canonical_query/2`` ^^^^^^^^^^^^^^^^^^^^^ Returns the canonical AWS SigV4 query string for the given name-value pairs. | **Compilation flags:** | ``static`` | **Template:** | ``canonical_query(Pairs,Query)`` | **Mode and number of proofs:** | ``canonical_query(+list(pair),-atom)`` - ``one_or_error`` | **Exceptions:** | ``Pairs`` is not a valid list of canonical query pairs: | ``domain_error(s3_query_pairs,Pairs)`` ------------ .. index:: canonical_request/6 .. _s3_signing/0::canonical_request/6: ``canonical_request/6`` ^^^^^^^^^^^^^^^^^^^^^^^ Builds the canonical request string for the given method, URI, query pairs, signed headers, and payload hash. | **Compilation flags:** | ``static`` | **Template:** | ``canonical_request(Method,CanonicalURI,QueryPairs,Headers,PayloadHash,CanonicalRequest)`` | **Mode and number of proofs:** | ``canonical_request(+atom,+atom,+list(pair),+list(compound),+atom,-atom)`` - ``one_or_error`` | **Exceptions:** | ``Method`` is not a supported HTTP method for this helper: | ``domain_error(s3_method,Method)`` | ``QueryPairs`` is not a valid list of canonical query pairs: | ``domain_error(s3_query_pairs,QueryPairs)`` ------------ .. index:: sign_request/8 .. _s3_signing/0::sign_request/8: ``sign_request/8`` ^^^^^^^^^^^^^^^^^^ Signs an S3 request and returns the final normalized header list. | **Compilation flags:** | ``static`` | **Template:** | ``sign_request(Method,HostHeader,CanonicalURI,QueryPairs,Body,Headers,SignedHeaders,Options)`` | **Mode and number of proofs:** | ``sign_request(+atom,+atom,+atom,+list(pair),+compound,+list(compound),-list(compound),+list(compound))`` - ``one_or_error`` | **Exceptions:** | ``Options`` is missing valid credentials: | ``domain_error(s3_credentials,missing)`` | ``Body`` is not a valid normalized HTTP body term: | ``domain_error(http_body,Body)`` | ``Headers`` contains a managed or invalid signed header: | ``domain_error(s3_managed_header,Header)`` | The signing timestamp is invalid: | ``domain_error(s3_amz_date,AmzDate)`` | **Remarks:** - Option ``credentials/1``: Required access credentials as ``credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey))``. - Option ``session_token/1``: Optional session token for temporary credentials. - Option ``region/1``: AWS region for the credential scope. Defaults to ``us-east-1``. - Option ``payload_hash_mode/1``: Payload signing mode, either ``signed`` or ``unsigned``. Defaults to ``signed``. - Option ``request_time/1``: Optional explicit local request time as ``date_time(Year, Month, Day, Hours, Minutes, Seconds)``. - Option ``utc_offset_seconds/1``: UTC offset used to derive the signing time from the local clock. Defaults to ``0``. - Option ``amz_date/1``: Optional explicit AWS SigV4 timestamp overriding any derived request time. ------------ .. index:: presigned_query_pairs/7 .. _s3_signing/0::presigned_query_pairs/7: ``presigned_query_pairs/7`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Signs an S3 request for query-string authentication and returns the final canonical query pairs, including the signature. | **Compilation flags:** | ``static`` | **Template:** | ``presigned_query_pairs(Method,HostHeader,CanonicalURI,QueryPairs,Headers,SignedQueryPairs,Options)`` | **Mode and number of proofs:** | ``presigned_query_pairs(+atom,+atom,+atom,+list(pair),+list(compound),-list(pair),+list(compound))`` - ``one_or_error`` | **Exceptions:** | ``Options`` is missing valid credentials: | ``domain_error(s3_credentials,missing)`` | ``Headers`` contains a managed or invalid signed header: | ``domain_error(s3_managed_header,Header)`` | The signing timestamp is invalid: | ``domain_error(s3_amz_date,AmzDate)`` | The expiration is invalid or outside the AWS SigV4 range: | ``domain_error(s3_presign_expires,Expires)`` | The payload hash is missing, invalid, or incompatible with unsigned mode: | ``domain_error(s3_presign_payload_hash,Hash)`` | **Remarks:** - Option ``credentials/1``: Required access credentials as ``credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey))``. - Option ``session_token/1``: Optional session token for temporary credentials. It is emitted as the ``X-Amz-Security-Token`` query parameter. - Option ``region/1``: AWS region for the credential scope. Defaults to ``us-east-1``. - Option ``payload_hash_mode/1``: Presigned URLs default to ``unsigned`` payload hashing and use ``UNSIGNED-PAYLOAD``. Use ``signed`` together with ``payload_hash/1`` to sign a precomputed payload hash. - Option ``payload_hash/1``: Precomputed hexadecimal SHA-256 payload hash required when ``payload_hash_mode(signed)`` is selected. - Option ``request_time/1``: Optional explicit local request time as ``date_time(Year, Month, Day, Hours, Minutes, Seconds)``. - Option ``utc_offset_seconds/1``: UTC offset used to derive the signing time from the local clock. Defaults to ``0``. - Option ``amz_date/1``: Optional explicit AWS SigV4 timestamp overriding any derived request time. - Option ``expires/1``: Presigned URL lifetime in seconds. Defaults to ``900`` and must not exceed ``604800``. ------------ Protected predicates -------------------- (no local declarations; see entity ancestors if any) Private predicates ------------------ (no local declarations; see entity ancestors if any) Operators --------- (none)