Detailed Description

This file contains the interface to the SM.

Data Structures
struct	authReq_t

struct	keyDist_t

struct	smDhKeyEvt_t

struct	smEccKeys_t

struct	smEccKeysEvt_t

struct	smEventHdr_t

struct	smIdentityInfo_t

struct	smLinkSecurityReq_t

struct	smNewRandKeyEvent_t

struct	smSecurityInfo_t

struct	smSigningInfo_t

Macros
#define	DISPLAY_ONLY 0x00
	Display Only Device.

#define	DISPLAY_YES_NO 0x01
	Display and Yes and No Capable.

#define	KEYBOARD_DISPLAY 0x04
	Both Keyboard and Display Capable.

#define	KEYBOARD_ONLY 0x02
	Keyboard Only.

#define	NO_INPUT_NO_OUTPUT 0x03
	No Display or Input Device.

#define	PASSKEY_LEN 6
	Passkey Character Length (ASCII Characters)

#define	SM_AUTH_MITM_MASK(a) (((a) & 0x04) >> 2)
	MITM Mask.

#define	SM_AUTH_REQ_BONDING 0x01
	Bonding.

#define	SM_AUTH_REQ_NO_BONDING 0x00
	No bonding.

#define	SM_AUTH_STATE_AUTHENTICATED 0x04
	Authenticate requested.

#define	SM_AUTH_STATE_BONDING 0x01
	Bonding requested.

#define	SM_AUTH_STATE_SECURECONNECTION 0x08
	Secure Connection requested.

#define	SM_DH_KEY_EVENT 0x01
	Diffie-Hellman key.

#define	SM_ECC_KEY_LEN 32
	ECC Key length in bytes.

#define	SM_ECC_KEYS_EVENT 0x00
	ECC Keys.

#define	SM_ECC_KEYS_NOT_AVAILABLE 0xFF
	Initial state of recycled keys before they exist.

#define	SM_ECC_KEYS_REGENERATE_ALWAYS 0x00
	Always regenerate the keys.

#define	SM_ECC_KEYS_REGNENERATE_NEVER 0xFF
	Never regenerate the keys.

#define	SM_PASSKEY_TYPE_DISPLAY 0x02
	Display the passkey.

#define	SM_PASSKEY_TYPE_INPUT 0x01
	Input the passkey.

Typedefs
typedef void(*	smCB_t) (uint8 secretKey, uint8 publicKeyX, uint8 *publicKeyY)

Functions
bStatus_t	SM_CalcRandomAddr (uint8 pIRK, uint8 pNewAddr)
	Calculate a new Private Resolvable address. More...

bStatus_t	SM_Encrypt (uint8 pKey, uint8 pPlainText, uint8 *pResult)
	Encrypt the plain text data with the key.. More...

bStatus_t	SM_GenerateAuthenSig (uint8 pData, uint16 len, uint8 pAuthenSig)
	Generate an outgoing Authentication Signature. More...

bStatus_t	SM_GetDHKey (uint8 secretKey, uint8 publicKeyX, uint8 *publicKeyY)
	Request a Diffie-Hellman key from the ECC engine. Key is returned through the callback registered in SM_RegisterCb, in the first parameter. More...

bStatus_t	SM_GetEccKeys (void)
	Get ECC private and public keys. Keys are returned through the callback registered in SM_RegisterCb. More...

bStatus_t	SM_GetScConfirmOob (uint8 publicKey, uint8 oob, uint8 *pOut)
	Generate a confirm value for OOB data. More...

bStatus_t	SM_InitiatorInit (void)
	Initialize SM Initiator on a master device. More...

bStatus_t	SM_NewRandKey (uint8 taskID)
	Generate a key with a random value. More...

bStatus_t	SM_PasskeyUpdate (uint8 *pPasskey, uint16 connectionHandle)
	Update the passkey for the pairing process. More...

void	SM_RegisterTask (uint8 taskID)
	Register Task with the Security Manager to receive ECC keys or a ECDH shared secret. More...

bStatus_t	SM_ResolveRandomAddrs (uint8 pIRK, uint8 pAddr)
	Resolve a Private Resolvable Address. More...

