docs: add BLE protocol specification#116
docs: add BLE protocol specification#116buckleypaul wants to merge 1 commit intoHubbleNetwork:mainfrom
Conversation
Formal specification for Hubble BLE advertisement protocol covering packet structure, KBKDF key derivation, AES-CTR encryption, CMAC authentication, and test vectors for implementation validation. Signed-off-by: Paul Buckley <paul@hubble.com>
github-actions
bot
requested review from
HongNguyen635,
ceolin and
hunterhubble
|
|
||
| Devices MUST be provisioned with UTC time before generating advertisements. The device MUST maintain time accuracy within ±1 hour to ensure gateway decryption succeeds. | ||
|
|
||
| Time synchronization methods: |
There was a problem hiding this comment.
These are only a few methods to have it, the way it is state is that must be one of those. I would reword it to make it clear these are options.
| The complete 10-bit sequence counter is reconstructed as: | ||
| ``` | ||
| seq_counter = ((prefix & 0x03) << 8) | seq_low | ||
| ``` |
There was a problem hiding this comment.
This block in this section is confusing because it covers bytes 2 and 3. seq_counter is two bytes long.
| | Full advertisement (no payload) | 18 bytes | | ||
| | Full advertisement (max payload) | 31 bytes | | ||
|
|
||
| The 31-byte limit is the maximum for legacy BLE 4.x advertisements. |
There was a problem hiding this comment.
I am not an expert, but I think that is not a legacy limit, this is part of newer specifications as well. It happens is that newer Bluetooth versions have extended advertisement format.
| ### A.1 Complete KBKDF Algorithm | ||
|
|
||
| ``` | ||
| FUNCTION KBKDF_Counter(key, label, context, output_bits): |
There was a problem hiding this comment.
output should be in bytes, it is byte aligned and we don't need number of bits.
| ``` | ||
| DeviceKey = KBKDF(MasterKey, "DeviceKey", "20370", 256) | ||
| NonceKey = KBKDF(MasterKey, "NonceKey", "20370", 256) | ||
| EncryptionKey = KBKDF(MasterKey, "EncryptionKey", "20370", 256) |
There was a problem hiding this comment.
Last parameter should by in bytes, see the comment in the implementation.
ceolin
left a comment
ceolin
left a comment
There was a problem hiding this comment.
Minor comments. I liked it very much !
HongNguyen635
left a comment
HongNguyen635
left a comment
There was a problem hiding this comment.
agree with @ceolin comments above ^
The rest looks good to me. Should we add @danielr-hubblenetwork as the reviewer as well since this relates to docs?
solidspark
left a comment
solidspark
left a comment
There was a problem hiding this comment.
Just a nit regarding the use of UTC Time vs Epoch Time.
| |------|------------| | ||
| | Advertisement | A BLE broadcast packet containing Hubble service data | | ||
| | EID | Ephemeral ID, a time-based identifier that rotates daily | | ||
| | Time Counter | Integer derived from UTC time, increments daily | |
There was a problem hiding this comment.
Note we're using "Epoch Time", not UTC Time.
There was a problem hiding this comment.
Should we also note here that it "increments daily upon new advertisement retrieval"?
| │ (Transmitter) │ ──────► │ (Receiver) │ ──────► │ Platform │ | ||
| │ │ │ │ │ │ | ||
| │ • Master Key │ │ • Decrypts adverts │ │ • Stores data │ | ||
| │ • UTC time │ │ • Validates auth │ │ • Delivers to │ |
There was a problem hiding this comment.
Same comment re: Epoch Time, throughout the document.
There was a problem hiding this comment.
Important: the receiver does not decrypt advertisement. This is on the backend. The gateway does not know device ID.
There was a problem hiding this comment.
This should be "forwards to Hubble Cloud" in my view.
May need 4th column: between receiver and Cloud Platform, Hubble Backend?
There was a problem hiding this comment.
And/or "Cloud Platform" should contain both decryption/storage as well as ability to retrieve packet data via API
| @@ -0,0 +1,808 @@ | |||
| # Hubble BLE Protocol Specification | |||
There was a problem hiding this comment.
Do we expect to have a separate resource for SATELLITE?
If yes, can we adopt a naming convention like
- Hubble Specification for Terrestrial Network
- Hubble Specification for Satellite Network
Otherwise consider generic "Hubble Protocol Specification"?
|
|
||
| ### 1.1 Purpose | ||
|
|
||
| This document specifies the Hubble Network Bluetooth Low Energy (BLE) advertisement protocol. It provides the complete technical specification required for implementers to create interoperable transmitters that communicate with Hubble Network gateways. |
There was a problem hiding this comment.
The SIG requires us to mark "Bluetooth®" on first use
There was a problem hiding this comment.
Recommend that we name "Terrestrial" then use BLE going forward, e.g.
"This document specifies the Hubble Network Bluetooth Low Energy (BLE) advertisement protocol used to transmit on the Terrestrial Network."
| This specification is limited to: | ||
|
|
||
| - Transmitter-side implementation | ||
| - UTC-based Ephemeral ID (EID) mode |
There was a problem hiding this comment.
Epoch-time encryption (see Ryan's comments throughout)
| | Advertisement | A BLE broadcast packet containing Hubble service data | | ||
| | EID | Ephemeral ID, a time-based identifier that rotates daily | | ||
| | Time Counter | Integer derived from UTC time, increments daily | | ||
| | Sequence Counter | Per-advertisement counter (0-1023) within a time period | |
There was a problem hiding this comment.
Might confuse readers because you can beacon the same advertisement multiple times. Can we be more clear e.g. "per unique advertisement counter"?
|
|
||
| ### 2.3 Time Synchronization Requirements | ||
|
|
||
| Devices MUST be provisioned with UTC time before generating advertisements. The device MUST maintain time accuracy within ±1 hour to ensure gateway decryption succeeds. |
There was a problem hiding this comment.
Technically our permissible range is +- 24 hours, do we want to conceal this?
|
|
||
| #### 3.4.6 Encrypted Payload (Bytes 12-24) | ||
|
|
||
| AES-CTR encrypted user payload data. Maximum 13 bytes. |
There was a problem hiding this comment.
Mention customers can also use their own encryption on the custom payload?
https://docs.hubble.com/docs/security/network#1-optional-customer-managed-encryption-at-payload-creation
| 1. A provisioned master key (128 or 256 bits) | ||
| 2. Current UTC time in milliseconds | ||
| 3. A sequence counter value (0-1023) | ||
| 4. Payload data (0-13 bytes) |
There was a problem hiding this comment.
Optional payload data
danielr-hubblenetwork
left a comment
danielr-hubblenetwork
left a comment
There was a problem hiding this comment.
This is a valuable addition. Good content. Especially the test vectors (net new content). Minor comments added.
5 participants
Formal specification for Hubble BLE advertisement protocol covering packet structure, KBKDF key derivation, AES-CTR encryption, CMAC authentication, and test vectors for implementation validation.