Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

SecurityDb Class Reference
Public Types | Public Member Functions

SecurityDb Class Reference

SecurityDb holds the state for active connections and bonded devices. More...

#include <SecurityDb.h>

Inherited by FileSecurityDb, and MemorySecurityDb.

Public Types

typedef void * entry_handle_t
 Opaque type representing a handle to a database entry.

Public Member Functions

virtual
SecurityDistributionFlags_t * 		get_distribution_flags (entry_handle_t db_handle)=0
 Return immediately security flags associated to a db entry.
virtual void set_distribution_flags (entry_handle_t db_handle, const SecurityDistributionFlags_t &new_flags)
 Set the distribution flags of a DB entry.
virtual void get_entry_local_keys (SecurityEntryKeysDbCb_t cb, entry_handle_t db_handle, const ediv_t &ediv, const rand_t &rand)
 Retrieve stored LTK based on passed in EDIV and RAND values.
virtual void get_entry_local_keys (SecurityEntryKeysDbCb_t cb, entry_handle_t db_handle)
 Retrieve stored LTK generated during secure connections pairing.
virtual void set_entry_local_ltk (entry_handle_t db_handle, const ltk_t &ltk)=0
 Save new local LTK for a connection.
virtual void set_entry_local_ediv_rand (entry_handle_t db_handle, const ediv_t &ediv, const rand_t &rand)=0
 Update EDIV and RAND used to identify the LTK.
virtual void get_entry_peer_csrk (SecurityEntrySigningDbCb_t cb, entry_handle_t db_handle)
 Return asynchronously the peer signing key through a callback so that signed packets can be verified.
virtual void get_entry_peer_keys (SecurityEntryKeysDbCb_t cb, entry_handle_t db_handle)
 Return asynchronously the peer encryption key through a callback so that encryption can be enabled.
virtual void set_entry_peer_ltk (entry_handle_t db_handle, const ltk_t &ltk)=0
 Save new LTK received from the peer.
virtual void set_entry_peer_ediv_rand (entry_handle_t db_handle, const ediv_t &ediv, const rand_t &rand)=0
 Update EDIV and RAND used to identify the LTK sent by the peer.
virtual void set_entry_peer_irk (entry_handle_t db_handle, const irk_t &irk)=0
 Update IRK for this connection.
virtual void set_entry_peer_bdaddr (entry_handle_t db_handle, bool address_is_public, const address_t &peer_address)=0
 Update the identity address of the peer.
virtual void get_entry_identity (SecurityEntryIdentityDbCb_t cb, entry_handle_t db_handle)
 Retrieve stored identity address and IRK.
virtual void get_identity_list (IdentitylistDbCb_t cb, Span< SecurityEntryIdentity_t > &identity_list)
 Asynchronously return the identity list stored in NVM through a callback.
virtual void set_entry_peer_csrk (entry_handle_t db_handle, const csrk_t &csrk)=0
 Update peer signing key.
virtual void set_entry_peer_sign_counter (entry_handle_t db_handle, sign_count_t sign_counter)=0
 Update peer signing counter.
virtual const csrk_t * get_local_csrk ()
 Return local signing key used for signing packets.
virtual sign_count_t get_local_sign_counter ()
 Return local signing counter.
virtual void set_local_csrk (const csrk_t &csrk)
 Update local signing key.
virtual void set_local_sign_counter (sign_count_t sign_counter)
 Update local signing counter.
virtual entry_handle_t open_entry (peer_address_type_t peer_address_type, const address_t &peer_address)
 Open a database entry.
virtual entry_handle_t find_entry_by_peer_address (peer_address_type_t peer_address_type, const address_t &peer_address)
 Find a database entry based on peer address.
virtual void close_entry (entry_handle_t db_handle)
 Close a connection entry.
virtual void remove_entry (peer_address_type_t peer_address_type, const address_t &peer_address)
 Remove entry for this peer from NVM.
virtual void clear_entries ()
 Remove all entries from the security DB.
virtual void get_whitelist (WhitelistDbCb_t cb,::Gap::Whitelist_t *whitelist)
 Asynchronously return the whitelist stored in NVM through a callback.
virtual void generate_whitelist_from_bond_table (WhitelistDbCb_t cb,::Gap::Whitelist_t *whitelist)
 Asynchronously return a whitelist through a callback, generated from the bond table.
virtual void set_whitelist (const ::Gap::Whitelist_t &whitelist)
 Update the whitelist stored in NVM by replacing it with new one.
virtual void add_whitelist_entry (const address_t &address)
 Add a new entry to the whitelist in the NVM.
virtual void remove_whitelist_entry (const address_t &address)
 Remove whitelist entry from NVM.
virtual void clear_whitelist ()
 Remove all whitelist entries stored in the NVM.
virtual void restore ()
 Read values from storage.
virtual void sync (entry_handle_t db_handle)
 Flush all values which might be stored in memory into NVM.
virtual void set_restore (bool reload)
 Toggle whether values should be preserved across resets.

Detailed Description

SecurityDb holds the state for active connections and bonded devices.

