Storage for SMP keys including the required connection parameter. More...

#include <SMPKeyBin.hpp>

Collaboration diagram for direct_bt::SMPKeyBin:

Public Member Functions
	SMPKeyBin (const BDAddressAndType &addrAndType_, const BTSecurityLevel sec_level_, const SMPIOCapability io_cap_)

	SMPKeyBin ()

constexpr bool	isVersionValid () const noexcept

constexpr uint16_t	getVersion () const noexcept

constexpr bool	isSizeValid () const noexcept

constexpr uint16_t	getSize () const noexcept

constexpr uint64_t	getCreationTime () const noexcept
	Returns the creation timestamp in seconds since Unix epoch. More...

constexpr const BDAddressAndType &	getAddrAndType () const noexcept

constexpr BTSecurityLevel	getSecLevel () const noexcept

constexpr SMPIOCapability	getIOCap () const noexcept

constexpr bool	hasLTKInit () const noexcept

constexpr bool	hasCSRKInit () const noexcept

constexpr const SMPLongTermKeyInfo &	getLTKInit () const noexcept

constexpr const SMPSignatureResolvingKeyInfo &	getCSRKInit () const noexcept

void	setLTKInit (const SMPLongTermKeyInfo &v) noexcept

void	setCSRKInit (const SMPSignatureResolvingKeyInfo &v) noexcept

constexpr bool	hasLTKResp () const noexcept

constexpr bool	hasCSRKResp () const noexcept

constexpr const SMPLongTermKeyInfo &	getLTKResp () const noexcept

constexpr const SMPSignatureResolvingKeyInfo &	getCSRKResp () const noexcept

void	setLTKResp (const SMPLongTermKeyInfo &v) noexcept

void	setCSRKResp (const SMPSignatureResolvingKeyInfo &v) noexcept

void	setVerbose (bool v) noexcept

constexpr bool	isValid () const noexcept
	Returns `true` if. More...

std::string	toString () const noexcept

std::string	getFileBasename () const noexcept
	Returns the base filename, see SMPKeyBin API doc for naming scheme. More...

bool	write (const std::string &fname, const bool overwrite) const noexcept

bool	read (const std::string &fname)

HCIStatusCode	apply (BTDevice &device) const noexcept
	If this instance isValid() and initiator or responder LTK available, i.e. More...

Static Public Member Functions
static SMPKeyBin	create (const BTDevice &device)
	Create a new SMPKeyBin instance based upon given BTDevice's BTSecurityLevel, SMPPairingState, PairingMode and LTK keys. More...

static bool	createAndWrite (const BTDevice &device, const std::string &path, const bool overwrite, const bool verbose_)
	Create a new SMPKeyBin instance on the fly based upon given BTDevice's BTSecurityLevel, SMPPairingState, PairingMode and LTK keys. More...

static SMPKeyBin	read (const std::string &fname, const bool verbose_)
	Create a new SMPKeyBin instance based upon stored file denoted by `fname`. More...

static HCIStatusCode	readAndApply (const std::string &path, BTDevice &device, const BTSecurityLevel minSecLevel, const bool verbose_)
	Create a new SMPKeyBin instance on the fly based upon stored file denoted by `path` and BTDevice::getAddressAndType(), i.e. More...

static std::string	getFileBasename (const BDAddressAndType &addrAndType_)
	Returns the base filename, see SMPKeyBin API doc for naming scheme. More...

static std::string	getFilename (const std::string &path, const BDAddressAndType &addrAndType_)

static bool	remove (const std::string &path, const BDAddressAndType &addrAndType_)

Static Public Attributes
constexpr static const uint16_t	VERSION = (uint16_t)0b0101010101010101U + (uint16_t)2U

Detailed Description

Storage for SMP keys including the required connection parameter.

Storage for a device's BDAddressAndType, its security connection setup BTSecurityLevel + SMPIOCapability and optionally the initiator and responder SMPLongTermKeyInfo (LTK) and SMPSignatureResolvingKeyInfo (CSRK) within one file.

Since the SMPLongTermKeyInfo (LTK) and SMPSignatureResolvingKeyInfo (CSRK) can be optionally set due to their availability per initiator and responder, implementation supports mixed mode for certain devices. E.g. LTK responder key only etc.

Filename as retrieved by SMPKeyBin::getFileBasename() has the following form bd_C0_26_DA_01_DA_B1_1-smpkey.bin:

'bd_'

denotes prefix
'C0_26_DA_01_DA_B1'

denotes the EUI48 address
'_1'

denotes the BDAddressType
'-smpkey.bin'

denotes the suffix

Definition at line 62 of file SMPKeyBin.hpp.

Constructor & Destructor Documentation

◆ SMPKeyBin() [1/2]

direct_bt::SMPKeyBin::SMPKeyBin	(	const BDAddressAndType &	addrAndType_,
		const BTSecurityLevel	sec_level_,
		const SMPIOCapability	io_cap_
	)

inline

Definition at line 199 of file SMPKeyBin.hpp.

◆ SMPKeyBin() [2/2]

direct_bt::SMPKeyBin::SMPKeyBin ( )

inline

Definition at line 209 of file SMPKeyBin.hpp.

Member Function Documentation

◆ apply()

HCIStatusCode SMPKeyBin::apply ( BTDevice & device ) const

noexcept

If this instance isValid() and initiator or responder LTK available, i.e.

hasLTKInit() or hasLTKResp(), the following procedure will be applied to the given BTDevice:

If BTSecurityLevel is BTSecurityLevel::NONE
- Setting security to BTSecurityLevel::NONE and SMPIOCapability::NO_INPUT_NO_OUTPUT via BTDevice::setConnSecurity()
else if BTSecurityLevel > BTSecurityLevel::NONE
- Setting security to BTSecurityLevel::ENC_ONLY and SMPIOCapability::NO_INPUT_NO_OUTPUT via BTDevice::setConnSecurity()
- Setting initiator LTK from getLTKInit() via BTDevice::setLongTermKeyInfo(), if available
- Setting responder LTK from getLTKResp() via BTDevice::setLongTermKeyInfo(), if available

If all three operations succeed, HCIStatusCode::SUCCESS will be returned, otherwise the appropriate status code below.

BTSecurityLevel::ENC_ONLY is set to avoid a new SMP PairingMode negotiation, which is undesired as this instances' stored LTK shall be used for PairingMode::PRE_PAIRED.

Method may fail for any of the following reasons:

Reason	HCIStatusCode
! isValid()	HCIStatusCode::INVALID_PARAMS
! hasLTKInit() && ! hasLTKResp()	HCIStatusCode::INVALID_PARAMS
BTDevice::isValid() == false	HCIStatusCode::INVALID_PARAMS
BTDevice has already being connected	HCIStatusCode::CONNECTION_ALREADY_EXISTS
BTDevice::connectLE() or BTDevice::connectBREDR() called	HCIStatusCode::CONNECTION_ALREADY_EXISTS
BTDevice::setLongTermKeyInfo() failed	HCIStatusCode from BT adapter

On failure and after BTDevice::setConnSecurity() has been performed, the BTSecurityLevel and SMPIOCapability pre-connect values have been written and must be set by the caller again.

Parameters

device the BTDevice for which this instances' LTK shall be applied

See also: isValid(); hasLTKInit(); hasLTKResp(); getLTKInit(); getLTKResp(); BTSecurityLevel; SMPIOCapability; BTDevice::isValid(); BTDevice::setConnSecurity(); BTDevice::setLongTermKeyInfo()

Definition at line 364 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create()

SMPKeyBin SMPKeyBin::create ( const BTDevice & device )

static

Create a new SMPKeyBin instance based upon given BTDevice's BTSecurityLevel, SMPPairingState, PairingMode and LTK keys.

Returned SMPKeyBin shall be tested if valid via SMPKeyBin::isValid(), whether the retrieved data from BTDevice is consistent and hence having BTDevice is a well connected state.

Parameters

device the BTDevice from which all required data is derived

Returns: a valid SMPKeyBin instance if properly connected, otherwise an invalid instance.

See also: BTDevice; isValid()

Definition at line 46 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ createAndWrite()

bool SMPKeyBin::createAndWrite	(	const BTDevice &	device,
		const std::string &	path,
		const bool	overwrite,
		const bool	verbose_
	)

static

Create a new SMPKeyBin instance on the fly based upon given BTDevice's BTSecurityLevel, SMPPairingState, PairingMode and LTK keys.

If valid, instance is stored to a file denoted by path and BTDevice::getAddressAndType().

Method returns false if resulting SMPKeyBin is not SMPKeyBin::isValid().

Otherwise, method returns the SMPKeyBin::write() result.

Parameters

device	the BTDevice from which all required data is derived
path	the path for the stored SMPKeyBin file.
overwrite	if `true` and file already exists, delete file first. If `false` and file exists, return `false` w/o writing.
verbose_	set to true to have detailed write processing logged to stderr, otherwise false

Returns: true if file has been successfully written, otherwise false.

See also: BTDevice; Create(); write(); isValid()

Examples: dbt_scanner10.cpp.

Definition at line 79 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getAddrAndType()

constexpr const BDAddressAndType& direct_bt::SMPKeyBin::getAddrAndType ( ) const

inlineconstexprnoexcept

Definition at line 227 of file SMPKeyBin.hpp.

◆ getCreationTime()

