Bill the Plumber

After describing Content-Signature in my last blog, it was picked up by InfoQ.  Also had a great private email exchange with Jean-Jacques Dubray in which we discussed various usecases for signature protocols.  Firstly, before I dive in, a disclaimer.  I am not a security expert and don’t pretend to be one.  While I have used various authentication and authorization protocols over the years, I have not been a designer or implementer of them.  So, here’s some use cases for Content-Signature:

The NULL Use Case

I think one of the most important aspects of something like Content-Signature is that this information can be ignored by any party in the request/response chain.  The signature becomes just another thing that describes the entity being passed around.  Why is this important?  I’ll give a simple example first, then later in the blog a more complex one.

Consider a simple blog.  Let’s say I posted some really stupid comment on somebody’s blog.  Its actually very easy to impersonate somebody in the comments section of anyone’s blog.  So, if a reader read my stupid comment and thought “Did Bill Burke really say that?!?”, how would they know if I really did post or not?  While not that practical in reality, what I could do is sign each comment I made to a blog.  That way, a reader could verify my signature if they so desired.

What’s interesting about this use case is that the blog itself doesn’t care about the signature.  Nor do most comment readers care about the signature.  Only a specific party cares about the signature.  With a header based approach like Content-Signature, renderers can completely ignore the signature applied to the comment if they do not care or understand how to process it.  This is why something like Content-Signature is better than multipart/signed, IMO.  Another interesting thing is that if the blog moved, lets say from Blogspot to WordPress, the import could take along the comment signature with it.  Even though the comment is served under a different URL, the signature is still valid.

Authentication, Authorization, and Message Integrity All In One

Another use for Content-Signature is that it could be used for authentication, authorization, and message integrity, all at the same time.  When a server received a request signed with Content-Signature, it could look into the metadata of Content-Signature to determine the signer.  (This assumes a asymetric key-pair solution)  Look up the public key of the signer in private registry.  Verify the signature with this public key.  If it is successful, the server knows a) that it is the signer that sent the message, and b)that the integrity of the message is good as well.  Now that the identity of the signer is known and valid, the server can determine internally whether the signer is authorized to make the request.  Because Content-Signature is flexible and allows you to add as much metadata as you wish to the signature, additional information like the request URL, a timestampe, a NONCE, whatever could be added to create a more secure process.

Approval Process

Consider a vacation request application.  An employee creates a vacation request form.  Signs it by adding a Content-Signature header and posts it to his manager.  The manager reads the request form, signs it, forwards the document and appends his signature to the Content-Signature header.  Forwards the doc and the new Content-Signature header to HR.  HR knows both parties approved of the document and processes the vacation.

Workflow

Consider a simple order entry workflow where each phase of order fulfillment needs to happen in a specific order.  Each phase also needs to know that the previous phases really happened.  i.e. don’t ship the product until it has been payed for.  It could work like this:

1. Customer posts order to order-entry system.  Signing it with his information.
2. Order entry verifies signature.  It also adds an additional signature “order-entry” which is customer-sig+message body.
3. Billing gets the order next.  It verifies the customer signature and that the “order-entry” signature.  Because “order-entry” was created with the customer-sig and message body, the billing system knows that the order is valid and that the exact order was looked at by the order-entry system.  The Billing system signs the message with customer-sig+message body.
4. Shipping gets the order next.  It verifies the customer and billing signatures and ships the product.

Ignorant Gateways and Authorization of Actions

Another use case that JJ talked to me about is the ignorant gateway scenario.  Imagine an application that would listen to your twitter messages and forward these messages, via SMS, to your friends’ mobile.  You would automatically be billed instead of the application forwarding the tweets.  In this case, Twitter is the ignorant, pass-through, gateway.   It knows nothing about the whole authorization process.  In an imaginary world, this is how it could work:

1. You post a twitter message.  You sign (“AT&T Auth Code” + “timestamp” + “message-id” + message body) and attach it as a signature to the method.
2. The App is listening to twitter.  Does an SMS of message and sends along signature too.
3. AT&T gets the SMS, looks at the signature.  Verifies it came from the user.  Because the “AT&T Auth Code” is part of the signature, AT&T knows that “Bill Burke” sent the SMS.  Since the “timestamp” and “Message-id” are part of the signature, AT&T can check to see if the SMS is a duplicate.  If all of these pass, then AT&T can bill “Bill Burke” instead of the App for the SMS.

