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.
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
, orsigned_headers
), anAttributeError
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
, orservice
), anAttributeError
exception is propagated.If the corresponding secret key for the
access_key
is not found, aKeyError
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 theAuthorization
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
, orcanonical_request
), anAttributeError
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:
Consecutive slashes in URI paths are preserved: “/a//b” is a distinct object from “/a/b”.
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
orSTREAMING-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
, orsigned_headers
), anAttributeError
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.