Upgrading to v2 security

[wrygiel]

As some of you might have already noticed, there were many new document releases in the last month. In particular, all APIs were upgraded to support Version 2 of the Authentication and Security document - the effect of our resolutions in Porto.

Brief summary of changes

Switching from Version 1 to Version 2 is not a backward-compatible task, so most stable APIs have increased their major version number. For example, Institutions API was bumped from version 1.0.1 up to 2.0.0. This means that all clients may access Institutions API v1 exactly as they did before, but if they want to access Institutions API v2, then they need to implement some additional checks.

The first thing to be aware of is that the sole switching to Version 2 security is not as hard as you think. This is because Version 2 security is largely compatible with Version 1. In particular, Version 2 security still allows the server to use exactly the same security protocols which the server has used in Version 1 security (TLS Client Certificate Authentication).

What has changed though is that the server is no longer required to support any standard set of security methods, and therefore, the client can no longer assume that the server does support the "v1 set" (which, among others, includes TLS Client Certificate Authentication). The client is now required to verify which security methods the server supports before it makes its request.

You can read all the details in the specifications.

The "minimal plan" for server  implementers

You need to upgrade all APIs to the most recent versions.

This operation is quite easy. You just need to change some stable-v1 XML namespaces to stable-v2 (both in your Manifest entries and in the HTTP responses your API generates). This assures that only the upgraded clients will be able to access your servers.

Note, that you are not required to implement new authentication and encryption methods. You MAY stick with the ones we used in Version 1 security (this doesn't apply to Norway though, because Norway didn't implement Version 1 security - more on that below).

The "minimal plan" for client implementers

There are two options here:

• Easy, but "bad". Simply make the requests to the new API URLs and hope they succeed. In time, you will be receiving a growing number of HTTP 400 errors from servers. This option cannot be used in production environment.
• Good, but harder. Implement the checks described below. Such clients can be used in production environment.

Most of the new APIs require you to check which security methods the server is supporting for them. This means that, for example, the server implementer may decide to serve Institutions API anonymously (without the need of any authentication), but he may also decide to serve the API only to the clients which support HTTP Signatures.

If the API follows the guidelines of Version 2 security, then its API entry will include a new element to parse for you. So, whenever you want to connect to such API, you SHOULD check which security method this particular server supports, and use a compatible set of methods in your request. If you don't check that, and you decide to simply guess, then your request may end up with an HTTP 400 error response.

Most APIs now include a <http-security> element - a standard way of supplying this information, as proposed in the Version 2 of the Authentication and Security document.

• If you are using the Java Registry Client, then you will need to use the findApis method (instead of the regular findApi), and filter the returned Collection<Element> yourself. The existing ApiSearchConditions class doesn't allow you to filter APIs based on the contents of their <http-security> element.

• Note, that the existence of the <http-security> element depends on the designers of the particular API. EWP Registry does not force its APIs to use any single security model. It's up to the API designer to choose its security model. This way, many other APIs (such as EMREX, for example) can be easily included in the EWP Registry in the future (without them being forced to switch to our v2-security model). It also means that Java Registry Client cannot "natively" allow you filter APIs based on their security settings.

Note, that you are not required to implement new authentication and encryption methods. You MAY stick with the ones we used in Version 1 security. You SHOULD NOT, however, connect to servers which do not support these methods.

The "extended plan" for server implementers

Once you switch your servers to the new APIs, you are recommended to start developing the newly introduced security methods - in particular, HTTP Signature Authentication. Note, that we have released a new version of the Java Registry Client, which has some extra methods which may help you with implementing HTTP Signature Client Authentication.

Note, that these new security methods are not yet released as stable (there already use the stable-v1 XML namespace, but they do not use the stable-v1 Git branch, and they are still in version 0.x.x). This means that they MAY still change in a backward-incompatible ways. We are not planning for them to change, but they may (for example, after some partners implement them, and find problems in the specification).

As the new methods get implemented, and tested, by a substantial number of partners, we will release them as stable. Hopefully, we will also find some time to release an updated Echo API v2 Validator, which should help all partners with this stage.

Note, that - even in the "extended plan" - you are NOT REQUIRED to drop the previously used authentication and security methods (e.g. TLS Client Certificate Authentication, or TLS Request and Response Encryption). Partners are allowed to drop such methods (either completely, or only for certain APIs), but it's up to the partner to weigh pros and cons of such decision.

The "extended plan" for client implementers

Eventually, all clients SHOULD support all released security methods. Otherwise, they won't be able to connect to some of the partners (the ones which - for one reason or another - do not support all security methods at their server endpoints). We have released a new version of the Java Registry Client, which has some extra methods which may help you with implementing HTTP Signature Server Authentication.

Partners MAY refuse to make use of some particular security methods for security reasons. For example, if the partner doesn't trust TLS encryption, then such partner MAY refuse to connect to the servers which do not support any form of additional encryption. It's up to the partner to weigh pros and cons of such decision.

The "minimal plan" for Norway?

Norway didn't implement TLS Client Certificate Authentication, so the "minimal plan" described above won't work for them. Our proposal is:

• Norway continues to "cheat", and simply state in their v2-security manifests that they do implement TLS Client Certificate Authentication.
• All clients which want to continue connecting with Norway's dev servers, will still need to supply the X-EWP-KeyId header.

Once Norway implements the "extended plan" for their servers, and some other partners implement the "extended plan" for their clients, this additional header may be removed. (We do hope that Norway will be one of the first partners to start implementing the "extended plan".)