TI BLE5-Stack API Documentation  3.02.01.00
sm.h
Go to the documentation of this file.
1 /******************************************************************************
2 
3  Group: WCS, BTS
4  $Target Device: DEVICES $
5 
6  ******************************************************************************
7  $License: TISD 2009 $
8  ******************************************************************************
9  $Release Name: PACKAGE NAME $
10  $Release Date: PACKAGE RELEASE DATE $
11  *****************************************************************************/
12 
18 #ifndef SM_H
19 #define SM_H
20 
21 #ifdef __cplusplus
22 extern "C"
23 {
24 #endif
25 
26 /*-------------------------------------------------------------------
27  * INCLUDES
28  */
29 #include "bcomdef.h"
30 #include "osal.h"
31 
32 #include "hci.h"
33 
34 /*-------------------------------------------------------------------
35  * MACROS
36  */
37 
38 /*-------------------------------------------------------------------
39  * CONSTANTS
40  */
49 #define DISPLAY_ONLY 0x00
50 #define DISPLAY_YES_NO 0x01
51 #define KEYBOARD_ONLY 0x02
52 #define NO_INPUT_NO_OUTPUT 0x03
53 #define KEYBOARD_DISPLAY 0x04
54 
56 #define SM_AUTH_MITM_MASK(a) (((a) & 0x04) >> 2)
57 
58 
62 #define SM_PASSKEY_TYPE_INPUT 0x01
63 #define SM_PASSKEY_TYPE_DISPLAY 0x02
64 
71 #define SM_AUTH_REQ_NO_BONDING 0x00
72 #define SM_AUTH_REQ_BONDING 0x01
73 
75 #define PASSKEY_LEN 6
76 
77 #define SM_AUTH_STATE_AUTHENTICATED 0x04
78 #define SM_AUTH_STATE_BONDING 0x01
79 #define SM_AUTH_STATE_SECURECONNECTION 0x08
80 
81 #define SM_ECC_KEY_LEN 32
82 
83 /* SM private/public key regeneration policy */
84 #define SM_ECC_KEYS_NOT_AVAILABLE 0xFF
85 #define SM_ECC_KEYS_REGNENERATE_NEVER 0xFF
86 #define SM_ECC_KEYS_REGENERATE_ALWAYS 0x00
87 
88 
92 #define SM_ECC_KEYS_EVENT 0x00
93 #define SM_DH_KEY_EVENT 0x01
94  // end of GAPBondMgr_Constants
97 
98 /*-------------------------------------------------------------------
99  * General TYPEDEFS
100  */
101 
106 typedef struct
107 {
109  uint8 newKey[KEYLEN];
111 
115 typedef struct
116 {
118  uint8 opcode;
119 } smEventHdr_t;
120 
125 typedef struct
126 {
128  uint8 opcode;
129  uint8 privateKey[SM_ECC_KEY_LEN];
130  uint8 publicKeyX[SM_ECC_KEY_LEN];
131  uint8 publicKeyY[SM_ECC_KEY_LEN];
133 
138 typedef struct
139 {
141  uint8 opcode;
142  uint8 dhKey[SM_ECC_KEY_LEN];
143 } smDhKeyEvt_t;
144 
148 typedef struct
149 {
150  unsigned int sEncKey:1;
151  unsigned int sIdKey:1;
152  unsigned int sSign:1;
153  unsigned int sLinkKey:1;
154  unsigned int sReserved:4;
155  unsigned int mEncKey:1;
156  unsigned int mIdKey:1;
157  unsigned int mSign:1;
158  unsigned int mLinkKey:1;
159  unsigned int mReserved:4;
160 } keyDist_t;
161 
165 typedef struct
166 {
167  uint8 isUsed;
168  uint8 sK[SM_ECC_KEY_LEN];
169  uint8 pK_x[SM_ECC_KEY_LEN];
170  uint8 pK_y[SM_ECC_KEY_LEN];
171 } smEccKeys_t;
172 
176 typedef struct
177 {
178  uint8 ioCaps;
179  uint8 oobAvailable;
180  uint8 oob[KEYLEN];
181  uint8 oobConfirm[KEYLEN];
183  uint8 localOob[KEYLEN];
184  uint8 isSCOnlyMode;
186  uint8 authReq;
190 
194 typedef struct
195 {
196  uint8 ltk[KEYLEN];
197  uint16 div;
198  uint8 rand[B_RANDOM_NUM_SIZE];
199  uint8 keySize;
201 
205 typedef struct
206 {
207  uint8 irk[KEYLEN];
208  uint8 addrType;
209  uint8 bd_addr[B_ADDR_LEN];
211 
215 typedef struct
216 {
217  uint8 srk[KEYLEN];
218  uint32 signCounter;
220 
224 typedef struct
225 {
226  unsigned int bonding:2;
227  unsigned int mitm:1;
228  unsigned int sc:1;
229  unsigned int kp:1;
230  unsigned int ct2:1;
231  unsigned int reserved:2;
232 } authReq_t;
233 
237 typedef void (*smCB_t)
238 (
239 uint8 *secretKey,
240 uint8 *publicKeyX,
241 uint8 *publicKeyY
242 );
243 
244 /*-------------------------------------------------------------------
245  * GLOBAL VARIABLES
246  */
247 
248 /*-------------------------------------------------------------------
249  * FUNCTIONS - APPLICATION API - Functions the application may call
250  */
251 
258 extern void SM_RegisterTask( uint8 taskID );
259 
268 extern bStatus_t SM_GetEccKeys( void );
269 
283 extern bStatus_t SM_GetDHKey( uint8 *secretKey, uint8 *publicKeyX,
284  uint8 *publicKeyY );
285 
299 extern bStatus_t SM_GetScConfirmOob( uint8 *publicKey, uint8 *oob, uint8 *pOut );
300 
311 extern void SM_GenerateRandBuf( uint8 *random, uint8 len );
312 
327 extern void SM_SetAuthenPairingOnlyMode( uint8 state );
328 
342 extern void SM_SetAllowDebugKeysMode( uint8 state );
357 extern uint8 SM_GetAuthenPairingOnlyMode( void );
371 extern uint8 SM_GetAllowDebugKeysMode( void );
372 /*-------------------------------------------------------------------
373  * FUNCTIONS - MASTER API - Only use these in a master device
374  */
375 
383 extern bStatus_t SM_InitiatorInit( void );
384 
403 extern bStatus_t SM_StartPairing( uint8 initiator,
404  uint8 taskID,
405  uint16 connectionHandle,
406  smLinkSecurityReq_t *pSecReqs );
407 
422 extern bStatus_t SM_StartEncryption( uint16 connHandle, uint8 *pLTK,
423  uint16 div, uint8 *pRandNum,
424  uint8 keyLen );
425 
426 
427 /*-------------------------------------------------------------------
428  * FUNCTIONS - SLAVE API - Only use these in a slave device
429  */
430 
438 extern bStatus_t SM_ResponderInit( void );
439 
440 /*-------------------------------------------------------------------
441  * FUNCTIONS - GENERAL API - both master and slave
442  */
443 
454 extern bStatus_t SM_NewRandKey( uint8 taskID );
455 
468 extern bStatus_t SM_Encrypt( uint8 *pKey, uint8 *pPlainText, uint8 *pResult );
469 
482 extern bStatus_t SM_GenerateAuthenSig( uint8 *pData, uint16 len,
483  uint8 *pAuthenSig, uint16 connHandle );
484 
500 extern bStatus_t SM_VerifyAuthenSig( uint16 connHandle,
501  uint8 authentication,
502  uint8 *pData,
503  uint16 len,
504  uint8 *pAuthenSig );
505 
516 extern bStatus_t SM_PasskeyUpdate( uint8 *pPasskey, uint16 connectionHandle );
517 
518 
524 extern void SM_SetECCRegenerationCount(uint8 count);
525 
527 
528 /*-------------------------------------------------------------------
529  * TASK API - These functions must only be called by OSAL.
530  */
531 
539  extern void SM_Init( uint8 task_id );
540 
551  extern uint16 SM_ProcessEvent( uint8 task_id, uint16 events );
552 
565  extern void SM_p256KeyCB( hciEvt_BLEReadP256PublicKeyComplete_t *pK,
566  uint8 *privateKey );
567 
580  extern void SM_dhKeyCB( hciEvt_BLEGenDHKeyComplete_t *pDhKey );
581 
583 
584 /*-------------------------------------------------------------------
585 -------------------------------------------------------------------*/
586 
587 #ifdef __cplusplus
588 }
589 #endif
590 
591 #endif /* SM_H */
uint8 opcode
SM_DH_KEY_EVENT.
Definition: sm.h:141
bStatus_t SM_PasskeyUpdate(uint8 *pPasskey, uint16 connectionHandle)
Update the passkey for the pairing process.
This API allows the software components in the Z-Stack to be written independently of the specifics o...
uint8 SM_GetAllowDebugKeysMode(void)
Get the device debug keys allownce policy. If not allowed, the pairing will be rejected with code of ...
Definition: sm.h:165
void SM_RegisterTask(uint8 taskID)
Register Task with the Security Manager to receive ECC keys or a ECDH shared secret.
Definition: sm.h:194
#define B_RANDOM_NUM_SIZE
BLE Random Number Size.
Definition: bcomdef.h:133
bStatus_t SM_StartPairing(uint8 initiator, uint8 taskID, uint16 connectionHandle, smLinkSecurityReq_t *pSecReqs)
Start the pairing process.
bStatus_t SM_GetScConfirmOob(uint8 *publicKey, uint8 *oob, uint8 *pOut)
Generate a confirm value for OOB data.
bStatus_t SM_NewRandKey(uint8 taskID)
Generate a key with a random value.
Definition: sm.h:125
Definition: sm.h:115
uint8 addrType
Address type for BD_ADDR.
Definition: sm.h:208
bStatus_t SM_GenerateAuthenSig(uint8 *pData, uint16 len, uint8 *pAuthenSig, uint16 connHandle)
void SM_SetECCRegenerationCount(uint8 count)
Update the regeneration count for ECC key re-usage.
#define SM_ECC_KEY_LEN
ECC Key length in bytes.
Definition: sm.h:81
bStatus_t SM_ResponderInit(void)
Initialize SM Responder on a slave device.
bStatus_t SM_GetEccKeys(void)
Get ECC private and public keys. Keys are returned through the callback registered in SM_RegisterCb...
Definition: sm.h:106
Definition: sm.h:148
uint8 keySize
LTK Key Size (7-16 bytes)
Definition: sm.h:199
Definition: sm.h:205
osal_event_hdr_t hdr
SM_MSG_EVENT and status.
Definition: sm.h:127
LE Generate DHKey Complete Event.
Definition: hci.h:1102
uint8 opcode
op code
Definition: sm.h:118
uint8 isUsed
FALSE if not used. USE_PKEYS if public keys only. USE_ALL_KEYS if public and private keys...
Definition: sm.h:167
Type definitions and macros for BLE stack.
uint8 opcode
SM_ECC_KEYS_EVENT.
Definition: sm.h:128
Definition: sm.h:215
OSAL Event Header.
Definition: osal.h:92
uint16 div
LTK Diversifier.
Definition: sm.h:197
HCI layer interface.
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 ...
Definition: sm.h:138
void(* smCB_t)(uint8 *secretKey, uint8 *publicKeyX, uint8 *publicKeyY)
Definition: sm.h:238
osal_event_hdr_t hdr
SM_MSG_EVENT and status.
Definition: sm.h:140
#define B_ADDR_LEN
Default Public and Random Address Length.
Definition: bcomdef.h:108
bStatus_t SM_StartEncryption(uint16 connHandle, uint8 *pLTK, uint16 div, uint8 *pRandNum, uint8 keyLen)
Send Start Encrypt through HCI.
uint8 SM_GetAuthenPairingOnlyMode(void)
Get the device into Authenticated Pairing Only Mode. If enabled and the key generation method does no...
bStatus_t SM_InitiatorInit(void)
Initialize SM Initiator on a master device.
Status_t bStatus_t
BLE Generic Status return.
Definition: bcomdef.h:251
osal_event_hdr_t hdr
osal event header
Definition: sm.h:117
uint32 signCounter
Sign Counter.
Definition: sm.h:218
LE Read P256 Public Key Complete Event.
Definition: hci.h:1093
Definition: sm.h:224
bStatus_t SM_VerifyAuthenSig(uint16 connHandle, uint8 authentication, uint8 *pData, uint16 len, uint8 *pAuthenSig)
Verify an Authentication Signature.
#define KEYLEN
Default key length.
Definition: bcomdef.h:111
osal_event_hdr_t hdr
SM_NEW_RAND_KEY_EVENT and status.
Definition: sm.h:108
bStatus_t SM_Encrypt(uint8 *pKey, uint8 *pPlainText, uint8 *pResult)
Encrypt the plain text data with the key..
© Copyright 1995-2023, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale