HTTP signatures provide a mechanism by which a shared secret key can be used to digitally "sign" a HTTP message to both verify the identity of the sender and verify that the message has not been tampered with in-transit.
This is done by concatenating the desired HTTP Headers together to form a string called a "Signing String". An encrypted
hash (digitial signature) is made of the Signing String using either an asymmetric algorithm (rsa-sha256) with a
public/private key pair or a symmetric algorithm (hmac-sha256) with a shared secret key.
Finally, the encrypted bytes are Base64 encoded and added to the Authorization header, along with the keyId, signing algorithm, header names, and the signature itself.
For example, the following Signing String:
digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
date: Tue, 07 Jun 2014 20:51:35 GMT
(request-target): get /foo/Barif encrypted using the hmac-sha256 algorithm with the secret don't tell, and then encoded with Base64 would yield the result:
6aq7lLvqJlYRhEBkvl0+qMuSbMyxalPICsBh1qV6V/s=This would then be applied to the Authorization header as below:
Authorization: Signature keyId="myusername:mykey",algorithm="hmac-sha256",headers="digest
date (request-target)",signature="6aq7lLvqJlYRhEBkvl0+qMuSbMyxalPICsBh1qV6V/s="Add the following dependency to your Maven pom file.
<dependency>
<groupId>org.tomitribe</groupId>
<artifactId>tomitribe-http-signatures</artifactId>
<version>1.5</version>
</dependency>There are 2 key classes in this library:
-
Signature- defines the headers that make up the signature - this must as a minimum include the headers that the server requires to be part of the signature -
Signer- computes the signature value using the headers/values defined on the Signature classes
The Signer instance is intended to be created once and reused to sign all the HTTP messages that require HTTP Signature Authentication.
It is immutable, fully thread-safe and optimized to check and verify the supplied Key on construction.
The first steps to creating a Signer instance are as follows:
final Signature signature = new Signature("key-alias", "hmac-sha256", null, "(request-target)"); // (1)
final Key key = new SecretKeySpec(passphrase.getBytes(), "HmacSHA256"); // (2)
final Signer signer = new Signer(key, signature); // (3)-
Define a new
Signatureobject. ThisSignatureobject isn’t fully computed signature, but rather a template for the Signatures that will be created by theSignerfor specific HTTP messages. It requires a key alias (1st parameter), the signature algorithm (2nd parameter - usually "hmac-sha256") and a var-arg list of header names indicating which headers will require signing (4th - nth parameters). -
Define a SecretKeySpec instance, this needs the shared secret passphrase, and the algorithm used to store it in the keystore (usually "HmacSHA256").
-
Initialize a new Signer object with the key and signature from <1> and <2> above
Once you have a Signer, signing an HTTP Message is as simple as passing in the respective parts and letting the signer do the
magic. The library is not specific to any HTTP Client Java library such as Apache HttpClient, therefore data must be copied from
the request object of your specifc HTTP Client library and passed to the Signer in simple String and Map form.
final String method = "GET";
final String uri = "/foo/Bar";
final Map<String, String> headers = new HashMap<String, String>();
headers.put("Host", "example.org");
headers.put("Date", "Tue, 07 Jun 2014 20:51:35 GMT");
headers.put("Content-Type", "application/json");
headers.put("Digest", "SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=");
headers.put("Accept", "*/*");
headers.put("Content-Length", "18");
// Here it is!
final Signature signed = signer.sign(method, uri, headers);The returned Signature object represents a full HTTP Signature. Simply call toString() on it to get a fully formatted Authorization header value.
Calling toString() on the above Signature instance will yeild the following:
Signature keyId="my-key-name","algorithm="hmac-sha256",headers="content-length host date (request-target)",signature="yT/NrPI9mKB5R7FTLRyFWvB+QLQOEAvbGmauC0tI+Jg="The output of signature.toString() should be used as the value the Authorization header for the request.
The following sections demonstrate a few common scenarios using http-signatures-java.
This is the simplest request. Only the request-target (URI) is used to build the signature.
final Signature signature = new Signature("key-alias", "hmac-sha256", null, "(request-target)"); // (1)
final Key key = new SecretKeySpec(passphrase.getBytes(), "HmacSHA256");
final Signer signer = new Signer(key, signature);
final Map<String, String> headers = new HashMap<>();
return signer.sign(method, uri, headers); // (2)-
Define the Signature object using just the "(request-target)" (note the use of parenthesis) element.
-
Use the Signer class with the method, URI, and an empty header map to create the signature.
This is similar to the the previous example, but expands on it by adding the date header to the signature. The date should be created in the "EEE, dd MMM yyyy HH:mm:ss zzz" format, and the exact same date should be passed to the Signer as is used on the Date header.
final Date today = new Date(); // default window is 1 hour
final String stringToday = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss zzz", Locale.US).format(today);
final Signature signature = new Signature("key-alias", "hmac-sha256", null, "(request-target)", "date"); // (1)
final Key key = new SecretKeySpec(passphrase.getBytes(), "HmacSHA256");
final Signer signer = new Signer(key, signature);
final Map<String, String> headers = new HashMap<>();
s.put("Date", stringToday); // (2)
return signer.sign(method, uri, headers);-
Define the Signature object with the "(request-target)" and "date" headers
-
Include the date in the headers map
final byte[] digest = MessageDigest.getInstance("SHA-256").digest(payload.getBytes()); // (1)
final String digestHeader = "SHA-256=" + new String(Base64.encodeBase64(digest));
final Signature signature = new Signature("key-alias", "hmac-sha256", null, "(request-target)", "digest"); // (2)
final Key key = new SecretKeySpec(passphrase.getBytes(), "HmacSHA256");
final Signer signer = new Signer(key, signature);
final Map<String, String> headers = new HashMap<>();
headers.put("digest", digestHeader);
return signer.sign(method, uri, headers);-
Define the Signature object with the "(request-target)" and "digest" headers
-
Include the digest in the headers map
Signing HTTP Messages (Internet Draft) https://tools.ietf.org/html/draft-ietf-httpbis-message-signatures-00
Instance Digests in HTTP http://tools.ietf.org/html/rfc3230
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
public class SigningExample {
public static void main(String... s) throws Exception {
final String key = "don't tell";
final String signingString = "digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n" +
"date: Tue, 07 Jun 2014 20:51:35 GMT\n" +
"(request-target): get /foo/Bar";
final Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256"));
final byte[] signedBytes = mac.doFinal(signingString.getBytes("UTF-8"));
final Base64.Encoder encoder = Base64.getEncoder();
final String result = new String(encoder.encode(signedBytes), "UTF-8");
if (!"6aq7lLvqJlYRhEBkvl0+qMuSbMyxalPICsBh1qV6V/s=".equals(result)) {
throw new IllegalStateException("Signing failed");
}
System.out.println(result);
}
}#!/bin/bash
# Secret Key
KEY="don't tell"
# Create the Signing string from the required headers
STRING='digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
date: Tue, 07 Jun 2014 20:51:35 GMT
(request-target): get /foo/Bar'
# Sign the string, base64
echo -n "$STRING" | openssl dgst -binary -sha256 -hmac "$KEY" | base64Running this will print:
6aq7lLvqJlYRhEBkvl0+qMuSbMyxalPICsBh1qV6V/s=