@aws-js-sdk-v3-prerelease/signature-v4-node v0.1.0-preview.2

AWS Signature V4 Signer for Node.JS

This module provides a class, SignatureV4, that will attempt to sign requests.

Supported configuration

The Signature V4 Signer requires several options to be set, and additionally has several optional configuration settings. You may provide these options in a hash to the SignatureV4 constructor. The following options are supported:

• service - The service signing name to use.
• region - The region name or a function that returns a promise that will be resolved with the region name.
• credentials - The credentials with which the request should be signed, or a function that returns a promise that will be resolved with credentials
• sha256 - Optional. A constructor function for a hash object that will calculate SHA-256 HMAC checksums. Defaults to an implementation using Node.JS' crypto module.
• unsignedPayload - Optional. Indicates whether to sign requests in such a way as to allow arbitrary message bodies. Useful for presigning requests for which the body is not known in advance. Defaults to false.
• uriEscapePath - Optional. Indicates whether to uri-escape the request URI path as part of computing the canonical request string. This is required for every AWS service, except Amazon S3, as of late 2017. Defaults to true.
• applyChecksum - Optional. Indicates whether to calculate a checksum of the request body and include it as either a request header (when signing) or as a query string parameter (when presigning). This is required for AWS Glacier and optional for every other AWS service as of late 2017. Defaults to false.

API

presignRequest

The presignRequest method accepts a request and returns a Promise that resolves with a presigned request. The presigned request will have an expiration and can be passed directly to an HTTP client. The following options can be provided within a hash to the presignRequest method:

• request - The request to be signed. This parameter will not be modified during the signing process but will instead be cloned. The shape of the request should be an object with the following defined:
  • method - HTTP method (e.g. 'GET', 'PUT', etc).
  • headers - A mapping of header names to string values. Multiple values for the same header should be represented as a single string with values separated by ,. Keys should be considered case insensitive.
  • body - Optional. May be a string, ArrayBuffer, or stream.
• signingDate - Optional. The date and time to be used as signature metadata. This value should be a Date object, a unix (epoch) timestamp, or a string that can be unerstood by the JavaScript Date constructor. Defaults to new Date().
• expiration - The time at which the signed URL should no longer be honored. This value should be a Date object, a unix (epoch) timestamp, or a string that can be understood by the JavaScript Date constructor.
• hoistHeaders - Optional. Indicates whether to move all values that would normally be sent as headers to the query string of the URL. This allows the returned value to be used in contexts that do not permit specifying additional headers, such as <img> tags or <a> links. If set to false, then the request must be sent along with the headers with which it was signed. Defaults to true.
• unsignableHeaders - Optional. An object whose keys represents headers that cannot be signed. All headers in the provided request will have their names converted to lower case and then checked for existence in the unsignableHeaders object using the in operator. Defaults to an object whose keys are lower-cased transfer-specific headers (such as user-agent, referer, expect, etc).
• unsignedPayload - Optional. Indicates whether to sign requests in such a way as to allow arbitrary message bodies. Useful for presigning requests for which the body is not known in advance. Defaults to value passed into constructor.

signRequest

The signRequest method accepts a request and returns a Promise that resolves with a signed request. The signed request will have an expiration and can be passed directly to an HTTP client. The following options can be provided within a hash to the signRequest method:

• request - The request to be signed. This parameter will not be modified during the signing process but will instead be cloned. The shape of the request should be an object with the following defined:
  • method - HTTP method (e.g. 'GET', 'PUT', etc).
  • headers - A mapping of header names to string values. Multiple values for the same header should be represented as a single string with values separated by ,. Keys should be considered case insensitive.
  • body - Optional. May be a string, ArrayBuffer, or stream.
• signingDate - Optional. The date and time to be used as signature metadata. This value should be a Date object, a unix (epoch) timestamp, or a string that can be unerstood by the JavaScript Date constructor. Defaults to new Date().
• unsignableHeaders - Optional. An object whose keys represents headers that cannot be signed. All headers in the provided request will have their names converted to lower case and then checked for existence in the unsignableHeaders object using the in operator. Defaults to an object whose keys are lower-cased transfer-specific headers (such as user-agent, referer, expect, etc).
• unsignedPayload - Optional. Indicates whether to sign requests in such a way as to allow arbitrary message bodies. Useful for presigning requests for which the body is not known in advance. Defaults to value passed into constructor.