sigv4namespacenamespace sigv4AWS 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 hostsigv4namespacenamespace sigv4sigv4.AwsCredentialstypeno test imports ittype 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 ittype 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 ittype 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 ittype 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 itconst ALGORITHM: "AWS4-HMAC-SHA256"The algorithm's name, as the string to sign and the Authorization header begin.
sigv4.UNSIGNED_PAYLOADconstno test imports itconst UNSIGNED_PAYLOAD: "UNSIGNED-PAYLOAD"What is signed in place of a body's hash where the payload is not signed.
sigv4.uriEncodefunctionno test imports itfunction uriEncode(text: string): stringRFC 3986 percent-encoding, as SigV4 wants it: everything but A-Z a-z 0-9 - _ . ~ encoded, in upper-case hexadecimal.
sigv4.amzDatefunctionno test imports itfunction amzDate(date: Date): string20150830T123600Z: the time as x-amz-date writes it.
sigv4.canonicalPathfunctionno test imports itfunction canonicalPath(path: string, service: string): stringThe 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 itfunction canonicalQuery(query: string): stringThe 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 itfunction 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 itfunction 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 itfunction 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 ittype 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.
SigV4Optionstypetype 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.
SigV4Requesttypeno test imports ittype 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 ittype 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 itconst ALGORITHM: "AWS4-HMAC-SHA256"The algorithm's name, as the string to sign and the Authorization header begin.
UNSIGNED_PAYLOADconstconst UNSIGNED_PAYLOAD: "UNSIGNED-PAYLOAD"What is signed in place of a body's hash where the payload is not signed.
uriEncodefunctionfunction uriEncode(text: string): stringRFC 3986 percent-encoding, as SigV4 wants it: everything but A-Z a-z 0-9 - _ . ~ encoded, in upper-case hexadecimal.
amzDatefunctionfunction amzDate(date: Date): string20150830T123600Z: the time as x-amz-date writes it.
canonicalPathfunctionfunction canonicalPath(path: string, service: string): stringThe 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.
canonicalQueryfunctionfunction canonicalQuery(query: string): stringThe query as SigV4 signs it: each name and value decoded and encoded by RFC 3986, a name without = given an empty value, sorted.
signingKeyfunctionno test imports itfunction 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.
signfunctionfunction 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.
signRequestfunctionfunction 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.