httpsig-java

Implementation of Joyent's HTTP Signature Authentication in Java

Introduction

This project is an adaptation of an earlier work I started on an SSHKey Authentication Scheme.

At some point, I discovered that Joyent had their own implementation of a similar scheme for JavaScript, so I decided to that porting my implementation over to their scheme would be better in the long run, as they had made more progress on a specification as well as already having some adoption. Luckily, I was able to switch over completely to the Joyent spec after only a few weeks of refactoring.

Only the RSA and DSA algorithms are supported at this point, by way of PEM-encoded public and private keys.

Additions to HTTP Signature Spec

• Definition of a simple WWW-Authenticate Challenge format to provide support for client/server parameter negotiation.

• Two additional signing algorithms based on the SSH public key authentication protocol, defined in RFC4253, "ssh-rsa" and "ssh-dss". I defined these in order to support implementations of the scheme using opaque SSH implementations, where the DER extraction and padding involved in RFC4253 are unavoidable.

Overview

• httpsig-api: Provides the Key, Keychain, and KeyId interfaces along with concrete implementations for Signer, Verifier, RequestContent, Challenge, and Authorization.

• httpsig-ssh-jce: Provides a JCE-based Key implementation for SSH RSA and DSA public keys and unencrypted private keys, with complete support for building Keychains from authorized_keys files.

• httpsig-ssh-bc: Use PEMUtil to read PEM-encoded SSH private keys (even encrypted) using the BouncyCastle provider.

• httpsig-http-helpers: Provides helpful utilities for three Java HTTP client implementations (Apache Commons HttpClient 3.x, Apache Http Client 4.x, Ning Async Http Client) as well as for javax.servlet.http on the server-side.

• net.adamcin.httpsig.osgi: Convenient OSGi bundle exporting httpsig-api, httpsig-ssh-jce, httpsig-ssh-bc, and httpsig-http-helpers.

• httpsig-ssh-jsch: Alternative implementation of SSH key support using the JSch API.

• httpsig-hmac: Provides a HMAC implementation with support for SHA-256 and SHA-512.

• httpsig-test-common: Provides several public/private SSH key pairs and utility methods for writing unit tests.

API

Signer

The Signer is the mechanism used by a client to select a Key from the Keychain, and sign the RequestContent in order to construct an Authorization header, which the client can then add to the request.

To create a Signer, you must provide both a Keychain and a KeyId. For example:

DefaultKeychain keychain = new DefaultKeychain();

// Use PEMUtil from httpsig-ssh-bc to read an SSH private key from a file
keychain.add(PEMUtil.readKey(new File("/home/user/.ssh/id_rsa"), "chang3m3"));

// The UserKeysFingerprintKeyId class is provided by httpsig-ssh-jce to
//   construct keyIds using the Joyent API convention, "/${username}/keys/${fingerprint}"
Signer signer = new Signer(keychain, new UserKeysFingerprintKeyId("admin"));

A keychain may have 0-to-many keys. The Signer selects a key based on a Challenge. The client triggers this selection by passing a Challenge to the rotateKeys() method.

Challenge challenge = Challenge.parse(wwwAuthnValue);

// Challenge.parse() may return null if a Signature challenge
//   could not be parsed from the provided header value.
if (challenge != null) {
    // The Signer will rotate the keychain until it finds the first
    //   signing key that supports the algorithms listed in the Challenge.
    signer.rotateKeys(challenge);
}

After selecting a key and building a RequestContent object, the client signs the content using the Signer.sign(requestContent) method in order to create an Authorization header.

RequestContent.Builder requestContentBuilder = new RequestContent.Builder();

// call requestContentBuilder.setRequestTarget(method, path) then
// for all request headers, requestContentBuilder.addHeader(name, value)...

Authorization authz = signer.sign(requestContentBuilder.build());

// The Signer.sign() method may return null if the request content
//   could not be signed.
if (authz != null) {
    // add request header "Authorization", authz.getHeaderValue()
}