This is also an example of authorization of a specific action via a signature.  I dont think you need separate signatures for each action you want to authorize.  It can just be a matter of concatenating multiple auth-codes within the same signature.  The hole in this approach is that hostile apps could trick users into adding an authorization to their signatures. i.e. “pay-me-$20-from-your-bank-account”.  This is why it is important for providers be involved in authorization code creation.

Complex Workflow

A complex workflow could combine some or all of these use cases together with the coordination of many different applications.

Conclusion

What it boils down to, is that, IMO, something like Content-Signature gives you a lot of flexibility when defining a distributed interface.  It allows you to combine metadata about a representation to the signing of a representation.  Because it is a header, it can be ignored if desired.  Since it is a set of simple name value pairs, it is very easy to create and parse.  (Well, depending on your platform, actually signing the message might be difficult, but, hey…).  Personally, I’m very interested in applying signatures to the RESTful interface we’re creating for our workflow engine.  Signatures just seem like a simpler way to manage multi-tier authentication and authorization.  Who knows, maybe I’m wrong here…

4/5/11: After a lot of feedback from the IETF HTTP WG, I found some work is already being done in this area in the DOSETA specification.  I’ll be retiring Content-Signature for the time being.

3/23/11: I’ve been encouraged to bring this to the IETF and have submitted an Internet-Draft on the subject.  Please go there to see further iterations on this specification.

Recently a RESTEasy user asked for the ability to digitally sign requests and responses.  They were pushing HTTP requests through one or more intermediaries and wanted to make sure that the integrity of the message was maintained as it hopped around the network.  They needed digital signatures.

There’s always been multipart/signed, but I never really liked the data format.  One, what if some clients support the format and some don’t?  Two, signature data seems really to belong in the HTTP header rather than enclosed within an envelope.  I found a nice blog that shared and added a bunch more to the conversation.  So, without finding a match by doing a google search, I decided to define our own protocol. (FYI, OAuth does have signatures as part of its protocol, but I wanted something that could be orthogonal to authentication as the client and server may not be using OAuth for authentication.)

Protocol Goals

The protocol goals and features we wanted to have were:

• Metadata defining exactly how the message was signed
• Ability to specify application metadata about the signature and have that metadata be a part of the signature
• Simplicity of headers.  Have all signature information be stored within HTTP request or response headers.  This makes it easier for frameworks and client and server code in general to handle signature verification.
• Expiration.  We wanted the option to expire signatures.
• Signer information.  We wanted the ability to know who signed the message.  This would allow receivers to look up verification keys within internal registries.
• Ability to ignore the signature if you don’t care about that information or if the client or server doesn’t know how to process it.
• Ability to forward representation/message to multiple endpoints/receivers
• Allow multiple different URLs to publish the same signed message
• Although it could be used as an authorization mechanism, it is not meant to replace existing OAuth or Digest protocols that ensure message integrity

The Content-Signature Header

The Content-Signature header contains all signature information.  It is an entity header that is transmitted along with a request or response.  It is a semicolon ‘;’ delimited list of name value pairs.  Values must be enclosed within quotes if they use any delimiting character within their name or value.  These attributes are metadata describing the signature as well as the signature itself.  Also, the Content-Signature may have more than one value, in other words, more than one signature may be included with the Content-Signature header.  Multiple signatures are delimited by the ‘,’ character.

These are the core attributes of the Content-Signature header:

signature – (required) This is the hex encoded signature of the message.  Hex encoding was chosen over Base64 because Base64 inserts cr/lf characters after 76 bytes which screws up HTTP header parsing.

values – (optional) this is a colon “:” delimited list of attributes that are included within Content-Signature header that are used to calculate the signature.  The order of these listed attributes defines how they are combined to calculate the signature.  The message body is always last when calculating the signature.  If this attribute is omitted, then no Content-Signature attribute is used within the calculation of the signature.

