IF Commons GitHub

sigv4

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-crypto FR-004

AWS Signature Version 4 (commons 0001-crypto FR-004): an HTTP request signed with AWS4-HMAC-SHA256, by HMAC-SHA256 on Web Crypto, from its parts or from a web Request. The canonical request (the method; the path normalized and encoded twice, except for S3, which signs it as given, encoded once; the query sorted and encoded by RFC 3986; the headers in lower case, trimmed, sorted and signed with host and x-amz-date; the payload's SHA-256), the string to sign over the credential scope, the key derived from the secret through the day, region, service and aws4_request, and the Authorization header. The time is the caller's: the kernel reads no clock. Taken from Stolos's src/archon/connect/aws.ts; checked against AWS's published examples.

import { sign } from "./sigv4.ts";
const credentials = { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY" }; // AWS's example key
const signed = await sign(
  { method: "GET", url: "https://iam.amazonaws.com/?Action=ListUsers&Version=2010-05-08", headers: {} },
  { credentials, region: "us-east-1", service: "iam", date: new Date() },
);
signed.headers; // the request's headers with x-amz-date and authorization added, never host

Source: commons/crypto/src/sigv4.ts

8 of 26 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

sigv4namespace
namespace sigv4
sigv4.AwsCredentialstypeno test imports it
type AwsCredentials = {
  readonly accessKeyId: string;
  readonly secretAccessKey: string;
  readonly sessionToken?: string;
};

An access key: its id, its secret, and a session token where the key is temporary.

sigv4.SigV4Optionstypeno test imports it
type SigV4Options = { readonly credentials: AwsCredentials; /** The region of the credential scope (`us-east-1`). */… (620 characters)
type SigV4Options = {
  readonly credentials: AwsCredentials;
  /** The region of the credential scope (`us-east-1`). */
  readonly region: string;
  /** The service of the credential scope (`iam`, `sts`, `s3`, `ec2`). */
  readonly service: string;
  /** The time of signing, which becomes `x-amz-date` (the kernel reads no clock). */
  readonly date: Date;
  /** Sign `UNSIGNED-PAYLOAD` instead of the body's SHA-256 (S3 allows it). */
  readonly unsignedPayload?: boolean;
  /** Also send the payload's hash as `x-amz-content-sha256` (always for S3, which requires it). */
  readonly contentSha256Header?: boolean;
};

How to sign.

sigv4.SigV4Requesttypeno test imports it
type SigV4Request = { readonly method: string; /** The whole URL, as text (its path is signed as written there, befo… (408 characters)
type SigV4Request = {
  readonly method: string;
  /** The whole URL, as text (its path is signed as written there, before any normalization a URL parser would make). */
  readonly url: string;
  /** The headers to send; each is signed, but for those a transport may change (`user-agent`, `traceparent`, ...). */
  readonly headers: Readonly<Record<string, string>>;
  readonly body?: string | Uint8Array;
};

A request to sign, by its parts.

sigv4.Signedtypeno test imports it
type Signed = { /** * The request's headers with `x-amz-date`, `x-amz-security-token` and `x-amz-content-sha256` wh… (519 characters)
type Signed = {
  /**
   * The request's headers with `x-amz-date`, `x-amz-security-token` and `x-amz-content-sha256` where they apply, and `authorization`;
   * never `host`, which the transport sets from the URL.
   */
  readonly headers: Readonly<Record<string, string>>;
  readonly canonicalRequest: string;
  readonly stringToSign: string;
  /** The signature, 64 lower-case hexadecimal digits. */
  readonly signature: string;
  /** The value of the `Authorization` header. */
  readonly authorization: string;
};

A signed request: the headers to send and, for whoever must check them, what was signed.

sigv4.ALGORITHMconstno test imports it
const ALGORITHM: "AWS4-HMAC-SHA256"

The algorithm's name, as the string to sign and the Authorization header begin.

sigv4.UNSIGNED_PAYLOADconstno test imports it
const UNSIGNED_PAYLOAD: "UNSIGNED-PAYLOAD"

What is signed in place of a body's hash where the payload is not signed.

sigv4.uriEncodefunctionno test imports it
function uriEncode(text: string): string

RFC 3986 percent-encoding, as SigV4 wants it: everything but A-Z a-z 0-9 - _ . ~ encoded, in upper-case hexadecimal.

sigv4.amzDatefunctionno test imports it
function amzDate(date: Date): string

20150830T123600Z: the time as x-amz-date writes it.

sigv4.canonicalPathfunctionno test imports it
function canonicalPath(path: string, service: string): string

The path as SigV4 signs it. For a service other than S3: . and .. segments resolved and empty segments dropped, each segment decoded and encoded twice (RFC 3986). For S3: the path as given, each segment decoded and encoded once.

sigv4.canonicalQueryfunctionno test imports it
function canonicalQuery(query: string): string

The query as SigV4 signs it: each name and value decoded and encoded by RFC 3986, a name without = given an empty value, sorted.

sigv4.signingKeyfunctionno test imports it
function signingKey(secretAccessKey: string, day: string, region: string, service: string): Promise<Uint8Array<ArrayBufferLike>>

The signing key: HMAC-SHA256 of AWS4 and the secret through the day (YYYYMMDD), the region, the service and aws4_request.

sigv4.signfunctionno test imports it
function sign(request: SigV4Request, options: SigV4Options): Promise<Signed>

A request signed by Signature Version 4 (FR-068): the headers to send, and the canonical request, string to sign and signature.

sigv4.signRequestfunctionno test imports it
function signRequest(request: Request, options: SigV4Options): Promise<Request>

A web Request signed by Signature Version 4 (FR-068): a new Request with the same method, URL and body and the signed headers. Its body is read once (from a clone) to be hashed. The URL is the one the Request holds, which a URL parser has already normalized.

AwsCredentialstypeno test imports it
type AwsCredentials = {
  readonly accessKeyId: string;
  readonly secretAccessKey: string;
  readonly sessionToken?: string;
};

An access key: its id, its secret, and a session token where the key is temporary.

SigV4Optionstype
type SigV4Options = { readonly credentials: AwsCredentials; /** The region of the credential scope (`us-east-1`). */… (620 characters)
type SigV4Options = {
  readonly credentials: AwsCredentials;
  /** The region of the credential scope (`us-east-1`). */
  readonly region: string;
  /** The service of the credential scope (`iam`, `sts`, `s3`, `ec2`). */
  readonly service: string;
  /** The time of signing, which becomes `x-amz-date` (the kernel reads no clock). */
  readonly date: Date;
  /** Sign `UNSIGNED-PAYLOAD` instead of the body's SHA-256 (S3 allows it). */
  readonly unsignedPayload?: boolean;
  /** Also send the payload's hash as `x-amz-content-sha256` (always for S3, which requires it). */
  readonly contentSha256Header?: boolean;
};

How to sign.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

SigV4Requesttypeno test imports it
type SigV4Request = { readonly method: string; /** The whole URL, as text (its path is signed as written there, befo… (408 characters)
type SigV4Request = {
  readonly method: string;
  /** The whole URL, as text (its path is signed as written there, before any normalization a URL parser would make). */
  readonly url: string;
  /** The headers to send; each is signed, but for those a transport may change (`user-agent`, `traceparent`, ...). */
  readonly headers: Readonly<Record<string, string>>;
  readonly body?: string | Uint8Array;
};

A request to sign, by its parts.

Signedtypeno test imports it
type Signed = { /** * The request's headers with `x-amz-date`, `x-amz-security-token` and `x-amz-content-sha256` wh… (519 characters)
type Signed = {
  /**
   * The request's headers with `x-amz-date`, `x-amz-security-token` and `x-amz-content-sha256` where they apply, and `authorization`;
   * never `host`, which the transport sets from the URL.
   */
  readonly headers: Readonly<Record<string, string>>;
  readonly canonicalRequest: string;
  readonly stringToSign: string;
  /** The signature, 64 lower-case hexadecimal digits. */
  readonly signature: string;
  /** The value of the `Authorization` header. */
  readonly authorization: string;
};

A signed request: the headers to send and, for whoever must check them, what was signed.

ALGORITHMconstno test imports it
const ALGORITHM: "AWS4-HMAC-SHA256"

The algorithm's name, as the string to sign and the Authorization header begin.

UNSIGNED_PAYLOADconst
const UNSIGNED_PAYLOAD: "UNSIGNED-PAYLOAD"

What is signed in place of a body's hash where the payload is not signed.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

uriEncodefunction
function uriEncode(text: string): string

RFC 3986 percent-encoding, as SigV4 wants it: everything but A-Z a-z 0-9 - _ . ~ encoded, in upper-case hexadecimal.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

amzDatefunction
function amzDate(date: Date): string

20150830T123600Z: the time as x-amz-date writes it.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

canonicalPathfunction
function canonicalPath(path: string, service: string): string

The path as SigV4 signs it. For a service other than S3: . and .. segments resolved and empty segments dropped, each segment decoded and encoded twice (RFC 3986). For S3: the path as given, each segment decoded and encoded once.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

canonicalQueryfunction
function canonicalQuery(query: string): string

The query as SigV4 signs it: each name and value decoded and encoded by RFC 3986, a name without = given an empty value, sorted.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

signingKeyfunctionno test imports it
function signingKey(secretAccessKey: string, day: string, region: string, service: string): Promise<Uint8Array<ArrayBufferLike>>

The signing key: HMAC-SHA256 of AWS4 and the secret through the day (YYYYMMDD), the region, the service and aws4_request.

signfunction
function sign(request: SigV4Request, options: SigV4Options): Promise<Signed>

A request signed by Signature Version 4 (FR-068): the headers to send, and the canonical request, string to sign and signature.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

signRequestfunction
function signRequest(request: Request, options: SigV4Options): Promise<Request>

A web Request signed by Signature Version 4 (FR-068): a new Request with the same method, URL and body and the signed headers. Its body is read once (from a clone) to be hashed. The URL is the one the Request holds, which a URL parser has already normalized.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.