Full Disclosure: Securing Internal Communication

Server

With the transmitted user name, the server can determine the associated PSK from its user database. It is used to generate the same signature again with the remaining information from the request (timestamp, HTTP verb, etc.) and compare it with the one transmitted in the header. If the two signatures differ, it is because the information used for signing differs. So either the PSK is wrong or it is a replay attack where parts of the original request have been changed. Obviously, in both cases the request can be rejected.

Otherwise, the system now checks whether the verified user also has the authorization to perform the requested action. If the user is not authorized to do so, the request can also be denied, otherwise the action is performed.

Use

A Java implementation of this method for JVM-based programs can be found at https://github.com/otto-de/hmac-auth.

To generate correct headers, theHMACJerseyClientortheHmacJersey2ClientRequestFiltercanbe used, which get the user name and the PSK when instantiated. The current time of the system is used as timestamp and the further information comes from the request, which the client generates anyway. The headers are then appended to each request without any further action.

final WebTarget webTarget = jerseyRestClientFactory.getClient().target(url); webTarget.register(new HmacJersey2ClientRequestFilter(userName, preSharedKey)); 

To check headers in application containers on the server side, the other component of the library can be used: theAuthenticationFilterchecks each incoming request for the HMAC headers and performs authentication if they are present. The filter is simply made known to the application container.

@Bean public AuthenticationFilter authenticationFilter() { return new AuthenticationFilter(new AuthenticationService(new PropertyUserRepository())); } 

Incoming requests are now rejected with HTTP status 401 if the HMAC headers are present but the signature is wrong or the timestamp is too old.

In applications that use Spring, the@AllowedForRolesAnnotationis available for authorization, which can be attached to service methods, for example. An aspect interrupts the call of the method and checks whether the user specified in the request has one of the roles that are in the annotation before the method is executed. If not, anAuthorizationExceptionis thrown, which must be handled by the library user, but generally also results in an HTTP status of 401:

@RequestMapping(value = {"/priceOfIPhone"}, method = RequestMethod.PUT) @AllowedForRoles(value = "iPhonePriceManager") @ResponseBody public void updateHealth(@RequestParam final Integer newIphonePrice) { final IPhoneData currentIPhoneData = allPhonesService.getIPhoneData(); newIPhoneData = currentIPhoneData.withPrice(newIphonePrice); allPhonesService.setIPhoneData(newIPhoneData); }

Implementation properties

Secure

Since the HMAC method does not specify which hash algorithms to use when signing the request, it is up to the concrete implementation to choose a secure function. We have chosen HmacSHA256 which was developed exactly for these purposes and is widely used and well tested as a state-of-the-art hash.

Other conceivable mechanisms, such as HTTP-Basic, are so vulnerable that their use without additional SSL encryption, which we want to avoid, is grossly negligent.

Stateless

The vast majority of our web servers are Docker containers, which should be able to constantly emerge and expire in their Mesos environment, while the machines are dynamically scaled according to load. So for two consecutive requests, it is by no means a given that they will end up on the same server. Also, for Blue-Green deployments, the machines must not share any state that changes.

Since our approach re-signs each request, there is no need to keep a session or the like in the server that would have to be laboriously synchronized between instances.

In the case of HTTP digest which would actually be a natural candidate for the problem, either the nonce must be synchronized for each user in all servers or the slow initial handshake must be re-executed for each request.

Resilient to replay attacks

These attacks attempt to re-send previously intercepted requests. This is promising because the intercepted request was probably successful and the attacker can hope that the resent request will also be successful. Although these attacks are still theoretically possible, they are considerably more difficult due to the time limit - requests have a built-in expiration time.

If attackers succeed in performing the replay within the short validity period, the attack possibilities for individual requests are quite limited: a POST is pointless (create a new resource again), a PUT will re-perform the performed change to the resource and thus cement it, a DELETE will delete the already deleted resource again, and a GET will reveal the non-confidential data. Only in the case of directly consecutive requests is it conceivable that the attacker has enough time after a request to resubmit the previous one and thus, for example, restore recently deleted resources or roll back a configuration to an earlier point in time. However, our business processes are very tolerant of human error in this regard anyway, so at best an attacker could hope to cause a bit of confusion.

A variation of this is to modify the original request. For example, an attacker might try to change a GET to a DELETE request in order to delete a previously requested resource. However, since both the HTTP verb and the request body are part of the signature, manipulating them will only cause the signature to no longer match the request and it will be rejected.

Only the uninvolved request headers remain for attackers to manipulate, and there is usually no interesting data there.

Performance

The method is extremely fast, especially compared to methods with integrated encryption. If confidential data is to be transmitted, the combination of HMAC with a transport encryption like SSL is still considerably faster than methods in the application layer like oAuth2 or the various wsSecurity variants.

Simple ...

Security is hard but we still want no bugs in this area if possible.

Especially in our multilingual environment, where teams may have to implement their own implementations of the standard, it is of great advantage to use a method that can be described comprehensively in a few words and that can be implemented especially without advanced mathematical methods.

... but only for machines

Due to the cumbersome calculation of headers and the time limit on request validity, it is very difficult to generate correct requests manually. To be able to send test requests to HMAC-secured interfaces anyway, there is a proxy in the Github project that can be started locally and that accepts requests, generates the necessary headers and forwards the correct request. However, the usage remains quite bulky and is not suitable for technically inexperienced users.