Authentication Using HMAC Signature

 

This is the second post in our series about authentication and the WorldShare Platform. The HMAC Signature lies at the heart of all our web service authentication mechanisms.

As a result, this HMAC Signature pattern is the first pattern we chose to adopt.  HMAC stands for keyed-hash message authentication code and is a specific way to construct a message authentication code. This method of authentication is based on a cryptographic hash function which utilizes a symmetric encryption pattern. In a symmetric encryption pattern two parties know the same secret and use it to establish a trusted relationship between them. In the case of WSKey, a secret is only known to the client with which it is associated and the OCLC web services.

What does it mean to sign a request?

From an HMAC-based authentication perspective, requests to web services are made up of the following elements:

  • WSKey
  • Request URL
  • Nonce
  • Timestamp

Most of elements within the request are not unique. The Request URL is not unique as the same request can be sent multiple times. The WSKey or client id is unique to a particular client but can be used in multiple request. When a particular request is sent, the timestamp, is close to unique but two requests for the same Request URL could conceivably be made at the same time. Moreover the client (WSKey) could request the same URL at the same time. Because none of these elements nor the combination of WSKey, Request URL, Timestamp is unique, each request must contain a random bit of data called a nonce.

By combining all four of these elements together then every request sent to a web service unique. Therefore, each request also has a unique signature associated with it. “Signing a request” means that each client uses a WSKey and secret and all the elements of the request in combination to create a unique signature for each request. This unique signature is passed to the web service via an HTTP Authorization header.

Example

Authorization: http://www.worldcat.org/wskey/v2/hmac/v1
clientId="tsFsoBXToV1uR8GEMJCcxz9NYpVvutsA5cJAD9cnKUc4FGYEntM6UkcIVlYp4ZhYFteVLAxOWJDUV85W",
timestamp="1361306811",
nonce="762343395744465450467911322335",
signature="2DwPAIYqlCOH9xCHM7PSnOBoVKk/PHrHPeIGmmEK/AI="

Note that the secret is not sent by the client as part of the request. If it was sent then it would no longer be secret and others could possibly use it to maliciously sign requests.

Once the web service receives the request, it examines the data in the HTTP Authorization header and verifies the signature for each request. It does this by taking the client ID (WSKey) passed with the request and looking up the corresponding secret. It then uses this information plus the request URL, nonce, timestamp to rebuild the signature. If the signature passed does not match the one computed by the web service then the authentication fails.

It is important to note that this authentication method assumes that the client can keep a secret safe and secure. This means that it is not suitable for client-side scripts such as Javascript, which are incapable for keeping a secret secure. In a future post, we’ll discuss the appropriate authentication method for client-side scripts.
 

  • Karen Coombs

    Karen Coombs

    Senior Product Analyst

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »