awssig.sigv4 — AWS signature version 4

This module provides support for verifying AWS calls made using the SigV4 algorithm.

Class AWSSigV4Verifier

Verify an AWS SigV4 signature.

AWSSigV4Verifier(request_method, uri_path, query_string, headers,
body, region, service, key_mapping, timestamp_mismatch=60)

Create a new AWSSigV4Verifier instance.

Parameters
  • request_method (str) – The HTTP method used to make the call. Typically “GET”, “POST”, “PUT”, “DELETE”, or “LIST”.

  • uri_path (str) – The path to the request. Typically “/”, but might be a filesystem-style path (“/folder/subfolder/object”) for S3-style requests.

  • query_string (str) – Query parameters supplied to the call (the part after the ‘?’). This must be the empty string (“”) if no query parameters were supplied.

  • headers (dict) – A dictionary of string keys and iterable of string values of the HTTP headers supplied in the request.

  • body (bytes) – The request body. This must be an empty bytes object (b””) if no body was supplied (even for GET, DELETE, and LIST requests). Note that this must be a bytes object in Python 3.

  • region (str) – The region the service is operating in (e.g. “us-east-1”).

  • service (str) – The name of the service being accessed.

  • key_mapping (Callable[str, [str, Optional[str]]) – A callable that is invoked to return a secret key given an access key and an optional session token.

  • timestamp_mismatch (int or None) – The allowable mismatch in the timestamp submitted for the request in seconds. If None, timestamp checking is disabled.

Raises

TypeError – if request_method, uri_path, query_string, region, or service are not strings; body is not a string (Python 2) or bytes (Python 3); or headers is not a dict containg string keys and string values.

AWSSigV4Verifier.verify()

Verifies that the request is properly signed.

Returns

True when the request is properly signed.

Raises

awssig.exc.InvalidSignatureError – if the request is not properly signed.

AWSSigV4Verifier.access_key

The access key used to sign the request.

If the access key was not provided or is not in the same credential scope as this request, an AttributeError exception is raised.

AWSSigV4Verifier.authorization_header_parameter

The authorization header, either from the HTTP “Authorization” header. If this header is not present, is present multiple times, or does not begin with “AWS4-HMAC-SHA256”, an AttributeError exception is raised.

AWSSigV4Verifier.canonical_query_string

The canonicalized form of the query string as documented in creating canonical requests. Note that the X-Amz-Signature parameter (if provided) is removed from this string.

AWSSigV4Verifier.canonical_request

The AWS SigV4 canonical request given parameters from an HTTP request, as described in the creating canonical requests document.

If an attribute required to compute the canonical request is not present (request_method, canonical_uri_path, canonical_query_string, or signed_headers), an AttributeError exception is propagated.

AWSSigV4Verifier.canonical_uri_path

A string containing the canonical URI according to RFC 3986. Redundant (“//”) and relative (“/../”, “/./”) path components are removed.

AWSSigV4Verifier.credential_scope

The scope of the credentials to use.

This is the request date, region, service, and the string “aws4_request” joined with slashes (‘/’).

AWSSigV4Verifier.expected_signature

The AWS SigV4 signature expected from the request, as described in the calculating the signature document.

If an attribute required to compute the signature is not present (access_key, request_date, region, or service), an AttributeError exception is propagated.

If the corresponding secret key for the access_key is not found, a KeyError exception is propagated.

AWSSigV4Verifier.headers

A dictionary containing all headers provided in the request.

AWSSigV4Verifier.query_parameters

A dictionary of query parameter names to a list of the values seen.

AWSSigV4Verifier.request_date

The date of the request in ISO8601 YYYYMMDD format.

If this is not available in the query parameters or headers, or the value is not a valid format for AWS SigV4, an AttributeError exception is raised.

AWSSigV4Verifier.request_signature

The request signature passed in the request, either from the X-Amz-Signature query parameter or the Authorization HTTP header.

If neither of these is present, an AttributeError exception is raised.

AWSSigV4Verifier.request_timestamp

The timestamp of the request in ISO8601 YYYYMMDD’T’HHMMSS’Z’ format.

If this is not available in the query parameters or headers, or the value is not a valid format for AWS SigV4, an AttributeError exception is raised.

AWSSigV4Verifier.signed_headers

An ordered dictionary containing the header names and values used to sign the request.

AWSSigV4Verifier.string_to_sign

The AWS SigV4 string being signed, as described in the calculating the string to sign document.

If an attribute required to compute the string to sign is not present (request_timestamp, credential_scope, or canonical_request), an AttributeError exception is propagated.

AWSSigV4Verifier.timestamp_mismatch

The allowable mismatch, in seconds, between the date in the request (and, thus, used to sign the request) and the current time, or None. If None, any timestamp is allowed. This should be used for testing only.

Class AWSSigV4S3Verifier

Variant of AWS SigV4 for S3-style authentication. This class inherits from AWSSigV4Verifier and provides the same constructor.

Compared to regular SigV4, SigV43 has the following differences:

  1. Consecutive slashes in URI paths are preserved: “/a//b” is a distinct object from “/a/b”.

  2. The x-amz-content-sha256 header must be present and set to either the SHA-256 checksum of the content (uploaded in a single chunk), "UNSIGNED-PAYLOAD", or "STREAMING-AWS4-HMAC-SHA256-PAYLOAD".

AWSSigV4S3Verifier.canonical_uri_path

The canonicalized URI path from the request, but with multiple slashes and dots preserved. All other characters are replaced according to RFC 3986.

AWSSigV4S3Verifier.canonical_request

The AWS SigV4S3 canonical request given parameters from an HTTP request. This is similar to the standard AWS SigV4 canonical request, but allows for the replacement of the final digest line with the literal UNSIGNED-PAYLOAD or STREAMING-AWS4-HMAC-SHA256-PAYLOAD, corresponding to the value of the (required) x-amz-content-sha256 header.

If an attribute required to compute the canonical request is not present (request_method, canonical_uri_path, canonical_query_string, or signed_headers), an AttributeError exception is propagated.

Utility Functions

awssig.sigv4.normalize_uri_path_component(path_component)

Normalize the path component according to RFC 3986. This performs the following operations:

  • Alpha, digit, and the symbols ‘-‘, ‘.’, ‘_’, and ‘~’ (unreserved characters) are left alone.

  • Characters outside this range are percent-encoded.

  • Percent-encoded values are upper-cased (‘%2a’ becomes ‘%2A’)

  • Percent-encoded values in the unreserved space (%41-%5A, %61-%7A, %30-%39, %2D, %2E, %5F, %7E) are converted to normal characters.

If a percent encoding is incomplete, the percent is encoded as %25.

Parameters

path_component (str) – The path component to normalize.

Returns

the normalized path component

Return type

str

Raises

ValueError – if a percent encoding includes non-hex characters (e.g. %3z)

get_canonical_uri_path(uri_path):

Normalizes the specified URI path component, removing redundant slashes and relative path components.

Parameters

uri_path (str) – The URI path to normalize.

Returns

the normalized path component

Return type

str

Raises

ValueError – If any of the following occurs: * The URI path is not empty and not absolute (does not start with ‘/’). * A parent relative path element (‘..’) attempts to go beyond the top. * An invalid percent-encoding is encountered.

normalize_query_parameters(query_string):

Converts a query string into a dictionary mapping parameter names to a list of the sorted values. This ensurses that the query string follows % encoding rules according to RFC 3986 and checks for duplicate keys.

Parameters

query_string (str) – The query string to normalize.

Returns

the normalized query string

Return type

str

Raises

ValueError – if a percent encoding is invalid.