Skip to main content

HTTP Signature

This service implements HTTP Signature authentication, which allow to send messages in a secure way between servers. It is used in particular with the ActivityPub federation mechanism.

Features

  • Generate actors key pair and attach them
  • Sign and verify HTTP signature
  • Build and verify HTTP digest
  • Authenticate server-to-server interactions (through ApiGateway)
  • Sign and verify Linked Data Signature (not implemented yet)

Sub-services

Other services

Dependencies

  • None

Install

$ yarn add @semapps/signature

Usage

const { SignatureService } = require('@semapps/signature');
const path = require('path');

module.exports = {
mixins: [SignatureService],
settings: {
actorsKeyPairsDir: path.resolve(__dirname, '../actors')
}
};

Authentication

If you wish users to be able to authenticate themselves through HTTP signature (for server-to-server interactions), but still want to allow regular authentication with JWT token, you can configure the API service like this:

const ApiGatewayService = require('moleculer-web');

const ApiService = {
mixins: [ApiGatewayService],
settings: { ... },
methods: {
authenticate(ctx, route, req, res) {
if (req.headers.signature) {
return ctx.call('signature.authenticate', {route, req, res});
} else {
return ctx.call('auth.authenticate', {route, req, res});
}
},
authorize(ctx, route, req, res) {
if (req.headers.signature) {
return ctx.call('signature.authorize', {route, req, res});
} else {
return ctx.call('auth.authorize', {route, req, res});
}
}
}
}

Settings

PropertyTypeDefaultDescription
actorsKeyPairsDirStringrequiredPath to where the actor's key pair will be stored.

Actions

The following service actions are available.

authenticate

To be used with the ApiGateway (see above)

authorize

To be used with the ApiGateway (see above)

generateSignatureHeaders

Generate a HTTP signature based on the actor's private key and the body of the message.

Parameters
PropertyTypeDefaultDescription
urlStringrequiredURL of the request to sign
methodStringrequiredHTTP method of the request to sign
bodyStringData to be sent. This is used to build the Digest string. If it is JSON, it must be stringified
actorUriStringrequiredURI of the actor for which will generate the signature
Return

Object - HTTP headers with Date and Signature properties, plus Digest if a body is provided.

verifyDigest

Verify that the digest of the header is valid.

Parameters
PropertyTypeDefaultDescription
headersObjectrequiredHeaders of the message (with or without a Digest property)
bodyStringrequiredData to the message. If it is JSON, it must be stringified
Return

String - The generated public key.

verifyHttpSignature

Fetch remote actor's public key and verify that the signature in the headers has been generated by this actor.

Parameters
PropertyTypeDefaultDescription
urlStringURL of the request (not necessary if path is provided
pathStringPath of the request (not necessary if url is provided)
methodStringrequiredHTTP method of the request received
headersObjectrequiredHeaders of the message received
Return

Object with two properties: isValid (Boolean) and actorUri (String)