Keys can be stored in NVM and are returned via callbacks. SecurityDb is responsible for serialising any requests and keeping the store in a consistent state. Active connections state must be returned immediately.

Definition at line 109 of file SecurityDb.h.

Member Typedef Documentation

typedef void* entry_handle_t

Opaque type representing a handle to a database entry.

Definition at line 114 of file SecurityDb.h.

Member Function Documentation

virtual void add_whitelist_entry ( const address_t &  address ) [virtual]

Add a new entry to the whitelist in the NVM.

Parameters:
[in]addressnew whitelist entry

Definition at line 630 of file SecurityDb.h.

virtual void clear_entries (  ) [virtual]

Remove all entries from the security DB.

Definition at line 551 of file SecurityDb.h.

virtual void clear_whitelist (  ) [virtual]

Remove all whitelist entries stored in the NVM.

Definition at line 642 of file SecurityDb.h.

virtual void close_entry ( entry_handle_t  db_handle ) [virtual]

Close a connection entry.

Parameters:
[in]db_handlethis handle will be freed up from the security db.

Definition at line 521 of file SecurityDb.h.

virtual entry_handle_t find_entry_by_peer_address ( peer_address_type_t  peer_address_type,
const address_t &  peer_address 
) [virtual]

Find a database entry based on peer address.

Parameters:
[in]peer_address_typetype of address
[in]peer_addressthis address will be used to locate an existing entry.
Returns:
A handle to the entry.

Definition at line 475 of file SecurityDb.h.

virtual void generate_whitelist_from_bond_table ( WhitelistDbCb_t  cb,
::Gap::Whitelist_t *  whitelist 
) [virtual]

Asynchronously return a whitelist through a callback, generated from the bond table.

Parameters:
[in]cbcallback that will receive the whitelist
[in]whitelistpreallocated whitelist that will be filled in

Definition at line 583 of file SecurityDb.h.

virtual SecurityDistributionFlags_t* get_distribution_flags ( entry_handle_t  db_handle ) [pure virtual]

Return immediately security flags associated to a db entry.

Parameters:
[in]db_handleEntry of the database queried.
Returns:
pointer to the flags or NULL if the entry do not have any associated flags.

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void get_entry_identity ( SecurityEntryIdentityDbCb_t  cb,
entry_handle_t  db_handle 
) [virtual]

Retrieve stored identity address and IRK.

Parameters:
[in]cbcallback that will receive the SecurityEntryIdentity_t struct
[in]db_handlehandle of the entry being queried.

Definition at line 316 of file SecurityDb.h.

virtual void get_entry_local_keys ( SecurityEntryKeysDbCb_t  cb,
entry_handle_t  db_handle 
) [virtual]

Retrieve stored LTK generated during secure connections pairing.

Parameters:
[in]cbcallback that will receive the LTK struct
[in]db_handlehandle of the entry being queried.

Definition at line 190 of file SecurityDb.h.

virtual void get_entry_local_keys ( SecurityEntryKeysDbCb_t  cb,
entry_handle_t  db_handle,
const ediv_t &  ediv,
const rand_t &  rand 
) [virtual]

Retrieve stored LTK based on passed in EDIV and RAND values.

Parameters:
[in]cbcallback that will receive the LTK struct
[in]db_handlehandle of the entry being queried.
[in]edivone of the values used to identify the LTK
[in]randone of the values used to identify the LTK

Definition at line 169 of file SecurityDb.h.

virtual void get_entry_peer_csrk ( SecurityEntrySigningDbCb_t  cb,
entry_handle_t  db_handle 
) [virtual]

Return asynchronously the peer signing key through a callback so that signed packets can be verified.

Parameters:
[in]cbcallback which will receive the key
[in]db_handlehandle of the entry being queried.

Definition at line 238 of file SecurityDb.h.

virtual void get_entry_peer_keys ( SecurityEntryKeysDbCb_t  cb,
entry_handle_t  db_handle 
) [virtual]

Return asynchronously the peer encryption key through a callback so that encryption can be enabled.

Parameters:
[in]cbcallback which will receive the key
[in]db_handlehandle of the entry being queried.

Definition at line 253 of file SecurityDb.h.

virtual void get_identity_list ( IdentitylistDbCb_t  cb,
Span< SecurityEntryIdentity_t > &  identity_list 
) [virtual]

Asynchronously return the identity list stored in NVM through a callback.

Function takes ownership of the memory. The identity list and the ownership will be returned in the callback.

Parameters:
[in]cbcallback that will receive the whitelist
[in]identity_listpreallocated identity_list that will be filled in.

Definition at line 341 of file SecurityDb.h.

virtual const csrk_t* get_local_csrk (  ) [virtual]

Return local signing key used for signing packets.

Returns:
pointer to local CSRK

Definition at line 393 of file SecurityDb.h.

virtual sign_count_t get_local_sign_counter (  ) [virtual]

Return local signing counter.

Returns:
signing counter

Definition at line 402 of file SecurityDb.h.

