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 NAT Component */ 16 /** */ 17 /** Network Address Translation Protocol (NAT) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 /**************************************************************************/ 23 /* */ 24 /* APPLICATION INTERFACE DEFINITION RELEASE */ 25 /* */ 26 /* nx_nat.h PORTABLE C */ 27 /* 6.1 */ 28 /* AUTHOR */ 29 /* */ 30 /* Yuxin Zhou, Microsoft Corporation */ 31 /* */ 32 /* DESCRIPTION */ 33 /* */ 34 /* This file defines the NetX Network Address Translation Protocol */ 35 /* (NAT) component, including all data types and external references. */ 36 /* It is assumed that tx_api.h, tx_port.h, nx_api.h, and nx_port.h, */ 37 /* have already been included. */ 38 /* */ 39 /* RELEASE HISTORY */ 40 /* */ 41 /* DATE NAME DESCRIPTION */ 42 /* */ 43 /* 05-19-2020 Yuxin Zhou Initial Version 6.0 */ 44 /* 09-30-2020 Yuxin Zhou Modified comment(s), */ 45 /* resulting in version 6.1 */ 46 /* */ 47 /**************************************************************************/ 48 49 #ifndef NX_NAT_H 50 #define NX_NAT_H 51 52 53 #ifdef __cplusplus 54 55 /* Yes, C++ compiler is present. Use standard C. */ 56 extern "C" { 57 58 #endif 59 60 61 #include "nx_api.h" 62 #include "nx_ip.h" 63 #include "nx_system.h" 64 65 #ifdef NX_NAT_ENABLE 66 67 /* Thread ID for identifying as an NAT device. */ 68 69 #define NX_NAT_ID 0x4E4154UL 70 71 72 /* Internal error processing codes. */ 73 74 #define NX_NAT_ERROR_CONSTANT 0xD00 75 76 #define NX_NAT_PARAM_ERROR (NX_NAT_ERROR_CONSTANT | 0x01) /* Invalid parameter for NAT service */ 77 #define NX_NAT_CACHE_ERROR (NX_NAT_ERROR_CONSTANT | 0x02) /* NAT translation cache currently is full. */ 78 #define NX_NAT_NOT_ENABLED (NX_NAT_ERROR_CONSTANT | 0x03) /* NAT is not enabled. */ 79 #define NX_NAT_ENTRY_NOT_FOUND (NX_NAT_ERROR_CONSTANT | 0x04) /* Did not find the entry in NAT entry list. */ 80 #define NX_NAT_INVALID_PROTOCOL (NX_NAT_ERROR_CONSTANT | 0x05) /* Invalid network protocol specified for translation entry. */ 81 #define NX_NAT_ROUTE_FIND_ERROR (NX_NAT_ERROR_CONSTANT | 0x06) /* Nat can not find the suitable interface to send the packet. */ 82 #define NX_NAT_INVALID_ENTRY (NX_NAT_ERROR_CONSTANT | 0x07) /* Invalid entry submitted for translation entry list. (e.g. invalid address). */ 83 #define NX_NAT_CACHE_FULL (NX_NAT_ERROR_CONSTANT | 0x08) /* NAT translation cache currently is full. */ 84 #define NX_NAT_NO_FREE_PORT_AVAILABLE (NX_NAT_ERROR_CONSTANT | 0x09) /* NAT unable to provide a unique public source port for outbound packet. */ 85 #define NX_NAT_ZERO_UDP_CHECKSUM (NX_NAT_ERROR_CONSTANT | 0x0A) /* UDP header checksum is zero but NAT not is configured to accept packets with zero UDP checksum. */ 86 #define NX_NAT_PACKET_CONSUMED_FAILED (NX_NAT_ERROR_CONSTANT | 0x0B) /* NAT sonsumed the packets failed. */ 87 #define NX_NAT_ENTRY_TYPE_ERROR (NX_NAT_ERROR_CONSTANT | 0x0C) /* The entry translation type error. */ 88 #define NX_NAT_PORT_UNAVAILABLE (NX_NAT_ERROR_CONSTANT | 0x0D) /* The port is unavailable. */ 89 90 91 /* Define the NAT entry attribute, */ 92 #define NX_NAT_STATIC_ENTRY 1 93 #define NX_NAT_DYNAMIC_ENTRY 2 94 95 /* NetX NAT translation entry's transaction status levels. */ 96 97 /* Define packet type based on direction (inbound, outbound, local). */ 98 99 #define NX_NAT_INBOUND_PACKET 1 /* Inbound packet with local host destination on private network */ 100 #define NX_NAT_OUTBOUND_PACKET 2 /* Outbound packet with external host destination on external network */ 101 102 103 /* Define the minimum count of NAT entries. */ 104 105 #ifndef NX_NAT_MIN_ENTRY_COUNT 106 #define NX_NAT_MIN_ENTRY_COUNT 3 107 #endif 108 109 110 /* Set the default expiration timeout (sec) for translation entries, 111 24 hours for TCP sessions, 4 minutes for non-TCP sessions. 112 RFC 2663, Section2.6, Page5. */ 113 114 #ifndef NX_NAT_TCP_SESSION_TIMEOUT 115 #define NX_NAT_TCP_SESSION_TIMEOUT (86400 * NX_IP_PERIODIC_RATE) 116 #endif 117 118 /* For backward compatibility, map the symbol NX_NAT_ENTRY_RESPONSE_TIMEOUT to NX_NAT_NON_TCP_SESSION_TIMEOUT. */ 119 #ifdef NX_NAT_ENTRY_RESPONSE_TIMEOUT 120 #define NX_NAT_NON_TCP_SESSION_TIMEOUT NX_NAT_ENTRY_RESPONSE_TIMEOUT 121 #endif /* NX_NAT_ENTRY_RESPONSE_TIMEOUT */ 122 123 #ifndef NX_NAT_NON_TCP_SESSION_TIMEOUT 124 #define NX_NAT_NON_TCP_SESSION_TIMEOUT (240 * NX_IP_PERIODIC_RATE) 125 #endif /* NX_NAT_NON_TCP_SESSION_TIMEOUT */ 126 127 /* Defined, this option enables automatic replacement when NAT cache is full. 128 Notice: only replace the oldest non-TCP session. */ 129 /* 130 #define NX_NAT_ENABLE_REPLACEMENT 131 */ 132 133 134 /* Set the ICMP query identifier/port for assigning to outbound ICMP/UDP/TCP packets 135 on NAT devices configured for port overloading (sharing a single global IP 136 address). Note this number must be high enough not to exceed with the local host 137 ICMP, UDP, TCP packet query IDs/port. */ 138 139 /* Set the minimum TCP port for assigning to outbound TCP packets. */ 140 #ifndef NX_NAT_START_TCP_PORT 141 #define NX_NAT_START_TCP_PORT 20000 142 #endif 143 144 /* Set the maximum TCP port for assigning to outbound TCP packets. */ 145 146 #ifndef NX_NAT_END_TCP_PORT 147 #define NX_NAT_END_TCP_PORT (NX_NAT_START_TCP_PORT + 10000) 148 #endif 149 150 /* Set the minimum UDP port for assigning to outbound UDP packets. */ 151 #ifndef NX_NAT_START_UDP_PORT 152 #define NX_NAT_START_UDP_PORT 20000 153 #endif 154 155 /* Set the maximum UDP port for assigning to outbound UDP packets. */ 156 157 #ifndef NX_NAT_END_UDP_PORT 158 #define NX_NAT_END_UDP_PORT (NX_NAT_START_UDP_PORT + 10000) 159 #endif 160 161 /* Set the minimum ICMP query identifier for assigning to outbound ICMP packets. */ 162 #ifndef NX_NAT_START_ICMP_QUERY_ID 163 #define NX_NAT_START_ICMP_QUERY_ID 20000 164 #endif 165 166 /* Set the maximum ICMP query identifier for assigning to outbound ICMP packets. */ 167 168 #ifndef NX_NAT_END_ICMP_QUERY_ID 169 #define NX_NAT_END_ICMP_QUERY_ID (NX_NAT_START_ICMP_QUERY_ID + 10000) 170 #endif 171 172 173 /* Configure NAT to disable record the packet forward counter. */ 174 /* 175 #define NX_DISABLE_NAT_INFO 176 */ 177 178 /* Define the NAT translation table entry structure. */ 179 typedef struct NX_NAT_TRANSLATION_ENTRY_STRUCT 180 { 181 182 /* 183 Local Network External Network 184 |----------------| 185 <local IP, | |<external IP, <peer IP, 186 ---------------| |----------------------------------------- 187 local port> | | external port> peer port> 188 | | 189 | | 190 |----------------| 191 */ 192 struct NX_NAT_TRANSLATION_ENTRY_STRUCT *next_entry_ptr; /* Pointer to the next translation entry in table */ 193 ULONG peer_ip_address; /* IP address of an external host sending/receiving packets through NAT. */ 194 ULONG local_ip_address; /* IP address of the local (private) host. */ 195 USHORT peer_port; /* Source port of an external host sending/receiving packets through NAT. */ 196 USHORT external_port; /* The external port of local (private) host. */ 197 USHORT local_port; /* Port of the local (private) host. */ 198 UCHAR translation_type; /* Translation type (static or dynamic). */ 199 UCHAR protocol; /* Packet's network sub protocol (TCP, UDP etc). */ 200 ULONG response_timeout; /* Expiration timeout for the entry. */ 201 ULONG response_timestamp; /* The last timestamp for entry used. */ 202 } NX_NAT_TRANSLATION_ENTRY; 203 204 205 /* Define the NAT device structure. */ 206 typedef struct NX_NAT_DEVICE_STRUCT 207 { 208 209 ULONG nx_nat_id; /* NAT Server thread ID */ 210 NX_IP *nx_nat_ip_ptr; /* IP instance for NAT's network. */ 211 UCHAR nx_nat_global_interface_index; /* NAT's global network. */ 212 UCHAR reserved[3]; /* Reserved. */ 213 #ifndef NX_DISABLE_NAT_INFO 214 ULONG forwarded_packets_received; /* Total number of packets received by NAT. */ 215 ULONG forwarded_packets_dropped; /* Total number of packets which cannot be forwarded. */ 216 ULONG forwarded_packets_sent; /* Total number of packets sent by NAT. */ 217 #endif 218 NX_NAT_TRANSLATION_ENTRY *nx_nat_dynamic_available_entry_head;/* Define the head pointer of available dynamic entries list. */ 219 NX_NAT_TRANSLATION_ENTRY *nx_nat_dynamic_active_entry_head; /* Define the head pointer of active dynamic entries list. */ 220 UINT nx_nat_dynamic_available_entries; /* Define the number of available dynamic entries. */ 221 UINT nx_nat_dynamic_active_entries; /* Define the number of active dynamic entries. */ 222 UINT nx_nat_static_active_entries; /* Define the number of active static entries. */ 223 VOID (*nx_nat_cache_full_notify)(struct NX_NAT_DEVICE_STRUCT *); 224 } NX_NAT_DEVICE; 225 226 227 #ifndef NX_NAT_SOURCE_CODE 228 229 230 /* Define the system API mappings based on the error checking 231 selected by the user. */ 232 233 /* Determine if error checking is desired. If so, map API functions 234 to the appropriate error checking front-ends. Otherwise, map API 235 functions to the core functions that actually perform the work. 236 Note: error checking is enabled by default. */ 237 238 239 #ifdef NX_NAT_DISABLE_ERROR_CHECKING 240 241 /* Services without error checking. */ 242 243 #define nx_nat_create _nx_nat_create 244 #define nx_nat_delete _nx_nat_delete 245 #define nx_nat_enable _nx_nat_enable 246 #define nx_nat_disable _nx_nat_disable 247 #define nx_nat_cache_notify_set _nx_nat_cache_notify_set 248 #define nx_nat_inbound_entry_create _nx_nat_inbound_entry_create 249 #define nx_nat_inbound_entry_delete _nx_nat_inbound_entry_delete 250 251 #else 252 253 /* Services with error checking. */ 254 255 #define nx_nat_create _nxe_nat_create 256 #define nx_nat_delete _nxe_nat_delete 257 #define nx_nat_enable _nxe_nat_enable 258 #define nx_nat_disable _nxe_nat_disable 259 #define nx_nat_cache_notify_set _nxe_nat_cache_notify_set 260 #define nx_nat_inbound_entry_create _nxe_nat_inbound_entry_create 261 #define nx_nat_inbound_entry_delete _nxe_nat_inbound_entry_delete 262 263 #endif /* NX_NAT_DISABLE_ERROR_CHECKING */ 264 265 /* Define API services available for NAT applications. */ 266 267 UINT nx_nat_create(NX_NAT_DEVICE *nat_ptr, NX_IP *ip_ptr, UINT global_interface_index, VOID *dynamic_cache_memory, UINT dynamic_cache_size); 268 UINT nx_nat_delete(NX_NAT_DEVICE *nat_ptr); 269 UINT nx_nat_enable(NX_NAT_DEVICE *nat_ptr); 270 UINT nx_nat_disable(NX_NAT_DEVICE *nat_ptr); 271 UINT nx_nat_cache_notify_set(NX_NAT_DEVICE *nat_ptr, VOID (*cache_full_notify_cb)(NX_NAT_DEVICE *nat_ptr)); 272 UINT nx_nat_inbound_entry_create(NX_NAT_DEVICE *nat_ptr, NX_NAT_TRANSLATION_ENTRY *entry_ptr, ULONG local_ip_address, UINT external_port, USHORT local_port, UCHAR protocol); 273 UINT nx_nat_inbound_entry_delete(NX_NAT_DEVICE *nat_ptr, NX_NAT_TRANSLATION_ENTRY *delete_entry_ptr); 274 275 #else /* NX_NAT_SOURCE_CODE */ 276 277 /* NAT source code is being compiled, do not perform any API mapping. */ 278 279 UINT _nx_nat_create(NX_NAT_DEVICE *nat_ptr, NX_IP *ip_ptr, UINT global_interface_index, VOID *dynamic_cache_memory, UINT dynamic_cache_size); 280 UINT _nxe_nat_create(NX_NAT_DEVICE *nat_ptr, NX_IP *ip_ptr, UINT global_interface_index, VOID *dynamic_cache_memory, UINT dynamic_cache_size); 281 UINT _nx_nat_delete(NX_NAT_DEVICE *nat_ptr); 282 UINT _nxe_nat_delete(NX_NAT_DEVICE *nat_ptr); 283 UINT _nx_nat_enable(NX_NAT_DEVICE *nat_ptr); 284 UINT _nxe_nat_enable(NX_NAT_DEVICE *nat_pt); 285 UINT _nx_nat_disable(NX_NAT_DEVICE *nat_ptr); 286 UINT _nxe_nat_disable(NX_NAT_DEVICE *nat_ptr); 287 UINT _nx_nat_cache_notify_set(NX_NAT_DEVICE *nat_ptr, VOID (*cache_full_notify_cb)(NX_NAT_DEVICE *nat_ptr)); 288 UINT _nxe_nat_cache_notify_set(NX_NAT_DEVICE *nat_ptr, VOID (*cache_full_notify_cb)(NX_NAT_DEVICE *nat_ptr)); 289 UINT _nx_nat_inbound_entry_create(NX_NAT_DEVICE *nat_ptr, NX_NAT_TRANSLATION_ENTRY *entry_ptr, ULONG local_ip_address, USHORT external_port, USHORT local_port, UCHAR protocol); 290 UINT _nxe_nat_inbound_entry_create(NX_NAT_DEVICE *nat_ptr, NX_NAT_TRANSLATION_ENTRY *entry_ptr, ULONG local_ip_address, USHORT external_port, USHORT local_port, UCHAR protocol); 291 UINT _nx_nat_inbound_entry_delete(NX_NAT_DEVICE *nat_ptr, NX_NAT_TRANSLATION_ENTRY *delete_entry_ptr); 292 UINT _nxe_nat_inbound_entry_delete(NX_NAT_DEVICE *nat_ptr, NX_NAT_TRANSLATION_ENTRY *delete_entry_ptr); 293 #endif 294 295 #endif /* NX_NAT_ENABLE */ 296 297 /* If a C++ compiler is being used....*/ 298 #ifdef __cplusplus 299 } 300 #endif 301 302 #endif /* NX_NAT_H */ 303 304