If the subsequent request fails with a 401 Unauthorized / WWW-Authenticate: Signature, the client may rotate the keychain again to discard the invalid key.

Challenge nextChallenge = Challenge.parse(wwwAuthnValue);

// Challenge.parse() may return null
if (nextChallenge != null) {
    // The current key will be discarded if it satisfies nextChallenge
    //   after failing to authenticate in failedAuthz.
    signer.rotateKeys(nextChallenge, failedAuthz);
}

Verifier

The Verifier is the mechanism used by a server to verify the signature provided in the Authorization header against the Request and the Challenge defined for the server.

To create a Verifier, you must provide a Keychain and a KeyId. For example:

// The AuthorizedKeys class is provided by httpsig-ssh-jce
Keychain keychain = AuthorizedKeys.getDefaultKeychain();

// The UserKeysFingerprintKeyId class is provided by httpsig-ssh-jce to
//   construct keyIds using the Joyent API convention, "/${username}/keys/${fingerprint}"
Verifier verifier = new Verifier(keychain, new UserKeysFingerprintKeyId("admin"));

After parsing an Authorization and building the RequestContent object from the HTTP request, the server verifies the Authorization header using Verifier.verify()

// The challenge is defined by the server.
Challenge challenge = ...

Authorization authz = Authorization.parse(authzValue);

// Authorization.parse() may return null if a valid Signature Authorization was
//   not provided.
if (authz != null) {
    RequestContent.Builder requestContentBuilder = new RequestContent.Builder();

    // call requestContentBuilder.setRequestTarget(method, path) then
    // for all request headers, requestContentBuilder.addHeader(name, value)

    if (verifier.verify(challenge, requestContentBuilder.build(), authz)) {
        // handle request after successful authentication
    }
}

// otherwise, send 401 Unauthorized / WWW-Authenticate: Signature

If an Authorization header specifies "date" as a signed header, during verify the Verifier will also compare the Date header value against the server time +/- a millisecond skew, which is set to 300000L (300 seconds) by default. To adjust the skew, the server may call verifier.setSkew().

// one minute skew
verifier.setSkew(60000L);

// disable date checking (not recommended)
verifier.setSkew(-1L);

Challenge

The Challenge class represents a "WWW-Authenticate: Signature" header. It follows the RFC2617 syntax for parameters, the three of which are defined as:

• realm: The authentication realm defined by RFC2617

• headers: The space-delimited list of headers that are required in Authorization signatures. The order of these headers is not significant.

• algorithms: The space-delimited list of signature algorithms supported by the server.

Authorization

The Authorization class represents an "Authorization: Signature" header. It follows the RFC2617 syntax for parameters, the four of which are defined as:

• keyId: The identifier of the key used for signing and verification. If a principal is associated with authentication, it may be included in the keyId value, but this specification does not define a method by which a client and server may negotiate the keyId format.

• headers: The space-delimited list of headers in the order used to build the signed request content.

• algorithm: The signing algorithm used by the client

• signature: The Base64-encoded signature of the request content.

RequestContent

The RequestContent class represents the sign-able portion of an HTTP Request. This includes the request target (as in "GET /some/page.html?foo=bar") and all of the request headers, excluding the "Authorization" header.

It is created using the RequestContent.Builder class:

// example HTTP headers provided by a client implementation
Map<String, String> headers = ...

RequestContent.Builder requestContentBuilder = new RequestContent.Builder();

// set the HTTP request target
requestContentBuilder.setRequestTarget("GET", "/index.html");

// add each HTTP header in request order
for (Map.Entry<String, String> header : headers.entrySet()) {
    requestContentBuilder.addHeader(header.getKey(), header.getValue());
}

// if the date header is not set, set it to the current time, but remember
//   to add the resulting date header back to the original client request
if (requestContentBuilder.build().getDate() == null) {
    requestContentBuilder.addDateNow();

    String dateValue = requestContentBuilder.build().getDate();

    // add header ("date", dateValue) to client HTTP request...
}

// build the request content
RequestContent requestContent = requestContentBuilder.build();