json-home format: resource discovery


Thank you Mark Little for turning me on to the JSON-Home format Internet Draft.  “application/json-home” is a format that describes resources available from a particular site as well as possible hints on how to interact with those services.

   GET / HTTP/1.1
   Host: example.org
   Accept: application/json-home

   HTTP/1.1 200 OK
   Content-Type: application/json-home
   Cache-Control: max-age=3600
   Connection: close

     "resources": {
       "http://example.org/rel/widgets": {
         "href": "/widgets/"
       "http://example.org/rel/widget": {
         "href-template": "/widgets/{widget_id}",
         "href-vars": {
           "widget_id": "http://example.org/param/widget"
         "hints": {
           "allow": ["GET", "PUT", "DELETE", "PATCH"],
           "representations": ["application/json"],
           "accept-patch": ["application/json-patch"],
           "accept-post": ["application/xml"],
           "accept-ranges": ["bytes"]

While I like the format, my own personal opinion is that hints are not needed.  Most(99%?) non-browser clients already know how to interact with the resources.  What they are looking for, really, is the actual URL to the resource.  IMO, a separate format(s) should be defined for resource description and the link relation URL can offer up that representation if it wants to.

Another beef I have with this (and the atom link XML format too) is that the value for the relationship, rel, can be a URL.  I'd much rather define a logical name, and have a separate attribute that specifies a URL that describes the relationship.  For applications, especially intra-net based ones, URLs can change more frequently than their Internet counterparts.  A logic name attribute could remain fixed and the description URL could be more dynamic.

BTW, I'm glad that the powers-that-be at IETF are showing some love to non-browser clients. Json-home is something similar I've done for a few of the RESTful services I've written.

Decentralized Auth with Cookies

Leave a comment

Way back in June I was brainstorming about ideas for decentralized authentication.  Here’s a summary of the requirements I wanted:

  • Competely stateless servers.  Servers that host browser applications and restful services would not have to store usernames, passwords, or permission metadata (roles allowed).
  • Servers would not have to handshake with an Identity Provider (IDP).  An HTTP request should contain all the information a server needs to authenticate and authorize a client.
  • A single web request can spawn complex authenticated and authorized interactions between underlying distributed web services.  This single web request would have all the metadata needed to invoke these complex underlying interactions between distributed services.

Unifying Interactions With Cookies

The problem with the protocol discussed in my previous blog was that it relied on new headers being transmitted between the client and server.  This sort of mechanism just wouldn’t work with browser-based applications.  Why?  Well, a browser isn’t going to know how to transmit and process new headers.  The only way to get a browser to store and forward metadata is via a cookie.  Most browser-based apps already use a session cookie to authenticate users (after a log-in of course).  There’s no reason we couldn’t re-use the digital signature techniques discussed in my previous blog with cookies.  Here’s how it could work:

  1. Browser points to example.com
  2. example.com redirects browser to idp.com (the identity provider)
  3. User logins into the IDP
  4. IDP redirects back to example.com.  The forward URL has all security metadata needed for the request, digitally signed (a query parameter would have the signature).  The amazon url signing technique could be used.
  5. Example.com would authenticate and authorize based on the query parameters of the forward URL and also verify the signature.
  6. Example.com would send back a set of cookies that contained all the security metadata expressed as cookie name/value pairs.  A special digital signature cookie would be used to sign them all so that on subsequent requests, the server could verify all the information stored in these cookies.

Step #4 might be problematic as the URLs could get quite large.  Who knows if a browser barfs on absurdly long URLs.  In this cast we could do a double form-post.  IDP could response from a successful login with an HTML Form whose target is Example.com.  This form would have all hidden fields within it containing security metadata.  One particulr form parameter would have a digital signature (I think SAML HTTP bindings work like this).

One vulnerability here is the cross-site scripting hack.  Most website already have this vulnerability I believe, so using existing techniques would be best.  I’m not sure how website solve this particular problem, but the HttpOnly flag could be used with each session cookie.  Javascript apps could have their javascript dynamically generated by the server and include the necessary code to manually apply and send the appropriate cookies.  Another thing that might mitigate things, is to include a timestamp with the cookies.  The application server would check for stale timestamps and with each request reset the digitally signed cookies with a new timestamp.

Non-Browser Clients Use Cookies Too

For non-browser clients, they could use a simpler RESTful protocol to obtain a signed URL or the set of signed form parameters.  There’s also no reason they couldn’t get a set of signed cookies instead of either of these approaches.



Web Sockets, a disaster in waiting?


Mark posted a really nice article to InfoQ: WebSockets vs. REST?

From what I understand of Websockets, its bascially used to set up a two-way socket connection and not really an application protocol. What worries me the most is that you’ve basically rolled back 20 years of protocol consolidation, and we’re now back to a free-for-all of everybody’s pet protocol. Not so bad if your client and server are a tightly coupled, unreusable UI application. Really bad if you’re writing a web service that is supposed to be reusable by unknown heterogenous clients. With Web Sockets, web services are not only going to have to negotiate the media type, but also the application protocol. Seems like a huge step backward to me in terms of integration.  Did we forget all the problems we had with Oracle Forms, PowerBuilder, Visual Basic and all the UI/framework specific protocols all those developer frameworks introduced?  Do we really want to go back to those days?

What about security issues?  With an anything-goes socket protocol, isn’t this a security nightmare for our operations folks?

Disclaimer:  You could say that I’m both biased and threated by the concept of Web Sockets given my involvement in REST frameworks and APIs.  But in all honesty, I’d be very happy to embrace a new protocol that is both ubiquitous and easily supportable and interoperable in many different languages and platforms.  There’s much to be said about the simple request/response text-based approach of HTTP (and REST over HTTP).  While it may not be uber-efficient, its just so easy to hack and support.

Resteasy 2.3.1 Released

1 Comment

This is a maitenance release of 2.3.x series.

As always, to download and see documentation follow the links from our website.  Take a look at our Jira release notes.  You might also want to check out the Migration guide to view what has broken as far as backward compatibility if you’re upgrading from an earlier version.

World of RESTCraft


An online buddy of mine drew my attention to Blizzard’s new Community API for World of Warcraft.  For those of you who aren’t familiar with World of Warcraft, it is a massive multi-player online role playing game.  They have millions of players.  The game is so successful and generates so much cash that Blizzard pays out a dividend to stock holders.  Not only do they have millions of players, there’s also a very large community around WoW.  The game itself has its own scripting language which you can use to write add-ons.  This add-on community is huge with thousand upon thousands of apps written.

There’s also a large variety of third-party sites that provide character and guild management, quest information, gear info, damage simulators, and gear optimization.  These types of tools need to access Blizzard’s databases.  This is where Blizzard’s new REST-based Community API comes.  Originally, a lot of these sites did screen scraping on WoW’s main website to grab information and access character management.  Since April, they’ve been developing and publishing a full read and write RESTful interface for their applications.  Its seems they picked REST because of the ease of integration between many languages.

Things to note

In browsing the API documentation here’s a few things that jumped out at me

Document by example

The first thing to note is that the API is documented by example.  Here’s the URL pattern you use.  This is what the HTTP request looks like.  This is the JSON data you should send, and this is what the JSON data looks like.  IMO, this is what REST API documentation should look like.  No WADL.  No schema.  Just plain, here’s what you can send, here’s what the request looks like.  This is the approach I’ve taken with my API documentation.  You gotta remember, the people that are going to be integrating with these APIs don’t come from SOAP-land, WS-*-land, CORBA-land, enterprise programming land.  All will understand HTTP and JSON pretty easily.  This is what I love about REST: “lightweight” interoperability with a very low barrier to entry.

Signature-based Authentication

Hackers are ruthless when it comes to World of Warcraft.  I myself was hacked once and had to get my account restored.  Blizzard is very careful about this as it creates a lot of support headaches for them.  You can use a soft-token via your smart-phone.  Or order and get an RSA-like physical token generator when you log into your game.  As for the REST api, you need to acquire a public and private key.  Authentication is done by hashing your private key along with the current time, URL, and HTTP method.

UrlPath = <HTTP-Request-URI, from the port to the query string>
StringToSign = HTTP-Verb + "\n" +
    Date + "\n" +
    UrlPath + "\n";

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( PrivateKey, StringToSign ) ) );
Header = "Authorization: BNET" + " " + PublicKey + ":" + Signature;

Amazon does something very similar for many of it's public REST apis.  While not true a true digital signature (sigs are encrypted hashes and don't include the private key), its very close, and a lot simpler to use and understand for users.

Not very link driven

Can you imagine this API being explained via a set of link publishings rather than a set of URI patterns?  I've taken advantage of HATEOAS, especially within the HornetQ REST API, but in many cases, just publishing the URI scheme can be very useful.  Maybe its data-publishing vs. interaction?  With a data-publishing app (WoW) it makes more sense to publish a URI scheme for your REST interface.  With an interactive application (i.e. HornetQ REST), HATEOAS, link-driven interfaces make a lot more sense and give you a lot more flexibility.


On one of the forum posts, the developer talked about how he/she planned to version the API in the future.  It seems that they will version using URIs.  The latest and greatest will always use the same top-level URI schemes.  If you want to tie yourself to an older version of the API, the URI scheme will be predicated ith a version identifier:

New API:


All and all it will be great to see this API evolve over time.  This will be a great public display of a REST API and it will be very interesting to see how Blizzard tackles various issues.  There's a lot we can learn here.

They are guidelines not laws


I’m catching up on some blog reading.  A great blog on REST, if you don’t read it already, is Subbu Allamaraju‘s (in my blog links too).  I like to call him Dr. REST.  Back in May he wrote about Richardson’s Maturity Model and how measuring your APIs against the model is the wrong thing to do (I think he’s followed it up with a presentation).  I can’t agree more.  What I like about this model (and other articles like it) is that I like to compare it to my own history of growing my understanding of REST.  IMO, what you should do these models and guidelines is read them, examine them, see if they spark any ideas for improving your application.  They just might improve your understanding of REST and why certain constraints are good.  Don’t try to fit your API to REST.  Let REST help you write a better API.  Don’t apply REST for the sake of REST.  This is primarily why I unplugged myself from the rest-discuss mailing list.  If you treated applying REST as a set of guidelines instead of a set of laws you were castigated for it.  Wrong approach.

Anyways, as usual, great blog Subbu.  BTW, you should check out his book too.

Is anybody doing HTTP message signing and encryption?

1 Comment

Over the past 6 months off and on I’ve been researching and prototyping various security related features for Resteasy.  One thing I’ve wondered is, is anybody really doing anything with HTTP message signing and encryption?  Email seems pretty well rounded in this area with specifications like DOSETA/DKIM and SMIME.  You could theoretically apply these specifications to HTTP, and I have, but I could find no examples of people doing so on the Web.  Maybe its just that my Google searching skillz are poor.

Another thing I’ve noticed is that the crypto libraries (bouncycastle and python’s M2Crypto) pretty much center around email as the protocol and you have to dive into the codebase a bit to figure out ways to transmit things over HTTP. Bouncycastle relies on javax.mail multipart implementation which is a bit limited and not very lenient on parsing (Didn’t like python’s SMIME output).

Anyways, I hope to do a Resteasy 2.3 beta soon with SMIME support.  With it I’ll have examples of Python clients posting to Resteasy services transmitting SMIME formated requests.  I’ll post a few blogs on the subject so you can see how to transmit SMIME between M2Crypto and Bouncycastle. (Python and Java).

In the meantime, does anybody have any experience in this area?

Resteasy 2.2.2 Released

Leave a comment

This is just a maintenance release to fix a few minor and critical bugs found by the community.  You can download 2.2.2 here.  Release notes are here.

Hopefully we can now focus on getting a 2.3 beta out the door.  Currently I’m working on S/MIME integration as well as a decentralized auth protocol discussed in previous blogs.

Decentralized Auth Ideas


Distributed workflow has to be the most complex use case to secure.  In it you could have multiple participants being coordinated both synchronously and asynchronously.  All forwarding and distributing information and data in between each other.  All needing to trust one another.  If you could define a relatively scalable and simple solution for workflow, you’d have something that would work in less complex scenarios.

The hub and spoke model that seems to be popular involves a central identity management provider (IDP) that participants ping to authenticate requests and to receive security information.  The biggest problem I foresee with this approach is that the IDP becomes a central point of failure.  The IDP needs to be available for applications to work.  It needs to be on the same network.  There’s a lot of extra distributed requests that need to be made.

All these problems bring me to thinking about the stateless principle of REST.  RESTful services can have state, but not session state.  The idea is that session state travels with the request.  Could we do something similar with security information?  Sure why not!  How could you trust the integrity of such information?  Digital Signatures.  I’m sure there are protocols out there that have thought of similar ideas, but its cool to think things out for yourself.  If your ideas match a particular existing protocol or specification you know you’re on the right track.  The idea have have works as follows.

Let’s pretend we have a User named Bill that wants to interact with a Travel Agent service that will buy a ticket for him on an airline, reserve an airport taxi, and reserve a hotel room.  So, Bill is interacting with the Travel Agent directly.  The Travel Agent is acting on behalf of Bill when it interacts with the airline, taxi, and hotel services.  The airline, tax, and hotel have to trust both the travel agent and Bill.

Step 1: Bill authenticates with an IDP saying he wants to interact with the Travel Agent.  The IDP returns metadata that specifies both Bill’s and the Travel Agent’s permissions for all the interactions that must take place.  It also returns the public keys for Bill and the Agent.  The IDP digitally signs all this information using its private key.

Step 2:  Bill sends a reservation request to the Travel Agent service.  Bill signs the request including the signed permissions and keys provided by the IDP.  Here’s what the request might look like:

POST /travel
Host: travelagent.com
Content-Type: application/reservation+xml
Authorization: doseta-auth user=bill;h=Visa:Permissions:Public-Keys:Host;verb=POST;path=/travel;bh=...;b=...
Visa: initiator=bill;h=Permissions:Public-Keys;d=idp.com;b=...
Permissions: bill="agent hotel airline taxi"; agent="reserve-hotel reserve-taxi reserve-flight"
Public-Keys: bill=23412341234;agent=3423412341234


Step 3: The Travel Agent authenticates and authorizes Bill's request.  The Authorization header contains metadata that is signed by Bill.  The metadata signed by bill is the HTTP verb and path of the request (POST and /travel), and the hash of the XML posted by the request, as well as the Visa, Permissions, and Public-Key headers included within the request.  The Travel Agent verifies this signed metadata by finding and using Bill's public key in the transmitted Public-Keys header.  If the signature passes, then the Travel Agent knows that Bill sent the request.  But....It does not know yet if Bill is a trusted identity.

Step 4: How does the Travel Agent know Bill is a valid person?  How does it know that Bill is allowed to make a reservation?  To answer these questions, the Travel Agent first looks at the transmitted Visa header.  What it boils down to is that the Travel Agent only trusts the IDP.  The Visa header was generated by the IDP and  is a digital signing of the Permissions and Public-Keys header.  The IDP  through the Visa header tells the Agent the permissions involved with the request and who will participate in the overall interaction.   The Agent only needs to know the IDP's public key prior to the request being initiated.  So, the Agent verifies the digital signed Visa header using the stored public key of the IDP.  A successful verification also means that the Agent can trust that Bill initiated the request.  It can then look at the Permissions header to determine whether or not Bill is allowed to perform the action.

Step 5:  Next the Travel Agent needs to interact with the Airline, Hotel and Taxi services on behalf of Bill.  Here's what a request to the Airline might look like.

POST /flights/tickets
Host: airline.com
Content-Type: application/ticket-purchase+xml
Authorization: doseta-auth user=agent;h=Visa:Permissions:Public-Keys:Host;verb=POST;path=/flights/tickets;bh=...;b=...
Visa: initiator=bill;h=Permissions:Public-Keys;d=idp.com;b=...
Permissions: bill="agent hotel airline taxi"; agent="reserve-hotel reserve-taxi reserve-flight"
Public-Keys: bill=23412341234;agent=3423412341234

You'll notice that the Visa, Permissions, and Public-Keys headers are the same values as the original request made by Bill.  The Authorization header is different as the Travel Agent is making the request.  The airline services does authentication and authorization of the Agent's request the same exact way the Agent did for Bill's request.  Again, the key part of this is that only the IDP is trusted and only the IDP's public key needs to be known ahead of time.


Disclaimer, I'm new to security so dealing and thinking about attacks is new to me.  Generally a lot of attacks can be prevented by specifying a timestamp and expiration with each sign piece of data.  Services can refuse to honor old requests.  Nonces could also be included within signature metadata to avoid replays.

User's Private Key is compromised

User's authentication with the IDP doesn't have to be key based.  It could be TOTP based where the user has to login through his browser providing a password along with a device-generated time-based key.  The IDP could then return a temporary private key the client uses to sign requests.

IDP's Private Key is compromised

This is a scary one.  Maybe it could be prevented by requiring and acquiring Visa's from multiple IDPs?  A service would verify signatures from two or more IDPs.  The probability of more than one IDP's private key being compromised becomes less and less the more IDPs you have involved with the interadtion.


So here's a summary of this brainstormed protocol:

  • The Public-Keys header's purpose is two-fold.  First, its a list of public keys.  More importantly it is a list of principles that are involved with the interaction.
  • The Permissions header is a list of permissions of each principle involved for each service they will interact with.
  • The Visa header is a digital signature of the Public-Keys and Permissions header.  It also will probably have a timestamp and an expiration as well (all digitally signed of course).
  • The Authorization header exists to verify the integrity of the HTTP request of the entity sending the request.  It is a digital signature of the HTTP verb, path, host, message body, Visa, Permissions, and Public-Keys headers.
  • The IDP is the only trusted entity in the whole multi-tier distributed interaction.
  • Each service must have the IDP's public key stored at deployment time prior to servicing any requests
  • There is no communication to the IDP by any service.  Even the initiating client's first interaction with the IDP to obtain a Visa could be done ahead of time and re-used for multiple interactions.

This is just a rough outline, but there's probably other things that could be added.  Like nonce's for instance.  Its just a matter of implementing it and getting people to use it.  The real question is, is there an existing protocol already out there that does this sort of thing?

Brainstorming REST Security Part I


If you went to my presentations at JUDCon/JBossWorld/RHS 2011 or read my recent blog posting you’ve probably noticed that I’m starting to focus on REST+Security.  This will be the start of a series of blogs that attempts to solidify a common vision around Security+REST and spec out what we’re going to do for RESTEasy and JBoss.

Internet Security is A Ghetto

One thing I’ve noticed is what a ghetto Internet security is, or even security in general.  There are old and new specifications, various industry collaborations efforts that succeed sort of (OpenID), start to succeed then have mutinies (OAuth), WS-* specs trying to bleed into the Web space (SAML), and promising specs that have had success in the email world (DKIM).  That’s just the small list of examples.  Its a freakin mess!  One common thread seems to be that most of them focus on providing security for the Internet (Internet with a capital ‘I’) and most have their roots in providing security for browser based apps.  Enterprise apps, while they can build off of security specs defined for the Internet, can often have very different requirements.  Web services can also have different requirements as well as a human (browser) may not be involved with client/server interactions.  In summary, I guess what I’m saying is that there are too many specs, no clear winners, too browser focused, and very little Enterprise focused.

What I’m trying to do with this and subsequent blogs is to brainstorm what high-level requirements for security enterprise apps should have, how can we make deployment of a security solution easier, what existing specs are applicable, what existing specs are open to input, what new specs have to be implemented, how can we make the protocols as easy to implement as possible in multiple languages, and finally, how can we design security services to make it as easy as possible to deploy to our Enterprise applications.

If I had to deploy a security solution…

A security solution I’d like to have would take enterprise as well as the difference between browser and non-browser clients in mind.  Its gotta balance strong security with ease of deployment, ease of use, and ease of implementation.  Many of these will be obvious, but I want to write it down.

  • For browser based clients I’d to authenticate using a user password and a one-time-password (OTP) generated by a soft or hard token generator.  Plain passwords are just not viable.   I myself have had both my GMail and World of Warcraft accounts hacked.  A combo of password + random key allows users to have simple to remember passwords yet be secure enough not to get hacked.  With smart phones like iPhone and Android, its easy to acquire a soft key generator (or implement one) without paying RSA an arm and a leg.
  • After authentication, the browser client should obtain an expirable cookie that it forwards with each request that contains authentication information the server will use to authenticate subsequent requests.
  • For non-browser clients,  I like the idea of digitally signed requests.  Verification of a digitally signed request would be the authentication mechanism.  What’s good about this (like the OTP of browser-based clients) is that credentials are different per request in that they are part of the attached signature.  A nonce and/or an expiration can be included within the digital signature to avoid replay attacks.
  • I foresee the need for non-browser clients to make requests on behalf of other services to other services.  Attaching multiple signatures to a request might be the way here.
  • It would be really cool to have a decentralized way to to both authenticate and authorize.  The hub and spoke approach that Picketlink STS uses creates a bit of a single point of failure and can require extra network round trips.  This decentralized mechanism should be able to work in an environment where services are making requests to other services on behalf of one or more identities.
  • A user had a really interesting case where they wanted to provide access to content through signed URLs.  The idea is that they would generate a signed URL and email it to a user to click on.  Very interesting.

Applicable Specs

Here’s some specs that I thought of off the top of my head that could be useful.  If anybody has ideas of others, let me know.

  • Time-based One Time Password Algorithm (TOTP).  Anil already did some work in Picketlink to implement this protocol.  We still need to integrate it as a Authenticator Valve in JBossWeb.  There’s also a nice iPhone app that supports TOTP.  I actually forked and re-implemented a lot of it on my own when I was learning Objective C a few months ago.  We’re looking at creating an Apple App Store account to distributed this forked implementation so we can brand it Red Hat.
  • SAML.  This may be what we need to do decentralized authorization.  I’m not fully versed in the spec, but I have read up on their HTTP bindings.  I’m not sure if there is any way to tunnel assertions through an HTTP header. (We don’t want to send SOAP requests).  If we can use SAML, we can piggyback off of a lot of the efforts already done in the Picketlink project.
  • Doseta.  I’ve already blogged about this protocol.  Using DNS to distribute keys is a little weird, but cool.  I’m asking that working group for this spec to break out Doseta into a few different specifications so that we can re-use the signature calculation algorithm in a standard way and to also make DNS public key publication optional and maybe also to provide an HTTP way to distribute keys.
  • Amazon REST Authentication.  Specs out how to sign URLs.  Maybe this could be standardized at IETF.
  • OpenID.  OpenID seems interesting for decentralized authentication, but I’m not sure if it can be used as a mechanism to do decentralized authorization.  OpenID is also more of a browser-based technology.
  • OAuth.  OAuth has both browser and non-browser bindings.  OAuth 2.0 pretty much leaves out what a token looks like.  I also don’t really want a token based system for non-browser clients

Possible Middleware Services

Here’s some ideas for services/integration we would implement.

  • HTTP Identity Proxy.  While implementing just an HTTP Proxy Cache is boring what might make these feasible is applying Identity to the mix.  This would delegate authentication and even authorization to an outside service.  Requests would be authenticated/authorized through the proxy, digitally signed, then forwarded to the target service.  The target service then only need to verify the signed request using the public key of the proxy.  While there’s obvious performance drawbacks, what’s interesting about this is that the application doesn’t have to think much about security and it could possibly be added even after the service is deployed.
  • TOTP Authenticator Valve.  Nuff said…I tihnk Anil already has this.
  • Better Auth integration with JBossWeb and the JBoss Security Domain abstraction.  Right now there’s just too many steps to enable things.
  • Various auth plugins for JBossWeb to realize our vision here.

Older Entries Newer Entries


Get every new post delivered to your Inbox.

Join 706 other followers

%d bloggers like this: