1 /****************************************************************************** 2 * Copyright (c) 2022 Telink Semiconductor (Shanghai) Co., Ltd. ("TELINK") 3 * All rights reserved. 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 #ifndef BLE_SMP_H_ 19 #define BLE_SMP_H_ 20 21 #include "stack/ble/ble_common.h" 22 23 /** @addtogroup SMP first pairing or connecting back definition 24 * @{ 25 */ 26 #define SMP_STANDARD_PAIR 0 27 #define SMP_FAST_CONNECT 1 28 /** @} end of group SMP first pairing or connecting back */ 29 30 /** @addtogroup SMP pairing fail reason definition 31 * @{ 32 */ 33 #define PAIRING_FAIL_REASON_PASSKEY_ENTRY 0x01 34 #define PAIRING_FAIL_REASON_OOB_NOT_AVAILABLE 0x02 35 #define PAIRING_FAIL_REASON_AUTH_REQUIRE 0x03 36 #define PAIRING_FAIL_REASON_CONFIRM_FAILED 0x04 37 #define PAIRING_FAIL_REASON_PAIRING_NOT_SUPPORTED 0x05 38 #define PAIRING_FAIL_REASON_ENCRYPT_KEY_SIZE 0x06 39 #define PAIRING_FAIL_REASON_CMD_NOT_SUPPORT 0x07 // -- core 4.2 40 #define PAIRING_FAIL_REASON_UNSPECIFIED_REASON 0x08 41 #define PAIRING_FAIL_REASON_REPEATED_ATTEMPT 0x09 42 #define PAIRING_FAIL_REASON_INVAILD_PARAMETER 0x0A 43 #define PAIRING_FAIL_REASON_DHKEY_CHECK_FAIL 0x0B 44 #define PAIRING_FAIL_REASON_NUMUERIC_FAILED 0x0C 45 #define PAIRING_FAIL_REASON_BREDR_PAIRING 0x0D 46 #define PAIRING_FAIL_REASON_CROSS_TRANSKEY_NOT_ALLOW 0x0E 47 #define PAIRING_FAIL_REASON_PAIRING_TIEMOUT 0x80 // TLK defined 48 #define PAIRING_FAIL_REASON_CONN_DISCONNECT 0x81 // TLK defined 49 #define PAIRING_FAIL_REASON_SUPPORT_NC_ONLY 0x82 // TLK defined 50 /** @} end of group SMP pairing fail reasone */ 51 52 // "SecReq" refer to "security request" 53 typedef enum { 54 SecReq_NOT_SEND = 0, // do not send "security request" after link layer connection established 55 SecReq_IMM_SEND = BIT( 56 0), // "IMM" refer to immediate, send "security request" immediately after link layer connection established 57 SecReq_PEND_SEND = BIT(1), // "PEND" refer to pending, pending "security request" for some time 58 // after link layer connection established, when pending time arrived. send it 59 } secReq_cfg; 60 61 // "PairReq" refer to "pairing request" 62 typedef enum { 63 PairReq_SEND_upon_SecReq = 0, // master send "pairing request" when received slave's "security request" 64 PairReq_AUTO_SEND = 1, // master send "pairing request" automatically, regardless of "security request" 65 } PairReq_cfg; 66 67 // See the Core_v5.0(Vol 3/Part C/10.2, Page 2067) for more information. 68 typedef enum { 69 LE_Security_Mode_1_Level_1 = BIT(0), 70 No_Authentication_No_Encryption = BIT(0), 71 No_Security = BIT(0), 72 LE_Security_Mode_1_Level_2 = BIT(1), 73 Unauthenticated_Pairing_with_Encryption = BIT(1), 74 LE_Security_Mode_1_Level_3 = BIT(2), 75 Authenticated_Pairing_with_Encryption = BIT(2), 76 LE_Security_Mode_1_Level_4 = BIT(3), 77 Authenticated_LE_Secure_Connection_Pairing_with_Encryption = BIT(3), 78 79 LE_Security_Mode_2_Level_1 = BIT(4), 80 Unauthenticated_Pairing_with_Data_Signing = BIT(4), 81 LE_Security_Mode_2_Level_2 = BIT(5), 82 Authenticated_Pairing_with_Data_Signing = BIT(5), 83 84 LE_Security_Mode_1 = (LE_Security_Mode_1_Level_1 | LE_Security_Mode_1_Level_2 | LE_Security_Mode_1_Level_3 | 85 LE_Security_Mode_1_Level_4) 86 } le_security_mode_level_t; 87 88 typedef enum { 89 non_debug_mode = 0, // ECDH distribute private/public key pairs 90 debug_mode = 1, // ECDH use debug mode private/public key pairs 91 } ecdh_keys_mode_t; 92 93 typedef enum { 94 Non_Bondable_Mode = 0, 95 Bondable_Mode = 1, 96 } bonding_mode_t; 97 98 // Pairing Methods select 99 // See the Core_v5.0(Vol 3/Part H/2.3) for more information. 100 typedef enum { 101 LE_Legacy_Pairing = 0, // BLE 4.0/4.2 102 LE_Secure_Connection = 1, // BLE 4.2/5.0/5.1 103 } pairing_methods_t; 104 105 typedef enum { 106 IO_CAPABILITY_UNKNOWN = 0xff, 107 IO_CAPABILITY_DISPLAY_ONLY = 0, 108 IO_CAPABILITY_DISPLAY_YES_NO = 1, 109 IO_CAPABILITY_KEYBOARD_ONLY = 2, 110 IO_CAPABILITY_NO_INPUT_NO_OUTPUT = 3, 111 IO_CAPABILITY_KEYBOARD_DISPLAY = 4, 112 } io_capability_t; 113 114 /** 115 * @brief This function is used to initialize each parameter configuration of SMP, 116 * including the initialization of the binding area FLASH. 117 * @param[in] none 118 * @return none 119 */ 120 void blc_smp_smpParamInit(void); 121 122 /** 123 * @brief This function is used to configure whether the slave sends a Security Request 124 * to the master immediately after the connection or after the connection is 125 * pending_ms milliseconds, or does not send the Security Request. 126 * @param[in] newConn_cfg - refer to "security request" 127 * @param[in] re_conn_cfg - refer to "security request" 128 * @param[in] pending_ms - Send a Security Request to the master after pending_ms milliseconds 129 * @return none. 130 */ 131 void blc_smp_configSecurityRequestSending(secReq_cfg newConn_cfg, secReq_cfg reConn_cfg, u16 pending_ms); 132 133 /** 134 * @brief This function is used to check whether active pairing or automatic connection back is required. 135 * @param[in] newConn_cfg - refer to "PairReq_cfg" 136 * @param[in] reConn_cfg - refer to "PairReq_cfg" 137 * @return none. 138 */ 139 void blc_smp_configPairingRequestSending(PairReq_cfg newConn_cfg, PairReq_cfg reConn_cfg); 140 141 /** 142 * @brief This function is used to set security level. 143 * @param[in] mode_level - The security level value can refer to the structure 'le_security_mode_level_t'. 144 * @return none. 145 */ 146 void blc_smp_setSecurityLevel(le_security_mode_level_t mode_level); 147 void blc_smp_setSecurityLevel_master(le_security_mode_level_t mode_level); 148 void blc_smp_setSecurityLevel_slave(le_security_mode_level_t mode_level); 149 150 /** 151 * @brief This function is used to set pairing method. 152 * @param[in] method - The pairing method value can refer to the structure 'pairing_methods_t'. 153 * 0: LE legacy pairing; 154 * 1: LE secure connection 155 * @return none. 156 */ 157 void blc_smp_setPairingMethods(pairing_methods_t method); 158 void blc_smp_setPairingMethods_master(pairing_methods_t method); // select pairing methods 159 void blc_smp_setPairingMethods_slave(pairing_methods_t method); // select pairing methods 160 161 /** 162 * @brief This function is used to set device's IO capability. 163 * @param[in] ioCapablility - The IO capability's value can refer to the structure 'io_capability_t'. 164 * @return none. 165 */ 166 void blc_smp_setIoCapability(io_capability_t ioCapablility); 167 void blc_smp_setIoCapability_master(io_capability_t ioCapablility); 168 void blc_smp_setIoCapability_slave(io_capability_t ioCapablility); 169 170 /** 171 * @brief This function is used to set if enable OOB authentication. 172 * @param[in] OOB_en - 0: Disable OOB authentication; 173 * 1: Enable OOB authentication. 174 * @return none. 175 */ 176 void blc_smp_enableOobAuthentication(int OOB_en); 177 void blc_smp_enableOobAuthentication_master(int OOB_en); 178 void blc_smp_enableOobAuthentication_slave(int OOB_en); 179 180 /** 181 * @brief This function is used to set bonding mode. 182 * @param[in] mode - The bonding mode value can refer to the structure 'bonding_mode_t'. 183 * 0: non bondable mode; 184 * 1: bondable mode. 185 * @return none. 186 */ 187 void blc_smp_setBondingMode(bonding_mode_t mode); 188 void blc_smp_setBondingMode_master(bonding_mode_t mode); 189 void blc_smp_setBondingMode_slave(bonding_mode_t mode); 190 191 /** 192 * @brief This function is used to set if enable authentication MITM protection. 193 * @param[in] MITM_en - 0: Disable MITM protection; 194 * 1: Enable MITM protection. 195 * @return none. 196 */ 197 void blc_smp_enableAuthMITM(int MITM_en); 198 void blc_smp_enableAuthMITM_master(int MITM_en); 199 void blc_smp_enableAuthMITM_slave(int MITM_en); 200 201 /** 202 * @brief This function is used to set device's Keypress. 203 * @param[in] keyPress_en - 0: Disable Keypress; 204 * 1: Enable Keypress. 205 * @return none. 206 */ 207 void blc_smp_enableKeypress(int keyPress_en); 208 void blc_smp_enableKeypress_master(int keyPress_en); 209 void blc_smp_enableKeypress_slave(int keyPress_en); 210 211 /** 212 * @brief This function is used to set whether the device uses the ECDH DEBUG key. 213 * @param[in] mode - The ECDH key mode value can refer to the structure 'ecdh_keys_mode_t'. 214 * 0: non debug mode; 215 * 1: debug mode. 216 * @return none. 217 */ 218 void blc_smp_setEcdhDebugMode(ecdh_keys_mode_t mode); 219 void blc_smp_setEcdhDebugMode_master(ecdh_keys_mode_t mode); 220 void blc_smp_setEcdhDebugMode_slave(ecdh_keys_mode_t mode); 221 222 /** 223 * @brief This function is used to set device's security parameters. 224 * @param[in] mode - The bonding mode value can refer to the structure 'bonding_mode_t'. 225 * @param[in] MITM_en - 0: Disable MITM protection; 1: Enable MITM protection. 226 * @param[in] method - 0: LE_Legacy_Pairing; 1: LE_Secure_Connection. 227 * @param[in] OOB_en - 0: Disable OOB authentication; 1: Enable OOB authentication. 228 * @param[in] keyPress_en - 0: Disable Keypress; 1: Enable Keypress. 229 * @param[in] ioCapablility - The IO capability's value can refer to the structure 'io_capability_t'. 230 * @return none. 231 */ 232 void blc_smp_setSecurityParameters(bonding_mode_t mode, int MITM_en, pairing_methods_t method, int OOB_en, 233 int keyPress_en, io_capability_t ioCapablility); 234 void blc_smp_setSecurityParameters_master(bonding_mode_t bond_mode, int MITM_en, pairing_methods_t method, int OOB_en, 235 int keyPress_en, io_capability_t ioCapablility); 236 void blc_smp_setSecurityParameters_slave(bonding_mode_t bond_mode, int MITM_en, pairing_methods_t method, int OOB_en, 237 int keyPress_en, io_capability_t ioCapablility); 238 239 /** 240 * @brief This function is used to set TK by OOB method. 241 * param[in] connHandle - Current ACL connection handle. 242 * @param[in] oobData - TK's value, size: 16 byte. 243 * @return none. 244 */ 245 u8 blc_smp_setTK_by_OOB(u16 connHandle, u8 *oobData); // used for set oob data 246 247 /** 248 * @brief This function is used to set TK by passkey entry method. 249 * param[in] connHandle - Current ACL connection handle. 250 * @param[in] pinCodeInput - TK's value, input range [000000, 999999]. 251 * @return none. 252 */ 253 u8 blc_smp_setTK_by_PasskeyEntry(u16 connHandle, u32 pinCodeInput); 254 255 /** 256 * @brief This function is used to set numeric compare confirm YES or NO. 257 * param[in] connHandle - Current ACL connection handle. 258 * @param[in] YES_or_NO - 1: numeric compare confirm YES; 259 * 0: numeric compare confirm NO. 260 * @return none. 261 */ 262 void blc_smp_setNumericComparisonResult(u16 connHandle, bool YES_or_NO); // numeric compare confirm, 1: YES 0: NO 263 264 /** 265 * @brief This function is used to check if the pairing is busy. 266 * @param[in] connHandle - Current ACL connection handle. 267 * @return 1:is pair busy 268 * 0:isn't pair busy 269 */ 270 int blc_smp_isPairingBusy(u16 connHandle); 271 272 /** 273 * @brief This function is used to check whether the PinCode needs to be input. 274 * @param[in] connHandle - Current ACL connection handle. 275 * @return 1: Need to enter PinCode 276 * 0: No need to enter PinCode 277 */ 278 u8 blc_smp_isWaitingToSetPasskeyEntry(u16 connHandle); 279 280 /** 281 * @brief This function is used to check whether it is needed to confirm NC YES/NO. 282 * @param[in] connHandle - Current ACL connection handle. 283 * @return 1: Need to confirm NC YES/NO 284 * 0: No need to confirm NC YES/NO 285 */ 286 u8 blc_smp_isWaitingToCfmNumericComparison(u16 connHandle); 287 288 /** 289 * @brief This function is used to enable/disable legacy LTK verification. 290 * @param[in] en - enable OR disable legacy LTK verification function. 291 * @return None 292 */ 293 void blc_smp_setLtkVerificationEnable(u8 en); 294 295 #endif /* BLE_SMP_H_ */ 296