idnits 2.17.1 draft-ietf-nat-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 320 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 62 has weird spacing: '...nts and the n...' == Line 241 has weird spacing: '...l Agent who h...' == Line 302 has weird spacing: '...essions beari...' == Line 360 has weird spacing: '...l Agent who h...' == Line 401 has weird spacing: '...l state for t...' == (1 more instance...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: 'Ref 1' on line 1015 == Unused Reference: '1' is defined on line 1020, but no explicit reference was found in the text == Unused Reference: '2' is defined on line 1024, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 1027, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 1029, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 1032, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 1035, but no explicit reference was found in the text == Unused Reference: '7' is defined on line 1037, but no explicit reference was found in the text == Unused Reference: '8' is defined on line 1040, but no explicit reference was found in the text == Unused Reference: '9' is defined on line 1042, but no explicit reference was found in the text == Unused Reference: '10' is defined on line 1045, but no explicit reference was found in the text == Unused Reference: '11' is defined on line 1047, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 1050, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1700 (ref. '3') (Obsoleted by RFC 3232) ** Obsolete normative reference: RFC 793 (ref. '8') (Obsoleted by RFC 9293) Summary: 11 errors (**), 0 flaws (~~), 18 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NAT Working Group P. Srisuresh 3 INTERNET-DRAFT Lucent Technologies 4 Category: Informational November, 1998 5 Expire in six months 7 IP Network Address Translator Application Programming Interface 8 10 Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its 14 areas, and its working groups. Note that other groups may also 15 distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other 19 documents at any time. It is inappropriate to use Internet- 20 Drafts as reference material or to cite them other than as 21 "work in progress." 23 To view the entire list of current Internet-Drafts, please check 24 the "1id-abstracts.txt" listing contained in the Internet-Drafts 25 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 26 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 27 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 28 (US West Coast). 30 Abstract 32 NAT provides routing transparency for hosts in disparate routing 33 realms to communicate with each other. However, external agents 34 such as Application Level Gateways (ALGs), Host-NAT-clients and 35 Management applications need to interact with NAT and influence 36 its operations. The document identifies the resources and other 37 elements controlled by a NAT device, with specific focus on areas 38 subject to influence from external agents. An Application 39 Programming Interface (API) framework by which external agents 40 could interact with NAT is presented. The intent of this document 41 is to leverage the API specification as a base to identify 42 requirements for the development of one or more protocols by which 43 external agents could interact with NAT. 45 1. Introduction 47 NAT provides routing transparency for hosts in disparate routing 48 realms to communicate with each other. [Ref 1] details the various 49 flavors of NAT that abound. Many of the internet applications use 50 IP address as host identifier rather than just as a way to locate a 51 host. For this reason, routing transparency by NAT alone is not 52 sufficient to provide end-to-end transparency for applications 53 operating across realms. Application specific ALGs are required 54 in conjunction with NAT to provide end-to-end transparency for 55 some applications. 57 In addition to ALGs, there are other kinds of external agents that 58 may like to influence NAT operation. Section 2 below is devoted to 59 describing the resources and other elements controlled by NAT. 60 Section 3 below outlines a selected list of external agents that 61 may likely interface with NAT. Together, the requirements by a 62 selected set of external agents and the nature of NAT resources 63 are used as the basis to derive an API framework, described in 64 section 4. 66 The intent of the document is two-fold. First, the document 67 suggests an Application programming Interface (API) by which 68 external agents could programmatically interface with NAT. 69 This does not assume or require external agents to reside on the 70 same physical device as NAT, even though assuming they reside on 71 the same physical device does help in understanding. In reality, 72 it is likely to be a combination of both. Some agents are 73 co-located with NAT on the same device and others reside on 74 external devices. The API is merely a suggestion and may vary from 75 vendor to vendor. 77 Second, the API provides a framework to identify requirements for 78 the development of one or more protocols by which external agents 79 (specified in section 3 below) could communicate with NAT. Such 80 a protocol would need to authenticate clients, locate NAT devices 81 and exchange data elements. The API specified in the document 82 assumes a trusted environment and does not address the first two 83 issues, namely authentication and Service location. The document 84 also does not cover any communication protocol that may be used by 85 external agents to interface with NAT using the API described here. 86 These issues will need to be addressed independently outside the 87 purview of this document. 89 2. Elements of NAT operation 91 In order to identify an API for use by external agents, it is 92 important to understand the resources and other elments managed 93 by NAT. This would help identify the extent to which an external 94 agent may influence NAT operation. This section describes objects 95 within NAT, that could be externalized via Management Information 96 Base (MIB). 98 2.1. NAT Descriptor 100 All flavors of NAT are designed to provide routing transparency 101 to hosts in disparate routing realms. A physical device may have 102 multiple NAT instances or there may be multiple NAT devices 103 associated with a specific realm. The following list of attributes 104 identify a specific instance of NAT. 106 a. NAT IDentifier: 108 A NAT Identifier uniquely identifies a NAT instantiation. 109 The External interface address may be one way to specify 110 NAT Identifier. 112 b. Private and External realm types: 114 Every NAT device will have a minimum of two routing 115 interfaces, one connecting to a private realm and one 116 connecting to external realm. An IPv4 NAT device will 117 have both its realm types set to IPv4. 119 c. NAT type 121 NAT type could be one of Basic-NAT, NAPT, Bi-directional-NAT, 122 Twice-NAT, Host-NAT server, Host-NAPT-server or a combination 123 of the above. NAT type is an indication of the direction in 124 which NAT sessions are allowed and the extent of translation 125 within the IP and transport headers. [Ref 1] has a discussion 126 on the nature of various NAT flavors and the extent of their 127 translations. 129 d. Address(and transport ID) maps 131 Address map on a NAT device could consist of one or more of 132 static and dynamic Address maps. Likewise, Transport ID mapping 133 could consists of one or more of static and dynamic Transport 134 ID maps. Transport ID mapping is more specific than address 135 mapping in that a specific TCP/UDP port (or port range) 136 pertaining to an address in external realm is mapped to a 137 specific TCP/UDP port (or port range) in private realm or vice 138 versa. Address (and Transport ID) maps may be defined for both 139 inbound and outbound directions. Outbound address map refers 140 to mapping a selected set of addresses from private realm to a 141 selected set of addresses in external realm; whereas inbound 142 address map refers to mapping a set of addresses from the 143 external realm to private realm. 145 e. Miscellaneous parameters 147 NAT may optionally provide TCP, UDP and other types of session 148 Idle-times used to terminate sessions. It may also provide the 149 current range (and, the maximum range) of session IDs and 150 Bind IDs (to be covered in the follow on sub-sections); and 151 the actual count of session IDs and BIND IDs. Specifically, 152 this information will be of relevance to another NAT (backup 153 NAT) that intends to emulate this NAT, in case of failure. 154 Lastly, NAT may choose to supply any other vendor specific 155 parameters such as log options, session direction failure 156 actions and so forth. 158 f. Host-NAT (and Host-NAPT) specific parameters 160 If the NAT device were to provide Host-NAT-Server capability; 161 optionally, the NAT device could specify the Host-NAT 162 tunneling type it supports. 164 2.2. Address (and Transport-ID) BINDing Descriptor 166 These bindings can be static or dynamic. Hereafter, the term BIND 167 will be referred in place of BINDing, for ease of use. When external 168 agents do not intervene, dynamic address(and transport-ID) binding 169 is determined by NAT based on the first packet of a session, as 170 described in [Ref 1]. Address binding is between an address in 171 private realm and an address from external realm. Transport-ID BIND 172 is extension of the same concept to the tuple of Address and 173 transport ID (such as TCP/UDP port no.). The following list of 174 attributes identify a BIND within a NAT. 176 a. Bind ID 178 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 179 to BIND to uniquely identify this BIND from a different BIND 180 on the same NAT. 182 b. Direction of Bind 184 A bind can be uni-directional or bi-directional, same as the 185 orientation of address map based on which this BIND is formed. 186 As before, the direction is with reference to private realm. 188 c. Bind type 190 Indicates whether the BIND is Address-BIND (between a pair of 191 addresses) or Transport-ID-Bind (between a pair of Address, 192 transport ID tuples). Note, a transport-ID bind intrinsically 193 assumes an address bind between the addresses specified in 194 the tuples. This also indicates if the Bind is static or 195 dynamic. 197 d. Private and External addresses (and Transport IDs) 199 The pair described here essentially identify the BINDing 200 items between private and external realms. 202 e. Maximum leased time 204 The validity of a BIND may be limited by the maximum length of 205 leased time it is allowed. Unless the leased time is renewed, 206 the BIND will no longer be valid past this time. As a special 207 case, a value of 0 may be assumed to indicate no lease time 208 limit. Typically, this attribute is of relevance in conjunction 209 with Host-NAT operation. 211 f. Available leased time 213 This parameter is of relevance only when Maximum Leased time is 214 set to a non-zero value. At any given instance of time, this 215 parameter indicates the real-time left for the BIND to remain 216 valid. Typically, this attribute is of relevance in conjunction 217 with Host-NAT operation. 219 g. Maximum Idle time 221 This parameter indicates maximum amount of time a dynamic BIND 222 is allowed to remain valid, with no NAT session hanging off this 223 BIND. Typically, a dynamic Bind is established when NAT notices 224 the first session that needs such a binding. Subsequent to 225 this, multiple NAT sessions can be maintained using the same 226 binding. When the last of these sessions is terminated, the 227 bind is also terminated. In other words, Maximum Idle time is 0, 228 by default, for native NAT. External agents could control this 229 parameter differently. Static Binds and lease time limited BINDs 230 are not effected by this parameter. 232 h. Current Idle time 234 This parameter is of relevance only when Maximum Idle time is 235 set to a non-zero value. At any given instance of time, this 236 parameter indicates the real-time the BIND has been idle with 237 no sessions attached to it. 239 i. Controlling Agent IDentification 241 This indicates the last external Agent who has tried to 242 control (i.e., set) parameters for this BIND. A value of 0 243 indicates that native NAT is the responsible agent. 245 2.3. Session State descriptor 247 NAT maintains soft state for the sessions it tracks. These states 248 are created dynamically during NAT operation and are responsible 249 for translation of packets pertaining to the session. The translation 250 element of a state is based on address (or Transport ID) bind (two 251 binds in case of twice-nat). The following list of attributes 252 identify a session (or session State) within NAT. 254 a. Session IDentifier 256 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 257 to session to uniquely identify this from other sessions on 258 the same NAT. 260 b. Direction of Session. 262 Direction of first packet of the session. As specified 263 earlier, direction is with reference to private realm. 265 c. Bind IDentifier 267 Identifies the Bind based on which this session is created. 268 The Direction of BIND must be same as that of the session, 269 if the BIND is uni-directional. Typically, if a Bind supporting 270 the session translation does not already exist, a Bind is 271 created prior to creating new session state. However, this 272 Identifier may be set to 0, when BIND creation is unnecessary 273 for the session. For example, there can be no more than one 274 ICMP Query session using am ICMP Query based transport-ID-bind. 275 In such a case, it suffices to do away with BIND and keep all 276 requisite information within the session state itself. 278 d. Second Bind IDentifier 280 This is of relevance only to Twice-NAT. For all other flavors 281 of NAT, this parameter may be set to zero. If the session is 282 outbound, this parameter refers to binding of the target 283 destination address from private realm to external realm. 285 e. Original Session parameters 287 These parameters identify the session level parameters as 288 they appear in the first packet of session. These parameters 289 include src and dest IP addresses, IP protocol and transport 290 IDentifier info (such as TCP/UDP port numbers or ICMP Query 291 Identifier). 293 f. Translated Session parameters 295 These parameters identify the session level parameters as 296 the first packet of session is translated. These parameters 297 are derived from the BIND ID(s) off which this session hangs. 299 g. Session tag 301 NAT managed sessions are assigned a session tag, so that 302 sessions bearing the same tag are handled the same way. 303 The tag value is of significance only to the processing 304 agent. Native NAT maintains four types of session tags for 305 TCP, UDP, ICMP QUERY and all other sessions. So, tag 306 numbers selected by the agents will need to be different 307 from the native tags, if the processing were to be done 308 differently. 310 h. Session Termination heuristic 312 Session-Idle-time is typically used as a heuristic means by NAT 313 to determine if the session has ended. There may other heuristic 314 approaches. A value of zero is an indication that NAT would not 315 use any heuristic to session termination, unless it is a TCP 316 session and the session has noticeable ended with FIN or RST 317 options. The agent may take the responsibility for terminating 318 the session. 320 i. Maximum Idle time 322 This parameter indicates maximum amount of time this session 323 is allowed to remain valid, even as there is no activity. 324 Idle time is typically used as a heuristic means to determine 325 session termination. There may be other heuristic approaches. 326 As a special case, a value of 0 implies that NAT should run 327 the same timer as used for native sessions. 329 j. Current Idle Time 331 This parameter is of relevance only when session termination 332 heuristic is set to session-idle-time. Typically, NAT would 333 examine the idle time on the sessions it manages periodically 334 and updates this variable. When the idle time exceeds the 335 maximum allowed idle time, the session is terminated. 337 k. Packet modifier functions 339 Typically, NAT modifies IP header and optionally, the 340 transport header. External agents could choose to assume 341 responsibility for payload modification alone, or the entire 342 packet modification. In the case an external agent assumes 343 responsibility for the entire packet modification, NAT will 344 simply redirect the original packet as is to external agent 345 modifier. 347 l. Bundle ID 349 Applications that deal with a bundle of sessions may cause 350 multiple sessions to be managed by NAT. Even though these 351 sessions constitute a single session from application stand 352 point, NAT is not congnizant of the relation. In such cases, 353 it is not uncommon for external agents to store a unique 354 application ID (say, the session ID of the first NAT session 355 the application originated) in all sessions it spawns in its 356 incarnation. 358 m. Controlling Agent IDentification 360 This indicates the last external Agent who has tried to 361 control parameters for this session. A value of 0 indicates 362 that native NAT is the responsible agent. 364 3. External agents interfacing with NAT 366 Many network applications assume the IP address of their host to be 367 host Identifier and embed the Identifier information in application 368 specific payload. When packets from such an application traverse 369 NAT, the IP address of private host remains uncorrected in the 370 payload, as the packet is delivered to hosts in external realm. An 371 Application Level Gateway (ALG) is required to re-interpret such a 372 payload as the payload traverses realms. 374 In addition, there are applications such as H.323 that use 375 out-of-band signaling to dynamically create newer sessions. While 376 a signaling session itself may be directed to a well-known port, 377 sessions created by it need not be that way. Once again, an ALG may 378 be required to process payload in the signaling sessions and notify 379 NAT to recognize the newly created sessions. 381 There may be other instances where an ALG may be required to 382 provide application level transparency. Clearly, there is a need 383 for a variety of ALGs to interface with NAT. The ALGs may reside 384 on the same NAT device or an external device. Independent of this, 385 the NAT interface requirement will remain the same. 387 In a multi-homed NAT configuration, there is a need for a backup NAT 388 to communicate with the primary and keep in sync, so that when the 389 primary goes away, the backup NAT could instantly assume support for 390 the sessions that primary NAT was responsible for. This is yet 391 another case where an external agent (i.e., backup NAT) has a need 392 to interface with NAT. 394 A NAT device is uniquely qualified to serve as host-NAT-Server 395 (or host-NAPT-Server) for host-NAT-clients (or host-NAPT-clients). 396 [Ref 1] has a description of Host-NAT terminology. Host-NAT 397 (and Host-NAPT) clients need to interface with the server node to 398 obtain an external address (or a tuple of address and TCP/UDP port) 399 while communicating with hosts in external realms. In addition, 400 if NAT were to act as tunnel end-point, host-NAT clients will 401 need to interface with NAT to setup tunnel state for the lifetime 402 of Host-NAT-client address assignment. So, once again, there is a 403 need for an API for use by an external agent(i.e., host-NAT-client) 404 to communicate with NAT, acting as host-NAT-server. 406 Lastly, a mangement utility would be useful to interface with NAT 407 for configuration and monitor purposes and to enforce NAT policies. 408 For example, reconfigure a NAT device to switch over from NAPT to 409 Basic-NAT configuration or vice versa. Or, add, terminate and 410 monitor ALGs and other external agents on a NAT box. Such a program 411 would also be useful to notify NAT about the status and setup 412 information concerning ALGs, backup NATs and Host-NAT clients. 414 Clearly, agents such as Host-NAT-clients and Backup-NATs are likely 415 to reside on a different physical device than the NAT device. Some 416 of the ALG agents may also reside on an external device. The API 417 presented in the follow-on section will provide a base to identify 418 requirements for the development of one or more protocols by which 419 each of these external agents could communicate with NAT. It may be 420 a single protocol applicable to all external agents (or) multiple 421 protocols, specific to each agent type. 423 The following diagram identifies a selected list of external agents 424 that might interact with NAT using its API. 426 +------------------+ +------+ +-------------+ +------------------+ 427 | Host-NAT-Clients | | ALGs | | Pri/Sec NAT | | Management Appl. | 428 +-----+------------+ +------+ +-------------+ +------------------+ 429 ^ ^ ^ ^ 430 | | | | 431 | | | | 432 v v v v 433 +---------------------------------------------+ 434 | NAT Application Program Interface (NAT-API) | 435 +---------------------------------------------+ 436 | N A T | 437 +---------------------------------------------+ 439 figure 1. External agents interfacing with NAT using NAT-API. 441 The following list of attributes uniquely identify an external 442 agent with reference to a NAT. 444 a. Agent IDentifier 446 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 447 to the agent by the NAT device to distinguish from other 448 agents. Typically, this handle may be assigned when the 449 agent registers with NAT. 451 b. Agent type 453 Based on the categories of external agents described thus far, 454 it is clear that the API requirements differ considerably 455 amongst them. A native NAT API may or may not be able to 456 support the requirements of all these agents. It is beneficial 457 for NAT to know the agent type to be one of ALG or 458 Host-NAT-Client or Backup-NAT or Management Application or 459 something else, so it can accept or deny registration. 461 c. Agent call-back requirements 463 The agents will typically require NAT to invoke a call-back 464 function within the agent when NAT notices the occurrence of 465 an external event. But, the call-back requirements across 466 the agents vary. For example, an ALG might require NAT to 467 call back when a data packet is received on a session with 468 a certain session-tag. But, other agents do not have such 469 a requirement. There may , however, be some common 470 requirements for call-back upon events such as termination 471 of a session, termination of a Bind and termination of NAT 472 itself. In addition, management applications and Backup-NAT 473 may have a requirement to have NAT periodically invoke a 474 call-back function. 476 d. Agent call-back functions 478 Depending upon call-back requirements, the agent will be 479 required to register one or more call-back function entry 480 points with NAT. Below are three different call-back 481 function prototypes. 483 Event notification - void agent_callback_event(nat_id, 484 agent_id, event_type, event_status) 486 Periodic notification - void agent_callback_periodic(nat_id, 487 agent_id, info_type, info_length, 488 information) 490 Packet notification - void agent_callback_packet(nat_id, 491 agent_id, session_id, 492 pkt_direction, packet) 494 e. Periodic Notification interval 496 This parameter would be required only when the agent calls 497 for periodic notification. This may be specified in units of 498 seconds. 500 f. Host-NAT-Server tunnel type requirement 502 A Host-NAT-client may have a requirement for NAT, acting as 503 Host-NAT-server to support a certain type of tunneling. In 504 such a case, the agent will specify the tunneling 505 requirement through this parameter. 507 g. Agent access information 509 In the case the agent is resident on a different physical 510 device than NAT, this parameter is used by the agent to 511 specify a means by which NAT can access the agent. This 512 will include a combination of Agent's IP address, 513 IP protocol (e.g., TCP or UDP), well-known port etc. 514 As a special case, a value of 0 to agent_ip_address would 515 indicate that the agent is on the same device as NAT. 517 4. NAT Application Programming Interface (NAT API) 519 The following API is specified in pseudo C language and is by no 520 means exhaustive in coverage. The API may vary from vendor to 521 vendor. The intent is to provide a framework that could be 522 expanded upon as required in the future. This section is divided 523 into two sub-sections. The first sub-section lists function 524 calls available to external agents. These calls are synchronous 525 and require NAT to return back a value. The second sub-section 526 lists functions that are expected to be provided by external 527 agents in order for NAT to call-back upon some events. 529 4.1. NAT API functions 531 4.1.1. int nat_enquire_IDentity(nat_type, &natid_info) 533 Purpose: 535 This function is used by external agents to obtain NAT-ID 536 and its characteristics, as described in section 2.1 538 Input parameters: 540 nat_type - This parameter is specified to verify if NAT 541 device supports a certain flavor of NAT. 543 Output Parameters: 545 natid_info - NAT will fill up the natid_info data structure 546 with its characteristics, as described in 547 section 2.1. Also returned in this block would be 548 an Identifier (nat_id) to uniquely identify this NAT. 550 Multiple pieces of this information may be returned, 551 if NAT supports multiple instances of the same NAT 552 type. 554 Return Value: 556 No-Error(0) - A return value of 0 implies success 557 and that natid_info may be examined 558 for NAT description. 560 NAT-TYPE-NOT-SUPPORTED - Notify the client that the 561 requested NAT device does not 562 support the specified NAT type. 564 4.1.2. int nat_enquire_address_bind (nat_id, pvt_address, 565 ext_address, &bind_info) 567 Purpose: 569 This function is used by external agents to obtain 570 Address BIND information. 572 Input parameters: 574 nat_id - The identifier that uniquely identifies the NAT instance. 576 pvt_address, ext_address - The caller might specify both or just 577 one of either private address or external address and 578 set the other to zero. 580 Output Parameters: 582 bind_info - NAT will fill up the bind_info data structure 583 with info as described in section 2.2, if NAT were 584 to find a match for the addresses specified. 586 Return Value: 588 No-Error(0) - A return value of 0 implies success 589 in finding a match. 591 NO-MATCHING_BIND - Notify the client that there isn't a BIND 592 matching the specified addresses. 594 INVALID-NAT-ID - The specified NAT-ID is not operational 595 or is incorrect. 597 4.1.3. int nat_enquire_transport_bind(nat_id, pvt_address, pvt_port, 598 transport_protocol, ext_address, ext_port, &bind_info) 600 Purpose: 602 This function is used by external agents to obtain 603 Transport ID BIND information. 605 Input parameters: 607 nat_id - The identifier that uniquely identifies the NAT instance. 609 pvt_address, pvt_port, 610 ext_address, ext_port - The caller might specify both or just 611 one of either (private address and the port no.) or 612 external address and the port number. 614 transport_protocol - This must be one of TCP, UDP or ICMP Query 616 Output Parameters: 618 bind_info - NAT will fill up the bind_info data structure 619 with info as described in section 2.2, if NAT were 620 to find a match for the addresses specified. 622 Return Value: 624 No-Error(0) - A return value of 0 implies success 625 in finding a match. 627 NO-MATCHING_BIND - Notify the client that there isn't a BIND 628 matching the specified addresses. 630 INVALID-NAT-ID - The specified NAT-ID is not operational 631 or is incorrect. 633 4.1.4. int nat_enquire_sess_range(nat_id, agent_id, sessid_min, 634 sessid_max, &sess_count, &sess_info) 636 Purpose: 638 This function is used by external agents to request NAT to 639 send all valid session information for sessions with an 640 ID in the range of sessid_min through sessid_max. 642 Input parameters: 644 nat_id - The identifier that uniquely identifies the NAT 645 instance. 647 agent_id - The agent Identifier that uniquely identifies the 648 agent to NAT. 650 sessid_min, 651 sessid_max - The range of session IDs that the agent is 652 interested in knowing about. 654 Output Parameters: 656 sess_count - Number of sessions being returned through 657 sess_info pointer. 659 sess_info - Return one or more sessions maintained by NAT, 660 with an ID in the given range. 662 Return Value: 664 No-Error(0) - A return value of 0 implies successful 665 session termination. 667 INVALID-NAT-ID - The specified NAT-ID is not operational 668 or is incorrect. 670 INVALID-AGENT-ID - The specified Agent-ID is not currently 671 registered with NAT. 673 4.1.5. int nat_register_agent (nat_id, &agent_info) 675 Purpose: 677 This function is used by external agents to register 678 with NAT. 680 Input parameters: 682 nat_id - The identifier that uniquely identifies the NAT 683 instance. 685 agent_info - The agent is required to provide all the requisite 686 information (with the exception of agent_id) as 687 described in section 3.0. This ID may be used by 688 the caller to control and influence NAT operation. 690 Output Parameters: 692 agent_info - NAT will return the agent_id in agent_info structure 693 when registration is successful. 695 Return Value: 697 No-Error(0) - A return value of 0 implies successful 698 registration. 700 AGENT-TYPE-NOT-SUPPORTED - Notify the caller that NAT does not 701 support API requirements of the agent. 703 TUNNEL-TYPE-NOT-SUPPORTED - Notify the caller that NAT does not 704 support Host-NAT tunnel type 705 requested. 707 INVALID-NAT-ID - The specified NAT-ID is not operational 708 or is incorrect. 710 4.1.6. int nat_set_bind (nat_id, agent_id, &bind_info) 711 Purpose: 713 This function is used by external agents to create a new Address 714 Bind or set certain parameters of an existing Bind. 716 Input parameters: 718 nat_id - The identifier that uniquely identifies the NAT 719 instance. 721 agent_id - The agent Identifier that uniquely identifies the 722 agent to NAT. 724 bind_info - The caller supplies the specifics of a new BIND or 725 sets a selected number of parameters of an existing 726 BIND to influence NAT operation. The BIND can be 727 an address BIND or transport BIND. A new BIND 728 request is made by setting the BIND ID within 729 bind_info structure to 0. A non-Zero Bind-ID would 730 be interpreted by NAT to mean that the agent is 731 attempting to set some BIND parameters. 733 Output Parameters: 735 bind_info - If the caller requested for a BIND creation and NAT 736 was successful in creating a new BIND, NAT will 737 fill the structure with the assigned BIND ID and 738 any other NAT assigned parameter values. If the 739 caller requested to set some BIND parameters and 740 NAT succeeded in doing so, the bind_info would 741 be filled with the values that NAT holds. 743 Return Value: 745 No-Error(0) - A return value of 0 implies successful 746 BIND creation or parameter setting. 748 BIND-MAKE-FAILED - When NAT was unable to create BIND 749 or was unable to set the requested 750 parameter(s). 752 INVALID-BIND-INFO - When NAT finds that one or all of the 753 parameters specified is not valid. 755 INVALID-NAT-ID - The specified NAT-ID is not operational 756 or is incorrect. 758 INVALID-AGENT-ID - The specified Agent-ID is not currently 760 registered with NAT. 762 4.1.7. int nat_set_sess(nat_id, agent_id, &sess_info) 764 Purpose: 766 This function is used by external agents to create a new session 767 state or set certain parameters of an existing session. 769 Input parameters: 771 nat_id - The identifier that uniquely identifies the NAT 772 instance. 774 agent_id - The agent Identifier that uniquely identifies the 775 agent to NAT. 777 sess_info - The caller supplies the specifics of a new session 778 parameters or sets a selected number of parameters 779 of an existing session to influence NAT operation. 780 A new session request is made by setting the 781 session-ID within sess_info structure to 0. A 782 non-Zero session-ID would be interpreted by NAT to 783 mean that the agent is attempting to set some 784 session specific parameters. 786 Output Parameters: 788 sess_info - If the caller requested for a session creation and 789 NAT was successful in creating a new session, NAT 790 will fill the structure with the assigned session-ID 791 and any other NAT assigned parameter values. If the 792 caller requested to set some session parameters and 793 NAT succeeded in doing so, the sess_info would 794 be filled with the values that NAT holds. 796 Return Value: 798 No-Error(0) - A return value of 0 implies successful 799 session creation or parameter setting. 801 SESS-MAKE-FAILED - When NAT was unable to create session 802 or was unable to set the requested 803 parameter(s). 805 INVALID-SESS-INFO - When NAT finds that one or all of the 806 parameters specified is not valid. 808 INVALID-NAT-ID - The specified NAT-ID is not operational 809 or is incorrect. 811 INVALID-AGENT-ID - The specified Agent-ID is not currently 812 registered with NAT. 814 4.1.8. int nat_free_bind(nat_id, agent_id, bind_id) 816 Purpose: 818 This function is used by external agents to terminate 819 the specified BIND and any sessions that are based on 820 this BIND. 822 Input parameters: 824 nat_id - The identifier that uniquely identifies the NAT 825 instance. 827 agent_id - The agent Identifier that uniquely identifies the 828 agent to NAT. 830 bind_id - The ID of the BIND that needs to be terminated. 832 Output Parameters: 834 none. 836 Return Value: 838 No-Error(0) - A return value of 0 implies successful 839 BIND termination. 841 INVALID-BIND-ID - The specified BIND ID does not exist. 843 INVALID-NAT-ID - The specified NAT-ID is not operational 844 or is incorrect. 846 INVALID-AGENT-ID - The specified Agent-ID is not currently 847 registered with NAT. 849 4.1.9. int nat_free_sess(nat_id, agent_id, sess_id) 851 Purpose: 853 This function is used by external agents to terminate 854 the specified session. 856 Input parameters: 858 nat_id - The identifier that uniquely identifies the NAT 859 instance. 861 agent_id - The agent Identifier that uniquely identifies the 862 agent to NAT. 864 sess_id - The ID of the session that needs to be terminated. 866 Output Parameters: 868 none. 870 Return Value: 872 No-Error(0) - A return value of 0 implies successful 873 session termination. 875 INVALID-SESS-ID - The specified session ID does not exist. 877 INVALID-NAT-ID - The specified NAT-ID is not operational 878 or is incorrect. 880 INVALID-AGENT-ID - The specified Agent-ID is not currently 881 registered with NAT. 883 4.1.10. int nat_free_sess_bundle(nat_id, agent_id, bundle_id) 885 Purpose: 887 This function is used by external agents to terminate 888 a bundle of sessions identified by the same bundle ID. 890 Input parameters: 892 nat_id - The identifier that uniquely identifies the NAT 893 instance. 895 agent_id - The agent Identifier that uniquely identifies the 896 agent to NAT. 898 bundle_id - The ID of the session bundle (group of sessions) 899 that needs to be terminated. 901 Output Parameters: 903 none. 905 Return Value: 907 No-Error(0) - A return value of 0 implies successful 908 session termination. 910 INVALID-BUNDLE-ID - The specified bundle ID does not exist. 912 INVALID-NAT-ID - The specified NAT-ID is not operational 913 or is incorrect. 915 INVALID-AGENT-ID - The specified Agent-ID is not currently 916 registered with NAT. 918 4.2. Call-back functions within an external agent 920 4.2.1. void agent_callback_event(nat_id, agent_id, event_type, 921 &event_info) 923 Purpose: 925 This function is used by NAT to notify an agent of an 926 event status. 928 Input parameters: 930 nat_id - The identifier that uniquely identifies the NAT 931 instance. 933 agent_id - The agent Identifier that uniquely identifies the 934 agent to NAT. 936 event_type - The event can be one of BIND creation, BIND 937 termination, session Creation, and session 938 termination. 940 event_info - This will return the BIND or session description 941 structure that contains the specific instance 942 identifier and other pertinent information. 944 4.2.2. void agent_callback_periodic(nat_id, agent_id, info_type, 945 info_length, &periodic_info) 947 Purpose: 949 This function is used by NAT to notify an agent of a 950 certain piece of information periodically. 952 Input parameters: 954 nat_id - The identifier that uniquely identifies the NAT 955 instance. 957 agent_id - The agent Identifier that uniquely identifies the 958 agent to NAT. 960 info_type - NAT may have been requested to periodically 961 notify the agent many types of information. 962 Possible values for this parameter would be 963 statistics update, Incremental BIND update 964 Incremental session update, Incremental 965 BIND termination, Incremental session 966 termination etc.. 968 info_length- Number of bytes included in periodic info block. 970 periodic_info - This point to the actual periodic information 971 being sent to the agent. 973 4.2.3. void agent_callback_packet(nat_id, agent_id, sess_id, 974 pkt_direction, packet) 976 Purpose: 978 This function is used by NAT to notify an agent of a 979 data packet for processing. The agent is expected to 980 process the packet and forward to the actual destination 981 in the first-in-first-out (FIFO) order. The processing 982 performed by the agent may be limited to just the payload 983 or the entire packet, as set by the agent at session 984 setup time. 986 Input parameters: 988 nat_id - The identifier that uniquely identifies the NAT 989 instance. 991 agent_id - The agent Identifier that uniquely identifies the 992 agent to NAT. 994 sess_id - The Identifier if NAT session to which the packet 995 belongs. 997 pkt_direction - This can be inbound or outbound. 999 packet - IP packet that needs to be processed by the agent. 1000 If NAT was required to perform header translation, 1001 this packet is post-NAT-translated version of 1002 the packet. In the case the agent selected to 1003 perform the entire translation, the original 1004 packet is sent as is to the agent, without any 1005 NAT transformation. 1007 5. Acknowledgement 1009 The author would like to express sincere appreciation and thanks 1010 to Yakov Rekhter for his valuable advice and contribution in the 1011 presentation of this document. 1013 6. Security considerations. 1015 The security considerations described in [Ref 1] for all variations 1016 of NATs are applicable here. 1018 REFERENCES 1020 [1] P. Srisuresh, M. Holdrege, "IP Network Address Translator 1021 (NAT) Terminology and Considerations", 1022 - Work in progress. 1024 [2] Y. Rekhter, B. Moskowitz, D. Karrenberg, G. de Groot, and, 1025 E. Lear, "Address Allocation for Private Internets", RFC 1918 1027 [3] J. Reynolds and J. Postel, "Assigned Numbers", RFC 1700 1029 [4] R. Braden, "Requirements for Internet Hosts -- Communication 1030 Layers", RFC 1122 1032 [5] R. Braden, "Requirements for Internet Hosts -- Application 1033 and Support", RFC 1123 1035 [6] F. Baker, "Requirements for IP Version 4 Routers", RFC 1812 1037 [7] J. Postel, J. Reynolds, "FILE TRANSFER PROTOCOL (FTP)", 1038 RFC 959 1040 [8] "TRANSMISSION CONTROL PROTOCOL (TCP) SPECIFICATION", RFC 793 1042 [9] J. Postel, "INTERNET CONTROL MESSAGE (ICMP) SPECIFICATION", 1043 RFC 792 1045 [10] J. Postel, "User Datagram Protocol (UDP)", RFC 768 1047 [11] J. Mogul, J. Postel, "Internet Standard Subnetting Procedure", 1048 RFC 950 1050 [12] Brian carpenter, Jon Crowcroft, Yakov Rekhter, "IPv4 Address 1051 Behaviour Today", RFC 2101 1053 Author's Address: 1055 Pyda Srisuresh 1056 Lucent technologies 1057 4464 Willow Road 1058 Pleasanton, CA 94588-8519 1059 U.S.A. 1061 Voice: (925) 737-2153 1062 Fax: (925) 737-2110 1063 EMail: suresh@ra.lucent.com