virtual void get_whitelist ( WhitelistDbCb_t  cb,
::Gap::Whitelist_t *  whitelist 
) [virtual]

Asynchronously return the whitelist stored in NVM through a callback.

Function takes ownership of the memory. The whitelist and the ownership will be returned in the callback.

Parameters:
[in]cbcallback that will receive the whitelist
[in]whitelistpreallocated whitelist that will be filled in

Definition at line 568 of file SecurityDb.h.

virtual entry_handle_t open_entry ( peer_address_type_t  peer_address_type,
const address_t &  peer_address 
) [virtual]

Open a database entry.

While this entry is opened; it can be queried and updated with the help of the database setter and getter functions.

Parameters:
[in]peer_address_typetype of address
[in]peer_addressthis address will be used to locate an existing entry.
Returns:
A handle to the entry.

Definition at line 442 of file SecurityDb.h.

virtual void remove_entry ( peer_address_type_t  peer_address_type,
const address_t &  peer_address 
) [virtual]

Remove entry for this peer from NVM.

Parameters:
[in]peer_address_typetype of address
[in]peer_addressthis address will be used to locate an existing entry.
Returns:
A handle to the entry.

Definition at line 538 of file SecurityDb.h.

virtual void remove_whitelist_entry ( const address_t &  address ) [virtual]

Remove whitelist entry from NVM.

Parameters:
[in]addressentry to be removed

Definition at line 637 of file SecurityDb.h.

virtual void restore (  ) [virtual]

Read values from storage.

Reimplemented in FileSecurityDb.

Definition at line 649 of file SecurityDb.h.

virtual void set_distribution_flags ( entry_handle_t  db_handle,
const SecurityDistributionFlags_t &  new_flags 
) [virtual]

Set the distribution flags of a DB entry.

Parameters:
[in]db_handleEntry of the database that will store the flags.
[in]flagsDistribution flags to store in db_handle.

Definition at line 149 of file SecurityDb.h.

virtual void set_entry_local_ediv_rand ( entry_handle_t  db_handle,
const ediv_t &  ediv,
const rand_t &  rand 
) [pure virtual]

Update EDIV and RAND used to identify the LTK.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]edivnew EDIV value
[in]randnew RAND value

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_local_ltk ( entry_handle_t  db_handle,
const ltk_t &  ltk 
) [pure virtual]

Save new local LTK for a connection.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]ltkthe new LTK, if the device is slave, this is the LTK that will be used when link is encrypted

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_peer_bdaddr ( entry_handle_t  db_handle,
bool  address_is_public,
const address_t &  peer_address 
) [pure virtual]

Update the identity address of the peer.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]address_is_publicis the identity address public or private
[in]peer_addressthe new address

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_peer_csrk ( entry_handle_t  db_handle,
const csrk_t &  csrk 
) [pure virtual]

Update peer signing key.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]csrknew CSRK value

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_peer_ediv_rand ( entry_handle_t  db_handle,
const ediv_t &  ediv,
const rand_t &  rand 
) [pure virtual]

Update EDIV and RAND used to identify the LTK sent by the peer.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]edivnew EDIV value
[in]randnew RAND value

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_peer_irk ( entry_handle_t  db_handle,
const irk_t &  irk 
) [pure virtual]

Update IRK for this connection.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]irknew IRK value

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_peer_ltk ( entry_handle_t  db_handle,
const ltk_t &  ltk 
) [pure virtual]

Save new LTK received from the peer.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]ltkthe new LTK, if the peer device is slave, this is the LTK that will be used when link is encrypted

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_entry_peer_sign_counter ( entry_handle_t  db_handle,
sign_count_t  sign_counter 
) [pure virtual]

Update peer signing counter.

Parameters:
[in]db_handlehandle of the entry being updated.
[in]sign_counternew signing counter value

Implemented in FileSecurityDb, and MemorySecurityDb.

virtual void set_local_csrk ( const csrk_t &  csrk ) [virtual]

Update local signing key.

Parameters:
[in]csrknew CSRK value

Definition at line 411 of file SecurityDb.h.

virtual void set_local_sign_counter ( sign_count_t  sign_counter ) [virtual]

Update local signing counter.

Parameters:
[in]sign_counternew signing counter value

Definition at line 422 of file SecurityDb.h.

virtual void set_restore ( bool  reload ) [virtual]

Toggle whether values should be preserved across resets.

Parameters:
[in]reloadif true values will be preserved across resets.

Reimplemented in FileSecurityDb.

Definition at line 661 of file SecurityDb.h.

virtual void set_whitelist ( const ::Gap::Whitelist_t &  whitelist ) [virtual]

Update the whitelist stored in NVM by replacing it with new one.

Parameters:
[in]whitelist

Definition at line 623 of file SecurityDb.h.

virtual void sync ( entry_handle_t  db_handle ) [virtual]

Flush all values which might be stored in memory into NVM.

Reimplemented in FileSecurityDb.

Definition at line 654 of file SecurityDb.h.

Generated on Tue Jul 12 2022 13:55:41 by  doxygen 1.7.2