constexpr uint64_t direct_bt::SMPKeyBin::getCreationTime ( ) const

inlineconstexprnoexcept

Returns the creation timestamp in seconds since Unix epoch.

Definition at line 225 of file SMPKeyBin.hpp.

◆ getCSRKInit()

constexpr const SMPSignatureResolvingKeyInfo& direct_bt::SMPKeyBin::getCSRKInit ( ) const

inlineconstexprnoexcept

Definition at line 234 of file SMPKeyBin.hpp.

◆ getCSRKResp()

constexpr const SMPSignatureResolvingKeyInfo& direct_bt::SMPKeyBin::getCSRKResp ( ) const

inlineconstexprnoexcept

Definition at line 249 of file SMPKeyBin.hpp.

◆ getFileBasename() [1/2]

std::string SMPKeyBin::getFileBasename ( ) const

noexcept

Returns the base filename, see SMPKeyBin API doc for naming scheme.

Definition at line 169 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getFileBasename() [2/2]

std::string SMPKeyBin::getFileBasename ( const BDAddressAndType & addrAndType_ )

static

Returns the base filename, see SMPKeyBin API doc for naming scheme.

Definition at line 174 of file SMPKeyBin.cpp.

Here is the call graph for this function:

◆ getFilename()

static std::string direct_bt::SMPKeyBin::getFilename	(	const std::string &	path,
		const BDAddressAndType &	addrAndType_
	)

inlinestatic

Examples: dbt_scanner10.cpp.

Definition at line 292 of file SMPKeyBin.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getIOCap()

constexpr SMPIOCapability direct_bt::SMPKeyBin::getIOCap ( ) const

inlineconstexprnoexcept

Definition at line 229 of file SMPKeyBin.hpp.

◆ getLTKInit()

constexpr const SMPLongTermKeyInfo& direct_bt::SMPKeyBin::getLTKInit ( ) const

inlineconstexprnoexcept

Definition at line 233 of file SMPKeyBin.hpp.

◆ getLTKResp()

constexpr const SMPLongTermKeyInfo& direct_bt::SMPKeyBin::getLTKResp ( ) const

inlineconstexprnoexcept

Definition at line 248 of file SMPKeyBin.hpp.

◆ getSecLevel()

constexpr BTSecurityLevel direct_bt::SMPKeyBin::getSecLevel ( ) const

inlineconstexprnoexcept

Definition at line 228 of file SMPKeyBin.hpp.

◆ getSize()

constexpr uint16_t direct_bt::SMPKeyBin::getSize ( ) const

inlineconstexprnoexcept

Definition at line 222 of file SMPKeyBin.hpp.

◆ getVersion()

constexpr uint16_t direct_bt::SMPKeyBin::getVersion ( ) const

inlineconstexprnoexcept

Definition at line 219 of file SMPKeyBin.hpp.

◆ hasCSRKInit()

constexpr bool direct_bt::SMPKeyBin::hasCSRKInit ( ) const

inlineconstexprnoexcept

Definition at line 232 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ hasCSRKResp()

constexpr bool direct_bt::SMPKeyBin::hasCSRKResp ( ) const

inlineconstexprnoexcept

Definition at line 247 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ hasLTKInit()

constexpr bool direct_bt::SMPKeyBin::hasLTKInit ( ) const

inlineconstexprnoexcept

Definition at line 231 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ hasLTKResp()

constexpr bool direct_bt::SMPKeyBin::hasLTKResp ( ) const

inlineconstexprnoexcept

Definition at line 246 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ isSizeValid()

constexpr bool direct_bt::SMPKeyBin::isSizeValid ( ) const

inlineconstexprnoexcept

Definition at line 221 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ isValid()

constexpr bool direct_bt::SMPKeyBin::isValid ( ) const

inlineconstexprnoexcept

Returns true if.

isVersionValid() && isSizeValid() && not BTSecurityLevel::UNSET && not SMPIOCapability::UNSET && has valid LTK, if at all

Definition at line 272 of file SMPKeyBin.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isVersionValid()

constexpr bool direct_bt::SMPKeyBin::isVersionValid ( ) const

inlineconstexprnoexcept

Definition at line 218 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ read() [1/2]

bool SMPKeyBin::read ( const std::string & fname )

Definition at line 260 of file SMPKeyBin.cpp.

Here is the call graph for this function:

◆ read() [2/2]

static SMPKeyBin direct_bt::SMPKeyBin::read	(	const std::string &	fname,
		const bool	verbose_
	)

inlinestatic

Create a new SMPKeyBin instance based upon stored file denoted by fname.

Returned SMPKeyBin shall be tested if valid via SMPKeyBin::isValid(), whether the read() operation was successful and data is consistent.

