1 /****************************************************************************** 2 * 3 * Copyright 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 functions for the Bluetooth Security Manager 22 * 23 ******************************************************************************/ 24 25 #pragma once 26 #include <cstdint> 27 #include <string> 28 29 #include "stack/btm/security_device_record.h" 30 #include "stack/include/bt_device_type.h" 31 #include "stack/include/bt_octets.h" 32 #include "stack/include/btm_sec_api_types.h" 33 #include "stack/include/btm_status.h" 34 #include "stack/include/hci_error_code.h" 35 #include "stack/include/security_client_callbacks.h" 36 #include "stack/include/smp_api_types.h" 37 #include "types/ble_address_with_type.h" 38 #include "types/bt_transport.h" 39 #include "types/hci_role.h" 40 #include "types/raw_address.h" 41 42 #define BTM_SEC_MAX_COLLISION_DELAY (5000) 43 44 /******************************************************************************* 45 * 46 * Function BTM_SecRegister 47 * 48 * Description Application manager calls this function to register for 49 * security services. There can be one and only one 50 * application saving link keys. BTM allows only first 51 * registration. 52 * 53 * Returns true if registered OK, else false 54 * 55 ******************************************************************************/ 56 bool BTM_SecRegister(const tBTM_APPL_INFO* p_cb_info); 57 58 bool BTM_IsEncrypted(const RawAddress& bd_addr, tBT_TRANSPORT transport); 59 bool BTM_IsLinkKeyAuthed(const RawAddress& bd_addr, tBT_TRANSPORT transport); 60 bool BTM_IsLinkKeyKnown(const RawAddress& bd_addr, tBT_TRANSPORT transport); 61 bool BTM_IsAuthenticated(const RawAddress& bd_addr, tBT_TRANSPORT transport); 62 bool BTM_CanReadDiscoverableCharacteristics(const RawAddress& bd_addr); 63 64 /******************************************************************************* 65 * 66 * Function BTM_SetPinType 67 * 68 * Description Set PIN type for the device. 69 * 70 * Returns void 71 * 72 ******************************************************************************/ 73 void BTM_SetPinType(uint8_t pin_type, PIN_CODE pin_code, uint8_t pin_code_len); 74 75 /******************************************************************************* 76 * 77 * Function BTM_SetSecurityLevel 78 * 79 * Description Register service security level with Security Manager 80 * 81 * Parameters: is_originator - true if originating the connection 82 * p_name - Name of the service relevant only if 83 * authorization will show this name to user. 84 * Ignored if BT_MAX_SERVICE_NAME_LEN is 0. 85 * service_id - service ID for the service passed to 86 * authorization callback 87 * sec_level - bit mask of the security features 88 * psm - L2CAP PSM 89 * mx_proto_id - protocol ID of multiplexing proto below 90 * mx_chan_id - channel ID of multiplexing proto below 91 * 92 * Returns true if registered OK, else false 93 * 94 ******************************************************************************/ 95 bool BTM_SetSecurityLevel(bool is_originator, const char* p_name, uint8_t service_id, 96 uint16_t sec_level, uint16_t psm, uint32_t mx_proto_id, 97 uint32_t mx_chan_id); 98 99 /******************************************************************************* 100 * 101 * Function BTM_SecClrService 102 * 103 * Description Removes specified service record(s) from the security 104 * database. All service records with the specified name are 105 * removed. Typically used only by devices with limited RAM so 106 * that it can reuse an old security service record. 107 * 108 * Note: Unpredictable results may occur if a service is 109 * cleared that is still in use by an application/profile. 110 * 111 * Parameters Service ID - Id of the service to remove. '0' removes all 112 * service records (except SDP). 113 * 114 * Returns Number of records that were freed. 115 * 116 ******************************************************************************/ 117 uint8_t BTM_SecClrService(uint8_t service_id); 118 119 /******************************************************************************* 120 * 121 * Function BTM_SecClrServiceByPsm 122 * 123 * Description Removes specified service record from the security database. 124 * All service records with the specified psm are removed. 125 * Typically used by L2CAP to free up the service record used 126 * by dynamic PSM clients when the channel is closed. 127 * The given psm must be a virtual psm. 128 * 129 * Parameters Service ID - Id of the service to remove. '0' removes all 130 * service records (except SDP). 131 * 132 * Returns Number of records that were freed. 133 * 134 ******************************************************************************/ 135 uint8_t BTM_SecClrServiceByPsm(uint16_t psm); 136 137 /******************************************************************************* 138 * 139 * Function BTM_PINCodeReply 140 * 141 * Description This function is called after Security Manager submitted 142 * PIN code request to the UI. 143 * 144 * Parameters: bd_addr - Address of the device for which PIN was 145 * requested 146 * res - result of the operation tBTM_STATUS::BTM_SUCCESS 147 * if success 148 * pin_len - length in bytes of the PIN Code 149 * p_pin - pointer to array with the PIN Code 150 * 151 ******************************************************************************/ 152 void BTM_PINCodeReply(const RawAddress& bd_addr, tBTM_STATUS res, uint8_t pin_len, uint8_t* p_pin); 153 154 /******************************************************************************* 155 * 156 * Function btm_sec_bond_by_transport 157 * 158 * Description this is the bond function that will start either SSP or SMP. 159 * 160 * Parameters: bd_addr - Address of the device to bond 161 * pin_len - length in bytes of the PIN Code 162 * p_pin - pointer to array with the PIN Code 163 * 164 * Note: After 2.1 parameters are not used and preserved here not to change API 165 ******************************************************************************/ 166 tBTM_STATUS btm_sec_bond_by_transport(const RawAddress& bd_addr, tBLE_ADDR_TYPE addr_type, 167 tBT_TRANSPORT transport); 168 169 /******************************************************************************* 170 * 171 * Function BTM_SecBond 172 * 173 * Description This function is called to perform bonding with peer device. 174 * If the connection is already up, but not secure, pairing 175 * is attempted. If already paired tBTM_STATUS::BTM_SUCCESS is returned. 176 * 177 * Parameters: bd_addr - Address of the device to bond 178 * transport - doing SSP over BR/EDR or SMP over LE 179 * 180 * Note: After 2.1 parameters are not used and preserved here not to change API 181 ******************************************************************************/ 182 tBTM_STATUS BTM_SecBond(const RawAddress& bd_addr, tBLE_ADDR_TYPE addr_type, 183 tBT_TRANSPORT transport, tBT_DEVICE_TYPE device_type); 184 185 /******************************************************************************* 186 * 187 * Function BTM_SecBondCancel 188 * 189 * Description This function is called to cancel ongoing bonding process 190 * with peer device. 191 * 192 * Parameters: bd_addr - Address of the peer device 193 * transport - false for BR/EDR link; true for LE link 194 * 195 ******************************************************************************/ 196 tBTM_STATUS BTM_SecBondCancel(const RawAddress& bd_addr); 197 198 /******************************************************************************* 199 * 200 * Function BTM_SecGetDeviceLinkKeyType 201 * 202 * Description This function is called to obtain link key type for the 203 * device. 204 * it returns tBTM_STATUS::BTM_SUCCESS if link key is available, or 205 * tBTM_STATUS::BTM_UNKNOWN_ADDR if Security Manager does not know about 206 * the device or device record does not contain link key info 207 * 208 * Returns BTM_LKEY_TYPE_IGNORE if link key is unknown, link type 209 * otherwise. 210 * 211 ******************************************************************************/ 212 tBTM_LINK_KEY_TYPE BTM_SecGetDeviceLinkKeyType(const RawAddress& bd_addr); 213 214 /******************************************************************************* 215 * 216 * Function BTM_SetEncryption 217 * 218 * Description This function is called to ensure that connection is 219 * encrypted. Should be called only on an open connection. 220 * Typically only needed for connections that first want to 221 * bring up unencrypted links, then later encrypt them. 222 * 223 * Parameters: bd_addr - Address of the peer device 224 * transport - Link transport 225 * p_callback - Pointer to callback function called if 226 * this function returns PENDING after required 227 * procedures are completed. Can be set to 228 * NULL if status is not desired. 229 * p_ref_data - pointer to any data the caller wishes to 230 * receive in the callback function upon 231 * completion. can be set to NULL if not used. 232 * sec_act - LE security action, unused for BR/EDR 233 * 234 * Returns tBTM_STATUS::BTM_SUCCESS - already encrypted 235 * BTM_PENDING - command will be returned in the callback 236 * tBTM_STATUS::BTM_WRONG_MODE- connection not up. 237 * tBTM_STATUS::BTM_BUSY - security procedures are currently active 238 * tBTM_STATUS::BTM_ERR_KEY_MISSING - link key is missing. 239 * tBTM_STATUS::BTM_MODE_UNSUPPORTED - if security manager not linked in. 240 * 241 ******************************************************************************/ 242 tBTM_STATUS BTM_SetEncryption(const RawAddress& bd_addr, tBT_TRANSPORT transport, 243 tBTM_SEC_CALLBACK* p_callback, void* p_ref_data, 244 tBTM_BLE_SEC_ACT sec_act); 245 246 bool BTM_SecIsSecurityPending(const RawAddress& bd_addr); 247 248 /******************************************************************************* 249 * 250 * Function BTM_ConfirmReqReply 251 * 252 * Description This function is called to confirm the numeric value for 253 * Simple Pairing in response to BTM_SP_CFM_REQ_EVT 254 * 255 * Parameters: res - result of the operation tBTM_STATUS::BTM_SUCCESS if 256 * success 257 * bd_addr - Address of the peer device 258 * 259 ******************************************************************************/ 260 void BTM_ConfirmReqReply(tBTM_STATUS res, const RawAddress& bd_addr); 261 262 /******************************************************************************* 263 * 264 * Function BTM_PasskeyReqReply 265 * 266 * Description This function is called to provide the passkey for 267 * Simple Pairing in response to BTM_SP_KEY_REQ_EVT 268 * 269 * Parameters: res - result of the operation tBTM_STATUS::BTM_SUCCESS if success 270 * bd_addr - Address of the peer device 271 * passkey - numeric value in the range of 272 * BTM_MIN_PASSKEY_VAL(0) - 273 * BTM_MAX_PASSKEY_VAL(999999(0xF423F)). 274 * 275 ******************************************************************************/ 276 void BTM_PasskeyReqReply(tBTM_STATUS res, const RawAddress& bd_addr, uint32_t passkey); 277 278 /******************************************************************************* 279 * 280 * Function BTM_ReadLocalOobData 281 * 282 * Description This function is called to read the local OOB data from 283 * LM 284 * 285 ******************************************************************************/ 286 void BTM_ReadLocalOobData(void); 287 288 /******************************************************************************* 289 * 290 * Function BTM_RemoteOobDataReply 291 * 292 * Description This function is called to provide the remote OOB data for 293 * Simple Pairing in response to BTM_SP_RMT_OOB_EVT 294 * 295 * Parameters: bd_addr - Address of the peer device 296 * c - simple pairing Hash C. 297 * r - simple pairing Randomizer C. 298 * 299 ******************************************************************************/ 300 void BTM_RemoteOobDataReply(tBTM_STATUS res, const RawAddress& bd_addr, const Octet16& c, 301 const Octet16& r); 302 303 /******************************************************************************* 304 * 305 * Function BTM_PeerSupportsSecureConnections 306 * 307 * Description This function is called to check if the peer supports 308 * BR/EDR Secure Connections. 309 * 310 * Parameters: bd_addr - address of the peer 311 * 312 * Returns true if BR/EDR Secure Connections are supported by the peer, 313 * else false. 314 * 315 ******************************************************************************/ 316 bool BTM_PeerSupportsSecureConnections(const RawAddress& bd_addr); 317 318 /******************************************************************************* 319 * 320 * Function BTM_GetInitialSecurityMode 321 * 322 * Description This function is called to retrieve the configured 323 * security mode. 324 * 325 ******************************************************************************/ 326 uint8_t BTM_GetSecurityMode(); 327 328 /******************************************************************************* 329 * 330 * Function btm_sec_l2cap_access_req 331 * 332 * Description This function is called by the L2CAP to grant permission to 333 * establish L2CAP connection to or from the peer device. 334 * 335 * Parameters: bd_addr - Address of the peer device 336 * psm - L2CAP PSM 337 * is_originator - true if protocol above L2CAP originates 338 * connection 339 * p_callback - Pointer to callback function called if 340 * this function returns PENDING after required 341 * procedures are complete. MUST NOT BE NULL. 342 * 343 * Returns tBTM_STATUS 344 * 345 ******************************************************************************/ 346 tBTM_STATUS btm_sec_l2cap_access_req(const RawAddress& bd_addr, uint16_t psm, bool is_originator, 347 tBTM_SEC_CALLBACK* p_callback, void* p_ref_data); 348 349 // Allow enforcing security by specific requirement (from shim layer). 350 tBTM_STATUS btm_sec_l2cap_access_req_by_requirement(const RawAddress& bd_addr, 351 uint16_t security_required, bool is_originator, 352 tBTM_SEC_CALLBACK* p_callback, 353 void* p_ref_data); 354 355 /******************************************************************************* 356 * 357 * Function btm_sec_mx_access_request 358 * 359 * Description This function is called by all Multiplexing Protocols 360 *during establishing connection to or from peer device to grant permission 361 *to establish application connection. 362 * 363 * Parameters: bd_addr - Address of the peer device 364 * psm - L2CAP PSM 365 * is_originator - true if protocol above L2CAP originates 366 * connection 367 * mx_proto_id - protocol ID of the multiplexer 368 * mx_chan_id - multiplexer channel to reach application 369 * p_callback - Pointer to callback function called if 370 * this function returns PENDING after 371 *required procedures are completed p_ref_data - Pointer to any reference 372 *data needed by the the callback function. 373 * 374 * Returns tBTM_STATUS::BTM_CMD_STARTED 375 * 376 ******************************************************************************/ 377 tBTM_STATUS btm_sec_mx_access_request(const RawAddress& bd_addr, bool is_originator, 378 uint16_t security_requirement, tBTM_SEC_CALLBACK* p_callback, 379 void* p_ref_data); 380 381 /******************************************************************************* 382 * 383 * Function btm_sec_conn_req 384 * 385 * Description This function is when the peer device is requesting 386 * connection 387 * 388 * Returns void 389 * 390 ******************************************************************************/ 391 void btm_sec_conn_req(const RawAddress& bda, const DEV_CLASS dc); 392 393 /******************************************************************************* 394 * 395 * Function btm_create_conn_cancel_complete 396 * 397 * Description This function is called when the command complete message 398 * is received from the HCI for the create connection cancel 399 * command. 400 * 401 * Returns void 402 * 403 ******************************************************************************/ 404 void btm_create_conn_cancel_complete(uint8_t status, const RawAddress bd_addr, uint32_t value); 405 406 /******************************************************************************* 407 * 408 * Function btm_sec_dev_reset 409 * 410 * Description This function should be called after device reset 411 * 412 * Returns void 413 * 414 ******************************************************************************/ 415 void btm_sec_dev_reset(void); 416 417 /******************************************************************************* 418 * 419 * Function btm_sec_abort_access_req 420 * 421 * Description This function is called by the L2CAP or RFCOMM to abort 422 * the pending operation. 423 * 424 * Parameters: bd_addr - Address of the peer device 425 * 426 * Returns void 427 * 428 ******************************************************************************/ 429 void btm_sec_abort_access_req(const RawAddress& bd_addr); 430 431 /******************************************************************************* 432 * 433 * Function btm_sec_rmt_name_request_complete 434 * 435 * Description This function is called when remote name was obtained from 436 * the peer device 437 * 438 * Returns void 439 * 440 ******************************************************************************/ 441 void btm_sec_rmt_name_request_complete(const RawAddress* p_bd_addr, const uint8_t* p_bd_name, 442 tHCI_STATUS status); 443 444 /******************************************************************************* 445 * 446 * Function btm_sec_rmt_host_support_feat_evt 447 * 448 * Description This function is called when the 449 * HCI_RMT_HOST_SUP_FEAT_NOTIFY_EVT is received 450 * 451 * Returns void 452 * 453 ******************************************************************************/ 454 void btm_sec_rmt_host_support_feat_evt(const RawAddress bd_addr, uint8_t features_0); 455 456 /******************************************************************************* 457 * 458 * Function btm_io_capabilities_req 459 * 460 * Description This function is called when LM request for the IO 461 * capability of the local device and 462 * if the OOB data is present for the device in the event 463 * 464 * Returns void 465 * 466 ******************************************************************************/ 467 void btm_io_capabilities_req(RawAddress p); 468 469 /******************************************************************************* 470 * 471 * Function btm_io_capabilities_rsp 472 * 473 * Description This function is called when the IO capability of the 474 * specified device is received 475 * 476 * Returns void 477 * 478 ******************************************************************************/ 479 void btm_io_capabilities_rsp(const tBTM_SP_IO_RSP evt_data); 480 481 /******************************************************************************* 482 * 483 * Function btm_proc_sp_req_evt 484 * 485 * Description This function is called to process/report 486 * HCI_USER_CONFIRMATION_REQUEST_EVT 487 * or HCI_USER_PASSKEY_REQUEST_EVT 488 * or HCI_USER_PASSKEY_NOTIFY_EVT 489 * 490 * Returns void 491 * 492 ******************************************************************************/ 493 void btm_proc_sp_req_evt(tBTM_SP_EVT event, const RawAddress bda, uint32_t value); 494 495 /******************************************************************************* 496 * 497 * Function btm_simple_pair_complete 498 * 499 * Description This function is called when simple pairing process is 500 * complete 501 * 502 * Returns void 503 * 504 ******************************************************************************/ 505 void btm_simple_pair_complete(const RawAddress bd_addr, uint8_t status); 506 507 /******************************************************************************* 508 * 509 * Function btm_rem_oob_req 510 * 511 * Description This function is called to process/report 512 * HCI_REMOTE_OOB_DATA_REQUEST_EVT 513 * 514 * Returns void 515 * 516 ******************************************************************************/ 517 void btm_rem_oob_req(const RawAddress bd_addr); 518 519 /******************************************************************************* 520 * 521 * Function btm_read_local_oob_complete 522 * 523 * Description This function is called when read local oob data is 524 * completed by the LM 525 * 526 * Returns void 527 * 528 ******************************************************************************/ 529 void btm_read_local_oob_complete(const tBTM_SP_LOC_OOB evt_data); 530 531 /******************************************************************************* 532 * 533 * Function btm_sec_auth_complete 534 * 535 * Description This function is when authentication of the connection is 536 * completed by the LM 537 * 538 * Returns void 539 * 540 ******************************************************************************/ 541 void btm_sec_auth_complete(uint16_t handle, tHCI_STATUS status); 542 543 /******************************************************************************* 544 * 545 * Function btm_sec_encryption_change_evt 546 * 547 * Description This function is called to process an encryption change. 548 * 549 * Returns void 550 * 551 ******************************************************************************/ 552 void btm_sec_encryption_change_evt(uint16_t handle, tHCI_STATUS status, uint8_t encr_enable, 553 uint8_t key_size); 554 555 /******************************************************************************* 556 * 557 * Function btm_sec_encrypt_change 558 * 559 * Description This function is when encryption of the connection is 560 * completed by the LM 561 * 562 * Returns void 563 * 564 ******************************************************************************/ 565 void btm_sec_encrypt_change(uint16_t handle, tHCI_STATUS status, uint8_t encr_enable, 566 uint8_t key_size, bool from_key_refresh); 567 568 /******************************************************************************* 569 * 570 * Function btm_sec_connected 571 * 572 * Description This function is when a connection to the peer device is 573 * established 574 * 575 * Returns void 576 * 577 ******************************************************************************/ 578 void btm_sec_connected(const RawAddress& bda, uint16_t handle, tHCI_STATUS status, uint8_t enc_mode, 579 tHCI_ROLE assigned_role = HCI_ROLE_PERIPHERAL); 580 581 /******************************************************************************* 582 * 583 * Function btm_sec_disconnect 584 * 585 * Description This function is called to disconnect HCI link 586 * 587 * Returns btm status 588 * 589 ******************************************************************************/ 590 tBTM_STATUS btm_sec_disconnect(uint16_t handle, tHCI_STATUS reason, std::string); 591 592 /******************************************************************************* 593 * 594 * Function btm_sec_disconnected 595 * 596 * Description This function is when a connection to the peer device is 597 * dropped 598 * 599 * Returns void 600 * 601 ******************************************************************************/ 602 void btm_sec_disconnected(uint16_t handle, tHCI_STATUS reason, std::string comment); 603 604 /******************************************************************************* 605 * 606 * Function btm_sec_role_changed 607 * 608 * Description This function is called when receiving an HCI role change 609 * event 610 * 611 * Returns void 612 * 613 ******************************************************************************/ 614 void btm_sec_role_changed(tHCI_STATUS hci_status, const RawAddress& bd_addr, tHCI_ROLE new_role); 615 616 /** This function is called when a new connection link key is generated */ 617 void btm_sec_link_key_notification(const RawAddress& p_bda, const Octet16& link_key, 618 uint8_t key_type); 619 620 /** This function is called for each encryption key refresh complete event */ 621 void btm_sec_encryption_key_refresh_complete(uint16_t handle, tHCI_STATUS status); 622 623 /******************************************************************************* 624 * 625 * Function btm_sec_link_key_request 626 * 627 * Description This function is called when controller requests link key 628 * 629 * Returns Pointer to the record or NULL 630 * 631 ******************************************************************************/ 632 void btm_sec_link_key_request(const RawAddress bda); 633 634 /******************************************************************************* 635 * 636 * Function btm_sec_pin_code_request 637 * 638 * Description This function is called when controller requests PIN code 639 * 640 * Returns Pointer to the record or NULL 641 * 642 ******************************************************************************/ 643 void btm_sec_pin_code_request(const RawAddress bda); 644 645 /******************************************************************************* 646 * 647 * Function btm_sec_update_clock_offset 648 * 649 * Description This function is called to update clock offset 650 * 651 * Returns void 652 * 653 ******************************************************************************/ 654 void btm_sec_update_clock_offset(uint16_t handle, uint16_t clock_offset); 655 656 /******************************************************************************* 657 * 658 * Function btm_sec_dev_rec_cback_event 659 * 660 * Description This function calls the callback function with the given 661 * result and clear the callback function. 662 * 663 * Parameters: void 664 * 665 ******************************************************************************/ 666 void btm_sec_dev_rec_cback_event(tBTM_SEC_DEV_REC* p_dev_rec, tBTM_STATUS res, 667 bool is_le_transport); 668 669 /******************************************************************************* 670 * 671 * Function btm_sec_clear_ble_keys 672 * 673 * Description This function is called to clear out the BLE keys. 674 * Typically when devices are removed in BTM_SecDeleteDevice, 675 * or when a new BT Link key is generated. 676 * 677 * Returns void 678 * 679 ******************************************************************************/ 680 void btm_sec_clear_ble_keys(tBTM_SEC_DEV_REC* p_dev_rec); 681 682 /******************************************************************************* 683 * 684 * Function btm_sec_is_a_bonded_dev 685 * 686 * Description Is the specified device is a bonded device 687 * 688 * Returns true - dev is bonded 689 * 690 ******************************************************************************/ 691 bool btm_sec_is_a_bonded_dev(const RawAddress& bda); 692 693 /******************************************************************************* 694 * 695 * Function btm_sec_set_peer_sec_caps 696 * 697 * Description This function is called to set sm4 and rmt_sec_caps fields 698 * based on the available peer device features. 699 * 700 * Returns void 701 * 702 ******************************************************************************/ 703 void btm_sec_set_peer_sec_caps(uint16_t hci_handle, bool ssp_supported, bool sc_supported, 704 bool hci_role_switch_supported, bool br_edr_supported, 705 bool le_supported); 706 707 /******************************************************************************* 708 * 709 * Function btm_sec_cr_loc_oob_data_cback_event 710 * 711 * Description This function is called to pass the local oob up to caller 712 * 713 * Returns void 714 * 715 ******************************************************************************/ 716 void btm_sec_cr_loc_oob_data_cback_event(const RawAddress& address, tSMP_LOC_OOB_DATA loc_oob_data); 717 718 // Return DEV_CLASS of bda. If record doesn't exist, create one. 719 DEV_CLASS btm_get_dev_class(const RawAddress& bda); 720