headers -(optional) List of colon “:” delimited  HTTP request or response headers that were included within the signature calculation.  The order of these listed headers defines how they are combined to calculate the signature.

algorithm – (optional) The algorithm used to sign the message.  The allowable values here are the same as those allowed by java.security.Signature.getInstance().  If there is a W3C RFC registry of signing algorithms we could use those instead.

signer - (optional) This is the identity of the signer of the message.  It allows the receiver to look up verification keys within an internal registry.  It also allows applications to know who sent the message.

id - (optional) This is the identity of the signature.  It could be used to describe the purpose of a particular signature included with the Content-Signature header.

timestamp – (optional) The time and date the message was signed.  This gives the receiver the option to refuse old signed messages.  The format of this timestamp is the Date format described in RFC 2616.

expiration – (optional) The time and date the message should be expired.  This gives the sender the option to set an expiration date on the message.  The format of this attribute is the Date format described in RFC 2616.

signature-refs – This is a ‘:’ delimited list referencing other signatures by their id attribute within the Content-Signature header.  This means that these referenced signature values will be included within the calculation of the current signature.  The hex-encoded value of the referenced signature will be used .

Other attributes may be added later depending on user requirements and interest.   URI and query parameters were specifically left out of the protocol as integrity between two parties should be handled by HTTPS/SSL, the Digest authentication scheme discussed in RFC 2617, or OAuth.  Remember, the point of writing this protocol is so that representations can be signed and exchanged between multiple parties on multiple machines and URLs.

Signing and Verifying a message

The signer of a message decides which Content-Signature attributes and HTTP headers it wants to include within the full signature.  The signature is calculated by signing the concatenation of

attribute-values + header-values + signature-refs + message-body

Attribute-values pertain to the list of attribute names defined within the ‘values’ attribute of the Content-Signature element.  Header-values pertain to the list of header names defined within the ‘headers’ attribute of the Content-Signature element.  Signature-refs pertains to referenced signatures that also appear in the Content-Signature header.  Attributes must always precede headers.  Headers must precede signature refs.  The message-body always comes last.  For example, if the signer decides to include the signer, expiration attributes and Content-Type and Date headers with a text/plain message of “hello world”, the base for the signature would look like this:

billSunday, 06-Nov-11 08:49:37 GMTtext/plainFriday, 11-Feb-11 07:49:37 GMThello world

The Content-Signature header transmitted would look like:

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

To verify a signature, the verifier would recreate the signature string by concatenating the attributes specified in the “values” attribute, HTTP headers defined in “headers” attribute, and finally the message body. Then apply the verification algorithm.

If there is an attribute declared within the “values” attribute that isn’t specified in the Content-Signature header, it is assumed it is a secret held between the signer and verifier.  i.e. the signer.  The value of this attribute must be determined in an undefined way.

If there is a header declared within the “headers” attribute that doesn’t exist, the server may choose to abort if it cannot figure out how to reproduce this value.

Here’s an example of multiple signatures.  Let’s say the Content-Signature header is initially set up like this with a message body of “hello”:

Content-Signature: id=husband;
                   signature=0001,
                   id=wife;
                   signature=0002

Here, we have two initial signatures signed by two different entities, husband and wife (found by their id attribute).  We want to define a third signature, marriage, that includes those signatures.

Content-Signature: id=husband;
                   signature=0001,
                   id=wife;
                   signature=0002,
                   id=marriage;
                   signature-refs=husband:wife
                  signature=00033

The marriage signature would be calculate by the signing of this string:

00010002hello

Which is:

husband’s signature + wife’s signature + message body

If there is a signature reference declared within the signature-refs attribute that doesn’t exist, the server may choose to abort if it cannot figure out how to reproduce this value.

Other similar protocols out there?

I only spent about an hour looking to see if there were similar protocols out there.  If somebody knows, let me know.  It would be cool to get feedback on this proposal as well.

Edited:

People in the comments section of this entry keep mentioning two-legged OAuth, but I don’t see how they describe anything other than in the Authorization header.  This is something we don’t want as we want to be able to use traditional authentication mechanisms so that signing can be supported on servers or clients that don’t understand OAuth (or don’t want to use it).