# Hubble Network Platform Docs — Security > Documentation for developers integrating with Hubble Network — an IoT connectivity platform using Bluetooth chips and a satellite/terrestrial gateway network. --- # Encryption Concepts # Encryption Concepts The cryptographic techniques used by the Terrestrial Network for Bluetooth® Low Energy (BLE) transmission ensure confidentiality, integrity, and authenticity of the data being advertised by your anonymous devices. --- ## Key Concepts AES-256 provides strong encryption, CMAC ensures data integrity and authenticity, and the KBKDF securely derives keys from a master key. The use of nonces and sequence numbers prevents replay attacks and ensures that each advertisement is unique. ### AES Encryption The SDK supports AES-256 ([Advanced Encryption Standard](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf) with a 256-bit key) or AES-128 (128-bit key) for encryption. AES is a symmetric encryption algorithm, meaning the same key is used for both encryption and decryption. ### CMAC (Cipher-based Message Authentication Code) CMAC is used to generate a message authentication code (MAC) to ensure data integrity and authenticity. The CMAC is computed over the input data using the provided key, and the result is stored in the output buffer. ### KBKDF (Key-Based Key Derivation Function) The code uses a KBKDF to derive keys from a master key. It derives keys based on a master key, a label, a context, and a counter. It uses CMAC as the pseudorandom function (PRF) to generate the derived keys. Learn more: [NIST - Recommendation for Key Derivation Using Pseudorandom Functions](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf) ### Nonce Generation A nonce (number used once) is generated for each encryption operation to ensure that the same plaintext encrypted multiple times will produce different ciphertexts. The nonce is derived using the KBKDF with a specific label (“Nonce”) and the current sequence number. ### AES-128-EAX Supported specifically for **InPlay IN100** devices, AES-128-EAX provides Authenticated Encryption with Associated Data (AEAD). This [encryption mode](/docs/security/device/encryption-modes) uses device uptime and is optimized for the IN100's hardware constraints. It protects against both eavesdropping and bit-flipping attacks while maintaining the low power consumption profile required for nanobeacon applications. --- # Device Encryption Modes # Device Encryption Modes Hubble Network supports multiple device encryption schemes compatible with your hardware, with configurations to ensure transmission privacy. --- ## Overview Your device is [anonymous end-to-end](/docs/security/network) on Hubble Network because the Device SDK encrypts and rotates IDs. Device ownership is only determined on our backend after transmissions are received, so that we can securely deliver the data packet to your organization. ## Configurations The [Hubble Device SDK handles](/docs/security/device/sdk-encryption) all this based on your selected encryption mode, which is a function of the encryption algorithm, key size, and counter source – and for IN100, a custom configuration called the period exponent. ### Encryption Algorithm When you [register devices](/docs/guides/cloud-integration/register-devices) to your Hubble organization, you must specify encryption mode for **Ephemeral ID (EID) rotation**. Hubble Network supports two primary device encryption schemes that govern EID rotation, based on your hardware capabilities: - **AES-256 / AES-128 (Standard):** Uses AES-CTR (counter mode) and CMAC. Set **key size** and **counter source**. Best for standard BLE devices. - **AES-128-EAX:** An Authenticated Encryption (AEAD) mode specifically optimized for **IN100** (nanobeacon) chips. Must use **device uptime** as counter source. Set **period exponent** to define EID rotation period (the rotation period is calculated as 2^*n* seconds, where *n* is the `period_exponent`). ### Key Size Hubble Network supports **AES-256** and **AES-128** length keys. 256-bit is recommended. ### Counter Source Use **unix time** to rotate EIDs if your hardware can maintain an accurate, synchronized clock. Otherwise use **device uptime**, which does not require the device to know current time. AES-128-EAX encryption mode requires "DEVICE_UPTIME" counter source. #### Comparing Encryption Modes by Counter Source |Feature|UNIX_TIME (Default)|DEVICE_UPTIME| |---|---|---| |**Supported algorithms /
Key sizes**|AES-256, AES-128|AES-256, AES-128, or **AES-128-EAX** (required for IN100)| |**Best for**|Devices with reliable time sync; maximum privacy.|Devices without a time source; best for "out-of-the-box" provisioning (e.g. IN100).| |**Time sync**|**Required.** Device must maintain current Unix epoch time across power cycles.|**Not Required.** Ideal for simple hardware without a time-aware Real-Time Clock (RTC).| |**Reset behavior**|**Persistent.** EIDs remain unique as long as the UTC clock is maintained.|**Volatile.** Counter typically resets to 0 (or a number in the pool) on boot.| |**Rotation logic**|**Time-Based.** EIDs are derived from the current UTC epoch and never repeat.| **Pool-Based.** Increments by device uptime counter within a fixed pool; wraps at the `pool_size` constant.| |**Clock drift**|+/-1 epoch in counter value is permissible. |Does not apply.| |**EID validity**|**Strict.** Advertisement packets must be rotated at least every 24 hours to generate the next valid EID.|**Flexible.** EIDs are pre-computed on the backend; advertisements remain valid even if a rotation cycle is missed.| |**EID reuse**|**Never.** Unix time is the most secure encryption mode. |**Cyclical.** EIDs repeat after `pool_size` rotations (default 128).| > **Go further:** Review [**Onboard Devices**](/docs/guides/cloud-integration/register-devices) for guidance on how to register a new device to your Hubble organization with your specified security configuration. --- # SDK Encryption # SDK Encryption Data integrity is ensured through [encryption](/docs/security/device/encryption-concepts), with secure key management on the device, and message security is protected by an authentication tag included in every BLE payload. Each packet can also carry a customer-defined [encrypted payload](/docs/security/network) up to the supported size limit. --- ## How It Works An application will get the encrypted advertisment data using `hubble_ble_advertise_get` in the **Hubble Device SDK**. This function performs the following steps to prepare the advertisement data: 1. Derives the device ID, nonce, and encryption key using the KBKDF. 2. Sets the BLE address using the derived device ID and sequence number. 3. Encrypts the payload data using the device encryption mode (AES-256/AES-128 in CTR mode, or AES-128-EAX) with the derived encryption key and nonce. 4. Computes the CMAC of the encrypted payload data to generate an authentication tag for AES-256/AES-128 CTR mode. 5. Copies the authentication tag and encrypted data into the advertisement buffer. ## Device Key Management Hubble employs a secure key management architecture to ensure the integrity and confidentiality of device communications. The **Hubble Device SDK** can be used to perform this functionality on the devices. ### Key Derivation * **Master Key (Km)**: A root key stored securely in Hubble’s backend. * **Derived Keys**: * **Device Key (Ke)**: Used for generating unique device identifiers. * **Nonce Key (Kn)**: Ensures unique encryption for each message. * **Encryption Key (Kd)**: Secures message payloads. * Derived keys are generated using AES-CMAC in counter mode, compliant with NIST 800-108. ### **Key Rotation** * **Frequency**: Keys rotate on every sequence number rollover to prevent reuse. * **Process**: * A new encryption key and nonce are derived for each message based on the sequence number. * This ensures compliance with AES-CTR mode security requirements. :::warning When using "UNIX_TIME" counter source, i.e. time-based encryption, you must update advertising payload on your device at least once every 24 hours to maintain ID rotation. ::: ### **Replay Protection** * **Sequence Numbers**: * Incremented with each transmitted packet. * Reset upon rollover, with the rollover counter incremented. * **Server Validation**: * The server authenticates packets against the last seen sequence number and rollover counter. * New packets are validated within a permissible range of sequence numbers to account for minor desynchronization. --- # Network Security # Network Security Hubble Network is designed for end-to-end data security, from anonymous, encrypted device broadcasts to protected cloud storage. - Devices remain anonymous on the network through **KBKDF (Key-Based Key Derivation Function)** and secure key management on the device. - Each transmission is encrypted using **AES (Advanced Encryption Standard) counter mode**, with **CMAC (Cipher-based Message Authentication Code)** providing message authentication to ensure integrity. Hubble's backend validates message sequence numbers to prevent replay attacks. - On the cloud, data is encrypted at rest and protected with authentication-based access control for your organization, following industry best practice security standards. Each packet transmitted using the Hubble protocol can also carry a customer-defined encrypted payload, enabling **double envelope encryption** as a best practice. If encrypted by you, the network user, your private data is never visible to Hubble Network. :::note Learn more about Hubble's encyrption process and secure key management on the Terrestrial Network module [**Security Overview**](/docs/security/device/encryption-concepts). ::: ## End-to-End Data Security !["Dual layered network encryption"](/img/encryption-in-network-transmission.svg) #### **1. Optional customer-managed encryption at payload creation** To achieve full end‑to‑end encryption, you can add your own encryption layer between the device and your server. For example, your device can retrieve a nonce from the Hubble Device SDK and apply proprietary encryption. You also control the retention period of your encrypted data, managing how long it persists outside your systems. #### **2. From the Bluetooth® device to the Hubble Terrestrial Network Partner Gateway** The Hubble SDK encrypts each packet using AES in counter mode. Except for the Hubble identifier in the advertisement payload (16‑bit Service UUID), the entire payload is encrypted and unreadable to the partner gateway. #### **3. From the Hubble Partner backend to the Hubble Cloud** Data remains encrypted with AES in counter mode. The partner backend does not store the data—it is immediately forwarded to the Hubble Cloud. #### **4. Decryption and validation in the Hubble Cloud** Payloads are decrypted using the key provisioned at device registration. CMAC authentication tags are verified to ensure message integrity and authenticity. If customer‑managed encryption was applied, the payload content remains encrypted. #### **5. From the Hubble Cloud to your cloud** Decrypted packets are delivered to your server. If you applied your own encryption layer, you perform the final payload decryption using your key. On the Hubble backend, all data at rest is stored in encrypted storage and access is authenticated. --- # Vulnerabilities # Vulnerabilities :::warn This page serves as a repository for tracking vulnerabilities identified and resolved in each software release. It will frequently include **additional details** beyond what is provided in Release Notes. ::: --- # Vulnerability Handling # Vulnerability Handling Hubble Network is committed to maintaining a secure and reliable platform. This document outlines the security vulnerability reporting and management policy for Hubble Network. --- ## Process Overview Vulnerabilities in the Hubble Network platform may be reported via email to the **security@hubble.com** mailing list. These reports will be acknowledged and analyzed by the security response team within 1 week. Each vulnerability will be entered into the Hubble Network Security Advisory system. The original submitter will be granted permission to view the issues they have reported. ## Security Issue Management Issues within the bug tracking system will transition through several states as described below: !["Hubble Network Vulnerability Handling flow"](/img/vulnerability-handling.svg) 1. **New:** Represents new reports entered directly by a reporter. When entered by the response team in response to an email, the issue transitions directly to Triage. 2. **Triage:** The issue is awaiting analysis by the response team. The team will determine a responsible entity, assign the issue, and set its priority. 3. **Assigned:** The issue has been assigned and is awaiting a fix by the assignee. 4. **Review:** Once a pull request (PR) is created for the issue, the PR link will be added to a comment, and the issue will move to Review. 5. **Accepted:** Indicates that the issue has been merged into the appropriate branch. 6. **Public:** The embargo period has ended, and the issue will be made publicly visible. Associated CVEs and documentation will be updated. ### Advisory Policy The security advisories are kept private due to the sensitive nature of security reports. Access is limited to: - Members of the Project Security Incident Response Team (PSIRT). - The reporter. - Others as approved by Hubble Network. ### Embargo Policy Hubble Network will review reported vulnerabilities and determine if it needs to be embargoed based on: - Severity of the issue. - Exploitability of the issue. Security-sensitive vulnerabilities will be made public after an embargo period of at most 90 days, allowing: - **30 days** for Hubble Network to fix the issue. - **60 days** for external parties to apply and distribute fixes. ## Fix Recommendations Fixes to the code shall be made through pull requests (PRs) in the Hubble Network GitHub repository and they will: - Avoid revealing sensitive details about the vulnerability. - Avoid referencing advisory information in PR descriptions. ## Vulnerability Notification Each Hubble Network release will include a report of vulnerabilities fixed in that release. After the embargo period, the vulnerabilities page will be updated with additional details, giving credit to reporters unless anonymity is requested. When issues are triaged, Hubble Network will inform users of: - The Hubble Network Security Advisory link. - The area involved. - The severity of the issue. After a PR fixing the issue is merged, customers will also be informed of: - The association between the advisory and the PR. - Backport plans within Hubble Network. ## Backporting Security Vulnerabilities Each security issue fixed in Hubble Network will be backported to **the two (2) most recent releases.**