http-signature.md

description
This page provides the technical details of the HTTP Signature policy

HTTP Signature

Overview

HTTP Signature is a kind of authentication method which is adding a new level of security. By using this policy, the consumer is enforced to send a signature which is used to identify the request temporarily and ensure that the request is really coming from the requesting consumer, using a secret key.

Functional and implementation information for the http-signature policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 proxy APIs. It cannot be applied to v4 message APIs. {% endhint %}

{% tabs %} {% tab title="Proxy API example" %} Sample policy configuration:

{
  "http-signature": {
	"scheme":"AUTHORIZATION",
	"clockSkew":30,
	"secret":"my-passphrase",
	"algorithms":["HMAC_SHA256"],
	"enforceHeaders":["Date","Host"]
  }
}

{% endtab %} {% endtabs %}

Configuration

The "Signature" authentication scheme is based on the model that the client must authenticate itself with a digital signature produced by either a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., HMAC).

To authenticate, clients can use Authorization header or Signature header. For example:

• Authorization: Signature "keyId="rsa-key-1",created=1630590825,expires=1630590831061,algorithm="hmac-sha256",headers="host",signature="Ib/KOuoDjyZPmLbKPvrnz+wj/kcEFZt5aPCxF4e7tO0="",
• Signature: "keyId="rsa-key-1",created=1630590825,expires=1630590831061,algorithm="hmac-sha256",headers="host",signature="Ib/KOuoDjyZPmLbKPvrnz+wj/kcEFZt5aPCxF4e7tO0="",

{% hint style="info" %} The current version of the policy does not support Digest, (request-target), Host, and Path headers {% endhint %}

Phases

The phases checked below are supported by the http-signature policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The http-signature policy can be configured with the following options:

Property	Required	Description	Default	Example
scheme	true	Signature Scheme (authorization header or signature header)	authorization	-
secret	true	The secret key used to generate and verify the signature (supports EL).	-	passphrase
algorithms	false	A list of supported HMAC digest algorithms.	-	-
enforceHeaders	false	List of headers the consumer must at least use for HTTP signature creation.	-	-
clockSkew	false	Clock Skew in seconds to prevent replay attacks.	30	-

Compatibility matrix

The following is the compatibility matrix for APIM and the http-signature policy:

Plugin version	Supported APIM versions
1.x	All

Errors

Code	Message
401	Missing or signature Request does not contain headers part of the signature Enforce HTTP headers not part of the signature

To override the default response provided by the policy, use the response templates feature. These templates must be define at the API level (see Response Templates from the Proxy menu).

Below are the error keys sent by the http-signature policy:

Key	Parameters
HTTP_SIGNATURE_INVALID_SIGNATURE	-

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-http-signature/blob/master/CHANGELOG.md" %}