Authentication Improvements - JSON Web Signatures

API Issues
#1

Hello!

Presently the API’s authentication mechanism is vulnerable to a variety of attacks. Once a 3rd party obtains your API key, it’s essentially game over. If the API is to maximize its utility (e.g. for automated submission of accounts with the merging of the XML gateway functionality) it realistically requires a better authentication model.

So, I would like to recommend JSON Web Signatures as used by, for example, the Let’s Encrypt ACME protocol (which is used for automated issuing of SSL certificates).

To give a quick summary of how it works, it’s like so:

  1. The client generates a public/private keypair. E.g. A Secp256k1 pair (as used by Bitcoin).

  2. The public key is registered with their account. In many instances, the public key “is” the account, however the ability to replace the keypair is generally favourable.

  3. Requests are structured as a JSON object, including a signature created with the private key as proof of authenticity. Typically ECDSA.

  4. The JWS header contains a nonce (it is often just a timestamp for ‘linear’ APIs) to block replay attacks.

JWS is generally a very promising approach for unattended APIs mainly because of its simplicity; by comparison, OAuth is very easy to get wrong. If it’s unattended then it can also happen more regularly, potentially providing CH with more realtime information and making it considerably easier for small business owners like me, especially if HMRC also used the same structure with their API too.

Fantastic work so far anyway! I can’t wait to see where the Government takes these APIs next.

All the best,
Luke

#2

Good suggestion.

We have a JWE model under the hood, that has not been released publicly yet as the necessary customer ecosystem (public/private key generation) is not in place yet.

In essence, you can register a user-not-present application instead of an API key application. Out developer hub (will) issue you a private key, which you have to store as Companies House will not store this (it’s exactly as you describe, actually). You use this private key to sign a JWE to use instead of an OAuth2 authorization_code (therefore there is no web UI interaction), which you exchange for a token.

JWS improves the API key authentication, as you note. However, outside of API keys our requirements are a little more involved, as there will be other credentials to supply to gain access to submit/change data for companies. The JWE model fits in with the OAuth2 user-present filing model, also mandatory for us. Google have done a similar user-not-present implementation I believe.

We appreciate there is a little legwork involved with the OAuth2 handshake, but do expect developers to use off the shelf client implementations, so it should be pretty trivial.

JWS instead of a straight API key does offer benefits on its own, but may not offer much over the JWE/OAuth2 model which we have a need for anyway…

We’ll keep JWS in mind. Over the coming months we will be releasing further details of filing/data-change at Companies House and the authentication models involved, along with a request-for-comments from you all ! We’d like to get it right :wink:

Thanks for the kind words, too.
Chris

1 Like