Lab: Hand-sign an AWS request with SigV4 (Lab 4.5)
Implement AWS Signature Version 4 in plain C#, prove it against AWS's published test vectors, sign a real STS GetCallerIdentity call and compare it with the SDK, then reuse the signer as a DelegatingHandler for IAM-protected APIs.
Assumes: .NET 10 LTS · xUnit v3 4.0.3 · AWS SDK for .NET v4 (AWSSDK.Core 4.1.1.1, AWSSDK.SecurityToken 4.1.0.2) · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of this lab you can:
- Derive a SigV4 signing key and compute a signature in C# using nothing but the .NET base class library.
- Build a canonical request by hand and explain why each line is there (method, path, query, headers, signed headers, payload hash).
- Prove your signer correct against published test vectors instead of "it seemed to work", and explain why you never edit an expected value to make a test pass.
- Sign a real
sts:GetCallerIdentityrequest, send it with a plainHttpClient, and show that it returns the same ARN as the AWS SDK. - Wrap the signer in a
DelegatingHandlerthat signs every outgoing request for IAM-protected API Gateway (execute-api) and VPC Lattice (vpc-lattice-svcs) endpoints, and say where it must sit in the handler chain. - Diagnose the three classic failures:
SignatureDoesNotMatch, clock skew and wrong service name.
This lab is Lab 4.5 of the module plan. It is the hands-on half of Calling AWS APIs from C# and supports Service-to-service communication.
Prerequisites
- Calling AWS APIs from C#: the SDK and a hand-written SigV4 signer, which explains the algorithm; this lab runs it.
- Service-to-service communication for the IAM-authorised API and VPC Lattice context.
- Docker Desktop. The .NET 10 SDK is optional: the tests run in a container.
- Only for Part 3 (the real STS call): AWS CLI v2 and a working
aws sso login --profile learn-sandbox. Use only the sandbox account.
Why this matters in banking
Harbourline's batch jobs call an IAM-protected internal API through an outbound proxy. A well-meaning proxy change normalised header whitespace after the request was signed, and every call began failing with 403 SignatureDoesNotMatch. The team lost two days because nobody could say what was signed. Someone who has written the signer once can read the error message, compare the canonical request the server expected with the one the client built, and find the changed byte in ten minutes.
There is a second reason. Your bank will have HTTP endpoints that no SDK wraps: an IAM-authorised API Gateway API owned by another team, or a VPC Lattice service that fronts the sanctions-screening service. You will sign those requests with a handler, and you need to trust it.
The idea in plain language
AWS does not accept a password on each request. It accepts a receipt that proves you hold a secret without sending it. The client builds a text summary of the request (the canonical request), hashes it, mixes the hash with a short-lived key derived from the secret, and sends only the result (the signature) in the Authorization header. AWS repeats the same computation with its copy of the key. If the two results match, the request is authentic and was not changed in transit. Anything that alters a signed byte after signing makes the receipt wrong.
Analogy: a tamper-evident bag at a cash-in-transit depot. You seal the contents, write the seal number on the manifest, and the depot only accepts the bag if the seal number matches what it computes from the contents. If anyone opens the bag and closes it again, even tidily, the number no longer matches.
The lab walks through the five stages:
- Derive the signing key from your secret key, the date, the Region and the service, using four chained HMAC-SHA256 operations.
- Build the canonical request: method, URI path, sorted query string, sorted lower-cased headers, the list of signed header names, and the SHA-256 of the body.
- Build the string to sign: the algorithm name, the timestamp, the credential scope and the hash of the canonical request.
- Compute the signature: HMAC-SHA256 of the string to sign with the signing key.
- Attach the result as an
Authorizationheader, plusX-Amz-Dateand, for temporary credentials,X-Amz-Security-Token.
What the AWS services do here
- AWS STS is the target of the real call.
GetCallerIdentityneeds no permissions and creates nothing, which makes it the safest possible "does my signature work" probe. - IAM Identity Center (SSO) supplies the temporary credentials through the
learn-sandboxprofile. The SDK resolves and refreshes them; the signer only uses what it is given. - API Gateway (
execute-api) and VPC Lattice (vpc-lattice-svcs) are the two services the handler targets. Neither is called in this lab; the handler tests prove the shape of the signed request locally.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | This lab | What's different |
|---|---|---|
A bearer token from Entra ID in the Authorization header | A per-request signature in the Authorization header | The credential never travels. Each request is signed separately, so a captured request cannot be modified, and it expires in minutes |
DelegatingHandler that adds a token (Microsoft.Identity.Web downstream API) | SigV4DelegatingHandler | Same extension point, but the handler must see the final request, because the signature covers headers and body |
| Azure shared key signing for Storage | SigV4 | The shape is similar: canonicalise, HMAC, header. SigV4 adds a derived, scoped key so one leaked signature does not expose the secret |
DefaultAzureCredential | SDK credential chain wrapped by AwsSdkCredentialSource | You never write a credential lookup yourself. You borrow the SDK's, including refresh |
Architecture
The signer has no dependency on the AWS SDK. Only AwsSdkCredentialSource references AWSSDK.Core, so you can see that signing is just hashing.
Step-by-step implementation
The lab folder is labs/m04-sigv4-signer. The solution file is Harbourline.SigV4.slnx.
Part 1: read the signer and run the tests (free)
Look at the layout
src/Harbourline.SigV4/ SigningKey, CanonicalRequest, SigV4Signer, SigV4Options,
SigV4DelegatingHandler, IAwsCredentialSource, AwsSdkCredentialSource
src/Harbourline.SigV4.Demo/ console app: hand-signed STS GetCallerIdentity vs the SDK
tests/Harbourline.SigV4.Tests/ published test vectors, handler tests, real STS test (RUN_AWS_TESTS=1)Run the tests in Docker
MSYS_NO_PATHCONV=1 docker run --rm --memory 3g \
-v "$PWD/labs/m04-sigv4-signer:/src" \
-v cea-nuget-m04:/root/.nuget/packages \
-w /src mcr.microsoft.com/dotnet/sdk:10.0 \
sh -c "dotnet test --solution Harbourline.SigV4.slnx; find . -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} +"On PowerShell, use a backtick for line continuation and ${PWD} for the path. The first run downloads NuGet packages into the named volume; later runs are much faster. If you have the .NET 10 SDK installed locally, dotnet test --solution Harbourline.SigV4.slnx is enough.
Expected result (verified 2026-11-18 in Docker): total: 10, failed: 0, succeeded: 9, skipped: 1. The skipped test is the real STS call, which runs only when RUN_AWS_TESTS=1. A skip is not a failure: it tells you the check exists and was deliberately not run.
Read the tests before the code
Open SigV4SignerTests.cs. The class comment says the expected values come from AWS's published test suite and the signing-key example in the AWS General Reference. Read that as a rule: never "fix" an expected value to make a test pass. If a test fails, your signer is wrong. These are the six signer tests:
| Test | What it proves |
|---|---|
Signing_key_matches_the_documented_example | Key derivation: secret wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY, date 20120215, Region us-east-1, service iam gives f4780e2d...b404d |
Get_vanilla | The simplest request: empty path, no query, no body. Checks the canonical request, string to sign, signature and the final Authorization header |
Get_vanilla_query_order_key_case | Query parameters are sorted by name, so Param2=value2&Param1=value1 becomes Param1=value1&Param2=value2 |
Post_x_www_form_urlencoded_canonical_request_and_signature | A POST with content-length and x-amz-content-sha256 in the signed headers, so you build the header set yourself and check the payload hash 9095672b... |
Session_token_is_sent_and_signed | With temporary credentials, X-Amz-Security-Token is sent and listed in SignedHeaders |
Execute_api_path_segments_are_encoded_twice_but_s3_paths_once | q3%20report becomes q3%2520report for most services, but stays q3%20report for S3 |
Part 2: break the signer on purpose (free)
Reading a passing test teaches little. Make each one fail, once, and read the failure.
Sort the query ignoring case
In CanonicalRequest.CanonicalQuery, replace StringComparer.Ordinal with StringComparer.OrdinalIgnoreCase in the OrderBy. Run the tests. Get_vanilla_query_order_key_case should fail, because this vector deliberately mixes the case of parameter names. SigV4 sorts by byte value, so uppercase letters sort before lowercase. Revert the change.
Stop signing the session token
In SigV4Signer.SignAsync, comment out the line that adds x-amz-security-token to the signed headers. Session_token_is_sent_and_signed fails on SignedHeaders=. In real life AWS would reject the request. Revert the change.
Encode the path only once
Make CanonicalUri always behave as if isS3 were true. The encoding test fails. Note how small the difference is: one %25 in a path segment that contains a space. This is exactly the kind of bug that works for a year and then fails on the first file name with a space in it.
Part 3: sign a real request (free, needs your sandbox login)
STS GetCallerIdentity has no charge and needs no IAM permission, so this part is free.
Log in
aws sso login --profile learn-sandbox
aws sts get-caller-identity --profile learn-sandboxThe second command confirms that your CLI works and shows the ARN you expect the demo to print.
Run the demo
The demo needs your SSO profile, which lives in your Windows home directory, so run it with the local .NET 10 SDK (or mount ~/.aws into a container read-only if you prefer Docker):
dotnet run --project src/Harbourline.SigV4.DemoThe output shows the canonical request, the string to sign, the ARN from the hand-signed call and the ARN from the SDK, and ends with Match: True. Values such as the timestamp and the ARN differ on your machine.
⚠ Learning shortcut — not for production
The demo prints the canonical request, and the canonical request contains the x-amz-security-token header, which is a live session token. Never paste this output into a ticket or chat. In production code, log the request ID and the signed header names, never their values.
Run the real-AWS test
$env:RUN_AWS_TESTS = "1"; dotnet test --solution Harbourline.SigV4.slnxThe test Hand_signed_GetCallerIdentity_returns_the_same_arn_as_the_sdk signs a request, sends it, and asserts that the response XML contains the ARN the SDK reports. With the variable set you should see skipped: 0. The build environment had no AWS account, so this run was not executed there: treat the exact result as ⚠ VERIFY on your machine.
Part 4: use the signer as a handler (free)
Read SigV4DelegatingHandler
It is twelve lines: fetch credentials, sign the request, pass it on. The doc comment holds the rule that matters: register it as the innermost handler, after any retry handler, so each retry is signed again with a fresh timestamp. A retry that re-sends an old signed request fails once the timestamp is more than five minutes old, and the retry that "reuses" an old request after a long back-off is the usual victim.
Read the three handler tests
| Test | What it proves |
|---|---|
Execute_api_requests_are_signed_with_the_execute_api_scope | The credential scope is 20261118/us-east-1/execute-api/aws4_request, X-Amz-Date is 20261118T093000Z (from a fake clock) and the session token is sent. No X-Amz-Content-Sha256 header is added |
Vpc_lattice_requests_use_an_unsigned_payload_header | With SigV4Options.VpcLattice, the payload hash is the literal UNSIGNED-PAYLOAD, the header X-Amz-Content-Sha256 carries it and is in SignedHeaders, and the scope service is vpc-lattice-svcs |
Each_send_is_signed_again | Two sends to different paths produce different Authorization headers: nothing is cached between requests |
The tests use FakeTimeProvider from Microsoft.Extensions.TimeProvider.Testing, so the timestamp in every signature is deterministic. Inject the clock whenever time ends up in a hash.
Wire it into an HttpClient (your own project)
using Amazon.Runtime.CredentialManagement;
using Harbourline.SigV4;
// Reuse the SDK's credential chain so that SSO, ECS task roles and Lambda roles all work.
var chain = new CredentialProfileStoreChain();
chain.TryGetAWSCredentials("learn-sandbox", out var sdkCredentials);
var signer = new SigV4Signer(TimeProvider.System);
var handler = new SigV4DelegatingHandler(
signer, new AwsSdkCredentialSource(sdkCredentials), "us-east-1", "execute-api")
{
InnerHandler = new HttpClientHandler(),
};
using var client = new HttpClient(handler);
// Replace with the invoke URL of an IAM-authorised API you own in the sandbox.
var response = await client.GetAsync("https://<api-id>.execute-api.us-east-1.amazonaws.com/learn/internal/accounts/ACC-0000012345/balance");
Console.WriteLine((int)response.StatusCode);Inside an ECS task or a Lambda function, replace the profile lookup with FallbackCredentialsFactory.GetCredentials() so the SDK uses the task or execution role. The caller's role needs execute-api:Invoke on the target API's ARN. This snippet is illustrative and was not run against a live API (⚠ VERIFY on your own API).
AWS Console instructions
The lab needs no Console work. For the optional "sign a call to your own IAM-protected API" experiment in Exercise 🔴: Console → API Gateway → your REST API → Resources → method → Method request → Authorization → AWS_IAM, then Deploy API to a stage. Menu wording changes over time (⚠ VERIFY).
AWS CLI
# Who am I? The ARN here is what the demo's "SDK:" line should show.
aws sts get-caller-identity --profile learn-sandbox
# Compare a CLI-signed request with yours: --debug prints the canonical request the CLI built.
# Redact the Authorization header and the security token before sharing any of this output.
aws sts get-caller-identity --profile learn-sandbox --debug 2>&1 | grep -A12 "CanonicalRequest"
# Check the clock: SigV4 allows roughly five minutes of drift (see the lesson for the exact limit).
date -uInfrastructure as Code
This lab creates no AWS resources, so there is no CDK or Terraform. The only infrastructure it touches is STS, which exists in every account. For the IAM-authorised API you would sign against, see the CDK in the module project walkthrough, which defines an HTTP API with a JWT authoriser; an IAM authoriser variant is Exercise 🔴.
Complete code
The complete lab is in labs/m04-sigv4-signer/. The two files that matter are reproduced here.
public async Task<SigningResult> SignAsync(HttpRequestMessage request, AwsCredentials credentials,
string region, string service, SigV4Options options, CancellationToken ct = default)
{
var uri = request.RequestUri ?? throw new ArgumentException("RequestUri is required.", nameof(request));
var now = time.GetUtcNow();
var amzDate = now.ToString("yyyyMMdd'T'HHmmss'Z'", CultureInfo.InvariantCulture);
var dateStamp = now.ToString("yyyyMMdd", CultureInfo.InvariantCulture);
string payloadHash;
if (options.UnsignedPayload)
{
payloadHash = UnsignedPayload;
}
else
{
var body = request.Content is null ? [] : await request.Content.ReadAsByteArrayAsync(ct);
payloadHash = Convert.ToHexStringLower(SHA256.HashData(body));
}
var headers = new SortedDictionary<string, string>(StringComparer.Ordinal)
{
["host"] = uri.IsDefaultPort ? uri.Host : $"{uri.Host}:{uri.Port}",
["x-amz-date"] = amzDate,
};
if (request.Content?.Headers.ContentType is { } contentType) headers["content-type"] = contentType.ToString();
if (credentials.SessionToken is { } token) headers["x-amz-security-token"] = token;
if (options.AddContentSha256Header) headers["x-amz-content-sha256"] = payloadHash;
// S3 and VPC Lattice use the path as sent; other services encode each segment a second time.
var (canonical, signedHeaders) = CanonicalRequest.Build(request.Method.Method, uri, headers, payloadHash,
isS3: service == "s3" || !options.DoubleEncodePath);
var scope = $"{dateStamp}/{region}/{service}/aws4_request";
var stringToSign = string.Join('\n', "AWS4-HMAC-SHA256", amzDate, scope,
Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(canonical))));
var key = SigningKey.Derive(credentials.SecretAccessKey, dateStamp, region, service);
var signature = Convert.ToHexStringLower(HMACSHA256.HashData(key, Encoding.UTF8.GetBytes(stringToSign)));
// ... headers (X-Amz-Date, X-Amz-Security-Token, X-Amz-Content-Sha256, Authorization) are then set on the request
return new SigningResult(canonical, stringToSign, signature);
}public static byte[] Derive(string secretAccessKey, string dateStamp, string region, string service)
{
var kDate = HMACSHA256.HashData(Encoding.UTF8.GetBytes("AWS4" + secretAccessKey), Encoding.UTF8.GetBytes(dateStamp));
var kRegion = HMACSHA256.HashData(kDate, Encoding.UTF8.GetBytes(region));
var kService = HMACSHA256.HashData(kRegion, Encoding.UTF8.GetBytes(service));
return HMACSHA256.HashData(kService, Encoding.UTF8.GetBytes("aws4_request"));
}Code explained line by line
time.GetUtcNow()reads the clock from an injectedTimeProvider. Production passesTimeProvider.System; tests pass aFakeTimeProvider, which is why the published vectors (timestamp20150830T123600Z) can be asserted exactly.amzDateanddateStampare the two time formats SigV4 needs: the full ISO-8601 basic format forX-Amz-Dateand the date only for the credential scope and key derivation.payloadHashis the lower-case hex SHA-256 of the body. An empty body hashes toe3b0c442...b855, which is why theGet_vanillacanonical request ends with that value. WithUnsignedPayload, the literal textUNSIGNED-PAYLOADis used instead, which is what VPC Lattice expects.ReadAsByteArrayAsyncbuffers the body so it can be hashed and then still sent. Fine for a lab and small JSON; for large uploads the SDK's streaming signer or an unsigned payload over TLS is a better choice.- The
SortedDictionarywithStringComparer.Ordinalkeeps header names lower-case and in byte order, which the canonical request requires.hostandx-amz-dateare always signed;content-typeonly when there is a body;x-amz-security-tokenonly for temporary credentials. uri.IsDefaultPort ? uri.Host : $"{uri.Host}:{uri.Port}"matters: theHostheader includes the port when it is not 443 or 80, and the signature must use the same text the server will see.isS3: service == "s3" || !options.DoubleEncodePathselects single path encoding for S3 and for VPC Lattice, and double encoding (each segment encoded again) for everything else.scopeisdate/region/service/aws4_request. The signature is only valid for that day, Region and service, which limits what a leaked signature can do.SigningKey.Derivechains four HMACs. Each step uses the previous output as the key, starting with the literal"AWS4"plus your secret. The secret itself is used only in the first step and never leaves the process.Convert.ToHexStringLowerproduces the lower-case hex that AWS compares against. Upper-case hex would be a different string and a failed signature.- The final headers are set with
TryAddWithoutValidationafter removing any existing value, so signing the same message twice (a retry) replaces the old signature instead of sending two.
Security considerations
⚠ Learning shortcut — not for production
A hand-written signer is for learning and for HTTP endpoints the SDK does not wrap. For any AWS service with an SDK client, use the SDK: it handles regional endpoints, retries, clock-skew correction, event streams and the many service quirks (S3 chunked signing, SigV4a for multi-Region access points). Hand-rolled cryptographic code that you maintain becomes a liability the day AWS changes a detail. If you do ship a signer, keep the AWS test suite in your CI.
- Secrets never leave the process. The signer uses the secret key only to derive the signing key. Log nothing derived from it.
- Session tokens are credentials. Treat
X-Amz-Security-Tokenlike a password: not in logs, not in screenshots, not in tickets. - Least privilege on the caller. The role that signs requests to an
execute-apiendpoint needsexecute-api:Invokeon exactly that API's ARN, notexecute-api:*on*. - Prefer roles to access keys. A signer fed by a long-lived access key in an environment variable is the incident in the lesson's "why it matters". Feed it from the SDK chain so credentials are temporary and refreshed.
- TLS stays on. A signature does not hide the body. It proves authenticity and integrity; confidentiality comes from HTTPS.
Banking use case
A payments service calls an internal "balance" API owned by the core-banking integration team. The API sits behind an IAM-authorised API Gateway, and a second service reaches the sanctions screener through a VPC Lattice service network. Both teams require SigV4 so that the caller's IAM role, not a shared API key, identifies each request in CloudTrail and the access logs. The payments service uses SigV4DelegatingHandler registered through IHttpClientFactory with the retry handler outside it. The team keeps the AWS test vectors in the build as a regression guard.
Common mistakes
- Signing, then modifying. A proxy, a logging handler or a retry layer changes a header or the body after signing. Make the signing handler the innermost one.
- Wrong service name.
execute-apiis notapigateway, and VPC Lattice isvpc-lattice-svcs. The error is "Credential should be scoped to correct service". - Reusing a signed request for a retry. The timestamp is part of the signature and AWS rejects timestamps more than about five minutes away from its own clock.
- Encoding once instead of twice (or the reverse) for path segments with spaces, plus signs or Unicode characters.
- Fixing the test to match the code. If the vector disagrees with your output, the vector is right.
- Forgetting
AWSSDK.SSOandAWSSDK.SSOOIDC. Without them, profile credentials from IAM Identity Center cannot be resolved, and the demo reports that the profile was not found.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
SignatureDoesNotMatch | A header changed after signing (proxy, handler order), or path or query encoded differently | Compare your canonical request with the one in the error message line by line |
Signature expired / RequestTimeTooSkewed | Clock more than about five minutes off | Sync the Windows clock (Settings → Time & language → Sync now) |
Credential should be scoped to correct service | Wrong service in the scope | Use sts, execute-api or vpc-lattice-svcs as appropriate |
Profile learn-sandbox not found | Not logged in, or the SSO packages are missing | aws sso login --profile learn-sandbox; keep AWSSDK.SSO and AWSSDK.SSOOIDC in the project |
403 with execute-api only | The caller's role lacks execute-api:Invoke, or the API has a resource policy that blocks it | Test with the IAM policy simulator; read the API's resource policy |
| Tests pass locally but a test vector fails in CI | Line endings: a Git checkout converted \n to \r\n in a test fixture | Set * text=auto eol=lf for fixtures, or build expected strings in code as the tests do |
Assert.SkipUnless shows 1 skipped | RUN_AWS_TESTS is not 1 | That is correct for the offline run |
Cost and cleanup
Cost: free. One STS GetCallerIdentity call has no charge, and the lab creates no resources.
# Nothing to delete. Remove build output created by Docker or local runs:
find labs/m04-sigv4-signer -type d \( -name bin -o -name obj -o -name TestResults \) -prune -exec rm -rf {} +
# Optional: sign out of the sandbox profile
aws sso logoutExercises
- 🟢 Guided: run the tests, then perform the three "break it on purpose" changes from Part 2, one at a time, and note which test fails for each.
- 🟡 Challenge: add a test for a request with a query string containing a space and a plus sign (
?note=a b&tag=c%2Bd) and one for a non-default port (https://example.amazonaws.com:8443/). Predict the canonical request on paper first, then confirm it with the signer. Decide whether you have a vector to check against or only your own expectation, and say so in the test comment. - 🔴 Live problem: a colleague reports
403 SignatureDoesNotMatchfrom a service that signs with your handler only when it retries. The first attempt succeeds. Find the cause using what you know about handler order and timestamps, write a failing test that reproduces it withFakeTimeProvider, and fix the registration order.
Assignment
Add a SigV4Presigner to the library that produces a presigned URL for GET requests: the signature goes in the query string (X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders, X-Amz-Signature), the payload hash is UNSIGNED-PAYLOAD, and the expiry is capped at a value you choose. Write at least four tests, including one that rejects an expiry above your cap. Describe in a short README section when a bank should and should not hand out presigned URLs. Keep the work in your portfolio repository.
Solutions
- Case-insensitive sort breaks
Get_vanilla_query_order_key_case. The vector sendsParam2andParam1; ordinal sorting treats the bytes literally, which puts every upper-case letter before every lower-case one. Case-insensitive sorting would be a bug as soon as a name mixes cases. - Not signing
x-amz-security-tokenmakesSession_token_is_sent_and_signedfail on theSignedHeaders=assertion. Against real AWS the request would be rejected, because the token header is part of what the server expects to be signed. - Single encoding for non-S3 services makes
Execute_api_path_segments_are_encoded_twice_but_s3_paths_oncefail:/learn/files/q3%2520reportbecomes/learn/files/q3%20report.
The point of the exercise is to see that each rule in the algorithm has a test that guards it.
For ?note=a b&tag=c%2Bd, CanonicalQuery decodes each name and value (a + becomes a space, %2B becomes +), then re-encodes with the unreserved set. Expected: note=a%20b&tag=c%2Bd. Pairs are sorted by encoded name, then value.
For port 8443, the host header must be example.amazonaws.com:8443. The signer already handles it with uri.IsDefaultPort; the test should assert the host: line in the canonical request.
Neither case is in the AWS vector set you were given, so the test comment should say "expected value derived by hand from the SigV4 documentation, not from a published vector". Honest provenance is part of a good test.
Cause: a retry handler registered inside (closer to the network than) the signing handler re-sends the already-signed message. It reuses the old Authorization and X-Amz-Date. When the retry back-off is long, or when the first attempt took long, the timestamp is stale and AWS rejects it. The fix is to register the retry handler so that it wraps the signer: the retry calls the pipeline again, the signer runs again and issues a new timestamp.
Reproduce: use a FakeTimeProvider, send once, advance the clock by ten minutes, and send the same HttpRequestMessage through an inner retry. Assert that the X-Amz-Date header differs from the first attempt. In HttpClient, you can also not reuse the same HttpRequestMessage for a second send; build a new one per attempt, which is what IHttpClientFactory retry strategies do.
Knowledge check
Answer: The derived key is scoped to one date, Region and service, so a leak of a signing key limits the damage to that scope and day. The secret key is used once, in the first HMAC, and is never needed again for that day's signatures. A signature that used the secret directly could be replayed more widely.
Answer: The canonical request always ends with the lower-case hex SHA-256 of the body. SHA-256 of zero bytes is the well-known e3b0c442...b855 value. Omitting the line, or using an empty string, would produce a different canonical request and a failed signature.
Answer: It fails with a credential-scope error. The Region is part of the scope and of the derived key, so the server's computation uses a different key and produces a different signature. It is not a network error.
Answer: Each retry must carry a fresh timestamp and signature. If the signer runs once and the retry layer re-sends the same message, the later attempt may use a stale X-Amz-Date and be rejected. "After" in the registration order means closer to the network, so it is invoked on every attempt.
Answer: The body is no longer covered by the signature, so tampering with the body in transit is not detected by the signature alone. It is acceptable where TLS already protects the transport and the service requires it (VPC Lattice, and S3 over HTTPS). It is not a good default for internal APIs that accept the signed payload.
Interview questions
- "Walk me through how AWS verifies a request you sign with SigV4." The server rebuilds the canonical request from what it received, derives the same signing key from its copy of your secret, computes the signature and compares. If it matches and the timestamp is within the allowed window, the request is accepted. Nothing secret is on the wire.
- "Where would a hand-written signer be justified?" For HTTP endpoints the SDK does not wrap: IAM-authorised API Gateway APIs and VPC Lattice services called from your own
HttpClient. For AWS service APIs, use the SDK. - "A SigV4 call fails only through the corporate proxy. What do you check first?" Whether the proxy modifies headers, normalises whitespace or case, changes the host header or re-encodes the path after signing. Compare the server's expected canonical request in the error with what the client built.
- "Why use
TimeProvider?" So time-dependent code is deterministic under test; the published vectors fix the time and the test must too.
Certification practice
A developer writes a .NET service that calls an IAM-authorised API Gateway API with HttpClient. Requests succeed in tests but fail intermittently in production with 403 and a message that the signature is stale. A retry handler was added last week. Which change is MOST likely to fix it?
A. Increase the API Gateway timeout. B. Register the signing handler so that it runs for each retry attempt, and build a new request per attempt. C. Disable clock synchronisation on the host. D. Switch the API to an API key.
Answer: B. Stale-timestamp errors on retry mean the signed message is reused. A raises a different limit and does not touch the timestamp. C makes clock skew worse. D changes the authorisation model and loses IAM identity, and is not a fix for the signing order.
A security reviewer finds a service that stores a long-lived access key in an environment variable to sign requests to an internal IAM-authorised API. What is the BEST remediation?
A. Rotate the key monthly and keep it in the environment variable.
B. Run the service with an IAM role (task role or execution role), resolve credentials from the SDK chain and scope the role to execute-api:Invoke on that API.
C. Encrypt the environment variable with a customer managed KMS key and keep the access key.
D. Move the access key into the source repository's private secrets file.
Answer: B. Roles give short-lived credentials that the SDK refreshes, remove the stored secret, and let the policy name the one API. A and C keep a long-lived key; encryption of the variable does not change that the process holds a durable secret. D spreads the secret into source control.
Completion checklist
- I ran the tests in Docker and saw
total: 10, succeeded: 9, skipped: 1 - I broke each of the three rules on purpose and saw the matching test fail
- I signed a real STS request and saw
Match: True(or I read the demo and know why it needs an account) - I can explain why the handler sits after the retry handler
- I deleted
bin/andobj/and signed out of the profile
Key takeaways
- SigV4 is five small steps; each can be proved against a published test vector, so test it that way.
- The signature covers headers and body, so nothing may change the request after signing. Handler order is a security-relevant decision.
- Scope (date, Region, service) limits what one signature or derived key can do.
- Use the SDK for AWS services; write or use a signer only for IAM-protected HTTP endpoints the SDK does not wrap.
- Log header names, never header values, from a signed request.
Further reading
- Calling AWS APIs from C#: the SDK and a hand-written SigV4 signer, the lesson this lab belongs to
- Service-to-service communication, for where IAM-signed calls fit among mTLS and tokens
- Module 4 overview
- Signing AWS API requests (AWS documentation) ⚠ VERIFY the page path before relying on it
Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.
Service-to-service communication: IAM auth, private APIs and service discovery
Connect Harbourline's internal services securely on AWS: choose between private API Gateway, VPC Lattice, ECS Service Connect and events, sign calls with IAM from C#, discover services with Cloud Map, and propagate customer context without trusting it blindly.
API monitoring: access logs, metrics, traces and alarms that matter
Turn on structured API Gateway access logs, read the right CloudWatch metrics, trace a request from the edge into .NET with OpenTelemetry and X-Ray, and build a small set of alarms that page someone only when customers are affected.