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_security 18 * @ingroup hitls 19 * @brief TLS security features 20 */ 21 22 #ifndef HITLS_SECURITY_H 23 #define HITLS_SECURITY_H 24 25 #include <stdint.h> 26 #include "hitls_type.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * @ingroup hitls_security 34 * 35 * HiTLS default level of security. You can configure the default level by using the compilation macro. 36 * If the compilation macro is not defined, the default level 1 is used. 37 */ 38 #ifndef HITLS_DEFAULT_SECURITY_LEVEL 39 #define HITLS_DEFAULT_SECURITY_LEVEL 1 40 #endif 41 42 /* security level */ 43 #define HITLS_SECURITY_LEVEL_ZERO 0 44 #define HITLS_SECURITY_LEVEL_ONE 1 45 #define HITLS_SECURITY_LEVEL_TWO 2 46 #define HITLS_SECURITY_LEVEL_THREE 3 47 #define HITLS_SECURITY_LEVEL_FOUR 4 48 #define HITLS_SECURITY_LEVEL_FIVE 5 49 #define HITLS_SECURITY_LEVEL_MIN HITLS_SECURITY_LEVEL_ZERO 50 #define HITLS_SECURITY_LEVEL_MAX HITLS_SECURITY_LEVEL_FIVE 51 52 /* security strength */ 53 #define HITLS_SECURITY_LEVEL_ONE_SECBITS 80 54 #define HITLS_SECURITY_LEVEL_TWO_SECBITS 112 55 #define HITLS_SECURITY_LEVEL_THREE_SECBITS 128 56 #define HITLS_SECURITY_LEVEL_FOUR_SECBITS 192 57 #define HITLS_SECURITY_LEVEL_FIVE_SECBITS 256 58 59 /* What the "other" parameter contains in security callback */ 60 /* Mask for type */ 61 # define HITLS_SECURITY_SECOP_OTHER_TYPE 0xffff0000 62 # define HITLS_SECURITY_SECOP_OTHER_NONE 0 63 # define HITLS_SECURITY_SECOP_OTHER_CIPHER (1 << 16) 64 # define HITLS_SECURITY_SECOP_OTHER_CURVE (2 << 16) 65 # define HITLS_SECURITY_SECOP_OTHER_DH (3 << 16) 66 # define HITLS_SECURITY_SECOP_OTHER_PKEY (4 << 16) 67 # define HITLS_SECURITY_SECOP_OTHER_SIGALG (5 << 16) 68 # define HITLS_SECURITY_SECOP_OTHER_CERT (6 << 16) 69 70 /* Indicated operation refers to peer key or certificate */ 71 # define HITLS_SECURITY_SECOP_PEER 0x1000 72 73 /* Called to filter ciphers */ 74 /* Ciphers client supports */ 75 # define HITLS_SECURITY_SECOP_CIPHER_SUPPORTED (1 | HITLS_SECURITY_SECOP_OTHER_CIPHER) 76 /* Cipher shared by client/server */ 77 # define HITLS_SECURITY_SECOP_CIPHER_SHARED (2 | HITLS_SECURITY_SECOP_OTHER_CIPHER) 78 /* Sanity check of cipher server selects */ 79 # define HITLS_SECURITY_SECOP_CIPHER_CHECK (3 | HITLS_SECURITY_SECOP_OTHER_CIPHER) 80 /* Curves supported by client */ 81 # define HITLS_SECURITY_SECOP_CURVE_SUPPORTED (4 | HITLS_SECURITY_SECOP_OTHER_CURVE) 82 /* Curves shared by client/server */ 83 # define HITLS_SECURITY_SECOP_CURVE_SHARED (5 | HITLS_SECURITY_SECOP_OTHER_CURVE) 84 /* Sanity check of curve server selects */ 85 # define HITLS_SECURITY_SECOP_CURVE_CHECK (6 | HITLS_SECURITY_SECOP_OTHER_CURVE) 86 /* Temporary DH key */ 87 # define HITLS_SECURITY_SECOP_TMP_DH (7 | HITLS_SECURITY_SECOP_OTHER_PKEY) 88 /* SSL/TLS version */ 89 # define HITLS_SECURITY_SECOP_VERSION (9 | HITLS_SECURITY_SECOP_OTHER_NONE) 90 /* Session tickets */ 91 # define HITLS_SECURITY_SECOP_TICKET (10 | HITLS_SECURITY_SECOP_OTHER_NONE) 92 /* Supported signature algorithms sent to peer */ 93 # define HITLS_SECURITY_SECOP_SIGALG_SUPPORTED (11 | HITLS_SECURITY_SECOP_OTHER_SIGALG) 94 /* Shared signature algorithm */ 95 # define HITLS_SECURITY_SECOP_SIGALG_SHARED (12 | HITLS_SECURITY_SECOP_OTHER_SIGALG) 96 /* Sanity check signature algorithm allowed */ 97 # define HITLS_SECURITY_SECOP_SIGALG_CHECK (13 | HITLS_SECURITY_SECOP_OTHER_SIGALG) 98 /* Used to get mask of supported public key signature algorithms */ 99 # define HITLS_SECURITY_SECOP_SIGALG_MASK (14 | HITLS_SECURITY_SECOP_OTHER_SIGALG) 100 /* Use to see if compression is allowed */ 101 # define HITLS_SECURITY_SECOP_COMPRESSION (15 | HITLS_SECURITY_SECOP_OTHER_NONE) 102 /* EE key in certificate */ 103 # define HITLS_SECURITY_SECOP_EE_KEY (16 | HITLS_SECURITY_SECOP_OTHER_CERT) 104 /* CA key in certificate */ 105 # define HITLS_SECURITY_SECOP_CA_KEY (17 | HITLS_SECURITY_SECOP_OTHER_CERT) 106 /* CA digest algorithm in certificate */ 107 # define HITLS_SECURITY_SECOP_CA_MD (18 | HITLS_SECURITY_SECOP_OTHER_CERT) 108 /* Peer EE key in certificate */ 109 # define HITLS_SECURITY_SECOP_PEER_EE_KEY (HITLS_SECURITY_SECOP_EE_KEY | HITLS_SECURITY_SECOP_PEER) 110 /* Peer CA key in certificate */ 111 # define HITLS_SECURITY_SECOP_PEER_CA_KEY (HITLS_SECURITY_SECOP_CA_KEY | HITLS_SECURITY_SECOP_PEER) 112 /* Peer CA digest algorithm in certificate */ 113 # define HITLS_SECURITY_SECOP_PEER_CA_MD (HITLS_SECURITY_SECOP_CA_MD | HITLS_SECURITY_SECOP_PEER) 114 115 /** 116 * @ingroup hitls_security 117 * @brief Secure Callback Function Prototype 118 * 119 * @param ctx [IN] context 120 * @param config [IN] context 121 * @param option [IN] indicates the options to be checked, such as the version, certificate, temporary key, 122 * signature algorithm, support group, and session ticket... 123 * @param bits [IN] Number of security bits, which is used to check the level of security of the key. 124 * @param id [IN] Indicates the ID to be checked, such as the version ID, signature algorithm ID, 125 * and support group ID. Input based on the options that need to be checked. 126 * @param other [IN] Parameters to be checked, such as cipher suites, certificates, and signature algorithms. 127 * @param exData [IN] Input the data as required. 128 * @retval HITLS_SUCCESS, if successful. 129 * For details about other error codes,see hitls_error.h 130 */ 131 typedef int32_t (*HITLS_SecurityCb)(const HITLS_Ctx *ctx, const HITLS_Config *config, int32_t option, 132 int32_t bits, int32_t id, void *other, void *exData); 133 134 /** 135 * @ingroup hitls_security 136 * @brief Configure the security level 137 * 138 * @param config [IN/OUT] Config context 139 * @param securityLevel [IN] Security level 140 * @retval HITLS_SUCCESS, if successful. 141 * For details about other error codes, see hitls_error.h 142 */ 143 int32_t HITLS_CFG_SetSecurityLevel(HITLS_Config *config, int32_t securityLevel); 144 145 /** 146 * @ingroup hitls_security 147 * @brief Obtain the configured security level. 148 * 149 * @param config [IN] Config context 150 * @param securityLevel [OUT] Security Context 151 * @retval HITLS_SUCCESS, if successful. 152 * For details about other error codes, see hitls_error.h 153 */ 154 int32_t HITLS_CFG_GetSecurityLevel(const HITLS_Config *config, int32_t *securityLevel); 155 156 /** 157 * @ingroup hitls_security 158 * @brief Configure the security callback function. 159 * 160 * @param config [IN/OUT] Config context 161 * @param securityCb [IN] Security callback function 162 * @retval HITLS_SUCCESS, if successful. 163 * For details about other error codes, see hitls_error.h. 164 */ 165 int32_t HITLS_CFG_SetSecurityCb(HITLS_Config *config, HITLS_SecurityCb securityCb); 166 167 /** 168 * @ingroup hitls_security 169 * @brief Obtain the configured security callback function 170 * 171 * @param config [IN] Config context 172 * @retval Security callback function HITLS_SecurityCb. 173 */ 174 HITLS_SecurityCb HITLS_CFG_GetSecurityCb(const HITLS_Config *config); 175 176 /** 177 * @ingroup hitls_security 178 * @brief Configuring the Security ExData 179 * 180 * @param config [IN/OUT] Config context 181 * @param securityExData [IN] Security ExData 182 * @retval HITLS_SUCCESS, if successful. 183 * For details about other error codes, see hitls_error.h 184 */ 185 int32_t HITLS_CFG_SetSecurityExData(HITLS_Config *config, void *securityExData); 186 187 /** 188 * @ingroup hitls_security 189 * @brief Obtain the configured Security ExData 190 * 191 * @param config [IN] Config context 192 * @retval Security ExData 193 */ 194 void *HITLS_CFG_GetSecurityExData(const HITLS_Config *config); 195 196 /** 197 * @ingroup hitls_security 198 * @brief Set the link security level 199 * 200 * @param ctx [IN/OUT] Ctx context 201 * @param securityLevel [IN] Security level 202 * @retval HITLS_SUCCESS, if successful. 203 * For details about other error codes, see hitls_error.h 204 */ 205 int32_t HITLS_SetSecurityLevel(HITLS_Ctx *ctx, int32_t securityLevel); 206 207 /** 208 * @ingroup hitls_security 209 * @brief Obtain the link security level 210 * 211 * @param ctx [IN] Ctx context 212 * @param securityLevel [OUT] Security level 213 * @retval HITLS_SUCCESS, if successful. 214 * For details about other error codes, see hitls_error.h 215 */ 216 int32_t HITLS_GetSecurityLevel(const HITLS_Ctx *ctx, int32_t *securityLevel); 217 218 /** 219 * @ingroup hitls_security 220 * @brief Callback function for setting link security 221 * 222 * @param ctx [IN/OUT] Ctx context 223 * @param securityCb [IN] Security callback function 224 * @retval HITLS_SUCCESS, if successful. 225 * For details about other error codes, see hitls_error.h 226 */ 227 int32_t HITLS_SetSecurityCb(HITLS_Ctx *ctx, HITLS_SecurityCb securityCb); 228 229 /** 230 * @ingroup hitls_security 231 * @brief Obtain the Security callback function of the link 232 * 233 * @param ctx [IN] Ctx context 234 * @retval Security callback HITLS_SecurityCb. 235 */ 236 HITLS_SecurityCb HITLS_GetSecurityCb(const HITLS_Ctx *ctx); 237 238 /** 239 * @ingroup hitls_security 240 * @brief Setting Security ExData for the Link 241 * 242 * @param ctx [IN/OUT] Ctx context 243 * @param securityExData [IN] Security ExData 244 * @retval HITLS_SUCCESS, if successful. 245 * For details about other error codes, hitls_error.h 246 */ 247 int32_t HITLS_SetSecurityExData(HITLS_Ctx *ctx, void *securityExData); 248 249 /** 250 * @ingroup hitls_security 251 * @brief Obtains the configured Security ExData. 252 * 253 * @param ctx [IN] Ctx context 254 * @retval Security ExData 255 */ 256 void *HITLS_GetSecurityExData(const HITLS_Ctx *ctx); 257 258 #ifdef __cplusplus 259 } 260 #endif /* end __cplusplus */ 261 262 #endif /* end HITLS_SECURITY_H */