Clients can make a request to most web services by sending an HMAC signature on the HTTP Authorization request header. A request header with an HMAC signature looks like the following:
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="tsFsoBXToV1uR8GEMJCcxz9NYpVvutsA5cJAD9cnKUc4FGYEntM6UkcIVlYp4ZhYFteVLAxOWJDUV85W", timestamp="1361306811", nonce="762343395744465450467911322335", signature="2DwPAIYqlCOH9xCHM7PSnOBoVKk/PHrHPeIGmmEK/AI=", principalID="8eaa9f92-3951-431c-975a-d7dfkd9rd131", principalIDNS="urn:oclc:wms:da"
Note: for readability the line breaks have been added between the key/value pairs, but the Authorization value should be sent as a string with no line breaks. The principal ID and principal ID namespace parameters are optional and not required by all web services.
A signature is generated by calculating a digest using the HMAC-SHA256 hashing algorithm. The inputs to the hashing algorithm include the WSKey secret and a normalized string that represents the current request.
To build the pre-hashed string concatenate the following elements separated by new line characters:
If making a GET request to the following URL
With the following parameters:
The pre-hashed string would look like the following:
jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa 1361408273 981333313127278655903652665637 GET www.oclc.org 443 /wskey inst=128807
Note that the line numbers are there to illustrate that there is a new line character at the end. Also note that when making requests to URLs that have no query parameters, there should only be a single newline at the end of this pre-hashed string.
After calculating the signature, it should be base64 encoded.
digest = HMAC-SHA256 ( wskey_secret, prehashed_string ) signature = base64 ( digest )
This request would generate the following Authorization header value. This example does not include body content. Even if it did, because the there is no key/value pair in the Authorization header for the entity-body hash, line 4 of the pre-hashed string is an empty string.
Example (space added for readability)
http://www.worldcat.org/wskey/v2/hmac/v1 clientId="jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa", timestamp="1361408273", nonce="981333313127278655903652665637", signature="5O6SRig58wqm6gqEu3oSODVte6Albon9CCvNrZHCoys="
Requests that send a nonce or timestamp used on a previous request are considered invalid.
The OCLC Developer Network supports the use of OCLC Web Services—a set of tools and APIs that expose data and services for WorldCat and our member libraries and partner institutions or companies. learn more »
© 2010 OCLC Domestic and international trademarks and/or service marks of OCLC Online Computer Library Center, Inc. and its affiliates