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. More...
#define	DISPLAY_YES_NO   0x01
	Display and Yes and No Capable. More...
#define	KEYBOARD_DISPLAY   0x04
	Both Keyboard and Display Capable. More...
#define	KEYBOARD_ONLY   0x02
	Keyboard Only. More...
#define	NO_INPUT_NO_OUTPUT   0x03
	No Display or Input Device. More...
#define	PASSKEY_LEN   6
	Passkey Character Length (ASCII Characters) More...
#define	SM_AUTH_MITM_MASK(a)   (((a) & 0x04) >> 2)
	MITM Mask. More...
#define	SM_AUTH_REQ_BONDING   0x01
	Bonding. More...
#define	SM_AUTH_REQ_NO_BONDING   0x00
	No bonding. More...
#define	SM_AUTH_STATE_AUTHENTICATED   0x04
	Authenticate requested. More...
#define	SM_AUTH_STATE_BONDING   0x01
	Bonding requested. More...
#define	SM_AUTH_STATE_SECURECONNECTION   0x08
	Secure Connection requested. More...
#define	SM_DH_KEY_EVENT   0x01
	Diffie-Hellman key. More...
#define	SM_ECC_KEY_LEN   32
	ECC Key length in bytes. More...
#define	SM_ECC_KEYS_EVENT   0x00
	ECC Keys. More...
#define	SM_ECC_KEYS_NOT_AVAILABLE   0xFF
	Initial state of recycled keys before they exist. More...
#define	SM_ECC_KEYS_REGENERATE_ALWAYS   0x00
	Always regenerate the keys. More...
#define	SM_ECC_KEYS_REGNENERATE_NEVER   0xFF
	Never regenerate the keys. More...
#define	SM_PASSKEY_TYPE_DISPLAY   0x02
	Display the passkey. More...
#define	SM_PASSKEY_TYPE_INPUT   0x01
	Input the passkey. More...

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)
void	SM_GenerateRandBuf (uint8 *random, uint8 len)
uint8	SM_GetAllowDebugKeysMode (void)
	Get the device debug keys allownce policy. If not allowed, the pairing will be rejected with code of invalid parameters. If allowed, pairing will continue noramlly. More...
uint8	SM_GetAuthenPairingOnlyMode (void)
	Get the device into Authenticated Pairing Only Mode. If enabled and the key generation method does not result in a key that provides Authenticated MITM protection then the device will send the Pairing Failed command with the error code Authentication Requirements. More...
bStatus_t	SM_GetDHKey (uint8 *secretKey, uint8 *publicKeyX, uint8 *publicKeyY)
	Request a Diffie-Hellman key from the ECC engine. Key is returned through a SM_DH_KEY_EVENT event passed in the task the Security Manager has been registered into using SM_RegisterTask(). More...
bStatus_t	SM_GetEccKeys (void)
	Get ECC private and public keys. Keys are returned through a SM_ECC_KEYS_EVENT event passed in the task the Security Manager has been registered into using SM_RegisterTask(). 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 central 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 peripheral device. More...
void	SM_SetAllowDebugKeysMode (uint8 state)
void	SM_SetAuthenPairingOnlyMode (uint8 state)
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_GenerateRandBuf()

void SM_GenerateRandBuf	(	uint8 *	random,
		uint8	len
	)

SM_GetAllowDebugKeysMode()

SM_GetAllowDebugKeysMode

(

void

)

Get the device debug keys allownce policy. If not allowed, the pairing will be rejected with code of invalid parameters. If allowed, pairing will continue noramlly.

Parameters

none

Returns

state - TRUE debug keys as peer public keys are allowed FALSE when disallowed

SM_GetAuthenPairingOnlyMode()

SM_GetAuthenPairingOnlyMode

(

void

)

Get the device into Authenticated Pairing Only Mode. If enabled and the key generation method does not result in a key that provides Authenticated MITM protection then the device will send the Pairing Failed command with the error code Authentication Requirements.

Parameters

none

Returns

state - TRUE Authenticated Pairing Only Mode is enabled FALSE when disabled

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 a SM_DH_KEY_EVENT event passed in the task the Security Manager has been registered into using SM_RegisterTask().

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 a SM_ECC_KEYS_EVENT event passed in the task the Security Manager has been registered into using SM_RegisterTask().

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 central device.

Warning

Only use this API on a central 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 peripheral device.

Warning

Only use this API on a peripheral device

Returns

SUCCESS

SM_SetAllowDebugKeysMode()

void SM_SetAllowDebugKeysMode

(

uint8

state

)

SM_SetAuthenPairingOnlyMode()

void SM_SetAuthenPairingOnlyMode

(

uint8

state

)

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