bStatus_t	SM_ResponderInit (void)
	Initialize SM Responder on a slave device. More...

void	SM_SetECCRegenerationCount (uint8 count)
	Update the regeneration count for ECC key re-usage. More...

bStatus_t	SM_StartEncryption (uint16 connHandle, uint8 pLTK, uint16 div, uint8 pRandNum, uint8 keyLen)
	Send Start Encrypt through HCI. More...

bStatus_t	SM_StartPairing (uint8 initiator, uint8 taskID, uint16 connectionHandle, smLinkSecurityReq_t *pSecReqs)
	Start the pairing process. More...

bStatus_t	SM_VerifyAuthenSig (uint16 connHandle, uint8 authentication, uint8 pData, uint16 len, uint8 pAuthenSig)
	Verify an Authentication Signature. More...

Typedef Documentation

§ smCB_t

typedef void(* smCB_t) (uint8 *secretKey, uint8 *publicKeyX, uint8 *publicKeyY)

Application callback to the SM for ECC keys and Diffie-Hellman Shared Secret (ECDH).

Function Documentation

§ SM_CalcRandomAddr()

bStatus_t SM_CalcRandomAddr	(	uint8 *	pIRK,
		uint8 *	pNewAddr
	)

Calculate a new Private Resolvable address.

Parameters

pIRK	- Identity Root Key.
pNewAddr	- pointer to place to put new calc'd address

Returns: SUCCESS - if started; INVALIDPARAMETER

§ SM_Encrypt()

bStatus_t SM_Encrypt	(	uint8 *	pKey,
		uint8 *	pPlainText,
		uint8 *	pResult
	)

Encrypt the plain text data with the key..

Parameters

pKey	- key data
pPlainText	- Plain text data
pResult	- place to put the encrypted result

Returns: SUCCESS - if started; INVALIDPARAMETER - one of the parameters are NULL; bleAlreadyInRequestedMode; bleMemAllocError

§ SM_GenerateAuthenSig()

bStatus_t SM_GenerateAuthenSig	(	uint8 *	pData,
		uint16	len,
		uint8 *	pAuthenSig
	)

Generate an outgoing Authentication Signature.

Parameters

pData	- message data
len	- length of pData
pAuthenSig	- place to put new signature

Returns: SUCCESS - signature authentication generated; INVALIDPARAMETER - pData or pAuthenSig is NULL; bleMemAllocError

§ SM_GetDHKey()

bStatus_t SM_GetDHKey	(	uint8 *	secretKey,
		uint8 *	publicKeyX,
		uint8 *	publicKeyY
	)

Request a Diffie-Hellman key from the ECC engine. Key is returned through the callback registered in SM_RegisterCb, in the first parameter.

Parameters

secretKey	- the local private key
publicKeyX	- the remote public key, X-Coordinate.
publicKeyY	- the remote public key, Y-Coordinate.

Returns: SUCCESS if processing; FAILURE if SM is pairing; HCI_ERROR_CODE_MEM_CAP_EXCEEDED if out of heap memory.

§ SM_GetEccKeys()

bStatus_t SM_GetEccKeys ( void )

Get ECC private and public keys. Keys are returned through the callback registered in SM_RegisterCb.

Returns: SUCCESS if processing; FAILURE if SM is pairing; HCI_ERROR_CODE_MEM_CAP_EXCEEDED if out of heap memory.

§ SM_GetScConfirmOob()

bStatus_t SM_GetScConfirmOob	(	uint8 *	publicKey,
		uint8 *	oob,
		uint8 *	pOut
	)

Generate a confirm value for OOB data.

Parameters

publicKey	- the local public key X-coordinate
oob	- the random string to be sent to the remote device via oob
pOut	- pointer to the generated confirm value. The calling application must copy this data into its own buffer.

Returns: SUCCESS; INVALIDPARAMETER; bleMemAllocError

§ SM_InitiatorInit()

bStatus_t SM_InitiatorInit ( void )

Initialize SM Initiator on a master device.

Warning: Only use this API on a master device

Returns: SUCCESS

§ SM_NewRandKey()

bStatus_t SM_NewRandKey ( uint8 taskID )

Generate a key with a random value.

Parameters

