Allegion Developer Portal
Allegion Developer Portal
Keyed-Hashing for Message Authentication (HMAC) was developed by an IBM working group in February 1997.
The development and resulting algorithm is published in IBM document RFC2104.
The message authentication method was developed with the idea that any of the current and future hashing functions could be utilized. The cryptographic strength, of HMAC, depends on the properties of the underlying hash function.
The IBM working group had the following main goals:
The Keyed-Hashing for Message Authentication (HMAC) function produces a digest based on the dynamic contents of JSON messages. The digest and the hashing method along with the source message, are embedded in the JSON message objects.
The transmitting device embeds the digest, the hashing method used, and the target message within the transmitting JSON Objects. The receiving device extracts the digest, the hashing method used, and the source message. A digest is calculated from the source message using the specified hashing method. The extracted and calculated digest are compared to validate the message contents.
The implementation of the secure hash algorithm “Secure Hash Algorithm 1” (SHA-1) should be based on existing open source libraries such as OpenSSL.
The audience should be familiar with the following topics:
The purpose of this section is to describe the deployment of JSON Message Authentication functionality for the exchange of JSON messages by an IP Host, BLE enabled mobile application, or ENGAGE device.
The implementation of such protection requires JSON structures that provide securing methods beyond currently deployed methods. The enhancements focus on ensuring the desired receiver gets the JSON message exactly as transmitted and consumes the message while the message has not expired or occurred in the past. The result is the assurance of JSON data integrity and authenticity.
The message authentication implementation provides focus on ensuring the desired receiver gets the JSON message exactly as transmitted and consumes the message while the message has not expired or occurred in the past. The result is the assurance of JSON data integrity and authenticity beyond the use of Transport Layer Security (TLS).
The message authentication functionality requires a General Parameters JSON Object that will contain a Hash Message Authentication Code (HMAC) enable flag, a serial number designating the JSON message’s target device, and a JSON message timestamp to ensure that a message cannot be re-sent to the specified device.
The message authentication functionality additionally requires a Hash Message Authentication Code (HMAC) Data JSON Object that will contain the digest value and a keyed hash type (SHA-1). The Hash Message Authentication Code (HMAC) is a specific type of Message Authentication Code (MAC) that utilizes the cryptographic “hash” function (SHA-1) and a secret cryptographic key.
The secret cryptographic key is the site key. Each site is provided a unique 32-byte key. The site key should be protected and not distributed. If for any reason a site key has become compromised all devices should be removed from that site, and the site should be deleted. The devices must then be recommissioned to a new site utilizing a new site key. Due to the work required to complete this task if the site key is for any reason compromised, the site key should be held in a secure manner. It is the responsibility of the Software Alliance Member to securely store and protect the site key.
For more detailed information on adding HMAC, see (Keyed-Hashing for Message Authentication (HMAC) Application Note)
To enable HMAC, the following is an example of the additional parameters that need to be added to the JSON structure to enable HMAC.
genPrmtrs":{"mainSN":"A0E15352494B410B","msgTS":"0x8d59fa9f1c671cd","hmacEnable":"T"},
"hmacData":{"hmacType":"sha1","hmac":"052133e1b9cca789d8ceb8f5c0290da98fc4085c"}