Authentication and security of a REST API

Question

Scenario: I design a REST API where authenticated users can hit the API over TLS. I have to use TLS as the data transmitted over the wire is sensitive. I don't need authorization right now, but I don't want to exlude the possibility. I want to use some kind of API Key(/Secret) method. I would prefer to avoid using OAuth. I have two possible solutions. In both cases, the API key (and secret) would be generated by us.

I. Simple API Key

Include an API key in the HTTP header, I can authenticate the client based on that header. The API key is safe, because of TLS. Replay attacks are not possible, guaranteed also by TLS. Very simple to implement by our clients. As far as I understand TLS, the request cannot be tampered (MAC). All security measures are provided by TLS. The client only adds the API Key HTTP header.

II. HMAC signature with an API secret

The request should include a signature, hashed with the secret, timestamp and the hash of the request payload. Now it cannot be tampered or replayed and the secret is not even transmitted over the wire. Safest, but hard to implement on the client side. (writing client libraries is not an option)

Does the first solution pose any threat and provide sufficient security to my clients (and our API), or I should use the more complicated second one? Also, what are the shortcomings of the first one?

Answer 1

If you're using TLS already, I would lean towards using a secret API key in the header. With an API key you can store that encrypted which protects you in the case of a breach. Make sure your application and server aren't logging the secret key in any form and I would push your client to use long, complex keys. These will be handled by systems not people so there shouldn't be heartburn with having them present a long, complicated key with every request.

The hmac signatures are useful if you want to use an unencrypted channel and accept a little bit or risk. In this case the HMAC provides no benefit and would require you to store the secret in plaintext. In this case, I would consider a secret key to be more secure than a signature.

Performance-wise they are going to be similar.

One other note: Since you are TLS you should take care to make sure your example docs and howtos make it clear how to establish that connection correctly and alarm at certificate mismatches and your client SDK should do that by default.