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 /** Datagram Transport Layer Security (DTLS) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* APPLICATION INTERFACE DEFINITION RELEASE */ 26 /* */ 27 /* nx_secure_dtls_api.h PORTABLE C */ 28 /* 6.1 */ 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 DTLS 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 /* */ 47 /**************************************************************************/ 48 49 50 #ifndef SRC_NX_SECURE_DTLS_API_H_ 51 #define SRC_NX_SECURE_DTLS_API_H_ 52 53 /* Determine if a C++ compiler is being used. If so, ensure that standard 54 C is used to process the API information. */ 55 #ifdef __cplusplus 56 57 /* Yes, C++ compiler is present. Use standard C. */ 58 extern "C" { 59 60 #endif 61 62 /* Include the ThreadX and port-specific data type file. */ 63 64 #include "nx_api.h" 65 #include "nx_secure_tls_api.h" 66 #include "nx_secure_dtls.h" 67 68 #ifndef NX_SECURE_SOURCE_CODE 69 /* Services without error checking. */ 70 #ifdef NX_SECURE_DISABLE_ERROR_CHECKING 71 #define nx_secure_dtls_initialize _nx_secure_dtls_initialize 72 #define nx_secure_dtls_session_create _nx_secure_dtls_session_create 73 #define nx_secure_dtls_session_delete _nx_secure_dtls_session_delete 74 #define nx_secure_dtls_session_end _nx_secure_dtls_session_end 75 #define nx_secure_dtls_session_receive _nx_secure_dtls_session_receive 76 #define nx_secure_dtls_session_reset _nx_secure_dtls_session_reset 77 #define nx_secure_dtls_session_send _nx_secure_dtls_session_send 78 #define nx_secure_dtls_server_session_send _nx_secure_dtls_server_session_send 79 #define nx_secure_dtls_client_session_send _nx_secure_dtls_server_session_send 80 #define nx_secure_dtls_session_start _nx_secure_dtls_session_start 81 #define nx_secure_dtls_packet_allocate _nx_secure_dtls_packet_allocate 82 #define nx_secure_dtls_client_session_start _nx_secure_dtls_client_session_start 83 #define nx_secure_dtls_server_session_start _nx_secure_dtls_server_session_start 84 #define nx_secure_dtls_server_create _nx_secure_dtls_server_create 85 #define nx_secure_dtls_server_delete _nx_secure_dtls_server_delete 86 #define nx_secure_dtls_server_local_certificate_add _nx_secure_dtls_server_local_certificate_add 87 #define nx_secure_dtls_server_local_certificate_remove _nx_secure_dtls_server_local_certificate_remove 88 #define nx_secure_dtls_server_notify_set _nx_secure_dtls_server_notify_set 89 #define nx_secure_dtls_server_start _nx_secure_dtls_server_start 90 #define nx_secure_dtls_server_stop _nx_secure_dtls_server_stop 91 #define nx_secure_dtls_server_trusted_certificate_add _nx_secure_dtls_server_trusted_certificate_add 92 #define nx_secure_dtls_server_trusted_certificate_remove _nx_secure_dtls_server_trusted_certificate_remove 93 #define nx_secure_dtls_server_x509_client_verify_configure _nx_secure_dtls_server_x509_client_verify_configure 94 #define nx_secure_dtls_server_x509_client_verify_disable _nx_secure_dtls_server_x509_client_verify_disable 95 #define nx_secure_dtls_session_client_info_get _nx_secure_dtls_session_client_info_get 96 #define nx_secure_dtls_psk_add _nx_secure_dtls_psk_add 97 #define nx_secure_dtls_session_local_certificate_add _nx_secure_dtls_session_local_certificate_add 98 #define nx_secure_dtls_session_local_certificate_remove _nx_secure_dtls_session_local_certificate_remove 99 #define nx_secure_dtls_session_trusted_certificate_add _nx_secure_dtls_session_trusted_certificate_add 100 #define nx_secure_dtls_session_trusted_certificate_remove _nx_secure_dtls_session_trusted_certificate_remove 101 #define nx_secure_dtls_server_psk_add _nx_secure_dtls_server_psk_add 102 #define nx_secure_dtls_client_protocol_version_override _nx_secure_dtls_client_protocol_version_override 103 #define nx_secure_dtls_server_protocol_version_override _nx_secure_dtls_server_protocol_version_override 104 #define nx_secure_dtls_ecc_initialize _nx_secure_dtls_ecc_initialize 105 #define nx_secure_dtls_server_ecc_initialize _nx_secure_dtls_server_ecc_initialize 106 #else 107 /* Services with error checking. */ 108 #define nx_secure_dtls_initialize _nx_secure_dtls_initialize 109 #define nx_secure_dtls_session_create _nxe_secure_dtls_session_create 110 #define nx_secure_dtls_session_delete _nxe_secure_dtls_session_delete 111 #define nx_secure_dtls_session_end _nxe_secure_dtls_session_end 112 #define nx_secure_dtls_session_receive _nxe_secure_dtls_session_receive 113 #define nx_secure_dtls_session_reset _nxe_secure_dtls_session_reset 114 #define nx_secure_dtls_session_send _nxe_secure_dtls_session_send 115 #define nx_secure_dtls_server_session_send _nxe_secure_dtls_server_session_send 116 #define nx_secure_dtls_client_session_send _nxe_secure_dtls_server_session_send 117 #define nx_secure_dtls_session_start _nxe_secure_dtls_session_start 118 #define nx_secure_dtls_packet_allocate _nxe_secure_dtls_packet_allocate 119 #define nx_secure_dtls_client_session_start _nxe_secure_dtls_client_session_start 120 #define nx_secure_dtls_server_session_start _nxe_secure_dtls_server_session_start 121 #define nx_secure_dtls_server_create _nxe_secure_dtls_server_create 122 #define nx_secure_dtls_server_delete _nxe_secure_dtls_server_delete 123 #define nx_secure_dtls_server_local_certificate_add _nxe_secure_dtls_server_local_certificate_add 124 #define nx_secure_dtls_server_local_certificate_remove _nxe_secure_dtls_server_local_certificate_remove 125 #define nx_secure_dtls_server_notify_set _nxe_secure_dtls_server_notify_set 126 #define nx_secure_dtls_server_start _nxe_secure_dtls_server_start 127 #define nx_secure_dtls_server_stop _nxe_secure_dtls_server_stop 128 #define nx_secure_dtls_server_trusted_certificate_add _nxe_secure_dtls_server_trusted_certificate_add 129 #define nx_secure_dtls_server_trusted_certificate_remove _nxe_secure_dtls_server_trusted_certificate_remove 130 #define nx_secure_dtls_server_x509_client_verify_configure _nxe_secure_dtls_server_x509_client_verify_configure 131 #define nx_secure_dtls_server_x509_client_verify_disable _nxe_secure_dtls_server_x509_client_verify_disable 132 #define nx_secure_dtls_session_client_info_get _nxe_secure_dtls_session_client_info_get 133 #define nx_secure_dtls_psk_add _nxe_secure_dtls_psk_add 134 #define nx_secure_dtls_session_local_certificate_add _nxe_secure_dtls_session_local_certificate_add 135 #define nx_secure_dtls_session_local_certificate_remove _nxe_secure_dtls_session_local_certificate_remove 136 #define nx_secure_dtls_session_trusted_certificate_add _nxe_secure_dtls_session_trusted_certificate_add 137 #define nx_secure_dtls_session_trusted_certificate_remove _nxe_secure_dtls_session_trusted_certificate_remove 138 #define nx_secure_dtls_server_psk_add _nxe_secure_dtls_server_psk_add 139 #define nx_secure_dtls_client_protocol_version_override _nxe_secure_dtls_client_protocol_version_override 140 #define nx_secure_dtls_server_protocol_version_override _nxe_secure_dtls_server_protocol_version_override 141 #define nx_secure_dtls_ecc_initialize _nxe_secure_dtls_ecc_initialize 142 #define nx_secure_dtls_server_ecc_initialize _nxe_secure_dtls_server_ecc_initialize 143 #endif /* NX_SECURE_DISABLE_ERROR_CHECKING */ 144 145 /* Define the function prototypes of the DTLS API. */ 146 VOID nx_secure_dtls_initialize(VOID); 147 148 UINT nx_secure_dtls_session_create(NX_SECURE_DTLS_SESSION *session_ptr, 149 const NX_SECURE_TLS_CRYPTO *crypto_table, 150 VOID *metadata_buffer, ULONG metadata_size, 151 UCHAR *packet_reassembly_buffer, UINT packet_reassembly_buffer_size, 152 UINT certs_number, 153 UCHAR *remote_certificate_buffer, ULONG remote_certificate_buffer_size); 154 155 UINT nx_secure_dtls_session_delete(NX_SECURE_DTLS_SESSION *dtls_session); 156 UINT nx_secure_dtls_session_end(NX_SECURE_DTLS_SESSION *dtls_session, UINT wait_option); 157 UINT nx_secure_dtls_session_receive(NX_SECURE_DTLS_SESSION *dtls_session, 158 NX_PACKET **packet_ptr_ptr, ULONG wait_option); 159 UINT nx_secure_dtls_session_reset(NX_SECURE_DTLS_SESSION *session_ptr); 160 UINT nx_secure_dtls_session_send(NX_SECURE_DTLS_SESSION *dtls_session, NX_PACKET *packet_ptr, 161 NXD_ADDRESS *ip_address, UINT port); 162 UINT nx_secure_dtls_server_session_send(NX_SECURE_DTLS_SESSION *dtls_session, NX_PACKET *packet_ptr); 163 UINT nx_secure_dtls_session_start(NX_SECURE_DTLS_SESSION *dtls_session, NX_UDP_SOCKET *udp_socket, 164 UINT is_client, UINT wait_option); 165 UINT nx_secure_dtls_packet_allocate(NX_SECURE_DTLS_SESSION *dtls_session, NX_PACKET_POOL *pool_ptr, 166 NX_PACKET **packet_ptr, ULONG wait_option); 167 168 UINT nx_secure_dtls_client_session_start(NX_SECURE_DTLS_SESSION *dtls_session, NX_UDP_SOCKET *udp_socket, NXD_ADDRESS *ip_address, UINT port, UINT wait_option); 169 UINT nx_secure_dtls_server_session_start(NX_SECURE_DTLS_SESSION *dtls_session, UINT wait_option); 170 171 UINT nx_secure_dtls_server_create(NX_SECURE_DTLS_SERVER *server_ptr, NX_IP *ip_ptr, UINT port, ULONG timeout, 172 VOID *session_buffer, UINT session_buffer_size, 173 const NX_SECURE_TLS_CRYPTO *crypto_table, 174 VOID *crypto_metadata_buffer, ULONG crypto_metadata_size, 175 UCHAR *packet_reassembly_buffer, UINT packet_reassembly_buffer_size, 176 UINT (*connect_notify)(NX_SECURE_DTLS_SESSION *dtls_session, NXD_ADDRESS *ip_address, UINT port), 177 UINT (*receive_notify)(NX_SECURE_DTLS_SESSION *dtls_session)); 178 179 UINT nx_secure_dtls_server_delete(NX_SECURE_DTLS_SERVER *server_ptr); 180 181 182 UINT nx_secure_dtls_server_local_certificate_add(NX_SECURE_DTLS_SERVER *server_ptr, 183 NX_SECURE_X509_CERT *certificate, UINT cert_id); 184 185 UINT nx_secure_dtls_server_local_certificate_remove(NX_SECURE_DTLS_SERVER *server_ptr, 186 UCHAR *common_name, UINT common_name_length, UINT cert_id); 187 188 189 UINT nx_secure_dtls_server_notify_set(NX_SECURE_DTLS_SERVER *server_ptr, 190 UINT (*disconnect_notify)(NX_SECURE_DTLS_SESSION *dtls_session), 191 UINT (*error_notify)(NX_SECURE_DTLS_SESSION *dtls_session, UINT error_code)); 192 193 UINT nx_secure_dtls_server_start(NX_SECURE_DTLS_SERVER *server_ptr); 194 195 UINT nx_secure_dtls_server_stop(NX_SECURE_DTLS_SERVER *server_ptr); 196 197 UINT nx_secure_dtls_server_trusted_certificate_add(NX_SECURE_DTLS_SERVER *server_ptr, 198 NX_SECURE_X509_CERT *certificate, UINT cert_id); 199 200 201 UINT nx_secure_dtls_server_trusted_certificate_remove(NX_SECURE_DTLS_SERVER *server_ptr, 202 UCHAR *common_name, UINT common_name_length, UINT cert_id); 203 204 UINT nx_secure_dtls_server_psk_add(NX_SECURE_DTLS_SERVER *server_ptr, UCHAR *pre_shared_key, 205 UINT psk_length, UCHAR *psk_identity, UINT identity_length, UCHAR *hint, 206 UINT hint_length); 207 208 UINT nx_secure_dtls_server_x509_client_verify_configure(NX_SECURE_DTLS_SERVER *server_ptr, UINT certs_per_session, 209 UCHAR *certs_buffer, ULONG buffer_size); 210 211 UINT nx_secure_dtls_server_x509_client_verify_disable(NX_SECURE_DTLS_SERVER *server_ptr); 212 213 UINT nx_secure_dtls_session_client_info_get(NX_SECURE_DTLS_SESSION *dtls_session, 214 NXD_ADDRESS *client_ip_address, UINT *client_port, UINT *local_port); 215 216 217 UINT nx_secure_dtls_session_local_certificate_add(NX_SECURE_DTLS_SESSION *dtls_session, 218 NX_SECURE_X509_CERT *certificate, UINT cert_id); 219 UINT nx_secure_dtls_session_local_certificate_remove(NX_SECURE_DTLS_SESSION *dtls_session, 220 UCHAR *common_name, UINT common_name_length, UINT cert_id); 221 UINT nx_secure_dtls_session_trusted_certificate_add(NX_SECURE_DTLS_SESSION *dtls_session, 222 NX_SECURE_X509_CERT *certificate, UINT cert_id); 223 UINT nx_secure_dtls_session_trusted_certificate_remove(NX_SECURE_DTLS_SESSION *dtls_session, 224 UCHAR *common_name, UINT common_name_length, UINT cert_id); 225 UINT nx_secure_dtls_psk_add(NX_SECURE_DTLS_SESSION *dtls_session, UCHAR *pre_shared_key, 226 UINT psk_length, UCHAR *psk_identity, UINT identity_length, UCHAR *hint, 227 UINT hint_length); 228 UINT nx_secure_dtls_client_protocol_version_override(NX_SECURE_DTLS_SESSION *dtls_session, 229 USHORT protocol_version); 230 UINT nx_secure_dtls_server_protocol_version_override(NX_SECURE_DTLS_SERVER *dtls_server, 231 USHORT protocol_version); 232 233 234 #endif /* NX_SECURE_SOURCE_CODE */ 235 236 237 #ifdef __cplusplus 238 } 239 #endif 240 241 #endif /* SRC_NX_SECURE_DTLS_API_H_ */ 242 243
