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 of Nandgto use the RFC5054 1024-bit group.

Format

The following table provides the contents of the frame. For details on frame structure, see API frames.

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
BLE Unlock Response - 0xAC

4

8-bit

Step

Indicates the phase of authentication and interpretation of payload data:

  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

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 presents B and salt)

Offset Size Frame Field Description

5

32-bit
(4 bytes)

Salt

The SRP Salt value from the $S command.

9

1024-bit
(128 bytes)

B

One-time ephemeral host public key.

Phase 3 (Client presents M1)

Offset Size Frame Field Description

5

256-bit
(32 bytes)

M1

SHA256 hash algorithm digest.

Phase 4 (Server presents M2)

Offset Size Frame Field Description

5

256-bit
(32 bytes)

M2

SHA256 hash algorithm digest .

37

96-bit
(12 bytes)

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.

Example

Refer to SRP authentication on XBee devices for an example of how to unlock the connection and communicate with the device over BLE.