RESTful Web services and signatures

A common question relating to REST security is whether or not one can achieve message level integrity in the context of a RESTful web service exchange. Security at the message level (as opposed to transport level security such as HTTPS) presents a number of advantages and is essential for achieving a number of advanced security related goals.

When faced with the question of how to achieve message level integrity in REST, the typical reaction of an architect with a WS-* background is to incorporate an XML digital signature in the payload. Technically, including an XML dSig inside a REST payload is certainly possible. After all, XML dSig can be used independently of WS-Security. However there are a number of reasons why this approach is awkward. First, REST is not bound to XML. XML signatures only sign XML, not JSON, and other content types popular with RESTful web services. Also, it is practical to separate the signatures from the payload. This is why WS-Security defines signatures located in SOAP headers as opposed to using enveloped signatures. And most importantly, a REST ‘payload’ by itself has limited meaning without its associated network level entities such as the HTTP verb and the HTTP URI. This is a fundamental difference between REST and WS-*, let me explain further.

Below, I illustrate a REST message and a WS-* (SOAP) message. Notice how the SOAP messages has it’s own SOAP headers in addition to transport level headers such as HTTP headers.

The reason is simple: WS-* specifications go out of their way to be transport independent. You can take a soap message and send it over HTTP, FTP, SMTP, JMS, whatever. The ‘W’ in WS-* does stand for ‘Web’ but this etymology does not reflect today’s reality.

In WS-*, the SOAP envelope can be isolated. All the necessary information needed is in there including the action. In REST, you cannot separate the payload from the HTTP verb because this is what defines the action. You can’t separate the payload from the HTTP URI either because this defines the resource which is being acted upon.

Any signature based integrity mechanism for REST needs to have the signature not only cover the payload but also cover those HTTP URIs and HTTP verbs as well. And since you can’t separate the payload from those HTTP entities, you might as well include the signature in the HTTP headers.

This is what is achieved by a number of proprietary authentication schemes today. For example Amazon S3 REST authentication and Windows Azure Platform both use HMAC based signatures located in the HTTP Authorization header. Those signatures cover the payload as well as the verb, the URI and other key headers.

OAuth v1 also defined a standard signature based token which does just this: it covers the verb, the uri, the payload, and other crucial headers. This is an elegant way to achieve integrity for REST. Unfortunately, OAuth v2 dropped this signature component of the specification. Bearer type tokens are also useful but, as explained by Eran Hammer-Lahav in this post, dropping payload signatures completely from OAuth is very unfortunate.


7 Responses to RESTful Web services and signatures

  1. Tbee says:

    Makes a lot of sense

  2. Hello,

    I just wanted to note that the XML Signature specification states that XML Signature can be applied to any type: not only XML. ( See Abstract )

    • Alex Cruise says:


      Calculating a signature over arbitrary data (URI, HTTP verb, headers, request body…) isn’t the problem. The problem is deciding and agreeing on stuff like:

      * what the signature covers
      * what it doesn’t cover (i.e. what kinds of changes by intermediaries should be permitted without breaking signatures…)
      * what format it should have
      * where it goes
      * etc…

      WS-S + XML-DSig is ghastly in many ways, but at least messages are pretty much self-describing if you follow the rules; no need for prior agreement between parties, and a pretty fair chance to get a message through any number of different transports and intermediaries without breaking the original signature.

      • yes, agreeing on standards is key to doing signatures right, there is no technical barrier here. this post was about the ‘where it goes’ part. a lot of REST signatures like Amazon S3 and Azure Storage REST api make up their own HMAC with their own definition of what is covered, in which order, etc.

        we need a volunteer to write an RFC which standardizes this 😉

  3. Eclogue Chang says:

    If the solution requires client’s private key for signature, then it will not be a practical solution as most of clients do not have private key to sign.

    • Eclogue,

      Dealing with client side PKI is not uncommon in the Enterprise and is regularly used for B2B types of interactions for example. This said, signatures patterns with REST often rely on symmetric keys instead (HMAC signatures for example). A signature using a symmetric key requires a shared secret only (same as password type authentication).


  4. […] RESTful Web services and signatures « Francois Lascelles's Blog (tags: rest webservices security soap http headers) […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: