Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

BLE Secure Channel API Documentation

BLE Secure Channel API Documentation

Status: Active | Applies to: Lite / Pro (secured BLE, service A003) | Updated: 2026-10-16

This document is for third-party apps, gateways, or debugging tools integrating with the device BLE secure channel protocol. It describes only externally visible interface protocol, field definitions, interaction phases, key derivation rules, and message formats.

Where this fits in the repo: this is the authoritative protocol reference for the secured channel (Lite / Pro): J-PAKE / ZKP binary layout, key derivation, and the GATT envelope. Integration entry: Secured BLE API. Values read from advertising without a connection: Encrypted business advertising. Business commands: Business Command Reference. If this document and the API page disagree about the handshake or the envelope, this one wins.

1. Authentication Material

1.1 PIN

  • PIN is the base passphrase material for the device secure channel.

  • PIN is a fixed 8-digit numeric string.

  • Only characters 0-9 are allowed.

  • PIN can only be obtained from the device body label.

1.2 SN

  • SN is the device serial number, used in key derivation.

  • SN is the fixed unique device identifier.

2. Communication Method

  • The client sends JSON strings via the BLE write characteristic.

  • The device returns JSON strings via the BLE notify characteristic.

  • Before the secure channel is established, all traffic is plaintext JSON.

  • After the secure channel is established, all business messages use encrypted envelope JSON.

  • On firmware that enables this secure channel, application GATT service and characteristic UUIDs differ from “plaintext-only business” firmware: service 0xA003, write 0xC313, read 0xC314, notify 0xC315 (full 128-bit UUIDs are in Secured BLE API §4.1).

3. Basic Terminology

3.1 Version Number

  • The protocol version is returned by the device in d.ver via ble-crypto-ver.

  • The client must use the literal value of d.ver and the matching specification so handshake, derivation, and encryption rules align with that version.

3.2 nonce

  • client_nonce and device_nonce are fixed 8-byte random values.

  • In JSON they are represented as 16 hexadecimal characters, e.g. 0011223344556677.

  • client_nonce is the random value provided by the client when initiating handshake or session recovery.

  • device_nonce is the random value returned by the device.

3.3 PBKDF2

  • The device and client first run PBKDF2-HMAC-SHA256 on the 8-digit PIN.

  • Derived output length is 32 bytes.

  • salt = SN || protocol version || "PBKDF2".

  • Iteration count is the protocol constant: 10000 (device and client must match).

3.4 EC J-PAKE

  • The device and client use the PBKDF2 output as passphrase material for EC J-PAKE.

  • Curve: secp256r1.

  • Hash: SHA-256.

  • round1 and round2 messages are transmitted in base64.

  • Both parties obtain the same shared secret only when PIN matches.

3.4.1 Detailed Computation Flow

Notation:

  • G: secp256r1 base point (generator)

  • n: curve order (ORDER)

  • s: 32-byte key material from PBKDF2, interpreted as a big-endian unsigned integer

  • Client identity "client", device identity "server"

3.4.1.1 Schnorr Zero-Knowledge Proof (ZKP)

ZKP proves the prover knows a private key x (with X = x·G) and binds PIN-derived s into the proof so parties with different PINs cannot pass verification.

Generate proof ZKP-Write(G, x, X, id, s):

  1. Choose random v ∈ [1, n-1]

  2. Compute V = v·G

  3. Compute h = Hash(G, V, X, id, s) (see hash definition below)

  4. Compute r = (v - h·x) mod n

  5. Output V || len(r) || r

Verify proof ZKP-Read(G, X, id, s, V, r):

  1. Compute h = Hash(G, V, X, id, s)

  2. Compute V' = h·X + r·G

  3. Verify V' == V; reject if not equal

Hash function Hash(G, V, X, id, s):

where G_raw, V_raw, X_raw are uncompressed EC point encodings (0x04 || x || y, 65 bytes each), id is an ASCII string, and s_bytes is the minimal big-endian byte representation of s. Each field is prefixed with a 4-byte big-endian length.

Key point: s (PIN-derived key) participates in the hash. Different PIN → different s → different h → ZKP verification fails. This detects PIN mismatch as early as Round1.

3.4.1.2 Key Pair with Proof (KKP)

KKP-Write(G, x, X, id, s): generate key pair with ZKP

  1. Generate random key pair (x, X = x·G)

  2. Output X || ZKP-Write(G, x, X, id, s)

KKP-Read(G, id, s, data): read and verify key pair and its ZKP

  1. Read point X from data; verify it is not the point at infinity

  2. Read and verify ZKP-Read(G, X, id, s, ...)

  3. Return verified public key X

3.4.1.3 Round1

Each side generates two ephemeral key pairs with ZKP and sends them to the peer.

Client generates and sends:

After device receives:

  1. Parse and verify client Round1: KKP-Read(G, "client", s, data) → obtain Xp1, Xp2

    • ZKP verification uses the device’s own s (derived from device PIN)

    • If PIN differs → s differs → hash differs → ZKP fails → Round1 fails

  2. Generate device Round1:

  3. Return device_nonce + server_round1

Round1 data layout (each party):

Each key pair is about 133 bytes; Round1 contains two key pairs, about 266 bytes total.

3.4.1.4 Round2

Round2 uses PIN material s to compute a shared base point, then generates one key pair with ZKP.

Client:

Device:

Security design: The device verifies client Round2 before generating its own response. If PIN is wrong, the device does not leak its own key material.

3.4.1.5 Shared Key Derivation

After Round2 completes, each side computes the shared key:

Client:

Device:

If PIN matches, both sides compute the same K and thus the same shared_key. If PIN differs, s differs → Round1 or Round2 ZKP fails before this step.

3.4.1.6 Full Key Derivation Chain

3.5 LTK and session key

  • LTK and session key are derived with HKDF-SHA256.

  • LTK derivation:

    • Input key material: EC J-PAKE shared key

    • salt = device_nonce || client_nonce

    • info = SN || protocol version || "LTK"

  • session key derivation:

    • Input key material: LTK

    • salt = device_nonce || client_nonce

    • info = SN || protocol version || "session"

3.5.1 Broadcast key

  • Used for AES-128-CCM encryption of the long format (26-byte) payload in BLE advertising manufacturer data (byte layout: Encrypted business advertising).

  • Uses the same salt = device_nonce || client_nonce as LTK (8 bytes each, same order as LTK).

  • info = SN || protocol version || "broadcast" (interpret as ASCII byte sequence; no extra terminators from JSON or debug output).

  • Input key material: LTK (16 bytes).

  • Output length: 16 bytes as broadcast-only key; same lifecycle as LTK, persistence per §3.5.2. Not recomputed on ble-crypto-session-nonce session recovery (session only recomputes session key and GATT business CCM bases).

3.5.2 Persistence of LTK and broadcast key

After Wi-Fi association succeeds, the device stores the LTK and the broadcast key. A later BLE disconnect or reboot can restore the GATT session with ble-crypto-session-nonce, and the long advertising packet in Encrypted business advertising can be decrypted without a connection. Storage happens only after the secure handshake has finished and Wi-Fi association has succeeded.

Storage form

  • Persistence uses device non-volatile storage (same namespace as business configuration).

  • LTK and broadcast key are stored as 32-character hexadecimal strings (16-byte binary keys); integrators must handle the full 32 characters when reading, caching, or backing up.

First provisioning: deferred commit

Phase
Device behavior

ble-crypto-jpake-round2 success

Derive LTK, broadcast key, and current session key in memory; secure channel is immediately usable (step=3), not yet written to persistent storage.

Wi‑Fi config over encrypted channel

Device saves SSID/password and starts STA association; enters “LTK pending commit” state.

STA association success

One-time write of in-memory LTK and broadcast key to persistent storage; after reboot or reconnect, ble-crypto-ver may return step=2.

STA association failure

Do not persist LTK from this J-PAKE round; after the agreed wait window, discard pending keys in memory and roll back session state; J-PAKE must be repeated to provision again.

During “LTK pending commit”, the device will not write LTK or broadcast key to persistent storage through any other path.

Later connections: read-only load

  • When LTK is already persisted, the client sends ble-crypto-session-nonce with new client_nonce / device_nonce; the device reads LTK and broadcast key from storage and recomputes session key and §3.6 CCM bases.

  • This flow does not update persisted LTK or broadcast key.

Clear and invalidation

  • Clear device configuration (factory reset or equivalent debug entry) deletes persisted LTK and broadcast key; first-time provisioning must be repeated.

  • If connection passphrase (PIN-related material) changes and invalidates long-term keys, the device should clear persisted LTK and broadcast key accordingly.

Relation to typical flows

  • After J-PAKE Round2 in §6.1, encrypted business is available immediately; LTK commit requires Wi‑Fi configuration and STA success in the same encrypted session (see Business Command Reference §2.2).

  • §6.2 applies when LTK is already persisted; §7.5 only restores session keys and does not trigger re-commit.

3.6 AES-CCM and 12-byte nonce derivation (GATT business JSON ciphertext envelopes only)

This section describes JSON ciphertext over Notify/Write (Section 8), not the long advertising packet in Encrypted business advertising (that tag is 4 bytes).

GATT business ciphertext uses AES-128-CCM: no additional authenticated data (AAD length 0), authentication tag tag length 8 bytes. The full 12-byte CCM nonce is not sent in JSON; the JSON nonce field is only a 32-bit unsigned counter (Section 8). Both sides assemble 12 bytes locally per this section before CCM encrypt/decrypt.

3.6.1 Structure

The 12-byte nonce is two parts (big-endian / network byte order):

Offset
Length
Meaning

0–7

8 bytes

Session-fixed nonce base (from HKDF output)

8–11

4 bytes

Message counter counter as big-endian uint32_t

Notation: nonce_12 = nonce_base_8 || BE32(counter).

3.6.2 Base: HKDF-SHA256 (fixed 8-byte output)

After session key is derived and both sides agree on this round’s device_nonce and client_nonce (8 bytes each), each side computes two directions of 8-byte bases (HKDF salt is empty, length 0; info is the byte sequence of the ASCII strings below, without trailing NUL from language runtimes):

  1. Device → client

    • IKM = device_nonce || client_nonce (16 bytes)

    • info = "ccm-tx-nonce"

    • nonce_base_tx = HKDF-SHA256(salt=∅, IKM, info, L=8)

  2. Client → device

    • IKM = client_nonce || device_nonce (16 bytes, opposite order from above)

    • info = "ccm-rx-nonce"

    • nonce_base_rx = HKDF-SHA256(salt=∅, IKM, info, L=8)

Both first J-PAKE link and ble-crypto-session-nonce recovery recompute these bases and session key after exchanging new device_nonce / client_nonce. Counter rules after base or session key change are in Section 8.

3.6.3 Direction and base (device / client)

Operation

8-byte base used

JSON nonce field

Decrypt ciphertext from device Notify

nonce_base_tx

Matches counter in device envelope

Encrypt ciphertext sent via Write

nonce_base_rx

Client-maintained sequence for this direction

Symmetric on device: outbound to client uses nonce_base_tx and device send sequence per §8.1; inbound from client uses nonce_base_rx and envelope nonce.

4. Common Response Format

All plaintext responses use this structure:

Field descriptions:

  • ok: Boolean, whether the request succeeded.

  • msg: String; reason on failure, usually empty on success.

  • event: String; command this response belongs to.

  • d: Object, optional; business data for the command.

5. Protocol Phases

The device reports secure channel phase via step:

  • 0: Waiting for client ble-crypto-jpake-round1

  • 1: Waiting for client ble-crypto-jpake-round2

  • 2: Device has long-term keys; waiting for client ble-crypto-session-nonce to restore session

  • 3: Secure channel established; encrypted business messages allowed

6. Typical Flows

6.1 First-time secure channel establishment

  1. ble-crypto-ver

  2. ble-crypto-jpake-round1

  3. ble-crypto-jpake-round2 (LTK and session key in memory; encrypted traffic immediately)

  4. (Recommended) Send Wi‑Fi configuration in the same encrypted session; after STA success, LTK and broadcast key are committed (§3.5.2)

  5. Subsequent business uses encrypted envelopes

If step 4 is incomplete or Wi‑Fi association fails, LTK is not persisted; after reboot, J-PAKE must be repeated.

6.2 Restore secure channel after device reboot

  1. ble-crypto-ver

  2. If step=2, send ble-crypto-session-nonce

  3. Proceed with encrypted business

7. Plaintext Commands

7.1 Query protocol version

Request:

Success response example:

Common failure response:

7.2 Reset current handshake

Request:

Notes:

  • Allowed only when step=0 or step=1.

  • Does not clear existing device LTK.

7.3 J-PAKE round 1

Request:

When client_round1 is too long, the client may upload in parts:

Success response example:

If server_round1 is too long, the device returns one part per request. After the first part, the client must request the next:

When multipart upload is not yet complete, the device may return continue-upload confirmation:

Field descriptions:

  • client_nonce: Client random for this round.

  • client_round1: Full client J-PAKE round 1 data, base64 encoded.

  • client_round1_part: Client J-PAKE round 1 fragment, base64 encoded.

  • part_idx: Current fragment index, starting at 0.

  • part_total: Total fragment count.

  • device_nonce: Device random.

  • server_round1: Full device J-PAKE round 1 data, base64 encoded.

  • server_round1_part: Device J-PAKE round 1 fragment, base64 encoded.

  • done: When true, this is the last fragment.

  • fetch_next: Client requests the next server_round1_part.

Additional notes:

  • If a single packet suffices, the client may send client_round1 directly.

  • If too long, use client_round1_part fragments.

  • The device runs J-PAKE round1 verification and response only after the last upload fragment.

  • If the device returns server_round1_part, the client must send fetch_next=true until done=true.

  • Only round1 supports fragmentation; round2 remains single-packet.

