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 /** 17 * @defgroup hitls_psk 18 * @ingroup hitls 19 * @brief Basic functions for link establishment based on PSK 20 */ 21 22 #ifndef HITLS_PSK_H 23 #define HITLS_PSK_H 24 25 #include "hitls_type.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** 32 * @ingroup hitls_psk 33 * @brief PSK Maximum size of the identity message 34 */ 35 #define HITLS_IDENTITY_HINT_MAX_SIZE 128 36 #define HITLS_PSK_FIND_SESSION_CB_SUCCESS 1 37 #define HITLS_PSK_FIND_SESSION_CB_FAIL 0 38 #define HITLS_PSK_USE_SESSION_CB_SUCCESS 1 39 #define HITLS_PSK_USE_SESSION_CB_FAIL 0 40 41 /** 42 * @ingroup hitls_psk 43 * @brief Obtain the PSK prototype on the client. 44 * 45 * @param ctx [IN] Context. 46 * @param hint [IN] Message. 47 * @param identity [OUT] Identity information written back by the user. 48 * @param maxIdentityLen [IN] Maximum length of the identity buffer. 49 * @param psk [OUT] PSK information written back by the user. 50 * @param maxPskLen [IN] Maximum length of the psk buffer. 51 * @retval Return the PSK length. 52 */ 53 typedef uint32_t (*HITLS_PskClientCb)(HITLS_Ctx *ctx, const uint8_t *hint, uint8_t *identity, uint32_t maxIdentityLen, 54 uint8_t *psk, uint32_t maxPskLen); 55 56 /** 57 * @ingroup hitls_psk 58 * @brief Obtain the PSK prototype on the server. 59 * 60 * @param ctx [IN] Context. 61 * @param identity [IN] Identity information. 62 * @param psk [OUT] PSK information written back by the user. 63 * @param maxPskLen [IN] Maximum length of the psk buffer. 64 * @retval Return the PSK length. 65 */ 66 typedef uint32_t (*HITLS_PskServerCb)(HITLS_Ctx *ctx, const uint8_t *identity, uint8_t *psk, uint32_t maxPskLen); 67 68 /** 69 * @ingroup hitls_psk 70 * @brief TLS1.3 server PSK negotiation callback 71 * 72 * @param ctx [IN] ctx context 73 * @param identity [OUT] Identity information 74 * @param identityLen [OUT] Identity information length 75 * @param session [OUT] session 76 * @retval HITLS_PSK_FIND_SESSION_CB_SUCCESS, if successful. 77 * HITLS_PSK_FIND_SESSION_CB_FAIL, if failed 78 */ 79 typedef int32_t (*HITLS_PskFindSessionCb)(HITLS_Ctx *ctx, const uint8_t *identity, uint32_t identityLen, 80 HITLS_Session **session); 81 82 /** 83 * @ingroup hitls_psk 84 * @brief TLS1.3 client PSK negotiation callback 85 * 86 * @param ctx [IN] ctx context 87 * @param hashAlgo [IN] Hash algorithm 88 * @param id [IN] Identity information 89 * @param idLen [IN] Identity information length 90 * @param session [OUT] session 91 * @retval HITLS_PSK_USE_SESSION_CB_SUCCESS, if successful. 92 * HITLS_PSK_USE_SESSION_CB_FAIL, if failed 93 */ 94 typedef int32_t (*HITLS_PskUseSessionCb)(HITLS_Ctx *ctx, uint32_t hashAlgo, const uint8_t **id, 95 uint32_t *idLen, HITLS_Session **session); 96 97 /** 98 * @ingroup hitls_psk 99 * @brief Set the PSK prompt information for PSK negotiation. 100 * 101 * @param config [OUT] config Context 102 * @param hint [IN] Hint 103 * @param hintSize [IN] Hint length 104 * @retval HITLS_SUCCESS, if successful. 105 * For details about other error codes, see hitls_error.h. 106 */ 107 int32_t HITLS_CFG_SetPskIdentityHint(HITLS_Config *config, const uint8_t *hint, uint32_t hintSize); 108 109 /** 110 * @ingroup hitls_psk 111 * @brief Set the PSK callback function on the client, which is used to obtain the identity 112 * 113 * and PSK during PSK negotiation. 114 * @param config [OUT] config Context 115 * @param callback [IN] Client callback 116 * @retval HITLS_SUCCESS, if successful. 117 * For details about other error codes, see hitls_error.h. 118 */ 119 int32_t HITLS_CFG_SetPskClientCallback(HITLS_Config *config, HITLS_PskClientCb callback); 120 121 /** 122 * @ingroup hitls_psk 123 * @brief Set the PSK callback on the server, which is used to obtain the PSK during PSK negotiation. 124 * 125 * @param config [OUT] config Context 126 * @param callback [IN] Client callback 127 * @retval HITLS_SUCCESS, if successful. 128 * For details about other error codes, see hitls_error.h. 129 */ 130 int32_t HITLS_CFG_SetPskServerCallback(HITLS_Config *config, HITLS_PskServerCb callback); 131 132 /** 133 * @ingroup hitls_psk 134 * @brief Set the PSK callback function on the client, which is used to obtain the identity and PSK 135 * 136 * during PSK negotiation. 137 * @param ctx [OUT] TLS connection handle 138 * @param cb [IN] Client callback 139 * @retval HITLS_SUCCESS, if successful. 140 * For details about other error codes, see hitls_error.h. 141 */ 142 int32_t HITLS_SetPskClientCallback(HITLS_Ctx *ctx, HITLS_PskClientCb cb); 143 144 /** 145 * @ingroup hitls_psk 146 * @brief Set the PSK callback on the server, which is used to obtain the PSK during PSK negotiation. 147 * 148 * @param ctx [OUT] TLS connection handle 149 * @param cb [IN] Server callback 150 * @retval HITLS_SUCCESS, if successful. 151 * For details about other error codes, see hitls_error.h. 152 */ 153 int32_t HITLS_SetPskServerCallback(HITLS_Ctx *ctx, HITLS_PskServerCb cb); 154 155 /** 156 * @ingroup hitls_psk 157 * @brief Set the PSK identity hint on the server, which is used to provide identity hints for the 158 * 159 * client during PSK negotiation. 160 * @param ctx [OUT] TLS connection handle 161 * @param identityHint [IN] psk identity prompt 162 * @param identityHineLen [IN] psk Length of the identity message 163 * @retval HITLS_SUCCESS, if successful. 164 * For details about other error codes, see hitls_error.h. 165 */ 166 int32_t HITLS_SetPskIdentityHint(HITLS_Ctx *ctx, const uint8_t *identityHint, uint32_t identityHintLen); 167 168 /** 169 * @ingroup hitls_psk 170 * @brief Set the server callback, which is used to restore the PSK session of TLS1.3, cb can be NULL. 171 * 172 * @param ctx [OUT] TLS connection handle 173 * @param callback [IN] Callback function 174 * @retval HITLS_SUCCESS, if successful. 175 * For details about other error codes, see hitls_error.h. 176 */ 177 int32_t HITLS_CFG_SetPskFindSessionCallback(HITLS_Config *config, HITLS_PskFindSessionCb callback); 178 179 /** 180 * @ingroup hitls_psk 181 * @brief Set the server callback, which is used to restore the PSK session of TLS1.3, cb can be NULL. 182 * 183 * @param ctx [OUT] TLS connection handle 184 * @param callback [IN] Callback function 185 * @retval HITLS_SUCCESS, if successful. 186 * For details about other error codes, see hitls_error.h. 187 */ 188 int32_t HITLS_CFG_SetPskUseSessionCallback(HITLS_Config *config, HITLS_PskUseSessionCb callback); 189 190 /** 191 * @ingroup hitls_psk 192 * @brief Set the server callback, which is used to restore the PSK session of TLS1.3, cb can be NULL. 193 * 194 * @param ctx [OUT] TLS connection handle 195 * @param cb [IN] Callback function 196 * @retval HITLS_SUCCESS, if successful. 197 * For details about other error codes, see hitls_error.h. 198 */ 199 int32_t HITLS_SetPskFindSessionCallback(HITLS_Ctx *ctx, HITLS_PskFindSessionCb cb); 200 201 /** 202 * @ingroup hitls_psk 203 * @brief Set the client callback, which is used to restore the PSK session of TLS1.3, cb can be NULL. 204 * 205 * @param ctx [OUT] TLS connection handle 206 * @param cb [IN] Callback function 207 * @retval HITLS_SUCCESS, if successful. 208 * For details about other error codes, see hitls_error.h. 209 */ 210 int32_t HITLS_SetPskUseSessionCallback(HITLS_Ctx *ctx, HITLS_PskUseSessionCb cb); 211 212 #ifdef __cplusplus 213 } 214 #endif 215 216 #endif