sm.h File Reference

Detailed Description

This file contains the interface to the SM.

Go to the source code of this file.

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_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, uint16 connHandle)
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_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_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,
		uint16	connHandle
	)

Generate an outgoing Authentication Signature.

Parameters

pData	message data
len	length of pData
pAuthenSig	place to put new signature
connHandle	connection handle

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_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