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 /* APPLICATION INTERFACE DEFINITION RELEASE */ 26 /* */ 27 /* nx_secure_tls_api.h PORTABLE C */ 28 /* 6.2.0 */ 29 /* AUTHOR */ 30 /* */ 31 /* Timothy Stapko, Microsoft Corporation */ 32 /* */ 33 /* DESCRIPTION */ 34 /* */ 35 /* This file defines the basic Application Interface (API) to the */ 36 /* high-performance TLS implementation for the NetXDuo TCP/IP */ 37 /* protocol. */ 38 /* */ 39 /* RELEASE HISTORY */ 40 /* */ 41 /* DATE NAME DESCRIPTION */ 42 /* */ 43 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */ 44 /* 09-30-2020 Timothy Stapko Modified comment(s), */ 45 /* resulting in version 6.1 */ 46 /* 10-31-2022 Yanwu Cai Modified comment(s), and added*/ 47 /* API to set packet pool, */ 48 /* resulting in version 6.2.0 */ 49 /* */ 50 /**************************************************************************/ 51 52 #ifndef SRC_NX_SECURE_TLS_API_H_ 53 #define SRC_NX_SECURE_TLS_API_H_ 54 55 /* Determine if a C++ compiler is being used. If so, ensure that standard 56 C is used to process the API information. */ 57 #ifdef __cplusplus 58 59 /* Yes, C++ compiler is present. Use standard C. */ 60 extern "C" { 61 62 #endif 63 64 /* Include the ThreadX and port-specific data type file. */ 65 66 67 68 #include "tx_api.h" 69 #include "nx_port.h" 70 #include "nx_api.h" 71 #include "nx_secure_tls.h" 72 73 #ifndef NX_SECURE_SOURCE_CODE 74 75 #ifdef NX_SECURE_DISABLE_ERROR_CHECKING 76 #define nx_secure_tls_active_certificate_set _nx_secure_tls_active_certificate_set 77 #define nx_secure_tls_initialize _nx_secure_tls_initialize 78 #define nx_secure_tls_shutdown _nx_secure_tls_shutdown 79 #define nx_secure_tls_local_certificate_add _nx_secure_tls_local_certificate_add 80 #define nx_secure_tls_local_certificate_find _nx_secure_tls_local_certificate_find 81 #define nx_secure_tls_local_certificate_remove _nx_secure_tls_local_certificate_remove 82 #define nx_secure_tls_metadata_size_calculate _nx_secure_tls_metadata_size_calculate 83 #define nx_secure_tls_remote_certificate_allocate _nx_secure_tls_remote_certificate_allocate 84 #define nx_secure_tls_remote_certificate_buffer_allocate _nx_secure_tls_remote_certificate_buffer_allocate 85 #define nx_secure_tls_remote_certificate_free_all _nx_secure_tls_remote_certificate_free_all 86 #define nx_secure_tls_server_certificate_add _nx_secure_tls_server_certificate_add 87 #define nx_secure_tls_server_certificate_find _nx_secure_tls_server_certificate_find 88 #define nx_secure_tls_server_certificate_remove _nx_secure_tls_server_certificate_remove 89 #define nx_secure_tls_session_alert_value_get _nx_secure_tls_session_alert_value_get 90 #define nx_secure_tls_session_certificate_callback_set _nx_secure_tls_session_certificate_callback_set 91 #define nx_secure_tls_session_client_callback_set _nx_secure_tls_session_client_callback_set 92 #define nx_secure_tls_session_client_verify_disable _nx_secure_tls_session_client_verify_disable 93 #define nx_secure_tls_session_client_verify_enable _nx_secure_tls_session_client_verify_enable 94 #define nx_secure_tls_session_x509_client_verify_configure _nx_secure_tls_session_x509_client_verify_configure 95 #define nx_secure_tls_session_create _nx_secure_tls_session_create 96 #define nx_secure_tls_session_delete _nx_secure_tls_session_delete 97 #define nx_secure_tls_session_end _nx_secure_tls_session_end 98 #define nx_secure_tls_session_packet_buffer_set _nx_secure_tls_session_packet_buffer_set 99 #define nx_secure_tls_session_packet_pool_set _nx_secure_tls_session_packet_pool_set 100 #define nx_secure_tls_session_protocol_version_override _nx_secure_tls_session_protocol_version_override 101 #define nx_secure_tls_session_receive _nx_secure_tls_session_receive 102 #define nx_secure_tls_session_renegotiate _nx_secure_tls_session_renegotiate 103 #define nx_secure_tls_session_renegotiate_callback_set _nx_secure_tls_session_renegotiate_callback_set 104 #define nx_secure_tls_session_reset _nx_secure_tls_session_reset 105 #define nx_secure_tls_session_send _nx_secure_tls_session_send 106 #define nx_secure_tls_session_server_callback_set _nx_secure_tls_session_server_callback_set 107 #define nx_secure_tls_session_sni_extension_parse _nx_secure_tls_session_sni_extension_parse 108 #define nx_secure_tls_session_sni_extension_set _nx_secure_tls_session_sni_extension_set 109 #define nx_secure_tls_session_start _nx_secure_tls_session_start 110 #define nx_secure_tls_session_time_function_set _nx_secure_tls_session_time_function_set 111 #define nx_secure_tls_trusted_certificate_add _nx_secure_tls_trusted_certificate_add 112 #define nx_secure_tls_trusted_certificate_remove _nx_secure_tls_trusted_certificate_remove 113 #define nx_secure_tls_packet_allocate _nx_secure_tls_packet_allocate 114 #if defined(NX_SECURE_ENABLE_PSK_CIPHERSUITES) || defined(NX_SECURE_ENABLE_ECJPAKE_CIPHERSUITE) 115 #define nx_secure_tls_client_psk_set _nx_secure_tls_client_psk_set 116 #define nx_secure_tls_psk_add _nx_secure_tls_psk_add 117 #endif /* defined(NX_SECURE_ENABLE_PSK_CIPHERSUITES) || defined(NX_SECURE_ENABLE_ECJPAKE_CIPHERSUITE) */ 118 #else /* !NX_SEURE_DISABLE_ERROR_CHECKING */ 119 #define nx_secure_tls_active_certificate_set _nxe_secure_tls_active_certificate_set 120 #define nx_secure_tls_initialize _nx_secure_tls_initialize 121 #define nx_secure_tls_shutdown _nx_secure_tls_shutdown 122 #define nx_secure_tls_local_certificate_add _nxe_secure_tls_local_certificate_add 123 #define nx_secure_tls_local_certificate_find _nxe_secure_tls_local_certificate_find 124 #define nx_secure_tls_local_certificate_remove _nxe_secure_tls_local_certificate_remove 125 #define nx_secure_tls_metadata_size_calculate _nxe_secure_tls_metadata_size_calculate 126 #define nx_secure_tls_remote_certificate_allocate _nxe_secure_tls_remote_certificate_allocate 127 #define nx_secure_tls_remote_certificate_buffer_allocate _nxe_secure_tls_remote_certificate_buffer_allocate 128 #define nx_secure_tls_remote_certificate_free_all _nxe_secure_tls_remote_certificate_free_all 129 #define nx_secure_tls_server_certificate_add _nxe_secure_tls_server_certificate_add 130 #define nx_secure_tls_server_certificate_find _nxe_secure_tls_server_certificate_find 131 #define nx_secure_tls_server_certificate_remove _nxe_secure_tls_server_certificate_remove 132 #define nx_secure_tls_session_alert_value_get _nxe_secure_tls_session_alert_value_get 133 #define nx_secure_tls_session_certificate_callback_set _nxe_secure_tls_session_certificate_callback_set 134 #define nx_secure_tls_session_client_callback_set _nxe_secure_tls_session_client_callback_set 135 #define nx_secure_tls_session_client_verify_disable _nxe_secure_tls_session_client_verify_disable 136 #define nx_secure_tls_session_client_verify_enable _nxe_secure_tls_session_client_verify_enable 137 #define nx_secure_tls_session_x509_client_verify_configure _nxe_secure_tls_session_x509_client_verify_configure 138 #define nx_secure_tls_session_create _nxe_secure_tls_session_create 139 #define nx_secure_tls_session_delete _nxe_secure_tls_session_delete 140 #define nx_secure_tls_session_end _nxe_secure_tls_session_end 141 #define nx_secure_tls_session_packet_buffer_set _nxe_secure_tls_session_packet_buffer_set 142 #define nx_secure_tls_session_packet_pool_set _nxe_secure_tls_session_packet_pool_set 143 #define nx_secure_tls_session_protocol_version_override _nxe_secure_tls_session_protocol_version_override 144 #define nx_secure_tls_session_receive _nxe_secure_tls_session_receive 145 #define nx_secure_tls_session_renegotiate _nxe_secure_tls_session_renegotiate 146 #define nx_secure_tls_session_renegotiate_callback_set _nxe_secure_tls_session_renegotiate_callback_set 147 #define nx_secure_tls_session_reset _nxe_secure_tls_session_reset 148 #define nx_secure_tls_session_send _nxe_secure_tls_session_send 149 #define nx_secure_tls_session_server_callback_set _nxe_secure_tls_session_server_callback_set 150 #define nx_secure_tls_session_sni_extension_parse _nxe_secure_tls_session_sni_extension_parse 151 #define nx_secure_tls_session_sni_extension_set _nxe_secure_tls_session_sni_extension_set 152 #define nx_secure_tls_session_start _nxe_secure_tls_session_start 153 #define nx_secure_tls_session_time_function_set _nxe_secure_tls_session_time_function_set 154 #define nx_secure_tls_trusted_certificate_add _nxe_secure_tls_trusted_certificate_add 155 #define nx_secure_tls_trusted_certificate_remove _nxe_secure_tls_trusted_certificate_remove 156 #define nx_secure_tls_packet_allocate _nxe_secure_tls_packet_allocate 157 #if defined(NX_SECURE_ENABLE_PSK_CIPHERSUITES) || defined(NX_SECURE_ENABLE_ECJPAKE_CIPHERSUITE) 158 #define nx_secure_tls_client_psk_set _nxe_secure_tls_client_psk_set 159 #define nx_secure_tls_psk_add _nxe_secure_tls_psk_add 160 #endif /* defined(NX_SECURE_ENABLE_PSK_CIPHERSUITES) || defined(NX_SECURE_ENABLE_ECJPAKE_CIPHERSUITE) */ 161 #endif /* NX_SECURE_DISABLE_ERROR_CHECKING */ 162 #define nx_secure_crypto_table_self_test _nx_secure_crypto_table_self_test 163 #define nx_secure_crypto_rng_self_test _nx_secure_crypto_rng_self_test 164 #ifdef NX_SECURE_ENABLE_ECC_CIPHERSUITE 165 #define nx_secure_tls_ecc_initialize _nx_secure_tls_ecc_initialize 166 #endif /* NX_SECURE_ENABLE_ECC_CIPHERSUITE */ 167 168 UINT nx_secure_crypto_table_self_test(const NX_SECURE_TLS_CRYPTO *crypto_table, 169 VOID *metadata, UINT metadata_size); 170 UINT nx_secure_crypto_rng_self_test(); 171 UINT nx_secure_module_hash_compute(NX_CRYPTO_METHOD *hmac_ptr, 172 UINT start_address, 173 UINT end_address, 174 UCHAR *key, UINT key_length, 175 VOID *metadata, UINT metadata_size, 176 UCHAR *output_buffer, UINT output_buffer_size, UINT *actual_size); 177 178 179 UINT nx_secure_tls_active_certificate_set(NX_SECURE_TLS_SESSION *tls_session, 180 NX_SECURE_X509_CERT *certificate); 181 VOID nx_secure_tls_initialize(VOID); 182 UINT nx_secure_tls_shutdown(VOID); 183 UINT nx_secure_tls_local_certificate_add(NX_SECURE_TLS_SESSION *tls_session, 184 NX_SECURE_X509_CERT *certificate); 185 UINT nx_secure_tls_local_certificate_find(NX_SECURE_TLS_SESSION *tls_session, 186 NX_SECURE_X509_CERT **certificate, UCHAR *common_name, 187 UINT name_length); 188 UINT nx_secure_tls_local_certificate_remove(NX_SECURE_TLS_SESSION *tls_session, UCHAR *common_name, 189 UINT common_name_length); 190 UINT nx_secure_tls_metadata_size_calculate(const NX_SECURE_TLS_CRYPTO *cipher_table, 191 ULONG *metadata_size); 192 UINT nx_secure_tls_remote_certificate_allocate(NX_SECURE_TLS_SESSION *tls_session, 193 NX_SECURE_X509_CERT *certificate, 194 UCHAR *raw_certificate_buffer, UINT buffer_size); 195 UINT nx_secure_tls_remote_certificate_buffer_allocate(NX_SECURE_TLS_SESSION *tls_session, 196 UINT certs_number, VOID *certificate_buffer, ULONG buffer_size); 197 UINT nx_secure_tls_remote_certificate_free_all(NX_SECURE_TLS_SESSION *tls_session); 198 UINT nx_secure_tls_server_certificate_add(NX_SECURE_TLS_SESSION *tls_session, 199 NX_SECURE_X509_CERT *certificate, UINT cert_id); 200 UINT nx_secure_tls_server_certificate_find(NX_SECURE_TLS_SESSION *tls_session, 201 NX_SECURE_X509_CERT **certificate, UINT cert_id); 202 UINT nx_secure_tls_server_certificate_remove(NX_SECURE_TLS_SESSION *tls_session, UINT cert_id); 203 UINT nx_secure_tls_session_alert_value_get(NX_SECURE_TLS_SESSION *tls_session, 204 UINT *alert_level, UINT *alert_value); 205 UINT nx_secure_tls_session_certificate_callback_set(NX_SECURE_TLS_SESSION *tls_session, 206 ULONG (*func_ptr)(NX_SECURE_TLS_SESSION *session, 207 NX_SECURE_X509_CERT *certificate)); 208 UINT nx_secure_tls_session_client_callback_set(NX_SECURE_TLS_SESSION *tls_session, 209 ULONG (*func_ptr)(NX_SECURE_TLS_SESSION *tls_session, 210 NX_SECURE_TLS_HELLO_EXTENSION *extensions, 211 UINT num_extensions)); 212 UINT nx_secure_tls_session_client_verify_disable(NX_SECURE_TLS_SESSION *tls_session); 213 UINT nx_secure_tls_session_client_verify_enable(NX_SECURE_TLS_SESSION *tls_session); 214 UINT nx_secure_tls_session_x509_client_verify_configure(NX_SECURE_TLS_SESSION *tls_session, UINT certs_number, 215 VOID *certificate_buffer, ULONG buffer_size); 216 217 UINT nx_secure_tls_session_create(NX_SECURE_TLS_SESSION *session_ptr, 218 const NX_SECURE_TLS_CRYPTO *cipher_table, 219 VOID *metadata_area, 220 ULONG metadata_size); 221 UINT nx_secure_tls_session_delete(NX_SECURE_TLS_SESSION *tls_session); 222 UINT nx_secure_tls_session_end(NX_SECURE_TLS_SESSION *tls_session, UINT wait_option); 223 UINT nx_secure_tls_session_packet_buffer_set(NX_SECURE_TLS_SESSION *session_ptr, 224 UCHAR *buffer_ptr, ULONG buffer_size); 225 UINT nx_secure_tls_session_packet_pool_set(NX_SECURE_TLS_SESSION *tls_session, 226 NX_PACKET_POOL *packet_pool); 227 UINT nx_secure_tls_session_protocol_version_override(NX_SECURE_TLS_SESSION *tls_session, 228 USHORT protocol_version); 229 UINT nx_secure_tls_session_receive(NX_SECURE_TLS_SESSION *tls_session, NX_PACKET **packet_ptr_ptr, 230 ULONG wait_option); 231 UINT nx_secure_tls_session_renegotiate(NX_SECURE_TLS_SESSION *tls_session, UINT wait_option); 232 UINT nx_secure_tls_session_renegotiate_callback_set(NX_SECURE_TLS_SESSION *tls_session, 233 ULONG (*func_ptr)(NX_SECURE_TLS_SESSION *session)); 234 UINT nx_secure_tls_session_reset(NX_SECURE_TLS_SESSION *tls_session); 235 UINT nx_secure_tls_session_send(NX_SECURE_TLS_SESSION *tls_session, NX_PACKET *packet_ptr, 236 ULONG wait_option); 237 UINT nx_secure_tls_session_server_callback_set(NX_SECURE_TLS_SESSION *tls_session, 238 ULONG (*func_ptr)(NX_SECURE_TLS_SESSION *tls_session, 239 NX_SECURE_TLS_HELLO_EXTENSION *extensions, 240 UINT num_extensions)); 241 UINT nx_secure_tls_session_sni_extension_parse(NX_SECURE_TLS_SESSION *tls_session, 242 NX_SECURE_TLS_HELLO_EXTENSION *extensions, 243 UINT num_extensions, NX_SECURE_X509_DNS_NAME *dns_name); 244 UINT nx_secure_tls_session_sni_extension_set(NX_SECURE_TLS_SESSION *tls_session, 245 NX_SECURE_X509_DNS_NAME *dns_name); 246 UINT nx_secure_tls_session_start(NX_SECURE_TLS_SESSION *tls_session, NX_TCP_SOCKET *tcp_socket, 247 UINT wait_option); 248 UINT nx_secure_tls_session_time_function_set(NX_SECURE_TLS_SESSION *tls_session, 249 ULONG (*time_func_ptr)(VOID)); 250 UINT nx_secure_tls_trusted_certificate_add(NX_SECURE_TLS_SESSION *tls_session, 251 NX_SECURE_X509_CERT *certificate); 252 UINT nx_secure_tls_trusted_certificate_remove(NX_SECURE_TLS_SESSION *tls_session, UCHAR *common_name, 253 UINT common_name_length); 254 UINT nx_secure_tls_packet_allocate(NX_SECURE_TLS_SESSION *tls_session, NX_PACKET_POOL *pool_ptr, 255 NX_PACKET **packet_ptr, ULONG wait_option); 256 #ifdef NX_SECURE_ENABLE_PSK_CIPHERSUITES 257 UINT nx_secure_tls_psk_add(NX_SECURE_TLS_SESSION *tls_session, UCHAR *pre_shared_key, UINT psk_length, 258 UCHAR *psk_identity, UINT identity_length, UCHAR *hint, UINT hint_length); 259 260 UINT nx_secure_tls_client_psk_set(NX_SECURE_TLS_SESSION *tls_session, UCHAR *pre_shared_key, UINT psk_length, 261 UCHAR *psk_identity, UINT identity_length, UCHAR *hint, UINT hint_length); 262 #endif 263 #ifdef NX_SECURE_ENABLE_ECC_CIPHERSUITE 264 UINT nx_secure_tls_ecc_initialize(NX_SECURE_TLS_SESSION *tls_session, 265 const USHORT *supported_groups, USHORT supported_group_count, 266 const NX_CRYPTO_METHOD **curves); 267 #endif /* NX_SECURE_ENABLE_ECC_CIPHERSUITE */ 268 #endif /* NX_SECURE_SOURCE_CODE */ 269 270 271 #ifdef __cplusplus 272 } 273 #endif 274 275 #endif /* SRC_NX_SECURE_TLS_H_ */ 276 277
