REST APIs and message level security

Question

I need to implement message level security in a REST API and have some concerns and questions. I found the answer here: Message Level Security in Rest Web services

only partially helpful.

We currently support standard SSL transport security and several authentication methods including:

• Basic http auth (required by some network equipment services that talk to our API's)
• HMAC with pre-shared secrete key in both SHA1 and SHA256 flavors.
• Client identity certs sent @ the TLS level.
• SAML 2.0

Why we need message level security because:

• Customer industries include health care, financial and government, among others, and they often frown on SSL only.
• Need to guarantee end to end security. Through reverse proxies, SSL accelerators, etc...
• Some data passed through the services will include very sensitive data.
• Need to have a good answer for customers that insist that SOAP's WS-* security standards are "Enterprise strength" web services and REST APIs are not.

My initial thought is to use an PKCS#7 envelope, as an option, if client applications understand how to process enveloped responses.

I want client applications to tell the API that they want a secured response or tell the API that the message they are POSTing or PUTing is secured.

My real question is, should this be communicated through a media type? E.g.:

• Content-Type: application/vnd.resourcetype1+json+pkcs7
• Content-Type: txt/csv+pkcs7

i don't want to loose information on the media type that is enveloped.

It gets complicated as in some cases the signature is enough. Others require encryption as well. The term "pkcs7" is vague as to how the envelope is constructed.

I want the client and server to tell each other the type of content they are sending and the type of content they understand through standard HTTP headers.

Answer 1

Of course, it is up to you how to define your API, there is no right or wrong way, however S/MIME is a very well understood message format, well suited to the internet. As is PGP/MIME if your prefer a de-centralised trust hierarchy. Since these are well understood formats, it will allow clients to adopt existing libraries to process these message bodies.

If you are adament you do not want to use a multi-part response, you may want to take a look at the Content-Encoding header, besides just Content-Type. You could then specify the signature/encryption format as a custom encoding type.

There are significant benefits to using HTTP as an application protocol and not just a transport protocol, but you seem to understand that already. Be sure you set and parse the Accept* headers correctly, including q-values. Beware of things such as the default of q=1 meaning equal (not descending) preference, and q=0.