taskID - task ID to send results.

Returns: SUCCESS; bleNotReady; bleMemAllocError; FAILURE

§ SM_PasskeyUpdate()

bStatus_t SM_PasskeyUpdate	(	uint8 *	pPasskey,
		uint16	connectionHandle
	)

Update the passkey for the pairing process.

Parameters

pPasskey	- pointer to the 6 digit passkey
connectionHandle	- connection handle to link.

Returns: SUCCESS; bleIncorrectMode - Not pairing; INVALIDPARAMETER - link is incorrect

§ SM_RegisterTask()

void SM_RegisterTask ( uint8 taskID )

Register Task with the Security Manager to receive ECC keys or a ECDH shared secret.

Parameters

taskID - Application's task ID.

§ SM_ResolveRandomAddrs()

bStatus_t SM_ResolveRandomAddrs	(	uint8 *	pIRK,
		uint8 *	pAddr
	)

Resolve a Private Resolvable Address.

Parameters

pIRK	- pointer to the IRK
pAddr	- pointer to the random address

Returns: SUCCESS - match; FAILURE - don't match; INVALIDPARAMETER - parameters invalid

§ SM_ResponderInit()

bStatus_t SM_ResponderInit ( void )

Initialize SM Responder on a slave device.

Warning: Only use this API on a slave device

Returns: SUCCESS

§ SM_SetECCRegenerationCount()

void SM_SetECCRegenerationCount ( uint8 count )

Update the regeneration count for ECC key re-usage.

Parameters

count - number of times a keypair can be reused before regeneration.

§ SM_StartEncryption()

bStatus_t SM_StartEncryption	(	uint16	connHandle,
		uint8 *	pLTK,
		uint16	div,
		uint8 *	pRandNum,
		uint8	keyLen
	)

Send Start Encrypt through HCI.

Warning: Only use this API on a master device

Parameters

connHandle	- Connection Handle
pLTK	- pointer to 16 byte lkt
div	- div or ediv
pRandNum	- pointer to 8 byte random number
keyLen	- length of LTK (bytes)

Returns: SUCCESS; INVALIDPARAMETER

§ SM_StartPairing()

bStatus_t SM_StartPairing	(	uint8	initiator,
		uint8	taskID,
		uint16	connectionHandle,
		smLinkSecurityReq_t *	pSecReqs
	)

Start the pairing process.

This function is also called if the device is already bound.

Note: Only one pairing process at a time per device.

Warning: Only use this API on a master device

Parameters

initiator	- TRUE to start pairing as Initiator.
taskID	- task ID to send results.
connectionHandle	- Link's connection handle
pSecReqs	- Security parameters for pairing

Returns: SUCCESS; INVALIDPARAMETER; bleAlreadyInRequestedMode

§ SM_VerifyAuthenSig()

bStatus_t SM_VerifyAuthenSig	(	uint16	connHandle,
		uint8	authentication,
		uint8 *	pData,
		uint16	len,
		uint8 *	pAuthenSig
	)

Verify an Authentication Signature.

Parameters

connHandle	- connection to verify against.
authentication	- TRUE if requires an authenticated CSRK, FALSE if not
pData	- message data
len	- length of pData
pAuthenSig	- message signature to verify

Returns: SUCCESS - signature authentication verified; FAILURE - if not verified; bleNotConnected - Connection not found; INVALIDPARAMETER - pData or pAuthenSig is NULL, or signCounter is invalid; bleMemAllocError

Detailed Description

Data Structures

Macros

Typedefs

Functions

Typedef Documentation

§ smCB_t

Function Documentation

§ SM_CalcRandomAddr()

§ SM_Encrypt()

§ SM_GenerateAuthenSig()

§ SM_GetDHKey()

§ SM_GetEccKeys()

§ SM_GetScConfirmOob()

§ SM_InitiatorInit()

§ SM_NewRandKey()

§ SM_PasskeyUpdate()

§ SM_RegisterTask()

§ SM_ResolveRandomAddrs()

§ SM_ResponderInit()

§ SM_SetECCRegenerationCount()

§ SM_StartEncryption()

§ SM_StartPairing()

§ SM_VerifyAuthenSig()