BLE Unlock Request - 0x2C
Response frame: BLE Unlock Response - 0xAC
Description
This frame type is used to authenticate a connection on the Bluetooth interface and unlock the processing of AT command frames across this interface. The frame format for the BLE Unlock Request - 0x2C and BLE Unlock Response - 0xAC are identical.
The unlock process is an implementation of the SRP (Secure Remote Password) algorithm using the RFC5054 1024-bit group and the SHA-256 hash algorithm . The SRP identifying user name, commonly referred to as I, is fixed to the username apiservice.
Upon completion, each side will have derived a shared session key which is used to communicate in an encrypted fashion with the peer. Additionally, a Modem Status - 0x8A with the status code 0x32 (Bluetooth Connected) is emitted. When an unlocked connection is terminated, a Modem Status frame with the status code 0x33 (Bluetooth Disconnected) is emitted.
The following implementations are known to work with the BLE SRP implementation:
You need to modify the hashing algorithm to SAH256 and the values ofNandgto use the RFC5054 1024-bit group.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame format.
| Offset | Size | Frame Field | Description |
|---|---|---|---|
| 0 | 8-bit | Start Delimiter | Indicates the start of an API frame. |
| 1 | 16-bit | Length | Number of bytes between the length and checksum. |
| 3 | 8-bit | Frame type |
BLE Unlock Request - 0x2C |
| 4 | 8-bit | Step |
Indicates the phase of authentication and interpretation of payload data:
See the phase tables below for more information. Step values greater than 0x80 indicate error conditions: 0x80 = Unable to offer B—cryptographic error with content, usually due to A mod N == 0 0x81 = Incorrect payload length 0x82 = Bad proof of key 0x83 = Resource allocation error 0x84 = Request contained a step not in the correct sequence |
| 5-n |
varies |
Payload | Payload structure varies by Step value. Refer to the phase tables below for the structure of this field. |
| EOF | 8-bit | Checksum | 0xFF minus the 8-bit sum of bytes from offset 3 to this byte—between length and checksum. |
Phase tables
The following fields are inserted as the payload data depending on the phase of the authentication process
Phase 1 (Client presents A)
| Offset | Size | Frame Field | Description |
|---|---|---|---|
| 5 | 1024-bit (128 bytes) |
A |
One-time ephemeral client public key. If the A value is zero, the server will terminate the connection. |
Phase 2 (Server presentsBand salt)
| Offset | Size | Frame Field | Description |
|---|---|---|---|
| 5 |
32-bit |
Salt | The SRP Salt value from the $S command. |
| 9 | 1024-bit (128 bytes) |
B | One-time ephemeral host public key. |
Phase 3 (Client presentsM1)
| Offset | Size | Frame Field | Description |
|---|---|---|---|
| 5 |
256-bit |
M1 |
SHA256 hash algorithm digest. |
Phase 4 (Server presents M2)
| Offset | Size | Frame Field | Description |
|---|---|---|---|
| 5 |
256-bit |
M2 |
SHA256 hash algorithm digest . |
| 37 |
96-bit |
Tx nonce | Random nonce used as the constant prefix of the counter block for encryption/decryption of data transmitted to the API service by the client. |
| 49 | 96-bit (12 bytes) |
Rx nonce | Random nonce used as the constant prefix of the counter block for encryption/decryption of data received by the client from the API service. |
Upon completion of M2 verification, the session key has been determined to be correct and the API service is unlocked and will allow additional API frames to be used. Content from this point will be encrypted using AES-256-CTR with the following parameters:
- Key: The entire 32-byte session key.
-
Counter: 128 bits total, prefixed with the appropriate nonce shared during authentication. Initial remaining counter value is 1.
The counter for data sent into the XBee API Service is prefixed with the TX nonce value—see the Phase 4 table, above—and the counter for data sent by the XBee to the client is prefixed with the RX nonce value.
Examples
Example sequence to perform AT Command XBee API frames over BLE
- Discover the XBee 3 802.15.4 RF Module through scanning for advertisements.
- Create a connection to the GATT Server.
- Optional, but recommended: request a larger MTU for the GATT connection.
- Turn on indications for the API Response characteristic.
- Perform unlock procedure using BLE Unlock Request - 0x2C unlock frames.
- Once unlocked, you may send Local AT Command Request - 0x08 frames and receive AT Command Response frames received.
- For each frame to send, form the API Frame, and encrypt through the stream cipher as described in the unlock procedure.
- Write the frame using one or more write operations.
- When successful, the response arrives in one or more indications. If your stack does not do it for you, remember to acknowledge each indication as it is received. Note that you are expected to process these indications and the response data is not available if you attempt to perform a read operation to the characteristic.
- Decrypt the stream of content provided through the indications, using the stream cipher as described in the unlock procedure.
PDF
