Question

I’ve read about oAuth, Amazon REST API, HTTP Basic/Digest and so on but can’t get it all into “single piece”. This is probably the closest situation – Creating an API for mobile applications – Authentication and Authorization

I would like to built API-centric website – service. So (in the beginning) I would have an API in center and website (PHP + MySQL) would connect via cURL, Android and iPhone via their network interfaces. So 3 main clients – 3 API keys. And any other developer could also develop via API interface and they would get their own API key. API actions would be accepted/rejected based on userLevel status, if I’m an admin I can delete anything etc., all other can manipulate only their local (account) data.

First, authorization – should I use oAuth + xAuth or my some-kind-of-my-own implemenation (see http://docs.amazonwebservices.com/AmazonCloudFront/latest/DeveloperGuide/RESTAuthentication.html?r=9197)? As I understand, on Amazon service user is == API user (have API key). On my service I need to separate standard users/account (the one who registered on the website) and Developer Accounts (who should have their API key).

So I would firstly need to authorize the API key and then Authenticate the user itself. If I use Amazon’s scheme to check developer’s API keys (authorize their app), which sheme should I use for user authentication?

I read about getting a token via api.example.org/auth after (via HTTPS, HTTP Basic) posting my username and password and then forward it on every following request. How manage tokens if I’m logged in simultaneously on Android and a website? What about man-in-the-middle-attack if I’m using SSL only on first request (when username and password are transmitted) and just HTTP on every other? Isn’t that a problem in this example Password protecting a REST service?

Answer 1

As allways, the best way to protect a key is not to transmit it.

That said, we typically use a scheme, where every “API key” has two parts: A non-secret ID (e.g. 1234) and a secret key (e.g. byte[64]).

• If you give out an API key, store it (salted and hashed) in you
  service’s database.
• If you give out user accounts (protected by password), store the
  passwords (salted and hashed) in your service’s database

Now when a consumer first accesses your API, to connect, have him

• Send a “username” parameter (“john.doe” not secret)
• Send a “APIkeyID” parameter (“1234”, not secret)

and give him back

• the salts from your database (In case one of the parameters is wrong,
  just give back some repeatable salt – eg.
  sha1(username+”notverysecret”).
• The timestamp of the server

The consumer should store the salt for session duration to keep things fast and smooth, and he should calculate and keep the time offset between client and server.

The consumer should now calculate the salted hashes of API key and password. This way the consumer has the exact same hashes for password and API key, as what is stored in your database, but without anything seceret ever going over the wire.

Now when a consumer subseqently accesses your API, to do real work, have him

• Send a “username” parameter (“john.doe” not secret)
• Send a “APIkeyID” parameter (“1234”, not secret)
• Send a “RequestSalt” parameter (byte[64], random, not secret)
• Send a “RequestTimestamp” parameter (calculated from client time and known offset)
• Send a “RequestToken” parameter (hash(passwordhash+request_salt+request_timestamp+apikeyhash))

The server should not accept timestamps more than say 2 seconds in the past, to make this safe against a replay attack.

The server can now calculate the same hash(passwordhash+request_salt+request_timestamp+apikeyhash) as the client, and be sure, that

• the client knows the API key,
• the client knows the correct password