Digital signatures allow you to protect the integrity of a message. They are used to verify that a message sent was sent by the actual user that sent the message and was modified in transit. Most web apps handle message integrity by using TLS, like HTTPS, to secure the connection between the client and server. Sometimes though, we have representations that are going to be forwarded to more than one recipient. Some representations may hop around from server to server. In this case, TLS is not enough. There needs to be a mechanism to verify who sent the original representation and that they actually sent that message. This is where digital signatures come in.

Resteasy has developed its own protocol for digital signatures. It allows you to attach one or more digital signatures to a request or response via a Content-Signature header. Signatures are comprised of the message body and an arbitrary set of metadata. Adding metadata to the signature calculation gives you a lot of flexiblity to piggyback various features like expiration and authorization. Here's what an example Content-Signature header might look like.

Content-Signature: values=signer:expiration;
                   headers=Content-Type:Date;
                   signer=bill;
                   expiration="Sunday, 06-Nov-11 08:49:37 GMT";
                   signature=0f341265ffa32211333f6ab2d1

A complete description of the protocol is available on Bill Burke's Blog. We are also submitting this protocol as an Internet-Draft at IETF to hopefully get it standardized in some way or form. There's also another blog about various uses you might find for the protocol. The resteasy distribution also has an example you can check out.

import org.jboss.resteasy.security.signing.ContentSignature;
import org.jboss.resteasy.security.signing.ContentSignatures;
import java.security.PrivateKey;


@Path("/signed")
public static class SignedResource
{
   @GET
   @Produces("text/plain")
   @Path("manual")
   public Response getManual()
   {
      ContentSignature signature = new ContentSignature();
      PrivateKey privateKey = ...; // go find it
      signature.setPrivateKey(privateKey);
      Response.ResponseBuilder builder = Response.ok("hello");
      builder.header("Content-Signature", signature);
      return builder.build();
   }
}

// client example

ContentSignature signature = new ContentSignature();
PrivateKey privateKey = ...; // go find it
signature.setPrivateKey(privateKey);

ClientRequest request = new ClientRequest("http://...");
request.header("Content-Signature", signature);
request.body("text/plain", "some body to sign");
ClientResponse response = request.put();

$ keytool -genkeypair -alias myKey -keyalg RSA -keysize 1024 -keystore my-apps.jks 

    <context-param>
        <param-name>resteasy.keystore.classpath</param-name>
        <param-value>test.jks</param-value>
    </context-param>
    <context-param>
        <param-name>resteasy.keystore.password</param-name>
        <param-value>geheim</param-value>
    </context-param>

   @GET
   @Produces("text/plain")
   @Path("manual")
   public Response getManual()
   {
      ContentSignature signature = new ContentSignature();
      signature.setKeyAlias("myKey);
      Response.ResponseBuilder builder = Response.ok("hello");
      builder.header("Content-Signature", signature);
      return builder.build();
   }

import org.jboss.resteasy.core.Dispatcher;
import org.jboss.resteasy.security.keys.KeyRepository;
import org.jboss.resteasy.security.keys.KeyStoreKeyRepository;

import javax.ws.rs.core.Application;
import javax.ws.rs.core.Context;

public class SignatureApplication extends Application
{
   private HashSet<Class<?>> classes = new HashSet<Class<?>>();
   private KeyRepository repository;

   public SignatureApplication(@Context Dispatcher dispatcher)
   {
      classes.add(SignedResource.class);

      InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream("test.jks");
      repository = new KeyStoreKeyRepository(is, "password");
      dispatcher.getDefaultContextObjects().put(KeyRepository.class, repository);
   }

   @Override
   public Set<Class<?>> getClasses()
   {
      return classes;
   }
}

KeyStoreKeyRepository keyRepository = new KeyStoreKeyRepository("/usr/local/home/bill/my-apps.jks", "geheim");

ContentSignature signature = new ContentSignature();
signature.setSigner("myKey", true, true);

ClientRequest request = new ClientRequest("http://...");
request.getAttributes().put(KeyRepository.class.getName(), repository);
request.header("Content-Signature", signatures);

   @GET
   @Produces("text/plain")
   @Path("signedresource")
   @Signed(id="employee", signer="bill", timestamped=true, expires=@After(hours=24))
   public String getSigned()
   {
      return "hello world";
   }

Content-Signature: id=employee;
                   signer=bill;
                   timestamp="Wed, 09 Mar 2011 23:04:25 GMT";
                   expiration="Thur, 10 Mar 2011 23:04:25 GMT";
                   values=id:signer:timestamp:expiration;
                   signature=0FAB0CEF0050

      @POST
      @Consumes("text/plain")
      @Verify
      public void post(String input)
      {
      }

@POST
@Consumes("text/plain")
@Verifications(
   @Verify(id="inventory-signature", stale=@After(days=2)),
   @Verify(signer="bill"),
   @Verify(id="provider", attributeAlias="id)
}
public void post(String input) {...}

@POST
@Consumes("text/plain")
@Path("verify-manual")
public void verifyManual(@HeaderParam("Content-Signature") ContentSignature signature,
                         @Context KeyRepository repository, 
                         @Context HttpHeaders headers, 
                         MarshalledEntity<String> input) throws Exception
{
   PublicKey publicKey = repository.getPublicKey("someAlias");
   boolean verified = signature.verify(headers.getRequestHeaders(), 
                                       input.getMarshalledBytes(),
                                       publicKey);
   System.out.println("The text message posted is: " + input.getEntity());
}

ClientRequest request = new ClientRequest(TestPortProvider.generateURL("/signed"));
ClientResponse<MarshalledEntity<String>> response = request.get(new GenericType<MarshalledEntity<String>>() {});
MarshalledEntity<String> marshalledEntity = response.getEntity();
String signatureHeader = response.getHeaders().getFirst(ContentSignature.CONTENT_SIGNATURE);

ContentSignature contentSignature = new ContentSignature(signatureHeader);
boolean verified = contentSignature.verify(response.getHeaders(), marshalledEntity.getMarshalledBytes(), publicKey);