HTTP & LD Signature

This service implements the HTTP Signature and Linked Data Signature protocols, 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
  • Sign and verify HTTP signature
  • Build and verify HTTP digest
  • Sign and verify LD signature (not implemented yet)

Dependencies

  • None

Install

$ npm install @semapps/signature --save

Usage

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

Optionally, you can configure the API routes with moleculer-web:

const { ApiGatewayService } = require('moleculer-web');
module.exports = {
mixins: [ApiGatewayService],
dependencies: ['signature'],
async started() {
[
...(await this.broker.call('signature.getApiRoutes')),
// Other routes here...
].forEach(route => this.addRoute(route));
}
}

Settings

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

generateActorKeyPair

Parameters
PropertyTypeDefaultDescription
actorUriStringrequiredURI of the actor for which will generate the key pairs
Return

String - The generated public key.

generateSignatureHeaders

Parameters
PropertyTypeDefaultDescription
urlStringrequiredURL where the data will be sent
bodyStringrequiredData 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, Digest and Signature properties.

verifyDigest

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
urlStringrequiredURL where the message has been received
headersObjectrequiredHeaders of the message received
Return

Boolean - True if HTTP signature is verified.