http-signature

What is http-signature?

The http-signature npm package is used to create and verify HTTP request signatures. It is based on the Joyent HTTP Signature Scheme and allows for signing HTTP messages for authentication and message integrity. This package is commonly used in APIs and web services to ensure that HTTP requests are made by authenticated users and have not been tampered with in transit.

What are http-signature's main functionalities?

Signing HTTP Requests

This feature allows you to sign an HTTP request using a private key. The resulting signature is added to the request's headers, which can then be verified by the server to authenticate the request.

const httpSignature = require('http-signature');
const fs = require('fs');

const privateKey = fs.readFileSync('private.pem', 'ascii');

const requestOptions = {
  method: 'GET',
  path: '/foo',
  headers: {}
};

httpSignature.sign(requestOptions, {
  key: privateKey,
  keyId: 'myKeyId'
});

console.log(requestOptions.headers);

Verifying HTTP Requests

This feature allows you to verify the signature of an incoming HTTP request using a public key. If the signature is valid, it means the request was signed by the holder of the corresponding private key and has not been altered.

const httpSignature = require('http-signature');
const fs = require('fs');

const publicKey = fs.readFileSync('public.pem', 'ascii');

const request = {
  method: 'GET',
  url: '/foo',
  headers: {
    // headers should include the 'authorization' header with the signature
  }
};

const isValid = httpSignature.verifySignature(request, publicKey);

console.log(isValid);

Other packages similar to http-signature

jsonwebtoken

jsonwebtoken (or JWT) is a package that allows you to encode and decode JSON Web Tokens, which are a compact, URL-safe means of representing claims to be transferred between two parties. JWTs can also be signed like http-signature but are typically used for authorization tokens and information exchange, rather than signing HTTP requests.

oauth-1.0a

oauth-1.0a is a package that implements OAuth 1.0a, which is a protocol for authorization. It allows users to approve application to act on their behalf without sharing their password. It includes signing HTTP requests but is part of a broader authorization framework, unlike http-signature which focuses solely on signing and verifying HTTP messages.

passport-http

passport-http is a strategy for Passport, an authentication middleware for Node.js. It implements HTTP Basic and Digest authentication for Node.js applications but does not provide the same message signing capabilities as http-signature. Instead, it focuses on validating user credentials provided through HTTP headers.

README

node-http-signature is a node.js library that has client and server components for Joyent's HTTP Signature Scheme.

Usage

Note the example below signs a request with the same key/cert used to start an HTTP server. This is almost certainly not what you actaully want, but is just used to illustrate the API calls; you will need to provide your own key management in addition to this library.

Client

var fs = require('fs');
var https = require('https');
var httpSignature = require('http-signature');

var key = fs.readFileSync('./key.pem', 'ascii');

var options = {
  host: 'localhost',
  port: 8443,
  path: '/',
  method: 'GET',
  headers: {}
};

// Adds a 'Date' header in, signs it, and adds the
// 'Authorization' header in.
var req = https.request(options, function(res) {
  console.log(res.statusCode);
});


httpSignature.sign(req, {
  key: key,
  keyId: './cert.pem'
});

req.end();

Server

var fs = require('fs');
var https = require('https');
var httpSignature = require('http-signature');

var options = {
  key: fs.readFileSync('./key.pem'),
  cert: fs.readFileSync('./cert.pem')
};

https.createServer(options, function (req, res) {
  var rc = 200;
  var parsed = httpSignature.parseRequest(req);
  var pub = fs.readFileSync(parsed.keyId, 'ascii');
  if (!httpSignature.verifySignature(parsed, pub))
    rc = 401;

  res.writeHead(rc);
  res.end();
}).listen(8443);

Installation

npm install http-signature

License

MIT.

Bugs

See https://github.com/joyent/node-http-signature/issues.