If file is invalid, it is removed.

Parameters

fname	full path of the stored SMPKeyBin file.
verbose_	set to true to have detailed read processing logged to stderr, otherwise false

Returns: valid SMPKeyBin instance if file exist and read successfully, otherwise invalid SMPKeyBin instance.

See also: isValid(); read()

Definition at line 169 of file SMPKeyBin.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readAndApply()

HCIStatusCode SMPKeyBin::readAndApply	(	const std::string &	path,
		BTDevice &	device,
		const BTSecurityLevel	minSecLevel,
		const bool	verbose_
	)

static

Create a new SMPKeyBin instance on the fly based upon stored file denoted by path and BTDevice::getAddressAndType(), i.e.

path/ + getFileBasename().

Method returns HCIStatusCode::INVALID_PARAMS if resulting SMPKeyBin is not SMPKeyBin::isValid().

Otherwise, method returns the HCIStatusCode of SMPKeyBin::apply().

If key file is invalid or key could not be applied, i.e. not returning HCIStatusCode::SUCCESS, it is removed.

Parameters

path	the path of the stored SMPKeyBin file.
device	the BTDevice for which address the stored SMPKeyBin file will be read and applied to
minSecLevel	minimum BTSecurityLevel the read SMPKeyBin::sec_level must be compliant to. If SMPKeyBin::sec_level < minSecLevel method removes the key file and returns HCIStatusCode::ENCRYPTION_MODE_NOT_ACCEPTED.
verbose_	set to true to have detailed read processing logged to stderr, otherwise false

Returns: HCIStatusCode::SUCCESS or error code for failure

See also: Read(); isValid(); read(); apply()

Examples: dbt_scanner10.cpp.

Definition at line 92 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ remove()

static bool direct_bt::SMPKeyBin::remove	(	const std::string &	path,
		const BDAddressAndType &	addrAndType_
	)

inlinestatic

Examples: dbt_scanner10.cpp.

Definition at line 296 of file SMPKeyBin.hpp.

Here is the call graph for this function:

◆ setCSRKInit()

void direct_bt::SMPKeyBin::setCSRKInit ( const SMPSignatureResolvingKeyInfo & v )

inlinenoexcept

Definition at line 240 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ setCSRKResp()

void direct_bt::SMPKeyBin::setCSRKResp ( const SMPSignatureResolvingKeyInfo & v )

inlinenoexcept

Definition at line 255 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ setLTKInit()

void direct_bt::SMPKeyBin::setLTKInit ( const SMPLongTermKeyInfo & v )

inlinenoexcept

Definition at line 235 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ setLTKResp()

void direct_bt::SMPKeyBin::setLTKResp ( const SMPLongTermKeyInfo & v )

inlinenoexcept

Definition at line 250 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ setVerbose()

void direct_bt::SMPKeyBin::setVerbose ( bool v )

inlinenoexcept

Definition at line 261 of file SMPKeyBin.hpp.

Here is the caller graph for this function:

◆ toString()

std::string SMPKeyBin::toString ( ) const

noexcept

Definition at line 120 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write()

bool SMPKeyBin::write	(	const std::string &	fname,
		const bool	overwrite
	)		const

noexcept

Definition at line 189 of file SMPKeyBin.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ VERSION

constexpr static const uint16_t direct_bt::SMPKeyBin::VERSION = (uint16_t)0b0101010101010101U + (uint16_t)2U

staticconstexpr

Definition at line 64 of file SMPKeyBin.hpp.

The documentation for this class was generated from the following files:

/usr/local/projects/direct_bt/api/direct_bt/SMPKeyBin.hpp
/usr/local/projects/direct_bt/src/direct_bt/SMPKeyBin.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SMPKeyBin() [1/2]

◆ SMPKeyBin() [2/2]

Member Function Documentation

◆ apply()

◆ create()

◆ createAndWrite()

◆ getAddrAndType()

◆ getCreationTime()

◆ getCSRKInit()

◆ getCSRKResp()

◆ getFileBasename() [1/2]

◆ getFileBasename() [2/2]

◆ getFilename()

◆ getIOCap()

◆ getLTKInit()

◆ getLTKResp()

◆ getSecLevel()

◆ getSize()

◆ getVersion()

◆ hasCSRKInit()

◆ hasCSRKResp()

◆ hasLTKInit()

◆ hasLTKResp()

◆ isSizeValid()

◆ isValid()

◆ isVersionValid()

◆ read() [1/2]

◆ read() [2/2]

◆ readAndApply()

◆ remove()

◆ setCSRKInit()

◆ setCSRKResp()

◆ setLTKInit()

◆ setLTKResp()

◆ setVerbose()

◆ toString()

◆ write()

Member Data Documentation

◆ VERSION