AWS SigV4 Authentication Specification

Aarkam.Gateway natively implements the AWS Signature Version 4 (SigV4) authentication protocol. Any client configured for AWS S3 (including aws-cli, AWS SDKs, boto3, MinIO client mc, or Cyberduck) connects without code modifications.

1. Authorization Header Format

Every authenticated REST request must supply an Authorization header structured as follows:

Authorization: AWS4-HMAC-SHA256 
Credential=AKIAIOSFODNN7EXAMPLE/20260924/sa-central-1/s3/aws4_request, 
SignedHeaders=host;x-amz-content-sha256;x-amz-date, 
Signature=c5b2a74c10972...49581a0e

2. Canonical Request Construction

The gateway verifies the signature by reconstructing the Canonical Request:

<HTTPMethod>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
<HashedPayload>

Steps Executed by Gateway:

1. Canonical URI: URI-encoded path component of the request (e.g., /my-bucket/documents/report.pdf).
2. Canonical Query String: Query parameters sorted strictly by character code.
3. Canonical Headers: Lowercase header names followed by trimmed values, sorted alphabetically.
4. Hashed Payload: The SHA-256 hash of the request body (or literal string UNSIGNED-PAYLOAD for streaming chunked uploads).

3. String-to-Sign & Signature Verification

The gateway derives the signing key using the tenant's registered SecretAccessKey:

kDate    = HMAC-SHA256("AWS4" + SecretAccessKey, "20260924")
kRegion  = HMAC-SHA256(kDate, "sa-central-1")
kService = HMAC-SHA256(kRegion, "s3")
kSigning = HMAC-SHA256(kService, "aws4_request")

The calculated signature: \(\text{Signature} = \text{HexEncode}(\text{HMAC-SHA256}(kSigning, \text{StringToSign}))\)

Verification utilizes constant-time byte comparisons (CryptographicOperations.FixedTimeEquals) to eliminate side-channel timing leaks.

4. Presigned URLs

Aarkam.Gateway supports presigned URLs, permitting time-limited browser uploads and downloads without exposing secret access keys:

https://s3.aarkam.io/financial-vault/q3-report.pdf?
X-Amz-Algorithm=AWS4-HMAC-SHA256&
X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20260924%2Fsa-central-1%2Fs3%2Faws4_request&
X-Amz-Date=20260924T120000Z&
X-Amz-Expires=3600&
X-Amz-SignedHeaders=host&
X-Amz-Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855