1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 #ifndef HS_KX_H 17 #define HS_KX_H 18 19 #include <stdint.h> 20 #include "hs_ctx.h" 21 #include "hs_msg.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #define MASTER_SECRET_LABEL "CLIENT_RANDOM" 28 #define CLIENT_EARLY_LABEL "CLIENT_EARLY_TRAFFIC_SECRET" 29 #define CLIENT_HANDSHAKE_LABEL "CLIENT_HANDSHAKE_TRAFFIC_SECRET" 30 #define SERVER_HANDSHAKE_LABEL "SERVER_HANDSHAKE_TRAFFIC_SECRET" 31 #define CLIENT_APPLICATION_LABEL "CLIENT_TRAFFIC_SECRET_0" 32 #define SERVER_APPLICATION_LABEL "SERVER_TRAFFIC_SECRET_0" 33 #define EARLY_EXPORTER_SECRET_LABEL "EARLY_EXPORTER_SECRET" 34 #define EXPORTER_SECRET_LABEL "EXPORTER_SECRET" 35 36 /* The maximum premaster secret calculated by using the PSK may be: 37 * |uint16_t|MAX_OTHER_SECRET_SIZE|uint16_t|HS_PSK_MAX_LEN| */ 38 #define MAX_OTHER_SECRET_SIZE 1536 39 #define MAX_PRE_MASTER_SECRET_SIZE (sizeof(uint16_t) + MAX_OTHER_SECRET_SIZE + sizeof(uint16_t) + HS_PSK_MAX_LEN) 40 #define MAX_SHA1_SIZE 20 41 #define MAX_MD5_SIZE 16 42 43 /** 44 * @brief Create a key exchange context. 45 * 46 * @return A KeyExchCtx pointer is returned. If NULL is returned, the creation fails. 47 */ 48 KeyExchCtx *HS_KeyExchCtxNew(void); 49 50 /** 51 * @brief Release the key exchange context 52 * 53 * @param keyExchCtx [IN] Key exchange context. KeyExchCtx is left empty by the invoker 54 */ 55 void HS_KeyExchCtxFree(KeyExchCtx *keyExchCtx); 56 57 /** 58 * @brief Process the server ECDHE key exchange message 59 * 60 * @param ctx [IN] TLS context 61 * @param serverKxMsg [IN] Parsed handshake message 62 * 63 * @retval HITLS_SUCCESS succeeded. 64 * @retval HITLS_MEMALLOC_FAIL Memory application failed. 65 * @retval HITLS_MSG_HANDLE_UNKNOWN_CURVE_TYPE Unsupported elliptic curve type 66 * @retval HITLS_MSG_HANDLE_UNSUPPORT_NAMED_CURVE Unsupported ECDH elliptic curve 67 * @retval HITLS_MSG_HANDLE_ERR_ENCODE_ECDH_KEY Failed to obtain the ECDH public key. 68 */ 69 int32_t HS_ProcessServerKxMsgEcdhe(TLS_Ctx *ctx, const ServerKeyExchangeMsg *serverKxMsg); 70 71 /** 72 * @brief Process the client ECDHE key exchange message 73 * 74 * @param ctx [IN] TLS context 75 * @param clientKxMsg [IN] Parsed handshake message 76 * 77 * @retval HITLS_SUCCESS succeeded. 78 * @retval HITLS_MEMALLOC_FAIL Memory application failed. 79 * @retval HITLS_MSG_HANDLE_UNKNOWN_CURVE_TYPE Unsupported elliptic curve type 80 * @retval HITLS_MSG_HANDLE_UNSUPPORT_NAMED_CURVE Unsupported ECDH elliptic curve 81 */ 82 int32_t HS_ProcessClientKxMsgEcdhe(TLS_Ctx *ctx, const ClientKeyExchangeMsg *clientKxMsg); 83 84 /** 85 * @brief Process the server DH key exchange message 86 * 87 * @param ctx [IN] TLS context 88 * @param serverKxMsg [IN] Parsed handshake message 89 * 90 * @retval HITLS_SUCCESS succeeded. 91 * @retval HITLS_MEMALLOC_FAIL Memory application failed. 92 * @retval HITLS_MSG_HANDLE_ERR_ENCODE_DH_KEY Failed to obtain the DH public key. 93 */ 94 int32_t HS_ProcessServerKxMsgDhe(TLS_Ctx *ctx, const ServerKeyExchangeMsg *serverKxMsg); 95 96 /** 97 * @brief Process the client DH key exchange message 98 * 99 * @param ctx [IN] TLS context 100 * @param clientKxMsg [IN] Parsed handshake message 101 * 102 * @retval HITLS_SUCCESS succeeded. 103 * @retval HITLS_MEMALLOC_FAIL Memory application failed. 104 */ 105 int32_t HS_ProcessClientKxMsgDhe(TLS_Ctx *ctx, const ClientKeyExchangeMsg *clientKxMsg); 106 107 int32_t HS_ProcessClientKxMsgRsa(TLS_Ctx *ctx, const ClientKeyExchangeMsg *clientKxMsg); 108 109 int32_t HS_ProcessClientKxMsgSm2(TLS_Ctx *ctx, const ClientKeyExchangeMsg *clientKxMsg); 110 111 /** 112 * @brief Derive the master secret. 113 * 114 * @param ctx [IN] TLS context 115 * 116 * @retval HITLS_SUCCESS succeeded. 117 * @retval HITLS_MSG_HANDLE_UNSUPPORT_KX_ALG Unsupported Key Exchange Algorithm 118 * @retval For other error codes, see SAL_CRYPT_CalcEcdhSharedSecret. 119 */ 120 int32_t HS_GenerateMasterSecret(TLS_Ctx *ctx); 121 122 /** 123 * @brief Process the identity hint contained in ServerKeyExchange during PSK negotiation. 124 * 125 * @param ctx [IN] TLS context 126 * @param serverKxMsg [IN] Parsed handshake message 127 * 128 * @retval HITLS_SUCCESS succeeded. 129 * @retval HITLS_UNREGISTERED_CALLBACK The callback for obtaining the PSK on the client is not set. 130 * @retval HITLS_CONFIG_INVALID_LENGTH The length of the prompt message is incorrect. 131 * @retval HITLS_MEMALLOC_FAIL Memory application failed. 132 */ 133 int32_t HS_ProcessServerKxMsgIdentityHint(TLS_Ctx *ctx, const ServerKeyExchangeMsg *serverKxMsg); 134 135 /** 136 * @brief TLS1.3 derived secret 137 * 138 * @param deriveInfo [IN] secret derivation material 139 * @param isHashed [IN] true: indicates that the seed has been hashed false: indicates that the seed has not been 140 * hashed. 141 * @param outSecret [OUT] Output secret 142 * @param outLen [IN] Output secret length 143 * 144 * @retval HITLS_SUCCESS succeeded. 145 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 146 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation fails. 147 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 148 */ 149 int32_t HS_TLS13DeriveSecret(CRYPT_KeyDeriveParameters *deriveInfo, bool isHashed, uint8_t *outSecret, uint32_t outLen); 150 151 int32_t HS_TLS13DeriveBinderKey(HITLS_Lib_Ctx *libCtx, const char *attrName, 152 HITLS_HashAlgo hashAlgo, bool isExternalPsk, uint8_t *earlySecret, uint32_t secretLen, 153 uint8_t *binderKey, uint32_t keyLen); 154 155 /** 156 * @brief TLS1.3 Calculate the early secret. 157 * 158 * @param hashAlg [IN] secret derivation material 159 * @param psk [IN] PSK 160 * @param pskLen [OUT] PSK length 161 * @param earlySecret [IN] Output secret 162 * @param outLen [IN] Output secret length 163 * 164 * @retval HITLS_SUCCESS succeeded. 165 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 166 * @retval HITLS_CRYPT_ERR_HKDF_EXTRACT HKDF-Extract calculation failure 167 */ 168 int32_t HS_TLS13DeriveEarlySecret(HITLS_Lib_Ctx *libCtx, const char *attrName, 169 HITLS_HashAlgo hashAlgo, uint8_t *psk, uint32_t pskLen, uint8_t *earlySecret, uint32_t *outLen); 170 171 /** 172 * @brief TLS1.3 Calculate the secret in the next phase. 173 * 174 * @param hashAlg [IN] Hash algorithm 175 * @param inSecret [IN] secret of the current phase 176 * @param inLen [OUT] Current secret length 177 * @param givenSecret [IN] The secret specified by the 178 * @param givenLen [IN] Specify the secret length. 179 * @param outSecret [IN] Output secret 180 * @param outLen [IN/OUT] IN: Maximum buffer length OUT: Output secret length 181 * 182 * @retval HITLS_SUCCESS succeeded. 183 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 184 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation fails. 185 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 186 * @retval HITLS_CRYPT_ERR_HKDF_EXTRACT HKDF-Extract calculation failure 187 */ 188 int32_t HS_TLS13DeriveNextStageSecret(HITLS_Lib_Ctx *libCtx, const char *attrName, 189 HITLS_HashAlgo hashAlgo, uint8_t *inSecret, uint32_t inLen, uint8_t *givenSecret, 190 uint32_t givenLen, uint8_t *outSecret, uint32_t *outLen); 191 192 /** 193 * @brief TLS1.3 Calculate the FinishedKey. 194 * 195 * @param hashAlg [IN] Hash algorithm 196 * @param baseKey [IN] Key of the current phase 197 * @param baseKeyLen [IN] Current key length 198 * @param finishedkey [OUT] Output key 199 * @param finishedkeyLen [IN] Output key length 200 * 201 * @retval HITLS_SUCCESS succeeded. 202 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 203 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation failed. 204 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 205 */ 206 int32_t HS_TLS13DeriveFinishedKey(HITLS_Lib_Ctx *libCtx, const char *attrName, 207 HITLS_HashAlgo hashAlgo, uint8_t *baseKey, uint32_t baseKeyLen, uint8_t *finishedkey, uint32_t finishedkeyLen); 208 209 /** 210 * @brief TLS1.3 Switch the traffickey. 211 * 212 * @param ctx [IN] TLS context 213 * @param secret [IN] secret for calculating writekey and writeiv 214 * @param secretLen [IN] Input the secret length. 215 * @param isOut [IN] It is used to determine writeSate and readState. 216 * 217 * @retval HITLS_SUCCESS succeeded. 218 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 219 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation failed. 220 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 221 * @retval HITLS_INTERNAL_EXCEPTION Invalid null pointer 222 */ 223 int32_t HS_SwitchTrafficKey(TLS_Ctx *ctx, uint8_t *secret, uint32_t secretLen, bool isOut); 224 225 /** 226 * @brief Set parameters for initializing the panding state of the record layer. 227 * 228 * @param ctx [IN] TLS context 229 * @param isClient [IN] Whether it is a client 230 * @param keyPara [OUT] Output parameter 231 * @retval HITLS_SUCCESS succeeded. 232 * @retval HITLS_MEMCPY_FAIL Memory Copy Failure 233 */ 234 int32_t HS_SetInitPendingStateParam(const TLS_Ctx *ctx, bool isClient, REC_SecParameters *keyPara); 235 236 /** 237 * @brief TLS1.3 Derives the secret of the ServerHello procedure. 238 * 239 * @param ctx [IN] TLS context 240 * 241 * @retval HITLS_SUCCESS succeeded. 242 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 243 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 244 * @retval HITLS_CRYPT_ERR_HKDF_EXTRACT HKDF-Extract calculation failed. 245 * @retval HITLS_CRYPT_ERR_CALC_SHARED_KEY Failed to calculate the shared key. 246 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation fails. 247 * @retval For details about other error codes, see the SAL_CRYPT_DigestFinal interface. 248 */ 249 int32_t HS_TLS13CalcServerHelloProcessSecret(TLS_Ctx *ctx); 250 251 /** 252 * @brief TLS1.3 Derives the secret of the ServerFinish process. 253 * 254 * @param ctx [IN] TLS context 255 * 256 * @retval HITLS_SUCCESS succeeded. 257 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 258 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation failed. 259 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 260 * @retval HITLS_CRYPT_ERR_HKDF_EXTRACT HKDF-Extract calculation failed. 261 * @retval For details about other error codes, see the SAL_CRYPT_DigestFinal interface. 262 */ 263 int32_t HS_TLS13CalcServerFinishProcessSecret(TLS_Ctx *ctx); 264 265 /** 266 * @brief TLS1.3 Update the traffic secret. 267 * 268 * @param ctx [IN] TLS context 269 * @param isOut [IN] It is used to determine writeSate and readState. 270 * 271 * @retval HITLS_SUCCESS succeeded. 272 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 273 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation failed. 274 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 275 * @retval HITLS_CRYPT_ERR_HKDF_EXTRACT HKDF-Extract calculation failure 276 * @retval For other error codes, see the SAL_CRYPT_DigestFinal interface. 277 */ 278 int32_t HS_TLS13UpdateTrafficSecret(TLS_Ctx *ctx, bool isOut); 279 280 /** 281 * @brief TLS1.3 Derived by resumption_master_secret 282 * 283 * @param ctx [IN] TLS context 284 * 285 * @retval HITLS_SUCCESS succeeded. 286 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 287 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 288 * @retval HITLS_CRYPT_ERR_HKDF_EXTRACT HKDF-Extract calculation failure 289 * @retval HITLS_CRYPT_ERR_CALC_SHARED_KEY Failed to calculate the shared key. 290 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation failed. 291 * @retval For other error codes, see the SAL_CRYPT_DigestFinal interface 292 */ 293 int32_t HS_TLS13DeriveResumptionMasterSecret(TLS_Ctx *ctx); 294 295 /** 296 * @brief TLS1.3 calculate session resumption PSK 297 * 298 * @param ctx [IN] TLS context 299 * @param ticketNonce [IN] Unique ID of the ticket issued on the, which is used to calculate the PSK for session 300 * resumption. 301 * @param ticketNonceSize [IN] ticketNonce length 302 * @param resumePsk [OUT] Output the PSK key. 303 * @param resumePskLen [IN] Output the PSK length. 304 * 305 * @retval HITLS_SUCCESS succeeded. 306 * @retval HITLS_UNREGISTERED_CALLBACK Unregistered callback 307 * @retval HITLS_CRYPT_ERR_DIGEST hash calculation fails. 308 * @retval HITLS_CRYPT_ERR_HKDF_EXPAND HKDF-Expand calculation fails. 309 */ 310 int32_t HS_TLS13DeriveResumePsk( 311 TLS_Ctx *ctx, const uint8_t *ticketNonce, uint32_t ticketNonceSize, uint8_t *resumePsk, uint32_t resumePskLen); 312 313 int32_t HS_TLS13DeriveHandshakeTrafficSecret(TLS_Ctx *ctx); 314 315 #ifdef __cplusplus 316 } 317 #endif 318 319 #endif 320