1 /****************************************************************************** 2 * 3 * Copyright (C) 1999-2012 Broadcom Corporation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 /****************************************************************************** 20 * 21 * This file contains the SMP API function external definitions. 22 * 23 ******************************************************************************/ 24 #ifndef SMP_API_H 25 #define SMP_API_H 26 27 #include "bt_target.h" 28 29 #define SMP_PIN_CODE_LEN_MAX PIN_CODE_LEN 30 #define SMP_PIN_CODE_LEN_MIN 6 31 32 #if BLE_INCLUDED == TRUE && SMP_INCLUDED == TRUE 33 /* SMP command code */ 34 #define SMP_OPCODE_PAIRING_REQ 0x01 35 #define SMP_OPCODE_PAIRING_RSP 0x02 36 #define SMP_OPCODE_CONFIRM 0x03 37 #define SMP_OPCODE_RAND 0x04 38 #define SMP_OPCODE_PAIRING_FAILED 0x05 39 #define SMP_OPCODE_ENCRYPT_INFO 0x06 40 #define SMP_OPCODE_MASTER_ID 0x07 41 #define SMP_OPCODE_IDENTITY_INFO 0x08 42 #define SMP_OPCODE_ID_ADDR 0x09 43 #define SMP_OPCODE_SIGN_INFO 0x0A 44 #define SMP_OPCODE_SEC_REQ 0x0B 45 #define SMP_OPCODE_PAIR_PUBLIC_KEY 0x0C 46 #define SMP_OPCODE_PAIR_DHKEY_CHECK 0x0D 47 #define SMP_OPCODE_PAIR_KEYPR_NOTIF 0x0E 48 #define SMP_OPCODE_MAX SMP_OPCODE_PAIR_KEYPR_NOTIF 49 #define SMP_OPCODE_MIN SMP_OPCODE_PAIRING_REQ 50 #define SMP_OPCODE_PAIR_COMMITM 0x0F 51 #endif 52 53 /* SMP event type */ 54 #define SMP_IO_CAP_REQ_EVT 1 /* IO capability request event */ 55 #define SMP_SEC_REQUEST_EVT 2 /* SMP pairing request */ 56 #define SMP_PASSKEY_NOTIF_EVT 3 /* passkey notification event */ 57 #define SMP_PASSKEY_REQ_EVT 4 /* passkey request event */ 58 #define SMP_OOB_REQ_EVT 5 /* OOB request event */ 59 #define SMP_NC_REQ_EVT 6 /* Numeric Comparison request event */ 60 #define SMP_COMPLT_EVT 7 /* SMP complete event */ 61 #define SMP_PEER_KEYPR_NOT_EVT 8 /* Peer keypress notification received event */ 62 #define SMP_SC_OOB_REQ_EVT 9 /* SC OOB request event (both local and peer OOB data */ 63 /* can be expected in response) */ 64 #define SMP_SC_LOC_OOB_DATA_UP_EVT 10 /* SC OOB local data set is created */ 65 /* (as result of SMP_CrLocScOobData(...)) */ 66 #define SMP_BR_KEYS_REQ_EVT 12 /* SMP over BR keys request event */ 67 typedef UINT8 tSMP_EVT; 68 69 70 /* pairing failure reason code */ 71 #define SMP_PASSKEY_ENTRY_FAIL 0x01 72 #define SMP_OOB_FAIL 0x02 73 #define SMP_PAIR_AUTH_FAIL 0x03 74 #define SMP_CONFIRM_VALUE_ERR 0x04 75 #define SMP_PAIR_NOT_SUPPORT 0x05 76 #define SMP_ENC_KEY_SIZE 0x06 77 #define SMP_INVALID_CMD 0x07 78 #define SMP_PAIR_FAIL_UNKNOWN 0x08 79 #define SMP_REPEATED_ATTEMPTS 0x09 80 #define SMP_INVALID_PARAMETERS 0x0A 81 #define SMP_DHKEY_CHK_FAIL 0x0B 82 #define SMP_NUMERIC_COMPAR_FAIL 0x0C 83 #define SMP_BR_PARING_IN_PROGR 0x0D 84 #define SMP_XTRANS_DERIVE_NOT_ALLOW 0x0E 85 #define SMP_MAX_FAIL_RSN_PER_SPEC SMP_XTRANS_DERIVE_NOT_ALLOW 86 87 /* self defined error code */ 88 #define SMP_PAIR_INTERNAL_ERR (SMP_MAX_FAIL_RSN_PER_SPEC + 0x01) /* 0x0E */ 89 90 /* 0x0F unknown IO capability, unable to decide association model */ 91 #define SMP_UNKNOWN_IO_CAP (SMP_MAX_FAIL_RSN_PER_SPEC + 0x02) /* 0x0F */ 92 93 #define SMP_INIT_FAIL (SMP_MAX_FAIL_RSN_PER_SPEC + 0x03) /* 0x10 */ 94 #define SMP_CONFIRM_FAIL (SMP_MAX_FAIL_RSN_PER_SPEC + 0x04) /* 0x11 */ 95 #define SMP_BUSY (SMP_MAX_FAIL_RSN_PER_SPEC + 0x05) /* 0x12 */ 96 #define SMP_ENC_FAIL (SMP_MAX_FAIL_RSN_PER_SPEC + 0x06) /* 0x13 */ 97 #define SMP_STARTED (SMP_MAX_FAIL_RSN_PER_SPEC + 0x07) /* 0x14 */ 98 #define SMP_RSP_TIMEOUT (SMP_MAX_FAIL_RSN_PER_SPEC + 0x08) /* 0x15 */ 99 #define SMP_DIV_NOT_AVAIL (SMP_MAX_FAIL_RSN_PER_SPEC + 0x09) /* 0x16 */ 100 101 /* 0x17 unspecified failed reason */ 102 #define SMP_FAIL (SMP_MAX_FAIL_RSN_PER_SPEC + 0x0A) /* 0x17 */ 103 104 #define SMP_CONN_TOUT (SMP_MAX_FAIL_RSN_PER_SPEC + 0x0B) 105 #define SMP_SUCCESS 0 106 107 typedef UINT8 tSMP_STATUS; 108 109 110 /* Device IO capability */ 111 #define SMP_IO_CAP_OUT BTM_IO_CAP_OUT /* DisplayOnly */ 112 #define SMP_IO_CAP_IO BTM_IO_CAP_IO /* DisplayYesNo */ 113 #define SMP_IO_CAP_IN BTM_IO_CAP_IN /* KeyboardOnly */ 114 #define SMP_IO_CAP_NONE BTM_IO_CAP_NONE /* NoInputNoOutput */ 115 #define SMP_IO_CAP_KBDISP BTM_IO_CAP_KBDISP /* Keyboard Display */ 116 #define SMP_IO_CAP_MAX BTM_IO_CAP_MAX 117 typedef UINT8 tSMP_IO_CAP; 118 119 #ifndef SMP_DEFAULT_IO_CAPS 120 #define SMP_DEFAULT_IO_CAPS SMP_IO_CAP_KBDISP 121 #endif 122 123 /* OOB data present or not */ 124 enum 125 { 126 SMP_OOB_NONE, 127 SMP_OOB_PRESENT, 128 SMP_OOB_UNKNOWN 129 }; 130 typedef UINT8 tSMP_OOB_FLAG; 131 132 /* type of OOB data required from application */ 133 enum 134 { 135 SMP_OOB_INVALID_TYPE, 136 SMP_OOB_PEER, 137 SMP_OOB_LOCAL, 138 SMP_OOB_BOTH 139 }; 140 typedef UINT8 tSMP_OOB_DATA_TYPE; 141 142 #define SMP_AUTH_NO_BOND 0x00 143 #define SMP_AUTH_GEN_BOND 0x01 //todo sdh change GEN_BOND to BOND 144 145 /* SMP Authentication requirement */ 146 #define SMP_AUTH_YN_BIT (1 << 2) 147 #define SMP_SC_SUPPORT_BIT (1 << 3) 148 #define SMP_KP_SUPPORT_BIT (1 << 4) 149 150 #define SMP_AUTH_MASK (SMP_AUTH_GEN_BOND|SMP_AUTH_YN_BIT|SMP_SC_SUPPORT_BIT|SMP_KP_SUPPORT_BIT) 151 152 #define SMP_AUTH_BOND SMP_AUTH_GEN_BOND 153 154 /* no MITM, No Bonding, encryption only */ 155 #define SMP_AUTH_NB_ENC_ONLY 0x00 //(SMP_AUTH_MASK | BTM_AUTH_SP_NO) 156 157 /* MITM, No Bonding, Use IO Capability to determine authentication procedure */ 158 #define SMP_AUTH_NB_IOCAP (SMP_AUTH_NO_BOND | SMP_AUTH_YN_BIT) 159 160 /* No MITM, General Bonding, Encryption only */ 161 #define SMP_AUTH_GB_ENC_ONLY (SMP_AUTH_GEN_BOND ) 162 163 /* MITM, General Bonding, Use IO Capability to determine authentication procedure */ 164 #define SMP_AUTH_GB_IOCAP (SMP_AUTH_GEN_BOND | SMP_AUTH_YN_BIT) 165 166 /* Secure Connections, no MITM, no Bonding */ 167 #define SMP_AUTH_SC_ENC_ONLY (SMP_SC_SUPPORT_BIT) 168 169 /* Secure Connections, no MITM, Bonding */ 170 #define SMP_AUTH_SC_GB (SMP_SC_SUPPORT_BIT | SMP_AUTH_GEN_BOND) 171 172 /* Secure Connections, MITM, no Bonding */ 173 #define SMP_AUTH_SC_MITM_NB (SMP_SC_SUPPORT_BIT | SMP_AUTH_YN_BIT | SMP_AUTH_NO_BOND) 174 175 /* Secure Connections, MITM, Bonding */ 176 #define SMP_AUTH_SC_MITM_GB (SMP_SC_SUPPORT_BIT | SMP_AUTH_YN_BIT | SMP_AUTH_GEN_BOND) 177 178 /* All AuthReq RFU bits are set to 1 - NOTE: reserved bit in Bonding_Flags is not set */ 179 #define SMP_AUTH_ALL_RFU_SET 0xF8 180 181 typedef UINT8 tSMP_AUTH_REQ; 182 183 #define SMP_SEC_NONE 0 184 #define SMP_SEC_UNAUTHENTICATE (1 << 0) 185 #define SMP_SEC_AUTHENTICATED (1 << 2) 186 typedef UINT8 tSMP_SEC_LEVEL; 187 188 /* Maximum Encryption Key Size range */ 189 #define SMP_ENCR_KEY_SIZE_MIN 7 190 #define SMP_ENCR_KEY_SIZE_MAX 16 191 192 /* SMP key types */ 193 #define SMP_SEC_KEY_TYPE_ENC (1 << 0) /* encryption key */ 194 #define SMP_SEC_KEY_TYPE_ID (1 << 1) /* identity key */ 195 #define SMP_SEC_KEY_TYPE_CSRK (1 << 2) /* slave CSRK */ 196 #define SMP_SEC_KEY_TYPE_LK (1 << 3) /* BR/EDR link key */ 197 typedef UINT8 tSMP_KEYS; 198 199 #define SMP_BR_SEC_DEFAULT_KEY (SMP_SEC_KEY_TYPE_ENC | SMP_SEC_KEY_TYPE_ID | \ 200 SMP_SEC_KEY_TYPE_CSRK) 201 202 /* default security key distribution value */ 203 #define SMP_SEC_DEFAULT_KEY (SMP_SEC_KEY_TYPE_ENC | SMP_SEC_KEY_TYPE_ID | \ 204 SMP_SEC_KEY_TYPE_CSRK | SMP_SEC_KEY_TYPE_LK) 205 206 #define SMP_SC_KEY_STARTED 0 /* passkey entry started */ 207 #define SMP_SC_KEY_ENTERED 1 /* passkey digit entered */ 208 #define SMP_SC_KEY_ERASED 2 /* passkey digit erased */ 209 #define SMP_SC_KEY_CLEARED 3 /* passkey cleared */ 210 #define SMP_SC_KEY_COMPLT 4 /* passkey entry completed */ 211 #define SMP_SC_KEY_OUT_OF_RANGE 5 /* out of range */ 212 typedef UINT8 tSMP_SC_KEY_TYPE; 213 214 /* data type for BTM_SP_IO_REQ_EVT */ 215 typedef struct 216 { 217 tSMP_IO_CAP io_cap; /* local IO capabilities */ 218 tSMP_OOB_FLAG oob_data; /* OOB data present (locally) for the peer device */ 219 tSMP_AUTH_REQ auth_req; /* Authentication required (for local device) */ 220 UINT8 max_key_size; /* max encryption key size */ 221 tSMP_KEYS init_keys; /* initiator keys to be distributed */ 222 tSMP_KEYS resp_keys; /* responder keys */ 223 } tSMP_IO_REQ; 224 225 typedef struct 226 { 227 tSMP_STATUS reason; 228 tSMP_SEC_LEVEL sec_level; 229 BOOLEAN is_pair_cancel; 230 BOOLEAN smp_over_br; 231 } tSMP_CMPL; 232 233 typedef struct 234 { 235 BT_OCTET32 x; 236 BT_OCTET32 y; 237 } tSMP_PUBLIC_KEY; 238 239 /* the data associated with the info sent to the peer via OOB interface */ 240 typedef struct 241 { 242 BOOLEAN present; 243 BT_OCTET16 randomizer; 244 BT_OCTET16 commitment; 245 246 tBLE_BD_ADDR addr_sent_to; 247 BT_OCTET32 private_key_used; /* is used to calculate: */ 248 /* publ_key_used = P-256(private_key_used, curve_p256.G) - send it to the */ 249 /* other side */ 250 /* dhkey = P-256(private_key_used, publ key rcvd from the other side) */ 251 tSMP_PUBLIC_KEY publ_key_used; /* P-256(private_key_used, curve_p256.G) */ 252 } tSMP_LOC_OOB_DATA; 253 254 /* the data associated with the info received from the peer via OOB interface */ 255 typedef struct 256 { 257 BOOLEAN present; 258 BT_OCTET16 randomizer; 259 BT_OCTET16 commitment; 260 tBLE_BD_ADDR addr_rcvd_from; 261 } tSMP_PEER_OOB_DATA; 262 263 typedef struct 264 { 265 tSMP_LOC_OOB_DATA loc_oob_data; 266 tSMP_PEER_OOB_DATA peer_oob_data; 267 } tSMP_SC_OOB_DATA; 268 269 270 typedef union 271 { 272 UINT32 passkey; 273 tSMP_IO_REQ io_req; /* IO request */ 274 tSMP_CMPL cmplt; 275 tSMP_OOB_DATA_TYPE req_oob_type; 276 tSMP_LOC_OOB_DATA loc_oob_data; 277 }tSMP_EVT_DATA; 278 279 280 /* AES Encryption output */ 281 typedef struct 282 { 283 UINT8 status; 284 UINT8 param_len; 285 UINT16 opcode; 286 UINT8 param_buf[BT_OCTET16_LEN]; 287 } tSMP_ENC; 288 289 /* Security Manager events - Called by the stack when Security Manager related events occur.*/ 290 typedef UINT8 (tSMP_CALLBACK) (tSMP_EVT event, BD_ADDR bd_addr, tSMP_EVT_DATA *p_data); 291 292 /* callback function for CMAC algorithm 293 */ 294 typedef void (tCMAC_CMPL_CBACK)(UINT8 *p_mac, UINT16 tlen, UINT32 sign_counter); 295 296 /***************************************************************************** 297 ** External Function Declarations 298 *****************************************************************************/ 299 #ifdef __cplusplus 300 extern "C" 301 { 302 #endif 303 /* API of SMP */ 304 305 /******************************************************************************* 306 ** 307 ** Function SMP_Init 308 ** 309 ** Description This function initializes the SMP unit. 310 ** 311 ** Returns void 312 ** 313 *******************************************************************************/ 314 extern void SMP_Init(void); 315 316 /******************************************************************************* 317 ** 318 ** Function SMP_SetTraceLevel 319 ** 320 ** Description This function sets the trace level for SMP. If called with 321 ** a value of 0xFF, it simply returns the current trace level. 322 ** 323 ** Returns The new or current trace level 324 ** 325 *******************************************************************************/ 326 extern UINT8 SMP_SetTraceLevel (UINT8 new_level); 327 328 /******************************************************************************* 329 ** 330 ** Function SMP_Register 331 ** 332 ** Description This function register for the SMP service callback. 333 ** 334 ** Returns void 335 ** 336 *******************************************************************************/ 337 extern BOOLEAN SMP_Register (tSMP_CALLBACK *p_cback); 338 339 /******************************************************************************* 340 ** 341 ** Function SMP_Pair 342 ** 343 ** Description This function is called to start a SMP pairing. 344 ** 345 ** Returns SMP_STARTED if bond started, else otherwise exception. 346 ** 347 *******************************************************************************/ 348 extern tSMP_STATUS SMP_Pair (BD_ADDR bd_addr); 349 350 /******************************************************************************* 351 ** 352 ** Function SMP_BR_PairWith 353 ** 354 ** Description This function is called to start a SMP pairing over BR/EDR. 355 ** 356 ** Returns SMP_STARTED if pairing started, otherwise reason for failure. 357 ** 358 *******************************************************************************/ 359 extern tSMP_STATUS SMP_BR_PairWith (BD_ADDR bd_addr); 360 361 /******************************************************************************* 362 ** 363 ** Function SMP_PairCancel 364 ** 365 ** Description This function is called to cancel a SMP pairing. 366 ** 367 ** Returns TRUE - pairing cancelled 368 ** 369 *******************************************************************************/ 370 extern BOOLEAN SMP_PairCancel (BD_ADDR bd_addr); 371 372 /******************************************************************************* 373 ** 374 ** Function SMP_SecurityGrant 375 ** 376 ** Description This function is called to grant security process. 377 ** 378 ** Parameters bd_addr - peer device bd address. 379 ** res - result of the operation SMP_SUCCESS if success. 380 ** Otherwise, SMP_REPEATED_ATTEMPTS is too many attempts. 381 ** 382 ** Returns None 383 ** 384 *******************************************************************************/ 385 extern void SMP_SecurityGrant(BD_ADDR bd_addr, UINT8 res); 386 387 /******************************************************************************* 388 ** 389 ** Function SMP_PasskeyReply 390 ** 391 ** Description This function is called after Security Manager submitted 392 ** Passkey request to the application. 393 ** 394 ** Parameters: bd_addr - Address of the device for which PIN was requested 395 ** res - result of the operation SMP_SUCCESS if success 396 ** passkey - numeric value in the range of 397 ** BTM_MIN_PASSKEY_VAL(0) - BTM_MAX_PASSKEY_VAL(999999(0xF423F)). 398 ** 399 *******************************************************************************/ 400 extern void SMP_PasskeyReply (BD_ADDR bd_addr, UINT8 res, UINT32 passkey); 401 402 /******************************************************************************* 403 ** 404 ** Function SMP_ConfirmReply 405 ** 406 ** Description This function is called after Security Manager submitted 407 ** numeric comparison request to the application. 408 ** 409 ** Parameters: bd_addr - Address of the device with which numeric 410 ** comparison was requested 411 ** res - comparison result SMP_SUCCESS if success 412 ** 413 *******************************************************************************/ 414 extern void SMP_ConfirmReply (BD_ADDR bd_addr, UINT8 res); 415 416 /******************************************************************************* 417 ** 418 ** Function SMP_OobDataReply 419 ** 420 ** Description This function is called to provide the OOB data for 421 ** SMP in response to SMP_OOB_REQ_EVT 422 ** 423 ** Parameters: bd_addr - Address of the peer device 424 ** res - result of the operation SMP_SUCCESS if success 425 ** p_data - SM Randomizer C. 426 ** 427 *******************************************************************************/ 428 extern void SMP_OobDataReply(BD_ADDR bd_addr, tSMP_STATUS res, UINT8 len, 429 UINT8 *p_data); 430 431 /******************************************************************************* 432 ** 433 ** Function SMP_SecureConnectionOobDataReply 434 ** 435 ** Description This function is called to provide the SC OOB data for 436 ** SMP in response to SMP_SC_OOB_REQ_EVT 437 ** 438 ** Parameters: p_data - pointer to the data 439 ** 440 *******************************************************************************/ 441 extern void SMP_SecureConnectionOobDataReply(UINT8 *p_data); 442 443 /******************************************************************************* 444 ** 445 ** Function SMP_Encrypt 446 ** 447 ** Description This function is called to encrypt the data with the specified 448 ** key 449 ** 450 ** Parameters: key - Pointer to key key[0] conatins the MSB 451 ** key_len - key length 452 ** plain_text - Pointer to data to be encrypted 453 ** plain_text[0] conatins the MSB 454 ** pt_len - plain text length 455 ** p_out - pointer to the encrypted outputs 456 ** 457 ** Returns Boolean - TRUE: encryption is successful 458 *******************************************************************************/ 459 extern BOOLEAN SMP_Encrypt (UINT8 *key, UINT8 key_len, 460 UINT8 *plain_text, UINT8 pt_len, 461 tSMP_ENC *p_out); 462 463 /******************************************************************************* 464 ** 465 ** Function SMP_KeypressNotification 466 ** 467 ** Description This function is called to notify SM about Keypress Notification. 468 ** 469 ** Parameters: bd_addr - Address of the device to send keypress 470 ** notification to 471 ** value - keypress notification parameter value 472 ** 473 *******************************************************************************/ 474 extern void SMP_KeypressNotification (BD_ADDR bd_addr, UINT8 value); 475 476 /******************************************************************************* 477 ** 478 ** Function SMP_CreateLocalSecureConnectionsOobData 479 ** 480 ** Description This function is called to start creation of local SC OOB 481 ** data set (tSMP_LOC_OOB_DATA). 482 ** 483 ** Parameters: bd_addr - Address of the device to send OOB data block 484 ** to. 485 ** 486 ** Returns Boolean - TRUE: creation of local SC OOB data set started. 487 *******************************************************************************/ 488 extern BOOLEAN SMP_CreateLocalSecureConnectionsOobData ( 489 tBLE_BD_ADDR *addr_to_send_to); 490 491 #ifdef __cplusplus 492 } 493 #endif 494 #endif /* SMP_API_H */ 495