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