Core API

The core API provides the initialization, time, and key-management functions shared by every Hubble Device SDK network.

group Hubble Device SDK APIs

Hubble Device SDK APIs.

Functions

int hubble_init(uint64_t initial_time, const void *key)

Initializes the Hubble Device SDK.

Calling this function is essential before using any other SDK APIs.

The interpretation of the initial_time parameter depends on the configured counter source:

Unix time mode (CONFIG_HUBBLE_COUNTER_SOURCE_UNIX_TIME):

  • initial_time is the time in milliseconds since Unix epoch

  • Value of 0 is invalid and will return an error

  • Time can be updated later via hubble_time_set()

Device uptime mode (CONFIG_HUBBLE_COUNTER_SOURCE_DEVICE_UPTIME):

  • initial_time is the initial counter value

  • Value of 0 starts the counter at epoch 0 (valid)

  • The counter increments based on uptime from this initial value

  • Useful for resuming from a known state after reboot

// Unix time mode example
uint64_t unix_time_ms = 1705881600000; // Current Unix Epoch time
int ret = hubble_init(unix_time_ms, master_key);

// Device uptime mode example (start at 0)
int ret = hubble_init(0, master_key);

// Device uptime mode example (resume from saved counter)
uint64_t saved_counter = load_from_flash();
int ret = hubble_init(saved_counter, master_key);
Parameters:

  • initial_time – For Unix time mode: Unix time in milliseconds since epoch. For device uptime mode: Initial counter value (0 = start at 0).

  • key – An opaque pointer to the master key buffer. The SDK stores this pointer directly and does not copy the key data. The caller must ensure the buffer remains valid for the lifetime of SDK usage (do not use stack or temporary buffers). The key size must match CONFIG_HUBBLE_NETWORK_KEY_256 or CONFIG_HUBBLE_NETWORK_KEY_128. If NULL, must be set with hubble_key_set before getting advertisements.

Returns:

  • 0 on success.

  • Non-zero on failure.

int hubble_time_set(uint64_t unix_time)

Sets the current Unix time in the Hubble Device SDK.

Parameters:

unix_time – The Unix Epoch time in milliseconds since the Unix epoch (January 1, 1970).

Returns:

  • 0 on success.

  • Non-zero on failure.

uint64_t hubble_time_get(void)

Gets the current time.

Gets the time in milliseconds since the Unix epoch (January 1, 1970).

Returns:

  • 0 if time is not set.

  • current time since the Unix epoch.

int hubble_key_set(const void *key)

Sets the encryption key for advertisement data creation.

Parameters:

key – An opaque pointer to the master key buffer. The SDK stores this pointer directly and does not copy the key data. The caller must ensure the buffer remains valid for the lifetime of SDK usage. The key size must match CONFIG_HUBBLE_NETWORK_KEY_256 or CONFIG_HUBBLE_NETWORK_KEY_128.

Returns:

  • 0 on success.

  • Non-zero on failure.

int hubble_counter_get(uint32_t *counter)

Get the current time counter value.

Returns the time counter based on the configured counter source:

  • Device uptime: Uses uptime-derived counter with initial offset, wrapping at HUBBLE_EID_POOL_SIZE (128) to produce values in [0, pool_size-1]

  • Unix time: Uses Unix time divided by rotation period (no wrapping)

Parameters:

counter – Pointer to store the time counter value

Returns:

0 on success, negative error code on failure (Unix time mode only, if time not set)

group Hubble Network Crypto APIs

Hubble Device SDK Crypto APIs.

Cryptographic functions that need to be implemented by a crypto provider.

Functions

void hubble_crypto_zeroize(void *buf, size_t len)

Securely clear out a memory region.

This function is used to securely overwrite a memory buffer with zeros, ensuring that sensitive data is erased.

Parameters:

  • buf – Pointer to the input data.

  • len – Length of the input data.

int hubble_crypto_init(void)

Cryptographic initialization.

This function must be called before any other cryptographic function otherwise the behavior is undefined.

Returns:

0 on success, non-zero on error.

int hubble_crypto_aes_ctr(const uint8_t key[CONFIG_HUBBLE_KEY_SIZE], uint8_t nonce_counter[HUBBLE_NONCE_BUFFER_SIZE], const uint8_t *data, size_t len, uint8_t *output)

Perform AES encryption in Counter (CTR) mode.

Parameters:

  • key – A pointer to the encryption key (size: CONFIG_HUBBLE_KEY_SIZE).

  • nonce_counter – A pointer to the nonce and counter buffer (size: HUBBLE_NONCE_BUFFER_SIZE).

  • data – A pointer to the input data buffer to be encrypted.

  • len – The length of the input data in bytes.

  • output – A pointer to the output buffer where the encrypted data will be stored. It must be at least the size of the input data in bytes.

Returns:

Returns 0 on success, or a non-zero error code on failure.

int hubble_crypto_cmac(const uint8_t key[CONFIG_HUBBLE_KEY_SIZE], const uint8_t *data, size_t len, uint8_t output[HUBBLE_AES_BLOCK_SIZE])

Computes the Cipher-based Message Authentication Code (CMAC).

Parameters:

  • key – The secret key used for CMAC calculation. The size of the key is defined by CONFIG_HUBBLE_KEY_SIZE.

  • data – Pointer to the input data for which the CMAC is calculated.

  • len – The length of the input data in bytes.

  • output – Pointer to the buffer where the CMAC (message authentication code) will be stored. This buffer must be large enough to hold the CMAC value (typically the size of the AES block, 16 bytes).

Returns:

0 on success, non-zero on error.