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