http-signature-helpers

Helpers for the HTTP Signature spec.

Install

yarn add http-signature-helpers
# or
npm install http-signature-helpers

import { getSignatureString, createSignatureHeader, parseSignatureHeader } from "http-signature-helpers";
# or
const { getSignatureString, createSignatureHeader, parseSignatureHeader } = require("http-signature-helpers");

Usage

getSignatureString(options)

Get the signature string (this is the content to create the signature from).

Options (object):

• body: (string) Body content
• headers: (object) Key-value of HTTP headers to be used with signatureHeaders
• signatureHeaders (array) Which headers to include in signature string
• target: (object) Values to use with (request-target) signatureHeader (optional)
  • method: (string) HTTP method (GET, POST, etc)
  • path: (string) Request path (/, etc)
• nonce: (object) Used for signature nonce spec (optional)
  • clientId: (string/number)
  • nonce: (string/number)

Example:

getSignatureString({
	body: "body",
	headers: {
		Host: "example.org",
		Date: "Tue, 07 Jun 2014 20:51:35 GMT",
		"X-Example": `Example header
                        with some whitespace.`,
		"Cache-Control": "max-age=60, must-revalidate"
	},
	signatureHeaders: [
		"(request-target)",
		"host",
		"date",
		"cache-control",
		"x-example"
	],
	target: {
		method: "GET",
		path: "/foo"
	}
});

(request-target): get /foo
host: example.org
date: Tue, 07 Jun 2014 20:51:35 GMT
cache-control: max-age=60, must-revalidate
x-example: Example header with some whitespace.
body

createSignatureHeader(options)

Get the signature header to set to Authorization.

Options (object):

• keyId: (string) Key identifier
• algorithm: (string) Algorithm (known/recommended values: rsa-sha256, hmac-sha256. The algorithm link on the draft spec is dead)
• signature: (string) Signature generated from getSignatureString
• signatureHeaders: (array) Headers to be included in header param. Matching from getSignatureString
• nonce: (object) Used for signature nonce spec (optional). Matching from getSignatureString
  • clientId: (string/number)
  • nonce: (string/number)
• prefix (booleam, default: true) If it should prefix with Signature.

Example:

createSignatureHeader({
	keyId: "rsa-key-1",
	algorithm: "rsa-sha256",
	signatureHeaders: [
		"(request-target)",
		"host",
		"date",
		"digest",
		"content-length"
	],
	signature: "rsa-signature-1"
});

Signature keyId="rsa-key-1",algorithm="rsa-sha256",headers="(request-target) host date digest content-length",signature="rsa-signature-1"

parseSignatureHeader(value, prefix = true)

Parse the value from createSignatureHeader. If prefix is true, it will remove the Signature prefix.

Example:

parseSignatureHeader(
	`Signature keyId="rsa-key-1",algorithm="rsa-sha256",headers="(request-target) host date digest content-length",signature="rsa-signature-1"`
);

{
    keyId: "rsa-key-1",
    algorithm: "rsa-sha256",
    signatureHeaders: ["(request-target)", "host", "date", "digest", "content-length"],
    signature: "rsa-signature-1"
}