BLE Secure Channel API Documentation
BLE Secure Channel API Documentation
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
PINis the base passphrase material for the device secure channel.PINis a fixed8-digit numeric string.Only characters
0-9are allowed.PINcan only be obtained from the device body label.
1.2 SN
SNis the device serial number, used in key derivation.SNis 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, write0xC313, read0xC314, notify0xC315(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.verviable-crypto-ver.The client must use the literal value of
d.verand the matching specification so handshake, derivation, and encryption rules align with that version.
3.2 nonce
client_nonceanddevice_nonceare fixed8-byte random values.In JSON they are represented as
16hexadecimal characters, e.g.0011223344556677.client_nonceis the random value provided by the client when initiating handshake or session recovery.device_nonceis the random value returned by the device.
3.3 PBKDF2
The device and client first run
PBKDF2-HMAC-SHA256on the8-digitPIN.Derived output length is
32bytes.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
PBKDF2output as passphrase material forEC J-PAKE.Curve:
secp256r1.Hash:
SHA-256.round1andround2messages are transmitted inbase64.Both parties obtain the same shared secret only when
PINmatches.
3.4.1 Detailed Computation Flow
Notation:
G: secp256r1 base point (generator)n: curve order (ORDER)s: 32-byte key material fromPBKDF2, interpreted as a big-endian unsigned integerClient 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):
Choose random
v ∈ [1, n-1]Compute
V = v·GCompute
h = Hash(G, V, X, id, s)(see hash definition below)Compute
r = (v - h·x) mod nOutput
V || len(r) || r
Verify proof ZKP-Read(G, X, id, s, V, r):
Compute
h = Hash(G, V, X, id, s)Compute
V' = h·X + r·GVerify
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 → differents→ differenth→ 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
Generate random key pair
(x, X = x·G)Output
X || ZKP-Write(G, x, X, id, s)
KKP-Read(G, id, s, data): read and verify key pair and its ZKP
Read point
Xfrom data; verify it is not the point at infinityRead and verify
ZKP-Read(G, X, id, s, ...)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:
Parse and verify client Round1:
KKP-Read(G, "client", s, data)→ obtainXp1, Xp2ZKP verification uses the device’s own
s(derived from device PIN)If PIN differs →
sdiffers → hash differs → ZKP fails → Round1 fails
Generate device Round1:
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
LTKandsession keyare derived withHKDF-SHA256.LTKderivation:Input key material:
EC J-PAKE shared keysalt = device_nonce || client_nonceinfo = SN || protocol version || "LTK"
session keyderivation:Input key material:
LTKsalt = device_nonce || client_nonceinfo = 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_nonceasLTK(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-noncesession recovery (session only recomputessession keyand 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
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-noncewith newclient_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):
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):
Device → client
IKM = device_nonce || client_nonce(16 bytes)info = "ccm-tx-nonce"nonce_base_tx = HKDF-SHA256(salt=∅, IKM, info, L=8)
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 clientble-crypto-jpake-round11: Waiting for clientble-crypto-jpake-round22: Device has long-term keys; waiting for clientble-crypto-session-nonceto restore session3: Secure channel established; encrypted business messages allowed
6. Typical Flows
6.1 First-time secure channel establishment
ble-crypto-verble-crypto-jpake-round1ble-crypto-jpake-round2(LTK and session key in memory; encrypted traffic immediately)(Recommended) Send Wi‑Fi configuration in the same encrypted session; after STA success, LTK and broadcast key are committed (§3.5.2)
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
ble-crypto-verIf
step=2, sendble-crypto-session-nonceProceed 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=0orstep=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,base64encoded.client_round1_part: Client J-PAKE round 1 fragment,base64encoded.part_idx: Current fragment index, starting at0.part_total: Total fragment count.device_nonce: Device random.server_round1: Full device J-PAKE round 1 data,base64encoded.server_round1_part: Device J-PAKE round 1 fragment,base64encoded.done: Whentrue, this is the last fragment.fetch_next: Client requests the nextserver_round1_part.
Additional notes:
If a single packet suffices, the client may send
client_round1directly.If too long, use
client_round1_partfragments.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 sendfetch_next=trueuntildone=true.Only
round1supports fragmentation;round2remains 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-nonceis 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, thecounterin this section (matches the last 4 bytes big-endian of the 12-byte nonce in Section 3.6). Not the hex string ofclient_nonce/device_nonce.ct:AES-CCMciphertext, Base64 (RFC 4648, standard alphabet and=padding).tag:AES-CCMauthentication tag (8bytes), Base64 encoded.Full 12-byte CCM
nonceis 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_sendinitial value1.Each successfully encrypted and sent packet (e.g. via Notify) has envelope
nonceequal to currentN_send, thenN_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 envelopenonce.
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 withreplay detected: do not updateN_accept, do not decrypt.Only if
nonce > N_accept, decrypt with §3.6nonce_base_rx+BE32(nonce); on successN_accept ← nonce.
Therefore:
Strict increase vs device accepted value: each new client ciphertext must have
noncegreater than currentN_accept; equal or smaller is rejected.Gaps allowed: e.g. after accepting
nonce=5, next may be10if10 > 5.No “late” smaller values: if
N_accept=10, laternonce=5is replay and rejected.Retransmit: second packet with
noncenot greater thanN_acceptreturnsreplay detected.Non-incrementing or reused counters: rejected except possibly the first packet; encrypting different plaintext under the same
session keyand same full 12-byte CCMnonceviolates 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, corruptedct/tag,noncemismatch 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 lockedversion requiredinvalid stepinvalid round1invalid round2round1 verify failedround2 verify failedshared key derive failedltk derive failedsession derive failedreplay detected: see Section 8.2 (client → device ciphertextnoncenot greater than deviceN_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 + HKDFhandshake protocol.Legacy
ble-crypto-client-nonceandble-crypto-client-responseare deprecated.Clients must upgrade per this document; otherwise first-time link establishment will fail.
Last updated