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
- Authenticate server-to-server interactions (ApiGateway)
- Sign and verify LD signature (not implemented yet)
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
Property | Type | Default | Description |
---|---|---|---|
actorsKeyPairsDir | String | required | Path 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)
deleteActorKeyPair
Delete the private/public key pair of a given actor.
Parameters
Property | Type | Default | Description |
---|---|---|---|
actorUri | String | required | URI of the actor |
getActorPublicKey
Get the public key of a given actor
Parameters
Property | Type | Default | Description |
---|---|---|---|
actorUri | String | required | URI of the actor |
Return
String
- The actor's public key.
generateActorKeyPair
Generate the private/public key pair for a given actor.
Parameters
Property | Type | Default | Description |
---|---|---|---|
actorUri | String | required | URI of the actor for which will generate the key pairs |
Return
String
- The generated public key.
generateSignatureHeaders
Generate a HTTP signature based on the actor's private key and the body of the message.
Parameters
Property | Type | Default | Description |
---|---|---|---|
url | String | required | URL of the request to sign |
method | String | required | HTTP method of the request to sign |
body | String | Data to be sent. This is used to build the Digest string. If it is JSON, it must be stringified | |
actorUri | String | required | URI 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
Property | Type | Default | Description |
---|---|---|---|
headers | Object | required | Headers of the message (with or without a Digest property) |
body | String | required | Data 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
Property | Type | Default | Description |
---|---|---|---|
url | String | URL of the request (not necessary if path is provided | |
path | String | Path of the request (not necessary if url is provided) | |
method | String | required | HTTP method of the request received |
headers | Object | required | Headers of the message received |
Return
Object
with two properties: isValid
(Boolean) and actorUri
(String)