TI BLE-Stack for Bluetooth 4.2 API Documentation  3.01.00.07
Data Structures | Macros | Typedefs | Functions
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_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
Copyright 2017, Texas Instruments Incorporated