Allegion Developer Portal
Allegion Developer Portal
| REVISION CONTROL RECORD | |||
|---|---|---|---|
| VER | DATE | DESCRIPTION OF CHANGE | AUTHOR |
| 0.00 | 8/16/2017 | Initial Internal Release for Comments | T. Holt |
| 0.01 | 8/16/2017 | Additional content added and comments incorporated | T. Holt |
| 0.02 | 8/16/2017 | Internal review comments provided | T. Holt |
| 1.0 | 8/29/2017 | Official Release | T. Holt |
| 1.1 | 8/30/2017 | Included new section: Read Credential characteristic (UUID 52052C11-E701-4782-99F2-8CE88DBB1503) | T. Holt |
| 1.2 | 8/30/2017 | Updated Plain Text Format wording for clarity | T. Holt |
| Added description around padding at the end of the TLV payload | |||
| 1.3 | 8/30/2017 | Minor wording modifications for clarity | T. Holt |
Table of Contents
1 Introduction 3
2 Change List 4
2.1 BLE Advertisement and Security Revision 4
2.2 Data Transfer Service 4
2.3 General Service 4
2.3.1 UUID 4
2.3.2 Message Formatting 4
2.3.3 Bounce Diagram 6
2.4 REMOVE_BEFORE_PUBLISHING Real Time Access Control Service 6
2.5 REMOVE_BEFORE_PUBLISHING Gateway General Service 6
2.5.1 REMOVE_BEFORE_PUBLISHING Message Formatting 6
2.5.2 REMOVE_BEFORE_PUBLISHING Handling of Multiple TLVs 6
The purpose of this document is to describe how a MAPP or an ENGAGE Gateway can communicate with an ENGAGE device via the ENGAGE Bluetooth Low Energy (BLE) Security Revision 3. It is assumed that the reader is already familiar with BLE and GATT. This document specifies only the differences between the BLE Security Revision 2 and BLE Security Revision 3. It is assumed that if a change is not discussed in this document, the ENGAGE devices will operate identically between Security Revision 2 and Security Revision 3.
The purpose of the ENGAGE BLE Security Revision 3 is to provide enhancements to the security and reliability in the communication between ENGAGE devices, the ENGAGE Gateway, and BLE Enabled Mobile Applications.
As part of the BLE advertising data all ENGAGE devices broadcast their Security Revision in the last byte of the advertising data. As part of the ENGAGE 6.0 release all ENGAGE devices broadcast this byte as 0x03. Prior to the ENGAGE 6.0 release this byte was broadcast as 0x02.
BLE Enabled mobile devices must ensure their ability to communicate to devices with either Security Revision (0x02 or 0x03) in order to support ENGAGE devices with the ENGAGE 6.0 release as well as firmware versions prior to the ENGAGE 6.0 release.
Refer to the Advertising Data section of the ENGAGE- BLE GATT document for more details regarding the BLE Advertisement.
No changes have been made to the Data Transfer Service. BLE Enabled mobile devices may continue to utilize the Data Transfer Service identically to how this was accomplished in Security Revision 0x02.
BLE Security Revision 0x03 will utilize the same UUID’s and respective characteristics as BLE Security Revision 0x02. The UUID value, and utilization of each of the General Service characteristics is unchanged between BLE Security Revision 0x02 and 0x03.
ENGAGE devices now require the communication to be sent via the General Service characteristics and be formatted and encrypted using the following strategy.
This section shows the construction of the plain text format. This is the format prior to the encryption necessary in BLE Security Revision 3.
| Byte Number | Description | Length |
|---|---|---|
| 0 | Total Message Length (Includes CRC (2 bytes) plus Payload) | 1 byte |
| 1 | CRC | 2 bytes |
| 2 | CRC | |
| 3 | Message Payload and Random Padding as necessary. This is the same value as what was originally written in BLE Security Rev 2. Random Padding is added to the end of the Payload to force the total message size to a multiple of 16 bytes. | Variable |
| 4 | ||
| … | ||
| N |
Once the message length, CRC, payload, and any required padding are concatenated as defined in the Plain Text Format, the message must be encrypted using AES256-CBC encryption with an Initialization Vector of all 0’s. Padding must be utilized to force the message size to a multiple of 16 Bytes, which is a requirement of the AES256 encryption algorithm. This padding must be concatenated to the end of the payload and the padding should not be counted in the calculation of the message length (Byte 0 if the Plain Text Format).
Once the encrypted payload is received the ENGAGE devices check the length and CRC of the message and will not process data that fails due to either the length or CRC checks. If the length value is greater than 13 (Bytes) it may be assumed that at least one more message must follow to complete the entirety of the payload. This payload data will be of the same format as the BLE Security Rev 2 General Service communication.
The Temp Key which was established during the authentication procedure between the MAPP and the ENGAGE device is used for the AES256 encryption and decryption.
The utilization of the Read Credential characteristic between BLE Security Revision 0x02 and BLE Security Revision 0x03 is unchanged. However, BLE Security Revision 0x03 requires that this message now be packaged into the defined Plain Text Format and encrypted. This leads to the credential information being encrypted twice. The first encryption, on the credential value itself (utilizing the Site Key), and the second encryption on the entire TLV (utilizing the Temp Key).
An indication on this characteristic, signals to the MAPP that a credential has been presented to the edge device. A BLE Read request allows for the edge device to indicate multiple 20 byte blocks of BLE data that can be concatenated and decrypted.
For GWE to Edge Device communication, the RTAC Session Key shall be used for encryption and decryption.
No changes have been made to the Real Time Access Control Service. BLE Enabled mobile devices may continue to utilize the RTAC Service identically to how this is accomplished in Security Revision 0x02.
The Gateway General Service (UUID 1c745c9a-166a-4b6c-8055-5529dc6a36a1) contains only one characteristic: LinkStatus (UUID 1c745c9a-166a-4c25-b489-915086f1dc34). The UUID value, and utilization of the LinkStatus characteristic is unchanged between BLE Security Revision 0x02 and 0x03.
The message formatting for the Gateway General Service is identical to that of the General Service. Refer to the Plain Text Format section for the required message formatting information.
The LinkStatus characteristic allows for multiple TLVs to be concatenated and sent in a single indication from the ENGAGE Gateway to the MAPP. In all situations the sum of the TLV lengths should be less than or equal to 16 bytes, which is required for encryption and BLE transfer in a single packet. However, during MAPP directed linking of an edge device to an ENGAGE Gateway, if a 410IP Gateway fails to establish a link with the lock it is possible for the ENGAGE Gateway to concatenate 3 TLV’s the sum of which would be 17 bytes. This message in plain text format is stated below per the BLE Security Revision 0x02 requirements:
0x30 01 01 31 02 020X 23 08 6465763030303030
Link Mode Status, Len 1, Idle / Normal | Link Status Code, Len 2, Failure Status Code | Link ID, Len 8, dev00000
For BLE Security Revision 0x03, the last TLV in this concatenation is no longer allowable. Therefore the BLE Security Revision 0x03 TLV concatenation would look as follows (in plain text format):
0x30 01 01 31 02 020X 23 08 6465763030303030
Link Mode Status, Len 1, Idle / Normal | Link Status Code, Len 2, Failure Status Code