BLE Unlock API - 0x2C

Description

The XBee 3 Cellular LTE-M/NB-IoT uses this frame to authenticate a connection on the Bluetooth interface and unlock the processing of AT command frames. This frame is used in conjunction with the Response (0xAC) frame.

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 value 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 sent through the UART (if AP=1 or 2). When an unlocked connection is terminated, a Modem Status Frame with the status code 0x33 (Bluetooth Disconnected) is sent through the UART.

The following implementations are known to work with the BLE SRP implementation:

https://github.com/cncfanatics/SRP

You will need to modify the hashing algorithm to SHA256 and the values of N and g to 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.

Frame data fields	Offset	Description
Frame type	3	0x2C = Request 0xAC = Response
Step	4	Indicates the phase of authentication and interpretation of payload data. See 1 = Client presents A value 2 = Server presents B and salt 3 = Client present M1 session key validation value 4 = Server presents M2 session key validation value and two 12-byte nonces 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
Payload	5	Payload structure varies by Frame ID value. Descriptions are in the tables, below.

Frame data fields

Offset

Description

Frame type

0x2C = Request

0xAC = Response

Step

Indicates the phase of authentication and interpretation of payload data. See

1 = Client presents A value

2 = Server presents B and salt

3 = Client present M1 session key validation value

4 = Server presents M2 session key validation value and two 12-byte nonces

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

Payload

Payload structure varies by Frame ID value. Descriptions are in the tables, below.

The tables below give more information about the phase of authentication and interpretation of payload data.

Phase 1 (Client presents A)

If the A value is zero, the server will terminate the connection.

Frame data field	Offset in frame	Length
A	5	128 bytes

Phase 2 (Server presents B and salt)

Frame data field	Offset in frame	Length
salt	5	4 bytes
B	9	128 bytes

Phase 3 (Client presents M1)

Frame data field	Offset in frame	Length
M1	5	Hash algorithm digest length (32 bytes for SHA256)

Phase 4 (Server presents M2)

Frame data field	Offset in frame	Length
M2	5	Hash algorithm digest length (32 bytes for SHA256)
TX nonce	37	12-byte (96-bit) random nonce, used as the constant prefix of the counter block for encryption/decryption of data transmitted to the API service by the client
RX nonce	49	12-byte (96-bit) 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.