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