Bluetooth pairing and settings shared between the recovery (PRF) and normal firmware. More...

Modules
	Shared PRF storage debug
	Shell dump of the shared PRF storage.

	Legacy shared PRF storage layout
	Former single-struct layout of the shared PRF storage, not used by the firmware.

	Shared PRF storage layout
	On-flash layout of shared PRF storage entries.

Functions
bool	shared_prf_storage_get_local_device_name (char *local_device_name_out, size_t max_size)
	Get the custom local device name.

void	shared_prf_storage_set_local_device_name (const char *local_device_name)
	Store the custom local device name.

bool	shared_prf_storage_get_root_key (enum pbl_bt_sm_root_key_type key_type, struct pbl_bt_sm_key *key_out)
	Get a BLE root key.

void	shared_prf_storage_set_root_keys (struct pbl_bt_sm_key *keys_in)
	Store the BLE root keys.

bool	shared_prf_storage_get_ble_pairing_data (struct pbl_bt_sm_pairing_info pairing_info_out, char name_out, bool requires_address_pinning_out, uint8_t flags)
	Get the BLE pairing.

void	shared_prf_storage_store_ble_pairing_data (const struct pbl_bt_sm_pairing_info pairing_info, const char name, bool requires_address_pinning, uint8_t flags)
	Store the BLE pairing, replacing the previous one.

void	shared_prf_storage_erase_ble_pairing_data (void)
	Erase the BLE pairing and its device name.

bool	shared_prf_storage_get_ble_pinned_address (struct pbl_bt_addr *address_out)
	Get the pinned BLE address.

void	shared_prf_storage_set_ble_pinned_address (const struct pbl_bt_addr *address)
	Store the pinned BLE address.

bool	shared_prf_storage_get_local_identity_address (struct pbl_bt_addr *address_out)
	Get the local identity address.

void	shared_prf_storage_set_local_identity_address (const struct pbl_bt_addr *address)
	Store the local identity address.

bool	shared_prf_storage_get_bt_classic_pairing_data (struct pbl_bt_addr addr_out, char device_name_out, struct pbl_bt_sm_key link_key_out, uint8_t platform_bits)
	Get a BT Classic pairing.

void	shared_prf_storage_store_bt_classic_pairing_data (struct pbl_bt_addr addr, const char device_name, struct pbl_bt_sm_key *link_key, uint8_t platform_bits)
	Store a BT Classic pairing.

void	shared_prf_storage_store_platform_bits (uint8_t platform_bits)
	Store the BT Classic remote platform bits.

void	shared_prf_storage_erase_bt_classic_pairing_data (void)
	Erase the BT Classic pairing.

bool	shared_prf_storage_get_getting_started_complete (void)
	Check whether onboarding (getting started) has been completed.

void	shared_prf_storage_set_getting_started_complete (bool set)
	Set whether onboarding (getting started) has been completed.

void	shared_prf_storage_wipe_all (void)
	Erase all shared data, for a factory reset.

void	shared_prf_storage_init (void)
	Initialize shared PRF storage.

Detailed Description

Bluetooth pairing and settings shared between the recovery (PRF) and normal firmware.

Data is kept in a dedicated flash region as a rolling list of 256-byte entries (see Shared PRF storage layout). Each field carries its own CRC; changing a field invalidates the current entry and rewrites the data into the next one, and the region is erased once it fills up. All functions are serialized by a mutex.

Function Documentation

◆ shared_prf_storage_erase_ble_pairing_data()

void shared_prf_storage_erase_ble_pairing_data ( void )

Erase the BLE pairing and its device name.

◆ shared_prf_storage_erase_bt_classic_pairing_data()

void shared_prf_storage_erase_bt_classic_pairing_data ( void )

Erase the BT Classic pairing.

BT Classic is not supported: asserts if called.

◆ shared_prf_storage_get_ble_pairing_data()

bool shared_prf_storage_get_ble_pairing_data	(	struct pbl_bt_sm_pairing_info *	pairing_info_out,
		char *	name_out,
		bool *	requires_address_pinning_out,
		uint8_t *	flags
	)

Get the BLE pairing.

Output parameters may be NULL and are only valid when true is returned.

Parameters

[out]	pairing_info_out	Pairing keys.
[out]	name_out	Buffer of `PBL_BT_DEVICE_NAME_BUFFER_SIZE` bytes for the remote device name, empty if none is stored.
[out]	requires_address_pinning_out	Whether the pairing requires address pinning.
[out]	flags	Pairing flags.

Returns: true if a pairing is stored.

◆ shared_prf_storage_get_ble_pinned_address()

bool shared_prf_storage_get_ble_pinned_address ( struct pbl_bt_addr * address_out )

Get the pinned BLE address.

Parameters

[out] address_out Address, may be NULL. Only valid when true is returned.

Returns: true if a pinned address is stored.

◆ shared_prf_storage_get_bt_classic_pairing_data()

bool shared_prf_storage_get_bt_classic_pairing_data	(	struct pbl_bt_addr *	addr_out,
		char *	device_name_out,
		struct pbl_bt_sm_key *	link_key_out,
		uint8_t *	platform_bits
	)

Get a BT Classic pairing.

BT Classic is not supported: asserts if called.

Parameters

[out]	addr_out	Remote address.
[out]	device_name_out	Remote device name.
[out]	link_key_out	Link key.
[out]	platform_bits	Remote platform bits.

