Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
import datetime as dt
import hashlib
import pytest
from ministack.core.sigv4 import (
build_canonical_headers,
build_canonical_query_string,
build_canonical_request,
build_string_to_sign,
calculate_signature,
derive_signing_key,
header_signature_failure,
header_signing_documents,
parse_header_signature,
parse_query_signature,
presigned_request_is_expired,
region_set_covers,
request_time_failure,
signatures_match,
sigv4a_signature_matches,
sigv4a_signing_key,
uri_encode,
)
@pytest.mark.parametrize(
"value, encode_slash, expected",
[
("abcXYZ012-_.~", True, "abcXYZ012-_.~"),
("space + percent%", True, "space%20%2B%20percent%25"),
("folder/object", True, "folder%2Fobject"),
("folder/object", False, "folder/object"),
("caf\N{LATIN SMALL LETTER E WITH ACUTE}", True, "caf%C3%A9"),
],
)
def test_uri_encode_uses_sigv4_rules(value, encode_slash, expected):
assert uri_encode(value, encode_slash=encode_slash) == expected
def test_build_canonical_query_string_encodes_sorts_and_excludes_signature():
query_params = {
"space key": ["b/a", "a+b"],
"Action": "connect",
"X-Amz-Signature": "not-part-of-the-canonical-query",
}
assert build_canonical_query_string(query_params) == (
"Action=connect&space%20key=a%2Bb&space%20key=b%2Fa"
)
def test_build_canonical_query_string_accepts_custom_exclusions():
query_params = {"Action": "connect", "DBUser": "alice", "Nonce": "123"}
assert build_canonical_query_string(query_params, exclude=("nonce",)) == "Action=connect&DBUser=alice"
def test_build_canonical_headers_normalizes_names_and_values():
headers = {
"host": "examplebucket.s3.amazonaws.com",
"x-custom": " spaced\t value ",
}
assert build_canonical_headers(headers, "host;x-custom") == (
"host:examplebucket.s3.amazonaws.com\n"
"x-custom:spaced value\n"
)
def test_build_canonical_request_matches_fixed_vector():
query_params = {
"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
"X-Amz-Credential": "AKIDEXAMPLE/20130524/us-east-1/s3/aws4_request",
"X-Amz-Date": "20130524T000000Z",
"X-Amz-Expires": "86400",
"X-Amz-SignedHeaders": "host",
"X-Amz-Signature": "excluded",
}
assert build_canonical_request(
"GET",
"/test.txt",
{"host": "examplebucket.s3.amazonaws.com"},
query_params,
"host",
) == (
"GET\n"
"/test.txt\n"
"X-Amz-Algorithm=AWS4-HMAC-SHA256&"
"X-Amz-Credential=AKIDEXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&"
"X-Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host\n"
"host:examplebucket.s3.amazonaws.com\n"
"\n"
"host\n"
"UNSIGNED-PAYLOAD"
)
def test_signing_helpers_match_botocore_fixed_vector():
canonical_request = (
"GET\n"
"/test.txt\n"
"X-Amz-Algorithm=AWS4-HMAC-SHA256&"
"X-Amz-Credential=AKIDEXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&"
"X-Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host\n"
"host:examplebucket.s3.amazonaws.com\n"
"\n"
"host\n"
"UNSIGNED-PAYLOAD"
)
string_to_sign = build_string_to_sign(
"20130524T000000Z",
"20130524",
"us-east-1",
"s3",
canonical_request,
)
assert string_to_sign == (
"AWS4-HMAC-SHA256\n"
"20130524T000000Z\n"
"20130524/us-east-1/s3/aws4_request\n"
"fe76c9a452b5c779479d88b7efe53bc3935d1a56dd76e83e930f401e91272d73"
)
assert derive_signing_key(
"wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY",
"20130524",
"us-east-1",
"s3",
).hex() == "f117494eff5d09da21cbf7f0339559ea04fc9582d31299cb992be70a6b27c97a"
assert calculate_signature(
"wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY",
"20130524",
"us-east-1",
"s3",
string_to_sign,
) == "ca6159ff16837c055653a722d9f10b6a529b7c62c84174a2859958324bc78766"
# AWS's published SigV4a test vector "get-vanilla" (aws-c-auth v4a signing test suite).
_V4A_KEY_ID, _V4A_SECRET = "AKIDEXAMPLE", "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY"
_V4A_HEADERS = {
"host": "example.amazonaws.com",
"x-amz-date": "20150830T123600Z",
"x-amz-region-set": "us-east-1",
"authorization": (
"AWS4-ECDSA-P256-SHA256 Credential=AKIDEXAMPLE/20150830/service/aws4_request, "
"SignedHeaders=host;x-amz-date;x-amz-region-set, Signature=3046022100fddaaf816a31e30d04973875b13bc27b98da1"
"0907a3a1872fd5819a221334abc022100de2ee81d83b54f31efc82834de07e6cd4d5c6f25bfa08e0f29a15bb0977c343e"),
}
_V4A_HEADER_STRING_TO_SIGN = (
"AWS4-ECDSA-P256-SHA256\n20150830T123600Z\n20150830/service/aws4_request\n"
"cf59db423e841c8b7e3444158185aa261b724a5c27cbe762676f3eed19f4dc02"
)
_V4A_QUERY_STRING_TO_SIGN = (
"AWS4-ECDSA-P256-SHA256\n20150830T123600Z\n20150830/service/aws4_request\n"
"890c4ed28c1a1ac10b5862719b537afbe392e987dc1aab1efa16fe7de41d3c81"
)
_V4A_QUERY_SIGNATURE = (
"3045022100b3246f8e1442dd58e73292ae1294720c3256ee58f6cea50f3a3f83b4a4b0331a0220329693f7745c9008a5887c0529ce"
"ccb0fae4e16d707b712ea66acdbaf963769a"
)
def test_sigv4a_key_derivation_matches_the_published_vector():
public = sigv4a_signing_key(_V4A_KEY_ID, _V4A_SECRET).public_key().public_numbers()
assert (f"{public.x:064x}", f"{public.y:064x}") == (
"b6618f6a65740a99e650b33b6b4b5bd0d43b176d721a3edfea7e7d2d56d936b1",
"865ed22a7eadc9c5cb9d2cbaca1b3699139fedc5043dc6661864218330c8e518",
)
assert sigv4a_signature_matches(_V4A_KEY_ID, _V4A_SECRET, _V4A_QUERY_STRING_TO_SIGN, _V4A_QUERY_SIGNATURE)
assert not sigv4a_signature_matches(_V4A_KEY_ID, _V4A_SECRET, _V4A_HEADER_STRING_TO_SIGN, _V4A_QUERY_SIGNATURE)
assert not sigv4a_signature_matches(_V4A_KEY_ID, "other", _V4A_QUERY_STRING_TO_SIGN, _V4A_QUERY_SIGNATURE)
assert not sigv4a_signature_matches(_V4A_KEY_ID, _V4A_SECRET, _V4A_QUERY_STRING_TO_SIGN, "not hex")
def test_sigv4a_header_signature_of_the_published_vector_verifies():
signature = parse_header_signature(_V4A_HEADERS)
assert (signature.access_key_id, signature.service, signature.region_set) == (_V4A_KEY_ID, "service", "us-east-1")
assert header_signing_documents(signature, "GET", "/", {}, _V4A_HEADERS, b"")[1] == _V4A_HEADER_STRING_TO_SIGN
assert header_signature_failure(signature, _V4A_SECRET, "GET", "/", {}, _V4A_HEADERS, b"") is None
assert header_signature_failure(signature, _V4A_SECRET, "GET", "/x", {}, _V4A_HEADERS, b"")[0] == (
"SignatureDoesNotMatch")
@pytest.mark.parametrize("region_set, covered", [
("*", True), ("eu-central-1", True), ("us-west-2,eu-central-1", True), ("eu-*", True),
("us-west-2", False), ("eu-west-*", False),
])
def test_region_set_covers_lists_and_wildcards(region_set, covered):
assert region_set_covers(region_set, "eu-central-1") is covered
def test_presigned_request_expiry_is_exclusive_at_boundary():
expires_at = dt.datetime(2026, 9, 4, 12, 15, tzinfo=dt.timezone.utc)
assert not presigned_request_is_expired("20260904T120000Z", "900", now=expires_at)
assert presigned_request_is_expired(
"20260904T120000Z",
"900",
now=expires_at + dt.timedelta(microseconds=1),
)
@pytest.mark.parametrize(
"amz_date, expires",
[
("not-a-date", "900"),
("20260904T120000Z", "not-a-duration"),
],
)
def test_presigned_request_expiry_rejects_malformed_values(amz_date, expires):
with pytest.raises(ValueError):
presigned_request_is_expired(amz_date, expires)
def test_signatures_match_accepts_only_equal_values():
assert signatures_match("abc123", "abc123")
assert not signatures_match("abc123", "abc124")
_SCOPE = "AKIAIOSFODNN7EXAMPLE/20260930/eu-central-1/sts/aws4_request"
@pytest.mark.parametrize(
"authorization, code, message",
[
(
f"AWS4-HMAC-SHA256 Credential={_SCOPE}, Signature=abc",
"MissingAuthorizationParameter",
"Authorization header requires 'SignedHeaders' parameter. (Hashed with SHA-256 and encoded with Base64) "
"Authorization=NfAZ3F0AUnKOtT3DAo6CWylCcBLuRNI5BHzk96CvGwM=",
),
(
"AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/eu-central-1/sts/aws4_request, "
"SignedHeaders=host;x-amz-date, Signature=abc",
"IncompleteSignature",
"Credential must have exactly 5 slash-delimited elements, e.g. keyid/date/region/service/term, "
"got 'AKIAIOSFODNN7EXAMPLE/eu-central-1/sts/aws4_request'",
),
(
"AWS4-HMAC-SHA256 SignedHeaders=host;x-amz-date, Signature=abc",
"MissingAuthorizationParameter",
"Authorization header requires 'Credential' parameter. (Hashed with SHA-256 and encoded with Base64) "
"Authorization=ahJcBrcKAe4SBJto5I/CIJQro+xeLn5ihFrmUmERRpY=",
),
(
"AWS4-HMAC-SHA256 Credential=, SignedHeaders=host;x-amz-date, Signature=abc",
"IncompleteSignature",
"Authorization header requires 'Credential' parameter. (Hashed with SHA-256 and encoded with Base64) "
"Authorization=Rso9P5e0/U0V+vZQW+PsjFTI/EYgUn2YbmHes/SFYPA=",
),
(
"AWS4-HMAC-SHA256",
"MissingAuthorizationParameter",
"Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' "
"parameter. Authorization header requires 'SignedHeaders' parameter. (Hashed with SHA-256 and encoded "
"with Base64) Authorization=YI2YWea8FSxnksZL2ETHbs5elHm9HQufxTLK0W0ffV0=",
),
],
)
def test_parse_header_signature_names_the_missing_part_as_aws_does(authorization, code, message):
headers = {"authorization": authorization, "x-amz-date": "20260930T120000Z"}
assert parse_header_signature(headers) == (code, message)
def test_parse_header_signature_takes_the_date_header_when_x_amz_date_is_absent():
headers = {
"authorization": f"AWS4-HMAC-SHA256 Credential={_SCOPE}, SignedHeaders=date;host, Signature=abc",
"date": "Wed, 30 Sep 2026 12:00:00 GMT",
}
parsed = parse_header_signature(headers)
assert (parsed.access_key_id, parsed.service, parsed.amz_date) == (
"AKIAIOSFODNN7EXAMPLE", "sts", "20260930T120000Z")
def test_parse_header_signature_names_a_missing_date_with_the_missing_parameters():
headers = {"authorization": "AWS4-HMAC-SHA256 SignedHeaders=host, Signature=abc"}
assert parse_header_signature(headers) == (
"MissingAuthorizationParameter",
"Authorization header requires 'Credential' parameter. Authorization header requires existence of either "
"a 'X-Amz-Date' or a 'Date' header. (Hashed with SHA-256 and encoded with Base64) "
"Authorization=QtbsE59+Cww86WuNzDL08sE4JUxLk21/H/rRcBdVXrQ=",
)
@pytest.mark.parametrize("query, code, missing", [
({"X-Amz-Algorithm": ["AWS4-HMAC-SHA256"], "X-Amz-Date": ["20260930T120000Z"],
"X-Amz-SignedHeaders": ["host"], "X-Amz-Signature": ["abc"]},
"MissingAuthorizationParameter", ["X-Amz-Credential"]),
({"X-Amz-Algorithm": ["AWS4-HMAC-SHA256"], "X-Amz-Credential": [""], "X-Amz-Date": ["20260930T120000Z"],
"X-Amz-SignedHeaders": ["host"], "X-Amz-Signature": ["abc"]},
"IncompleteSignature", ["X-Amz-Credential"]),
({"X-Amz-Algorithm": ["AWS4-HMAC-SHA256"]},
"MissingAuthorizationParameter", ["X-Amz-Credential", "X-Amz-Signature", "X-Amz-SignedHeaders", "X-Amz-Date"]),
], ids=["no-credential", "empty-credential", "only-algorithm"])
def test_parse_query_signature_names_every_missing_parameter(query, code, missing):
assert parse_query_signature(query) == (code, " ".join(
[f"AWS query-string parameters must include '{name}'." for name in missing]
+ ["Re-examine the query-string parameters."]))
def _presigned(secret, token_signed, service="iotdevicegateway"):
"""Query parameters of a GET /mqtt presigned for ``service``, with its session token."""
amz_date = "20260930T120000Z"
query = {"X-Amz-Algorithm": ["AWS4-HMAC-SHA256"],
"X-Amz-Credential": [f"ASIAEXAMPLE/20260930/us-east-1/{service}/aws4_request"],
"X-Amz-Date": [amz_date], "X-Amz-SignedHeaders": ["host"]}
if token_signed:
query["X-Amz-Security-Token"] = ["token/+="]
canonical = build_canonical_request("GET", "/mqtt", {"host": "iot.example"}, query, "host",
payload_hash=hashlib.sha256(b"").hexdigest())
string_to_sign = build_string_to_sign(amz_date, amz_date[:8], "us-east-1", service, canonical)
query["X-Amz-Signature"] = [calculate_signature(secret, amz_date[:8], "us-east-1", service, string_to_sign)]
query["X-Amz-Security-Token"] = ["token/+="]
return query
@pytest.mark.parametrize("service, token_signed, expected", [
("iotdevicegateway", False, None),
("iotdevicegateway", True, "SignatureDoesNotMatch"),
("execute-api", True, None),
("execute-api", False, "SignatureDoesNotMatch"),
])
def test_presigned_iot_url_leaves_the_session_token_unsigned(service, token_signed, expected):
query = _presigned("secret", token_signed, service)
signature = parse_query_signature(query)
failure = header_signature_failure(signature, "secret", "GET", "/mqtt", query, {"host": "iot.example"}, b"",
presigned=True)
assert (failure and failure[0]) == expected
def test_signature_failure_can_name_the_strings_it_expected():
query = _presigned("secret", True, "execute-api")
signature = parse_query_signature(query)
code, message = header_signature_failure(signature, "other", "GET", "/mqtt", query, {"host": "iot.example"}, b"",
presigned=True, explain=True)
canonical = (
"GET\n/mqtt\nX-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAEXAMPLE%2F20260930%2Fus-east-1"
"%2Fexecute-api%2Faws4_request&X-Amz-Date=20260930T120000Z&X-Amz-Security-Token=token%2F%2B%3D"
f"&X-Amz-SignedHeaders=host\nhost:iot.example\n\nhost\n{hashlib.sha256(b'').hexdigest()}"
)
string_to_sign = build_string_to_sign("20260930T120000Z", "20260930", "us-east-1", "execute-api", canonical)
assert code == "SignatureDoesNotMatch"
assert message == (
"The request signature we calculated does not match the signature you provided. Check your AWS Secret "
"Access Key and signing method. Consult the service documentation for details.\n\n"
f"The Canonical String for this request should have been\n'{canonical}'\n\n"
f"The String-to-Sign should have been\n'{string_to_sign}'\n"
)
@pytest.mark.parametrize(
"service, amz_date, expected",
[
("kms", "20260930T120500Z", None),
("kms", "20260930T120501Z", "Signature not yet current: 20260930T120501Z is still later than "
"20260930T120500Z (20260930T120000Z + 5 min.)"),
("sts", "20260930T114500Z", None),
("sts", "20260930T114459Z", "Signature expired: 20260930T114459Z is now earlier than "
"20260930T114500Z (20260930T120000Z - 15 min.)"),
],
)
def test_request_time_failure_uses_the_services_window(service, amz_date, expected):
headers = {
"authorization": f"AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/{amz_date[:8]}/us-east-1/{service}/aws4_request, "
"SignedHeaders=host;x-amz-date, Signature=abc",
"x-amz-date": amz_date,
}
now = dt.datetime(2026, 9, 30, 12, 0, tzinfo=dt.timezone.utc)
failure = request_time_failure(parse_header_signature(headers), now=now)
assert failure == (expected and ("RequestTimeTooSkewed", expected))