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

Collaboration diagram for org.direct_bt.SMPKeyBin:

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

	SMPKeyBin ()

final boolean	isVersionValid ()

final short	getVersion ()

final boolean	isSizeValid ()

final short	getSize ()

final long	getCreationTime ()
	Returns the creation timestamp in seconds since Unix epoch. More...

final BDAddressAndType	getAddrAndType ()

final BTSecurityLevel	getSecLevel ()

final SMPIOCapability	getIOCap ()

final boolean	hasLTKInit ()

final boolean	hasCSRKInit ()

final SMPLongTermKeyInfo	getLTKInit ()

final SMPSignatureResolvingKeyInfo	getCSRKInit ()

final void	setLTKInit (final SMPLongTermKeyInfo v)

final void	setCSRKInit (final SMPSignatureResolvingKeyInfo v)

final boolean	hasLTKResp ()

final boolean	hasCSRKResp ()

final SMPLongTermKeyInfo	getLTKResp ()

final SMPSignatureResolvingKeyInfo	getCSRKResp ()

final void	setLTKResp (final SMPLongTermKeyInfo v)

final void	setCSRKResp (final SMPSignatureResolvingKeyInfo v)

final void	setVerbose (final boolean v)

final boolean	isValid ()

final String	getFileBasename ()
	Returns the base filename, see SMPKeyBin API doc for naming scheme. More...

final String	toString ()

final boolean	write (final String fname, final boolean overwrite)

final boolean	read (final String fname)

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

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

static boolean	createAndWrite (final BTDevice device, final String path, final boolean overwrite, final boolean verbose_)
	Create a new SMPKeyBin instance on the fly based upon given BTDevice's BTSecurityLevel, SMPPairingState, PairingMode and LTK keys. More...

static SMPKeyBin	read (final String fname, final boolean verbose_)
	Create a new SMPKeyBin instance based upon stored file denoted by `fname`. More...

static HCIStatusCode	readAndApply (final String path, final BTDevice device, final BTSecurityLevel minSecLevel, final boolean verbose_)
	Create a new SMPKeyBin instance on the fly based upon stored file denoted by `path` and BTDevice#getAddressAndType(), i.e. More...

final static String	getFileBasename (final BDAddressAndType addrAndType_)
	Returns the base filename, see SMPKeyBin API doc for naming scheme. More...

final static String	getFilename (final String path, final BDAddressAndType addrAndType_)

final static boolean	remove (final String path, final BDAddressAndType addrAndType_)

Static Public Attributes
static final short	VERSION = (short)0b0101010101010101 + (short)2

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 LTK and CSRK within one file.

Since the LTK and 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 getFileBasename(BDAddressAndType) and 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 60 of file SMPKeyBin.java.

Constructor & Destructor Documentation

◆ SMPKeyBin() [1/2]

org.direct_bt.SMPKeyBin.SMPKeyBin	(	final BDAddressAndType	addrAndType_,
		final BTSecurityLevel	sec_level_,
		final SMPIOCapability	io_cap_
	)

Definition at line 262 of file SMPKeyBin.java.

Here is the call graph for this function:

◆ SMPKeyBin() [2/2]

org.direct_bt.SMPKeyBin.SMPKeyBin ( )

Definition at line 284 of file SMPKeyBin.java.

Here is the caller graph for this function:

Member Function Documentation

◆ apply()

final HCIStatusCode org.direct_bt.SMPKeyBin.apply ( final BTDevice device )

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 679 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create()

static SMPKeyBin org.direct_bt.SMPKeyBin.create ( final 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 127 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ createAndWrite()

static boolean org.direct_bt.SMPKeyBin.createAndWrite	(	final BTDevice	device,
		final String	path,
		final boolean	overwrite,
		final boolean	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(String) 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(BTDevice); #write(String); isValid()

Definition at line 179 of file SMPKeyBin.java.

Here is the call graph for this function:

◆ getAddrAndType()

final BDAddressAndType org.direct_bt.SMPKeyBin.getAddrAndType ( )

Definition at line 313 of file SMPKeyBin.java.

◆ getCreationTime()

final long org.direct_bt.SMPKeyBin.getCreationTime ( )

Returns the creation timestamp in seconds since Unix epoch.

Definition at line 311 of file SMPKeyBin.java.

◆ getCSRKInit()

final SMPSignatureResolvingKeyInfo org.direct_bt.SMPKeyBin.getCSRKInit ( )

Definition at line 320 of file SMPKeyBin.java.

◆ getCSRKResp()

final SMPSignatureResolvingKeyInfo org.direct_bt.SMPKeyBin.getCSRKResp ( )

Definition at line 335 of file SMPKeyBin.java.

◆ getFileBasename() [1/2]

final String org.direct_bt.SMPKeyBin.getFileBasename ( )

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

Definition at line 360 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getFileBasename() [2/2]

final static String org.direct_bt.SMPKeyBin.getFileBasename ( final BDAddressAndType addrAndType_ )

static

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

Definition at line 367 of file SMPKeyBin.java.

Here is the call graph for this function:

◆ getFilename()

final static String org.direct_bt.SMPKeyBin.getFilename	(	final String	path,
		final BDAddressAndType	addrAndType_
	)

static

Definition at line 371 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getIOCap()

final SMPIOCapability org.direct_bt.SMPKeyBin.getIOCap ( )

Definition at line 315 of file SMPKeyBin.java.

◆ getLTKInit()

final SMPLongTermKeyInfo org.direct_bt.SMPKeyBin.getLTKInit ( )

Definition at line 319 of file SMPKeyBin.java.

Here is the caller graph for this function:

◆ getLTKResp()

final SMPLongTermKeyInfo org.direct_bt.SMPKeyBin.getLTKResp ( )

Definition at line 334 of file SMPKeyBin.java.

Here is the caller graph for this function:

◆ getSecLevel()

final BTSecurityLevel org.direct_bt.SMPKeyBin.getSecLevel ( )

Definition at line 314 of file SMPKeyBin.java.

◆ getSize()

final short org.direct_bt.SMPKeyBin.getSize ( )

Definition at line 308 of file SMPKeyBin.java.

◆ getVersion()

final short org.direct_bt.SMPKeyBin.getVersion ( )

Definition at line 305 of file SMPKeyBin.java.

◆ hasCSRKInit()

final boolean org.direct_bt.SMPKeyBin.hasCSRKInit ( )

Definition at line 318 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hasCSRKResp()

final boolean org.direct_bt.SMPKeyBin.hasCSRKResp ( )

Definition at line 333 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hasLTKInit()

final boolean org.direct_bt.SMPKeyBin.hasLTKInit ( )

Definition at line 317 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hasLTKResp()

final boolean org.direct_bt.SMPKeyBin.hasLTKResp ( )

Definition at line 332 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isSizeValid()

final boolean org.direct_bt.SMPKeyBin.isSizeValid ( )

Definition at line 307 of file SMPKeyBin.java.

Here is the caller graph for this function:

◆ isValid()

final boolean org.direct_bt.SMPKeyBin.isValid ( )

Definition at line 349 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isVersionValid()

final boolean org.direct_bt.SMPKeyBin.isVersionValid ( )

Definition at line 304 of file SMPKeyBin.java.

Here is the caller graph for this function:

◆ read() [1/2]

final boolean org.direct_bt.SMPKeyBin.read ( final String fname )

Definition at line 505 of file SMPKeyBin.java.

Here is the call graph for this function:

◆ read() [2/2]

static SMPKeyBin org.direct_bt.SMPKeyBin.read	(	final String	fname,
		final boolean	verbose_
	)

static

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.
removeInvalidFile	if `true` and file is invalid, remove it. Otherwise keep it alive.
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(String, String)

Definition at line 207 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readAndApply()

static HCIStatusCode org.direct_bt.SMPKeyBin.readAndApply	(	final String	path,
		final BTDevice	device,
		final BTSecurityLevel	minSecLevel,
		final boolean	verbose_
	)

static

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

path/ + getFileBasename(BDAddressAndType).

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

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

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(String, BDAddressAndType, boolean); isValid(); #read(String, String); apply(BTDevice)

Definition at line 235 of file SMPKeyBin.java.

Here is the call graph for this function:

◆ remove()

final static boolean org.direct_bt.SMPKeyBin.remove	(	final String	path,
		final BDAddressAndType	addrAndType_
	)

static

Definition at line 417 of file SMPKeyBin.java.

Here is the call graph for this function:

◆ setCSRKInit()

final void org.direct_bt.SMPKeyBin.setCSRKInit ( final SMPSignatureResolvingKeyInfo v )

Definition at line 326 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setCSRKResp()

final void org.direct_bt.SMPKeyBin.setCSRKResp ( final SMPSignatureResolvingKeyInfo v )

Definition at line 341 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setLTKInit()

final void org.direct_bt.SMPKeyBin.setLTKInit ( final SMPLongTermKeyInfo v )

Definition at line 321 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setLTKResp()

final void org.direct_bt.SMPKeyBin.setLTKResp ( final SMPLongTermKeyInfo v )

Definition at line 336 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setVerbose()

final void org.direct_bt.SMPKeyBin.setVerbose ( final boolean v )

Definition at line 347 of file SMPKeyBin.java.

Here is the caller graph for this function:

◆ toString()

final String org.direct_bt.SMPKeyBin.toString ( )

Definition at line 376 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write()

final boolean org.direct_bt.SMPKeyBin.write	(	final String	fname,
		final boolean	overwrite
	)

Definition at line 432 of file SMPKeyBin.java.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ VERSION

final short org.direct_bt.SMPKeyBin.VERSION = (short)0b0101010101010101 + (short)2

static

Definition at line 61 of file SMPKeyBin.java.

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

/usr/local/projects/direct_bt/java/org/direct_bt/SMPKeyBin.java

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