Returns: Does not return.

◆ shared_prf_storage_get_getting_started_complete()

bool shared_prf_storage_get_getting_started_complete ( void )

Check whether onboarding (getting started) has been completed.

Returns: true if completed.

◆ shared_prf_storage_get_local_device_name()

bool shared_prf_storage_get_local_device_name	(	char *	local_device_name_out,
		size_t	max_size
	)

Get the custom local device name.

Parameters

[out]	local_device_name_out	Buffer for the name, may be NULL. Set to an empty string when no name is stored.
	max_size	Size of `local_device_name_out` in bytes.

Returns: true if a non-empty name is stored.

◆ shared_prf_storage_get_local_identity_address()

bool shared_prf_storage_get_local_identity_address ( struct pbl_bt_addr * address_out )

Get the local identity address.

Parameters

[out] address_out Address, may be NULL. Only valid when true is returned.

Returns: true if a local identity address is stored.

◆ shared_prf_storage_get_root_key()

bool shared_prf_storage_get_root_key	(	enum pbl_bt_sm_root_key_type	key_type,
		struct pbl_bt_sm_key *	key_out
	)

Get a BLE root key.

Parameters

	key_type	Encryption Root (ER) or Identity Root (IR) key.
[out]	key_out	Key, may be NULL.

Returns: true if a non-zero key is stored.

◆ shared_prf_storage_init()

void shared_prf_storage_init ( void )

Initialize shared PRF storage.

Finds the valid entry, and erases the region, keeping that entry, when more than 75% of the region is used so that later writes are unlikely to block on an erase.

◆ shared_prf_storage_set_ble_pinned_address()

void shared_prf_storage_set_ble_pinned_address ( const struct pbl_bt_addr * address )

Store the pinned BLE address.

Parameters

address Address, or NULL to erase it.

◆ shared_prf_storage_set_getting_started_complete()

void shared_prf_storage_set_getting_started_complete ( bool set )

Set whether onboarding (getting started) has been completed.

Parameters

set	true if completed.

◆ shared_prf_storage_set_local_device_name()

void shared_prf_storage_set_local_device_name ( const char * local_device_name )

Store the custom local device name.

Parameters

local_device_name Name to store, or NULL to erase it.

◆ shared_prf_storage_set_local_identity_address()

void shared_prf_storage_set_local_identity_address ( const struct pbl_bt_addr * address )

Store the local identity address.

Parameters

address Address, or NULL to erase it.

◆ shared_prf_storage_set_root_keys()

void shared_prf_storage_set_root_keys ( struct pbl_bt_sm_key * keys_in )

Store the BLE root keys.

Parameters

keys_in Array of PBL_BT_SM_ROOT_KEY_TYPE_NUM keys indexed by pbl_bt_sm_root_key_type, or NULL to store zeroed keys.

◆ shared_prf_storage_store_ble_pairing_data()

void shared_prf_storage_store_ble_pairing_data	(	const struct pbl_bt_sm_pairing_info *	pairing_info,
		const char *	name,
		bool	requires_address_pinning,
		uint8_t	flags
	)

Store the BLE pairing, replacing the previous one.

Empty pairing info is ignored.

Parameters

pairing_info	Pairing keys.
name	Remote device name, or NULL to keep the stored name.
requires_address_pinning	Whether the pairing requires address pinning.
flags	Pairing flags.

◆ shared_prf_storage_store_bt_classic_pairing_data()

void shared_prf_storage_store_bt_classic_pairing_data	(	struct pbl_bt_addr *	addr,
		const char *	device_name,
		struct pbl_bt_sm_key *	link_key,
		uint8_t	platform_bits
	)

Store a BT Classic pairing.

BT Classic is not supported: asserts if called.

Parameters

addr	Remote address.
device_name	Remote device name.
link_key	Link key.
platform_bits	Remote platform bits.

◆ shared_prf_storage_store_platform_bits()

void shared_prf_storage_store_platform_bits ( uint8_t platform_bits )

Store the BT Classic remote platform bits.

BT Classic is not supported: asserts if called.

Parameters

platform_bits Remote platform bits.

◆ shared_prf_storage_wipe_all()

void shared_prf_storage_wipe_all ( void )

Erase all shared data, for a factory reset.

Modules

Functions

Detailed Description

Function Documentation

◆ shared_prf_storage_erase_ble_pairing_data()

◆ shared_prf_storage_erase_bt_classic_pairing_data()

◆ shared_prf_storage_get_ble_pairing_data()

◆ shared_prf_storage_get_ble_pinned_address()

◆ shared_prf_storage_get_bt_classic_pairing_data()

◆ shared_prf_storage_get_getting_started_complete()

◆ shared_prf_storage_get_local_device_name()

◆ shared_prf_storage_get_local_identity_address()

◆ shared_prf_storage_get_root_key()

◆ shared_prf_storage_init()

◆ shared_prf_storage_set_ble_pinned_address()

◆ shared_prf_storage_set_getting_started_complete()

◆ shared_prf_storage_set_local_device_name()

◆ shared_prf_storage_set_local_identity_address()

◆ shared_prf_storage_set_root_keys()

◆ shared_prf_storage_store_ble_pairing_data()

◆ shared_prf_storage_store_bt_classic_pairing_data()

◆ shared_prf_storage_store_platform_bits()

◆ shared_prf_storage_wipe_all()