7.4 J-PAKE round 2

Request:

Success response example:

Notes:

  • Allowed only when step=1.

  • On success, both sides derive LTK, broadcast key, and session key from EC J-PAKE shared key; secure channel is immediately usable (step=3).

  • LTK and broadcast key persistence waits for Wi‑Fi configuration and STA success per §3.5.2; until then they exist only in device memory.

  • After first link success, no ble-crypto-session-nonce is needed on the current connection; after reboot with persisted LTK, use §7.5 on reconnect.

7.5 Restore secure session

Request:

Success response example:

Notes:

  • Allowed only when step=2 (device has persisted LTK, see §3.5.2).

  • After exchanging new client_nonce / device_nonce, the device recomputes session key and §3.6 CCM bases from stored LTK; does not rewrite persisted LTK or broadcast key.

8. Encrypted Envelope Format

After the secure channel is established, business messages use this JSON envelope:

Field descriptions:

  • nonce: 32-bit unsigned integer, the counter in this section (matches the last 4 bytes big-endian of the 12-byte nonce in Section 3.6). Not the hex string of client_nonce / device_nonce.

  • ct: AES-CCM ciphertext, Base64 (RFC 4648, standard alphabet and = padding).

  • tag: AES-CCM authentication tag (8 bytes), Base64 encoded.

  • Full 12-byte CCM nonce is assembled locally per Section 3.6 from “8-byte HKDF base for that direction + BE32(nonce field)”.

8.1 Device-side sequence conventions

For alignment with §8.2, the device maintains two internal 32-bit counters (not extra JSON field names; semantics only):

  • N_send (device → client)

    • When encrypted business is allowed, device outbound ciphertext uses N_send initial value 1.

    • Each successfully encrypted and sent packet (e.g. via Notify) has envelope nonce equal to current N_send, then N_send ← N_send + 1 (arithmetic mod 2³²; redeploy should re-handshake or rotate session before wrap to avoid nonce reuse).

  • N_accept (last accepted client nonce)

    • New session starts at 0.

    • After each successful decrypt of a client write ciphertext, N_accept ← that packet’s envelope nonce.

The client should mirror: track device nonce for decrypt; use an independent sequence for writes toward the device per §8.2 relative to device N_accept.

8.2 nonce (counter) and replay protection (client → device)

When processing client write ciphertext, the device must:

  • If envelope nonce ≤ N_accept (unsigned 32-bit compare), reject with replay detected: do not update N_accept, do not decrypt.

  • Only if nonce > N_accept, decrypt with §3.6 nonce_base_rx + BE32(nonce); on success N_accept ← nonce.

Therefore:

  1. Strict increase vs device accepted value: each new client ciphertext must have nonce greater than current N_accept; equal or smaller is rejected.

  2. Gaps allowed: e.g. after accepting nonce=5, next may be 10 if 10 > 5.

  3. No “late” smaller values: if N_accept=10, later nonce=5 is replay and rejected.

  4. Retransmit: second packet with nonce not greater than N_accept returns replay detected.

  5. Non-incrementing or reused counters: rejected except possibly the first packet; encrypting different plaintext under the same session key and same full 12-byte CCM nonce violates CCM usage and risks keystream reuse.

Device → client: device increments N_send in send order. This protocol does not require extra anti-replay fields for that direction; clients should verify monotonic nonce on receive to reduce replay and state confusion (symmetric to device N_accept rules above).

8.3 Difference from decrypt failed

  • replay detected: counter check failed; CCM not entered.

  • decrypt failed: counter passed but CCM authenticated decrypt failed (wrong key, corrupted ct/tag, nonce mismatch with encrypting side, etc.).

9. BLE Advertising Manufacturer Data (Dynamic Advertising)

Encrypted business advertising has its own page: Encrypted business advertising.

This document keeps the handshake, key derivation (including the §3.5 broadcast key), and the GATT envelope. Packet layout, decrypt parameters, and the electrical fields are defined on that page.

10. Failure Conditions

Common failure reasons include:

  • device locked

  • version required

  • invalid step

  • invalid round1

  • invalid round2

  • round1 verify failed

  • round2 verify failed

  • shared key derive failed

  • ltk derive failed

  • session derive failed

  • replay detected: see Section 8.2 (client → device ciphertext nonce not greater than device N_accept).

  • decrypt failed: CCM verify or decrypt failed, see Section 8.3.

11. Compatibility Notes

  • This document corresponds to the new PBKDF2 + EC J-PAKE + HKDF handshake protocol.

  • Legacy ble-crypto-client-nonce and ble-crypto-client-response are deprecated.

  • Clients must upgrade per this document; otherwise first-time link establishment will fail.

Last updated