1 /* 2 * Copyright (c) 2021 Chipsea Technologies (Shenzhen) Corp., Ltd. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 #ifndef _HAL_SMPC_H 16 #define _HAL_SMPC_H 17 18 /** 19 **************************************************************************************** 20 * @addtogroup SMP Security Manager Protocol 21 * @ingroup HOST 22 * @brief Security Manager Protocol. 23 * 24 * The SMP is responsible for the over-all security policies of BLE. 25 * It defines methods for pairing and key distribution, handles encryption, 26 * data signing and privacy features such as random addressing generation and resolution. 27 * 28 * Pairing is performed to exchange pairing features and generate a short term 29 * key for link encryption. 30 * A transport specific key distribution is performed to 31 * share the keys that can be used to encrypt the link in the future 32 * reconnection process, signed data verification and random address 33 * resolution. 34 * 35 * There exist 3 phases in the complete security procedure: 36 * 1. Feature exchange (IO capabilities, OOB flags, Authentication Requirements, Key distributions) 37 * 2. Short Term Key generation 38 * Generation method depends on exchanged features: 39 * - Just Works - use Temporary key = 0 40 * - PassKey Entry - use Temporary Key = 6-digit provided by user 41 * - Out of Band (OOB) - use Temporary Key = 16-octet key, available form OOB source 42 * 3. Transport Specific Key Distribution (TKDP)(LTK+EDIV+RAND_NB, IRK+ADDR, CSRK) 43 *--------------------------------------------------------------------- 44 * @addtogroup SMPC Security Manager Protocol Controller 45 * @ingroup SMP 46 * @brief Security Manager Protocol Controller. 47 * 48 * This block handles control of SM procedures for several possible existing connections, 49 * for which the security procedure may be conducted simultaneously. 50 * 51 * It allows flow control for HCI access to encryption and random number generation, used 52 * at different moments in the procedure. 53 * 54 * It handles PDU creation and sending through L2CAP, also their reception from L2CAP 55 * and interpretation. 56 * 57 * Other small utilities such as maximum key size determination and TKDP organization are 58 * implemented in SMPC. 59 * @{ 60 * 61 **************************************************************************************** 62 */ 63 64 65 /* 66 * INCLUDE FILES 67 **************************************************************************************** 68 */ 69 #include "ble_ip_config.h" 70 71 #if (BLE_SMPC) 72 #include "bt_common.h" 73 #include "hal_gap.h" 74 #include "hal_gapc_task.h" 75 #include "ble_ke_task.h" 76 77 /* 78 * DEFINES 79 **************************************************************************************** 80 */ 81 82 /// MAC length 83 #define SMPC_SIGN_MAC_LEN (8) 84 /// SignCounter length 85 #define SMPC_SIGN_COUNTER_LEN (4) 86 /// Signature length 87 #define SMPC_SIGN_LEN (SMPC_SIGN_MAC_LEN + SMPC_SIGN_COUNTER_LEN) 88 89 /** 90 * Repeated Attempts Timer Configuration 91 */ 92 /// Repeated Attempts Timer default value (x10ms) 93 #define SMPC_REP_ATTEMPTS_TIMER_DEF_VAL (200) //2s 94 /// Repeated Attempts Timer max value (x10ms) 95 #define SMPC_REP_ATTEMPTS_TIMER_MAX_VAL (3000) //30s 96 /// Repeated Attempts Timer multiplier 97 #define SMPC_REP_ATTEMPTS_TIMER_MULT (2) 98 99 /** 100 * Timeout Timer Configuration 101 */ 102 #define SMPC_TIMEOUT_TIMER_DURATION (3000) //30s 103 104 #define SMPC_PUBLIC_KEY_256_COORD_LEN 0x20 105 /* 106 * ENUMERATIONS 107 **************************************************************************************** 108 */ 109 110 111 /// Information source. 112 enum smpc_addr_src 113 { 114 /// Local info. 115 SMPC_INFO_LOCAL, 116 /// Peer info. 117 SMPC_INFO_PEER, 118 /// Maximum info source. 119 SMPC_INFO_MAX 120 }; 121 122 /* 123 * STRUCTURES DEFINITION 124 **************************************************************************************** 125 */ 126 127 /// Master ID Information Structure 128 struct smpc_mst_id_info 129 { 130 // Encryption Diversifier 131 uint16_t ediv; 132 133 // Random Number 134 uint8_t randnb[GAP_RAND_NB_LEN]; 135 }; 136 137 #if (SECURE_CONNECTIONS) 138 struct smp_aes_cmac 139 { 140 uint8_t* M; // pointer to memory allocated by calling function 141 uint8_t M_len; 142 uint8_t M_last[16]; 143 uint8_t X[16]; 144 uint8_t Y[16]; 145 uint8_t* K; //[16]; 146 uint8_t K1[16]; 147 uint8_t K2[16]; 148 uint8_t next_block; 149 uint8_t num_blocks; 150 uint8_t state; // Only 3 States - Idle, SubKey Generation, Block AES 151 }; 152 153 struct smp_f4 154 { 155 uint8_t M[65]; 156 uint8_t X[16]; // The Key 157 }; 158 159 struct smp_f5 160 { 161 uint8_t M[53]; 162 uint8_t* W; 163 uint8_t T[16]; 164 uint8_t SALT[16]; 165 }; 166 167 168 struct smp_f6 169 { 170 uint8_t W[16]; 171 uint8_t M[65]; 172 }; 173 174 struct smp_g2 175 { 176 uint8_t X[16]; 177 uint8_t M[80]; 178 }; 179 180 struct gapc_public_key 181 { 182 uint8_t x[GAP_P256_KEY_LEN]; 183 uint8_t y[GAP_P256_KEY_LEN]; 184 }; 185 186 #endif // (SECURE_CONNECTIONS) 187 /// Pairing Information 188 struct smpc_pair_info 189 { 190 /// TK during Phase 2, LTK or IRK during Phase 3 191 struct gap_sec_key key; 192 /// Pairing request command 193 struct gapc_pairing pair_req_feat; 194 /// Pairing response feature 195 struct gapc_pairing pair_rsp_feat; 196 /// Random number value 197 uint8_t rand[RAND_VAL_LEN]; 198 /// Remote random number value 199 uint8_t rem_rand[RAND_VAL_LEN]; 200 /// Confirm value to check 201 uint8_t conf_value[GAP_KEY_LEN]; 202 /// Pairing Method 203 uint8_t pair_method; 204 /// Authentication level 205 uint8_t auth; 206 /// check that LTK exchanged during pairing 207 bool ltk_exchanged; 208 /// Key to be exchanged (transmitted or to be received) 209 uint8_t keys_dist; 210 211 212 #if (SECURE_CONNECTIONS) 213 // AES_CMAC Info 214 struct smp_aes_cmac* aes_cmac; 215 // Structure for Secure Connections Crypto functions 216 struct smp_f4* f4_info; 217 struct smp_f5* f5_info; 218 struct smp_f6* f6_info; 219 struct smp_g2* g2_info; 220 221 bool dh_key_calculation_complete; 222 223 uint8_t MacKey[GAP_KEY_LEN]; 224 uint8_t dh_key_check_peer[DHKEY_CHECK_LEN]; 225 uint8_t dh_key_local[DH_KEY_LEN]; 226 227 uint8_t dh_key_check_local[DHKEY_CHECK_LEN]; 228 bool dh_key_check_received_from_peer; 229 230 /// Local public key value 231 public_key_t local_public_key; 232 /// Peer public key value 233 public_key_t peer_public_key; 234 235 uint8_t passkey_bit_count; 236 uint32_t passkey; 237 238 // Required for OOB 239 uint8_t peer_r[GAP_KEY_LEN]; 240 uint8_t local_r[GAP_KEY_LEN]; 241 bool peer_rand_received; 242 bool peer_confirm_received; 243 #endif // (SECURE_CONNECTIONS) 244 }; 245 246 /// Signing Information 247 struct smpc_sign_info 248 { 249 /// Operation requester task id 250 ke_task_id_t requester; 251 252 /// Message offset 253 uint16_t msg_offset; 254 /// Number of block 255 uint8_t block_nb; 256 /// Cn-1 value -> Need to kept this value to retrieve it after L generation 257 uint8_t cn1[GAP_KEY_LEN]; 258 }; 259 260 /// SMPC environment structure 261 struct smpc_env 262 { 263 /// SMPC temporary information 264 union smpc_info 265 { 266 /** 267 * Pairing Information - This structure is allocated at the beginning of a pairing 268 * or procedure. It is freed when a disconnection occurs or at the end of 269 * the pairing procedure. If not enough memory can be found, the procedure will fail 270 * with an "Unspecified Reason" error 271 */ 272 struct smpc_pair_info *pair; 273 274 /** 275 * Signature Procedure Information - This structure is allocated at the beginning of a 276 * signing procedure. It is freed when a disconnection occurs or at the end of 277 * the signing procedure. If not enough memory can be found, the procedure will fail 278 * with an "Unspecified Reason" error. 279 */ 280 struct smpc_sign_info *sign; 281 } info; 282 283 /// CSRK values (Local and remote) 284 struct gap_sec_key csrk[SMPC_INFO_MAX]; 285 286 /// signature counter values (Local and remote) 287 uint32_t sign_counter[SMPC_INFO_MAX]; 288 289 /// Repeated Attempt Timer value 290 uint16_t rep_att_timer_val; 291 292 /// Encryption key size 293 uint8_t key_size; 294 295 /** 296 * Contains the current state of the two timers needed in the SMPC task 297 * Bit 0 - Is Timeout Timer running 298 * Bit 1 - Is Repeated Attempt Timer running 299 * Bit 2 - Has task reached a SMP Timeout 300 */ 301 uint8_t timer_state; 302 303 /// State of the current procedure 304 uint8_t state; 305 306 #if (SECURE_CONNECTIONS) 307 bool secure_connections_enabled; 308 #endif // (SECURE_CONNECTIONS) 309 }; 310 311 /* 312 * GLOBAL VARIABLES DEFINITION 313 **************************************************************************************** 314 */ 315 316 317 /* 318 * MACROS 319 **************************************************************************************** 320 */ 321 322 /* 323 * FUNCTION DECLARATIONS 324 **************************************************************************************** 325 */ 326 327 328 #endif //(BLE_SMPC) 329 330 #endif // _HAL_SMPC_H 331