generate-http-signature.md

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

Generate HTTP Signature

Overview

HTTP Signature is an authentication method for adding additional security.

Functional and implementation information for the generate-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 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

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

{
  "generate-http-signature": {
	"scheme":"AUTHORIZATION",
	"validityDuration":30,
	"keyId":"my-key-id",
	"secret":"my-passphrase",
	"algorithm":"HMAC_SHA256",
	"headers":["X-Gravitee-Header","Host"],
    "created": true,
    "expires": true
  }
}

{% endtab %} {% endtabs %}

Configuration

The Signature authentication model requires the client to 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, or Path headers. {% endhint %}

Sample policy configuration is shown below:

{% code title="Sample Configuration" %}

{
  "name": "Custom name",
  "description": "Adds HTTP signature auth",
  "policy": "generate-http-signature",
  "configuration": {
	"scheme": "AUTHORIZATION",
	"validityDuration": 30,
	"keyId": "my-key-id",
	"secret": "my-passphrase",
	"algorithm": "HMAC_SHA256",
	"headers": ["X-Gravitee-Header","Host"],
    	"created": true,
   	"expires": true
  }
}

{% endcode %}

Phases

The phases checked below are supported by the generate-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

You can configure the generate-http-signature policy with the following options:

Property	Required	Description	Default	Example
scheme	true	Signature Scheme (authorization header or signature header)	authorization	-
keyId	true	The key ID used to generate the signature (supports EL)	-	rsa-key-1
secret	true	The secret key used to generate and verify the signature (supports EL)	-	passphrase
algorithm	true	The HMAC digest algorithm	HMAC_SHA256	-
headers	false	List of headers to build the signature. If no headers, the request must at least contains Date header.	-	-
created	true	Include the created timestamp in the signature and (created) header	true	-
expires	true	Include the expires timestamp in the signature and (expires) header	true	-
validityDuration	false	Signature’s maximum validation duration in seconds (minimum is 1). Applied when expires is set to true.	3	-

Compatibility matrix

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

Plugin Version	Supported APIM versions
Up to 1.x	All

Errors

HTTP status code	Description
400	Request does not contain every header in the configuration headers list. Request does not contain Date header and the configuration headers list is empty. Policy needs at least Date header to create a signature. Unable to sign because of bad configuration.

You can override the default response provided by the policy via the response templates feature. These templates must be defined at the API level (see Response Templates from the Proxy menu). The following keys are sent by the generate-http-signature policy:

Key	Parameters
HTTP_SIGNATURE_IMPOSSIBLE_GENERATION	-

Changelogs

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