1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX Secure Component */ 16 /** */ 17 /** Transport Layer Security (TLS) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* PORT SPECIFIC C INFORMATION RELEASE */ 26 /* */ 27 /* nx_secure_user.h PORTABLE C */ 28 /* 6.2.0 */ 29 /* */ 30 /* AUTHOR */ 31 /* */ 32 /* Timothy Stapko, Microsoft Corporation */ 33 /* */ 34 /* DESCRIPTION */ 35 /* */ 36 /* This file contains user defines for configuring NetX Secure in */ 37 /* specific ways. This file will have an effect only if the */ 38 /* application and NetX Secure library are built with */ 39 /* NX_SECURE_INCLUDE_USER_DEFINE_FILE defined. */ 40 /* Note that all the defines in this file may also be made on the */ 41 /* command line when building NetX library and application objects. */ 42 /* */ 43 /* RELEASE HISTORY */ 44 /* */ 45 /* DATE NAME DESCRIPTION */ 46 /* */ 47 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */ 48 /* 09-30-2020 Timothy Stapko Modified comment(s), */ 49 /* resulting in version 6.1 */ 50 /* 08-02-2021 Timothy Stapko Modified comment(s), */ 51 /* resulting in version 6.1.8 */ 52 /* 10-15-2021 Timothy Stapko Modified comment(s), added */ 53 /* macro to disable client */ 54 /* initiated renegotiation for */ 55 /* TLS server instances, */ 56 /* resulting in version 6.1.9 */ 57 /* 10-31-2022 Yanwu Cai Modified comment(s), added */ 58 /* macro to custom secret size,*/ 59 /* resulting in version 6.2.0 */ 60 /* */ 61 /**************************************************************************/ 62 63 #ifndef SRC_NX_SECURE_USER_H 64 #define SRC_NX_SECURE_USER_H 65 66 67 /* Define various build options for the NetX Secure port. The application should either make changes 68 here by commenting or un-commenting the conditional compilation defined OR supply the defines 69 though the compiler's equivalent of the -D option. */ 70 71 72 /* Override various options with default values already assigned in nx_secure_tls.h */ 73 74 75 /* NX_SECURE_TLS_ENABLE_TLS_1_0 defines whether or not to enable TLS 1.0 protocol support. 76 BY default TLS 1.0 is not supported. */ 77 /* 78 #define NX_SECURE_TLS_ENABLE_TLS_1_0 79 */ 80 81 /* NX_SECURE_TLS_ENABLE_TLS_1_1 defines whether or not to enable TLS 1.1 protocol support. 82 BY default TLS 1.1 is not supported. */ 83 /* 84 #define NX_SECURE_TLS_ENABLE_TLS_1_1 85 */ 86 87 /* NX_SECURE_TLS_ENABLE_TLS_1_3 defines whether or not to disable TLS 1.3 protocol support. 88 BY default TLS 1.3 is not enabled. */ 89 /* 90 #define NX_SECURE_TLS_ENABLE_TLS_1_3 91 */ 92 93 /* NX_SECURE_TLS_DISABLE_PROTOCOL_VERSION_DOWNGRADE defines whether or not to disables 94 protocol version downgrade for TLS client. BY default protocol version downgrade is supported. */ 95 /* 96 #define NX_SECURE_TLS_DISABLE_PROTOCOL_VERSION_DOWNGRADE 97 */ 98 99 /* NX_SECURE_ENABLE_PSK_CIPHERSUITES enables Pre-Shared Key. By default 100 this feature is not enabled. */ 101 /* 102 #define NX_SECURE_ENABLE_PSK_CIPHERSUITES 103 */ 104 105 /* NX_SECURE_AEAD_CIPHER_CHECK allows to detect user-implemented AEAD algorithms other than AES-CCM or 106 AES-GCM. It can be defined like #define NX_SECURE_AEAD_CIPHER_CHECK(a) ((a) == NEW_ALGORITHM_ID). 107 It works only when NX_SECURE_ENABLE_AEAD_CIPHER is defined. 108 By default this feature is not enabled. */ 109 /* 110 #define NX_SECURE_AEAD_CIPHER_CHECK(a) NX_FALSE 111 */ 112 113 /* NX_SECURE_ALLOW_SELF_SIGNED_CERTIFICATES enables self signed certificates. By default 114 this feature is not enabled. */ 115 /* 116 #define NX_SECURE_ALLOW_SELF_SIGNED_CERTIFICATES 117 */ 118 119 /* NX_SECURE_DISABLE_X509 disables X509 feature. By default this feature is enabled. */ 120 /* 121 #define NX_SECURE_DISABLE_X509 122 */ 123 124 /* NX_SECURE_DTLS_COOKIE_LENGTH defines the length of DTLS cookie. 125 The default value is 32. */ 126 /* 127 #define NX_SECURE_DTLS_COOKIE_LENGTH 32 128 */ 129 130 /* NX_SECURE_DTLS_MAXIMUM_RETRANSMIT_RETRIES defineds the maximum retransmit retries 131 for DTLS handshake packet. The default value is 10. */ 132 /* 133 #define NX_SECURE_DTLS_MAXIMUM_RETRANSMIT_RETRIES 10 134 */ 135 136 /* NX_SECURE_DTLS_MAXIMUM_RETRANSMIT_TIMEOUT defines the maximum DTLS retransmit rate. 137 The default value is 60 seconds. */ 138 /* 139 #define NX_SECURE_DTLS_MAXIMUM_RETRANSMIT_TIMEOUT (60 * NX_IP_PERIODIC_RATE) 140 */ 141 142 /* NX_SECURE_DTLS_RETRANSMIT_RETRY_SHIFT defins how the retransmit timeout period changes between successive retries. 143 If this value is 0, the initial retransmit timeout is the same as subsequent retransmit timeouts. If this 144 value is 1, each successive retransmit is twice as long. The default value is 1. */ 145 /* 146 #define NX_SECURE_DTLS_RETRANSMIT_RETRY_SHIFT 1 147 */ 148 149 /* NX_SECURE_DTLS_RETRANSMIT_TIMEOUT defines the initial DTLS retransmit rate. 150 The default value is 1 second. */ 151 /* 152 #define NX_SECURE_DTLS_RETRANSMIT_TIMEOUT NX_IP_PERIODIC_RATE 153 */ 154 155 /* NX_SECURE_ENABLE_AEAD_CIPHER enables AEAD ciphersuites. 156 For AEAD ciphersuites other than AES-CCM or AES-GCM, additional defination of 157 NX_SECURE_AEAD_CIPHER_CHECK must be defined. By default this feature is not enabled. */ 158 /* 159 #define NX_SECURE_ENABLE_AEAD_CIPHER 160 */ 161 162 /* NX_SECURE_ENABLE_CLIENT_CERTIFICATE_VERIFY enables client certificate verification. 163 By default this feature is not enabled. */ 164 /* 165 #define NX_SECURE_ENABLE_CLIENT_CERTIFICATE_VERIFY 166 */ 167 168 /* NX_SECURE_ENABLE_DTLS enables DTLS feature. By default this feature is not enabled. */ 169 /* 170 #define NX_SECURE_ENABLE_DTLS 171 */ 172 173 /* NX_SECURE_ENABLE_ECJPAKE_CIPHERSUITE enables ECJPAKE ciphersuites for DTLS. 174 By default this feature is not enabled. */ 175 /* 176 #define NX_SECURE_ENABLE_ECJPAKE_CIPHERSUITE 177 */ 178 179 /* NX_SECURE_KEY_CLEAR enables key related materials cleanup when they are not used anymore. 180 By default this feature is not enabled. */ 181 /* 182 #define NX_SECURE_KEY_CLEAR 183 */ 184 185 /* NX_SECURE_MEMCMP defines the memory compare function. 186 By default it is mapped to C library function. */ 187 /* 188 #define NX_SECURE_MEMCMP memcmp 189 */ 190 191 /* NX_SECURE_MEMCPY defines the memory copy function. 192 By default it is mapped to C library function. */ 193 /* 194 #define NX_SECURE_MEMCPY memcpy 195 */ 196 197 /* NX_SECURE_MEMMOVE defines the memory move function. 198 By default it is mapped to C library function. */ 199 /* 200 #define NX_SECURE_MEMMOVE memmove 201 */ 202 203 /* NX_SECURE_MEMSET defines the memory set function. 204 By default it is mapped to C library function. */ 205 /* 206 #define NX_SECURE_MEMSET memset 207 */ 208 209 /* NX_SECURE_POWER_ON_SELF_TEST_MODULE_INTEGRITY_CHECK enables module integrity 210 self test. By default it is not enabled. */ 211 /* 212 #define NX_SECURE_POWER_ON_SELF_TEST_MODULE_INTEGRITY_CHECK 213 */ 214 215 /* NX_SECURE_RNG_CHECK_COUNT defines the random number check for duplication. 216 By default it is 3. */ 217 /* 218 #define NX_SECURE_RNG_CHECK_COUNT 3 219 */ 220 221 /* NX_SECURE_TLS_CLIENT_DISABLED disables TLS client. By default TLS client is enabled. */ 222 /* 223 #define NX_SECURE_TLS_CLIENT_DISABLED 224 */ 225 226 /* NX_SECURE_TLS_MAX_PSK_ID_SIZE defines the maximum size of PSK ID. 227 By default it is 20. */ 228 /* 229 #define NX_SECURE_TLS_MAX_PSK_ID_SIZE 20 230 */ 231 232 /* NX_SECURE_TLS_MAX_PSK_KEYS defines the maximum PSK keys. 233 By default it is 5. */ 234 /* 235 #define NX_SECURE_TLS_MAX_PSK_KEYS 5 236 */ 237 238 /* NX_SECURE_TLS_MAX_PSK_SIZE defines the maximum size of PSK. 239 By default it is 20. */ 240 /* 241 #define NX_SECURE_TLS_MAX_PSK_SIZE 20 242 */ 243 244 /* NX_SECURE_TLS_MINIMUM_CERTIFICATE_SIZE defines a minimum reasonable size for a TLS 245 X509 certificate. This is used in checking for * errors in allocating certificate space. 246 The size is determined by assuming a 512-bit RSA key, MD5 hash, and a rough estimate of 247 other data. It is theoretically possible for a real certificate to be smaller, 248 but in that case, bypass the error checking by re-defining this macro. 249 Approximately: 64(RSA) + 16(MD5) + 176(ASN.1 + text data, common name, etc) 250 The default value is 256. */ 251 /* 252 #define NX_SECURE_TLS_MINIMUM_CERTIFICATE_SIZE 256 253 */ 254 255 /* NX_SECURE_TLS_MINIMUM_MESSAGE_BUFFER_SIZE defines the minimum size for the TLS message buffer. 256 It is determined by a number of factors, but primarily the expected size of the TLS handshake 257 Certificate message (sent by the TLS server) that may contain multiple certificates of 1-2KB each. 258 The upper limit is determined by the length field in the TLS header (16 bit), and is 64KB. 259 The default value is 4000. */ 260 /* 261 #define NX_SECURE_TLS_MINIMUM_MESSAGE_BUFFER_SIZE 4000 262 */ 263 264 /* NX_SECURE_TLS_PREMASTER_SIZE defines the size of pre-master secret. 265 The default value is 48. */ 266 /* 267 #define NX_SECURE_TLS_PREMASTER_SIZE 48 268 */ 269 270 /* NX_SECURE_TLS_MASTER_SIZE defines the size of master secret. 271 The default value is 48. */ 272 /* 273 #define NX_SECURE_TLS_MASTER_SIZE 48 274 */ 275 276 /* NX_SECURE_TLS_KEY_MATERIAL_SIZE defines the size of key material. 277 The default value is (2 * (NX_SECURE_TLS_MAX_HASH_SIZE + NX_SECURE_TLS_MAX_KEY_SIZE + NX_SECURE_TLS_MAX_IV_SIZE)). */ 278 /* 279 #define NX_SECURE_TLS_KEY_MATERIAL_SIZE (2 * (NX_SECURE_TLS_MAX_HASH_SIZE + NX_SECURE_TLS_MAX_KEY_SIZE + NX_SECURE_TLS_MAX_IV_SIZE)) 280 */ 281 282 /* NX_SECURE_TLS_CLIENT_DISABLED disables TLS server. By default TLS server is enabled. */ 283 /* 284 #define NX_SECURE_TLS_SERVER_DISABLED 285 */ 286 287 /* NX_SECURE_TLS_SNI_EXTENSION_DISABLED disables Server Name Indication (SNI) extension. 288 By default this feature is enabled */ 289 /* 290 #define NX_SECURE_TLS_SNI_EXTENSION_DISABLED 291 */ 292 293 /* NX_SECURE_TLS_USE_SCSV_CIPHPERSUITE enables SCSV ciphersuite in ClientHello message. 294 By default this feature is not enabled. */ 295 /* 296 #define NX_SECURE_TLS_USE_SCSV_CIPHPERSUITE 297 */ 298 299 /* NX_SECURE_TLS_DISABLE_SECURE_RENEGOTIATION disables secure session renegotiation extension (RFC 5746). 300 By default this feature is enabled. */ 301 /* 302 #define NX_SECURE_TLS_DISABLE_SECURE_RENEGOTIATION 303 */ 304 305 /* NX_SECURE_TLS_REQUIRE_RENEGOTIATION_EXT defines whether or not the connection should be terminated immediately 306 upon failure to receive the secure renegotiation extension during the initial handshake. 307 By default the connection is not terminated. */ 308 /* 309 #define NX_SECURE_TLS_REQUIRE_RENEGOTIATION_EXT 310 */ 311 312 /* NX_SECURE_TLS_DISABLE_CLIENT_INITIATED_RENEGOTIATION disables client-initiated renegotiation for TLS 313 servers. In some instances, client-initiated renegotiation can become a possible denial-of-service 314 vulnerability. */ 315 /* 316 #define NX_SECURE_TLS_DISABLE_CLIENT_INITIATED_RENEGOTIATION 317 */ 318 319 /* NX_SECURE_CUSTOM_SECRET_GENERATION enables the user to pass pointers of customized secret generation functions to 320 TLS in the user defined nx_secure_custom_secret_generation_init function. This will allow TLS to use customized 321 secret generation functions. */ 322 /* 323 #define NX_SECURE_CUSTOM_SECRET_GENERATION 324 */ 325 326 /* NX_SECURE_X509_DISABLE_CRL disables X509 Certificate Revocation List check. 327 By default this feature is enabled. */ 328 /* 329 #define NX_SECURE_X509_DISABLE_CRL 330 */ 331 332 /* NX_SECURE_X509_STRICT_NAME_COMPARE enables strict X509 comparisons for all fields. 333 By default this feature is not enabled. */ 334 /* 335 #define NX_SECURE_X509_STRICT_NAME_COMPARE 336 */ 337 338 /* NX_SECURE_X509_USE_EXTENDED_DISTINGUISHED_NAMES enables extended distinguished names 339 for strict X509 comparisons. By default this feature is not enabled. */ 340 /* 341 #define NX_SECURE_X509_USE_EXTENDED_DISTINGUISHED_NAMES 342 */ 343 344 /* If the handshake hash state cannot be copied using memory copy on metadata, 345 NX_SECURE_HASH_METADATA_CLONE should be defined to a function that clones the hash state. 346 UINT nx_crypto_hash_clone(VOID *dest_metadata, VOID *source_metadata, ULONG length); 347 #define NX_SECURE_HASH_METADATA_CLONE nx_crypto_hash_clone 348 */ 349 350 /* If cleaning up is required for the handshake hash crypto after being cloned, 351 NX_SECURE_HASH_CLONE_CLEANUP macro should be defined to a clean up function: 352 UINT nx_crypto_clone_cleanup(VOID *metadata, ULONG length); 353 #define NX_SECURE_HASH_CLONE_CLEANUP nx_crypto_clone_cleanup 354 */ 355 356 #endif /* SRC_NX_SECURE_USER_H */ 357
