idnits 2.17.1 draft-ietf-nat-interface-framework-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 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 279 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 242 has weird spacing: '...l Agent who h...' == Line 304 has weird spacing: '...essions beari...' == Line 366 has weird spacing: '...l Agent who h...' == Line 408 has weird spacing: '...l state for t...' == Line 533 has weird spacing: '...section lists...' -- 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 1219 == Unused Reference: '1' is defined on line 1224, but no explicit reference was found in the text == Unused Reference: '2' is defined on line 1227, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 1230, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 1232, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 1235, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 1238, but no explicit reference was found in the text == Unused Reference: '7' is defined on line 1240, but no explicit reference was found in the text == Unused Reference: '8' is defined on line 1243, but no explicit reference was found in the text == Unused Reference: '9' is defined on line 1245, but no explicit reference was found in the text == Unused Reference: '10' is defined on line 1248, but no explicit reference was found in the text == Unused Reference: '11' is defined on line 1250, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 1253, 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: 9 errors (**), 0 flaws (~~), 17 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 NAT Working Group P. Srisuresh 2 INTERNET-DRAFT Consultant 3 Category: Informational October, 1999 4 Expire in six months 6 Framework for interfacing with Network Address Translator 7 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. Internet-Drafts 13 are working documents of the Internet Engineering Task Force 14 (IETF), its areas, and its working groups. Note that other 15 groups may also 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 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 Abstract 31 NAT provides routing transparency for hosts in disparate address 32 realms to communicate with each other. However, external agents 33 such as Application Level Gateways (ALGs), Realm Specific IP 34 (RSIP) clients and Management applications need to interact with 35 NAT and influence its operations. The document identifies NAT 36 controlled resources, which may be used as reference to generate 37 NAT Management Information Base (MIB). Further, an Application 38 Programming Interface (API) is presented to illustrate the 39 framework in which external agents interact with NAT. However, 40 it is not the intent of this document to mandate standardize the 41 API. Rather, use the API as basis to illustrate NAT interface 42 requirements. These requirements provide a basis for the 43 development of one or more protocols by which external agents 44 could interact with NAT. 46 1. Introduction 48 NAT provides routing transparency for hosts in disparate address 49 realms to communicate with each other. [Ref 1] details the various 50 flavors of NAT that abound. Many internet applications us IP 51 address as host identifier rather than just as a way to locate a 52 host. For this reason, routing transparency by NAT alone is not 53 sufficient to provide end-to-end transparency for applications 54 operating across realms. Application specific ALGs are required 55 in conjunction with NAT to provide end-to-end transparency for 56 some applications. 58 In addition to ALGs, there are other kinds of external agents that 59 may need to influence NAT operation. Section 3 below identifies a 60 list of external agents that may likely interface with NAT. 61 Section 2 below is devoted to describing the resources controlled 62 by NAT. The requirements of external agents, combined with the 63 nature of NAT resources provide the basis to derive an API 64 framework, described in section 4. Section 5 is used to illustrate 65 how an external agent could use the framework developed to 66 influence NAT operation. 68 The intent of the document is two-fold. First, the document 69 identifies the NAT controlled resources. This may be used as a 70 basis to develop NAT Management Information Base (MIB). This is 71 also used as the basis for developing a pseudo Application 72 Programming Interface (API) by which external agents could 73 interface with NAT. This does not assume or require external 74 agents to reside on the same physical device as NAT, even though 75 assuming they reside on the same physical device does help in 76 the understanding of the API. In reality, it is likely to be a 77 combination of both. Some agents are co-located with NAT on the 78 same device and others reside on external devices. The API is 79 merely a suggestion and may vary from vendor to vendor. 81 Second, the API provides a framework to identify requirements for 82 the development of one or more protocols by which external agents 83 (specified in section 3 below) could communicate with NAT. Such 84 a protocol would need to authenticate clients, locate NAT devices 85 and exchange data elements. The API specified in the document 86 assumes a trusted environment and does not address the first two 87 issues, namely authentication and Service location. The document 88 also does not cover any communication protocol that may be used by 89 external agents to interface with NAT using the API described here. 90 These issues will need to be addressed independently outside the 91 purview of this document. 93 2. Elements of NAT operation 95 In order to identify an API for use by external agents, it is 96 important to understand the resources and other elments managed 97 by NAT. This would help identify the extent to which an external 98 agent may influence NAT operation. This section describes objects 99 within NAT, that could be externalized via Management Information 100 Base (MIB). 102 2.1. NAT Descriptor 104 All flavors of NAT are designed to provide routing transparency 105 to hosts in disparate address realms. A physical device may have 106 multiple NAT instances or there may be multiple NAT devices 107 associated with a specific realm. The following list of attributes 108 identify a specific instance of NAT. 110 a. NAT IDentifier: 112 A NAT Identifier uniquely identifies a NAT instantiation. 113 The External interface address may be one way to uniquely 114 describe NAT Identifier. 116 b. Private and External realm types: 118 Every NAT device will have a minimum of two routing 119 interfaces, one connecting to a private realm and one 120 connecting to external realm. An IPv4 NAT device will 121 have both its realm types set to IPv4. 123 c. NAT type 125 NAT type could be one of Basic-NAT, NAPT, Bi-directional-NAT, 126 Twice-NAT, RSA-IP server, RSAP-IP-server or a combination 127 of the above. NAT type is an indication of the direction in 128 which NAT sessions are allowed and the extent of translation 129 within the IP and transport headers. [Ref 1] has a discussion 130 on the nature of various NAT flavors and the extent of their 131 translations. 133 d. Address(and Transport-ID) maps 135 Address map on a NAT device could consist of one or more of 136 static and dynamic Address maps. Likewise, Transport-ID 137 mapping could consists of one or more of static and dynamic 138 transport-ID maps. Transport-ID mapping is more specific 139 than address mapping in that a specific TCP/UDP port (or 140 port range) pertaining to an address in external realm is 141 mapped to a specific TCP/UDP port (or port range) in private 142 realm or vice versa. Address (and Transport-ID) maps may be 143 defined for both inbound and outbound directions. Outbound 144 address map refers to mapping a selected set of addresses 145 from private realm to a selected set of addresses in 146 external realm; whereas inbound address map refers to 147 mapping a set of addresses from the external realm to 148 private realm. 150 e. Miscellaneous parameters 152 NAT may optionally provide TCP, UDP and other types of session 153 Idle-times used to terminate sessions. It may also provide the 154 current range (and, the maximum range) of session IDs and 155 Bind IDs (to be covered in the follow on sub-sections); and 156 the actual count of session IDs and BIND IDs. Specifically, 157 this information will be of relevance to another NAT (backup 158 NAT) that intends to emulate this NAT, in case of failure. 159 Lastly, NAT may choose to supply any other vendor specific 160 parameters such as log options, session direction failure 161 actions and so forth. 163 f. Realm Specific IP (RSIP) parameters 165 A NAT device offering RSIP-Server capability may specify the 166 RSIP tunnel types it supports. 168 2.2. Address (and Transport-ID) BINDing Descriptor 170 These bindings can be static or dynamic. Hereafter, the term BIND 171 will be used in place of BINDing, for ease of use. When external 172 agents do not intervene, dynamic address(and transport-ID) binding 173 is determined by NAT based on the first packet of a session, as 174 described in [Ref 1]. Address binding is between an address in 175 private realm and an address from external realm. Transport-ID BIND 176 is an extension of the same concept to the tuple of Address and 177 transport ID (such as TCP/UDP port no.). The following list of 178 attributes describe the BIND object(s) maintained by a NAT device. 180 a. Bind ID 182 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 183 to BIND to uniquely identify this BIND from a different BIND 184 on the same NAT. 186 b. Direction of Bind 187 A bind can be uni-directional or bi-directional, same as the 188 orientation of address map based on which this BIND is formed. 189 As before, the direction is with reference to private realm. 191 c. Bind type 193 Indicates whether the BIND is Address-BIND (between a pair of 194 addresses) or Transport-ID-Bind (between a pair of Address, 195 transport ID tuples). Further, this also indicates if the Bind 196 is static or dynamically generated. 198 d. Private and External addresses (and Transport-IDs) 200 Theese parameters specify the BINDing items in private and 201 external realms. 203 e. Maximum lease time 205 The validity of a BIND may be limited by the duration of lease 206 time it is allowed. Unless the lease time is renewed, a BIND 207 will not be valid past the lease time. As a special case, a 208 value of 0 may be assumed to indicate no lease time limit. 209 Typically, this attribute is of relevance only in conjunction 210 with Realm-Specific-IP(RSIP) operation. 212 f. Available lease time 214 This parameter is of relevance only when Maximum lease time is 215 a non-zero value. At any given instance of time, this parameter 216 indicates the real-time left for a BIND to remain valid. 217 Typically, this attribute is of relevance only in conjunction 218 with Realm-Specific-IP(RSIP) operation. 220 g. Maximum Idle time 222 This parameter indicates maximum amount of time a dynamic BIND 223 is allowed to remain valid, with no NAT session hanging off this 224 BIND. Typically, a dynamic Bind is established when NAT notices 225 the first session that needs such a binding. Subsequent to 226 this, multiple NAT sessions can be maintained using the same 227 binding. When the last of these sessions is terminated, the 228 bind is also terminated. In other words, Maximum Idle time is 0, 229 by default, for native NAT. External agents could control this 230 parameter differently. Static Binds and lease time limited BINDs 231 are not effected by this parameter. 233 h. Current Idle time 235 This parameter is of relevance only when Maximum Idle time is 236 set to a non-zero value. At any given instance of time, this 237 parameter indicates the real-time the BIND has been idle with 238 no sessions attached to it. 240 i. Controlling Agent IDentification 242 This indicates the last external Agent who has tried to 243 control (i.e., set) parameters for this BIND. A value of 0 244 indicates that native NAT is the responsible agent. 246 2.3. Session State descriptor 248 NAT maintains soft-state for the sessions it tracks. Typically, these 249 states are created dynamically during NAT operation and are 250 referenced for translation of packets pertaining to the session. The 251 translation of a packet is based on the bind(two binds in case of 252 twice-nat) the session state points to. The following list of 253 attributes identify a session state (or, simply session) within NAT. 255 a. Session IDentifier 257 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 258 to session to uniquely identify this from other sessions on 259 the same NAT. 261 b. Direction of Session. 263 Direction of first packet of the session. As specified 264 earlier, direction is with reference to private realm. 266 c. Bind IDentifier 268 Identifies the Bind based on which this session is created. 269 The Direction of BIND must be same as that of the session, 270 if the BIND is uni-directional. Typically, if a Bind supporting 271 the session translation does not already exist, a Bind is 272 created prior to creating new session state. However, this 273 Identifier may be set to 0, when BIND creation is unnecessary 274 for the session. For example, there can be no more than one 275 ICMP Query session using am ICMP Query based transport-ID-bind. 276 In such a case, it suffices to do away with BIND and keep all 277 requisite information within the session state itself. 279 d. Second Bind IDentifier 281 This is of relevance only to Twice-NAT. For all other flavors 282 of NAT, this parameter may be set to zero. In the case of 283 Twice-NAT, the Primary Bind Identifier refers to the binding 284 of source address (of the first packet) and the Second Bind 285 Identifier refers to the binding of the destination address. 287 e. Original Session parameters 289 These parameters identify the session level parameters as 290 they appear in the first packet of session. These parameters 291 include src and dest IP addresses, IP protocol and transport 292 IDentifier info (such as TCP/UDP port numbers or ICMP Query 293 Identifier). 295 f. Translated Session parameters 297 These parameters identify the session level parameters as 298 the first packet of session is translated. These parameters 299 are derived from the BIND ID(s) off which this session hangs. 301 g. Session tag 303 NAT managed sessions are assigned a session tag, so that 304 sessions bearing the same tag (session bundle) are handled 305 the same way. A session tag may be identified as a tuple of 306 (, ). This tag value is of 307 significance to NAT or an external agent controlling the 308 session. NAT retains control of all sessions, unless an 309 agent registers to control the session. For example, an 310 FTP-ALG may choose to take control of all sessions with 311 an FTP (TCP port 21) session tag. 313 h. Session Termination heuristic 315 Session-Idle-time is typically used as a heuristic means by NAT 316 to determine if the session has ended. There may other heuristic 317 approaches. A value of zero is an indication that NAT would not 318 use any heuristic to session termination, unless it is a TCP 319 session and the session has noticeable ended with FIN or RST 320 options. The agent may take the responsibility for terminating 321 the session. 323 i. Maximum Idle time 325 This parameter indicates maximum amount of time this session 326 is allowed to remain valid, even as there is no activity. 327 Idle time is typically used as a heuristic means to determine 328 session termination. There may be other heuristic approaches. 329 As a special case, a value of 0 implies that NAT should run 331 the same timer as used for native sessions. 333 j. Current Idle Time 335 This parameter is of relevance only when session termination 336 heuristic is set to session-idle-time. Typically, NAT would 337 examine the idle time on the sessions it manages periodically 338 and updates this variable. When the idle time exceeds the 339 maximum allowed idle time, the session is terminated. 341 k. Packet modifier functions 343 Typically, NAT modifies IP header and sometimes the transport 344 header. External agents may choose to assume responsibility 345 for payload modification alone, or the entire packet 346 modification. In the case an external agent assumes 347 responsibility for the entire packet modification, NAT will 348 simply redirect the original packet as is to external 349 translation agent. Otherwise, NAT will perform its share of 350 translation (i.e., IP and transport header translation) and 351 direct the translated packet to external agent. 353 l. Bundle ID 355 Applications that deal with a bundle of sessions may cause 356 multiple sessions to be managed by NAT. Even though these 357 sessions constitute a single session from application stand 358 point, NAT is not congnizant of the relation. In such cases, 359 it is not uncommon for external agents to store a unique 360 application ID (say, the session ID of the first NAT session 361 the application originated) in all sessions it spawns in its 362 incarnation. By default, this would be same as the session-id. 364 m. Controlling Agent IDentification 366 This indicates the last external Agent who has tried to 367 control parameters for this session. A value of 0 indicates 368 that native NAT is the responsible agent. 370 3. External agents interfacing with NAT 372 Many network applications assume the IP address of their host to be 373 host Identifier and embed the Identifier information in application 374 specific payload. When packets from such an application traverse 375 NAT, the IP address of private host remains uncorrected in the 376 payload, as the packet is delivered to hosts in external realm. An 377 Application Level Gateway (ALG) is required to re-interpret such a 378 payload as the payload traverses realms. 380 In addition, there are applications such as H.323 that use 381 out-of-band signaling to dynamically create newer sessions. While 382 a signaling session itself may be directed to a well-known port, 383 sessions created by it need not be that way. Once again, an ALG may 384 be required to process payload in the signaling sessions and notify 385 NAT to recognize the newly created sessions. 387 There may be other instances where an ALG may be required to 388 provide application level transparency. In all cases, there is a 389 need for the ALGs to interface with NAT. The ALGs may reside 390 on the NAT device or on an external device. Independent of where 391 an ALG resides, NAT interface requirements remain the same. 393 In a multi-homed NAT configuration, there is a need for a backup NAT 394 to communicate with the primary and keep in sync, so that when the 395 primary goes away, the backup NAT could instantly assume support for 396 the sessions that primary NAT was responsible for. This is yet 397 another case where an external agent (i.e., backup NAT) has a need 398 to interface with NAT. 400 A NAT device is uniquely qualified to serve as Realm-Specific-IP 401 Server (i.e., RSA-IP-Server or RSAP-IP-Server) for Realm-Specific-IP 402 clients (i.e., RSA-IP clients or RSAP-IP clients). [Ref 1] has a 403 description of RSIP terminology. RSA-IP clients and RSAP-IP clients 404 need to interface with the server node to obtain an external address 405 (or a tuple of address and TCP/UDP port) while communicating with 406 hosts in external realms. In addition, if NAT were to act as tunnel 407 end-point, RSIP clients will need to interface with NAT to setup 408 tunnel state for the lifetime of RSIP-client address assignment. 409 So, once again, there is a need for an API for use by an external 410 agent(i.e., RSIP client) to communicate with NAT, acting as 411 RSIP-server. 413 Lastly, a mangement utility would be useful to interface with NAT 414 for configuration and monitor purposes and to enforce NAT policies. 415 For example, reconfigure a NAT device to switch over from NAPT to 416 Basic-NAT configuration or vice versa. Or, add, terminate and 417 monitor ALGs and other external agents on a NAT box. Such a program 418 would also be useful to notify NAT about the status and setup 419 information concerning ALGs, backup NATs and RSIP clients. 421 Clearly, agents such as RSIP clients and Backup-NATs are likely 422 to reside on a different physical device than the NAT device. Some 423 of the ALG agents may also reside on an external device. The API 424 presented in the follow-on section will provide a base to identify 425 requirements for the development of one or more protocols by which 426 each of these external agents could communicate with NAT. It may be 427 a single protocol applicable to all external agents (or) multiple 428 protocols, specific to each agent type. 430 The following diagram identifies a selected list of external agents 431 that might interact with NAT using its API. 433 +--------------+ +------+ +-------------+ +------------------+ 434 | RSIP Clients | | ALGs | | Pri/Sec NAT | | Management Appl. | 435 +--------------+ +------+ +-------------+ +------------------+ 436 ^ ^ ^ ^ 437 | | | | 438 | | | | 439 v v v v 440 +---------------------------------------------+ 441 | NAT Application Program Interface (NAT-API) | 442 +---------------------------------------------+ 443 | N A T | 444 +---------------------------------------------+ 446 figure 1. External agents interfacing with NAT using NAT-API. 448 The following list of attributes uniquely identify an external 449 agent with reference to a NAT. 451 a. Agent IDentifier 453 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 454 to the agent by the NAT device to distinguish from other 455 agents. Typically, this handle may be assigned when the 456 agent registers with NAT. 458 b. Agent type 460 Based on the categories of external agents described thus far, 461 it is clear that the API requirements differ considerably 462 amongst them. A native NAT API may or may not be able to 463 support the requirements of all these agents. It is beneficial 464 for NAT to know the agent type to be one of ALG or 465 RSIP Client or Backup-NAT or Management Application or 466 something else, so it can accept or deny registration. 468 c. Agent call-back requirements 470 An agent will typically require NAT to invoke a call-back 471 function supplied by the agent upon the occurrence of 472 specific events. However, events for which an agent 473 wants to be notified of varies based on agent type. 475 An ALG will require NAT to call back when a data packet is 476 received on a session with a certain session-tag (say, FTP 477 session). Management applications and Backup-NAT might 478 require NAT to periodically invoke a call-back function. 479 Events all agents might require to be notified of (through 480 a call-back function) would be - termination of a session 481 with certain session-tag or session-ID, termination of a 482 Bind and termination of NAT itself. 484 d. Agent call-back functions 486 Depending upon call-back requirements, the agent will be 487 required to register one or more call-back function entry 488 points with NAT. Below are three different call-back 489 function prototypes. 491 Event notification - void agent_callback_event(nat_id, 492 agent_id, event, event_info) 494 Periodic notification - void agent_callback_periodic(nat_id, 495 agent_id, info_type, info_length, 496 information) 498 Packet notification - void agent_callback_packet(nat_id, 499 agent_id, session_id, 500 pkt_direction, packet) 502 e. Periodic Notification interval 504 This parameter would be required only when the agent calls 505 for periodic notification. This may be specified in units of 506 seconds. 508 f. RSIP Server tunnel type requirement 510 An RSIP client may have a requirement for NAT, acting as 511 RSIP server to support a certain type of tunneling. In 512 such a case, the agent will specify the tunneling 513 requirement through this parameter. 515 g. Agent access information 517 In the case the agent is resident on a different physical 518 device than NAT, this parameter is used by the agent to 519 specify a means by which NAT can access the agent. This 520 will include a combination of Agent's IP address, 521 IP protocol (e.g., TCP or UDP), well-known port etc. 522 As a special case, a value of 0 to agent_ip_address would 523 indicate that the agent is on the same device as NAT and 524 a proprietary mechanism may be assumed to exist to access 525 the agent. 527 4. NAT Application Programming Interface (NAT API) 529 An API is specified below (in pseudo C language) to provide a 530 framework by which external agents could interface with a NAT 531 device. The API is by no means exhaustive in coverage and may 532 vary from vendor to vendor. This section is divided into two 533 sub-sections. The first sub-section lists function calls 534 available to external agents. These calls are synchronous 535 and require NAT to return back a value. The second sub-section 536 lists functions that are expected to be provided by external 537 agents in order for NAT to call-back upon some events. 539 4.1. NAT API functions 541 4.1.1. int nat_enquire_IDentity(nat_type, **natid_info) 543 Purpose: 545 This function is used by external agents to obtain NAT-ID 546 and its characteristics, as described in section 2.1 548 Input parameters: 550 nat_type - This parameter is specified to verify if NAT 551 device supports a certain flavor of NAT. 552 A value of 0 requires all instances of NAT 553 to be reported 555 Output Parameters: 557 natid_info - NAT will fill up a descriptor block with its 558 characteristics (as described in section 2.1) 559 for the matching nat_type and return pointer 560 to the descriptor block. The descriptor 561 block would specifically include an identifier 562 (nat_id) that uniquely identifies NAT instance. 564 Multiple pieces of this information may be returned, 565 if NAT supports multiple instances of the same NAT 566 type. Multiple instances of NAT descriptor blocks 567 may also be returned when nat_type is set to 0 and 568 the NAT device supports multiple NAT instances. 570 Return Value: 572 No-Error(0) - A return value of 0 implies success 573 and that natid_info may be examined 574 for NAT description. 576 NAT-TYPE-NOT-SUPPORTED - Notify the client that the 577 requested NAT device does not 578 support the specified NAT type. 580 4.1.2. int nat_enquire_address_bind (nat_id, pvt_address, 581 ext_address, &bind_info) 583 Purpose: 585 This function is used by external agents to obtain 586 Address BIND information. 588 Input parameters: 590 nat_id - The identifier that uniquely identifies the NAT instance. 592 pvt_address, ext_address - The caller might specify both or just 593 one of either private address or external address and 594 set the other to zero. 596 Output Parameters: 598 bind_info - NAT will fill up the bind_info data structure 599 with info as described in section 2.2, if NAT were 600 to find a match for the addresses specified. 602 Return Value: 604 No-Error(0) - A return value of 0 implies success 605 in finding a match. 607 NO-MATCHING_BIND - Notify the client that there isn't a BIND 608 matching the specified addresses. 610 INVALID-NAT-ID - The specified NAT-ID is not operational 611 or is incorrect. 613 4.1.3. int nat_enquire_transport_bind(nat_id, pvt_address, pvt_port, 614 transport_protocol, ext_address, ext_port, &bind_info) 615 Purpose: 617 This function is used by external agents to obtain 618 Transport ID BIND information. 620 Input parameters: 622 nat_id - The identifier that uniquely identifies the NAT instance. 624 pvt_address, pvt_port, 625 ext_address, ext_port - The caller might specify both or just 626 one of either (private address and the port no.) or 627 external address and the port number. 629 transport_protocol - This must be one of TCP, UDP or ICMP Query 631 Output Parameters: 633 bind_info - NAT will fill up the bind_info data structure 634 with info as described in section 2.2, if NAT were 635 to find a match for the addresses specified. 637 Return Value: 639 No-Error(0) - A return value of 0 implies success 640 in finding a match. 642 NO-MATCHING_BIND - Notify the client that there isn't a BIND 643 matching the specified addresses. 645 INVALID-NAT-ID - The specified NAT-ID is not operational 646 or is incorrect. 648 4.1.4. int nat_enquire_sess_range(nat_id, agent_id, sessid_min, 649 sessid_max, &sess_count, &sess_info) 651 Purpose: 653 This function is used by external agents to request NAT to 654 send valid session information for all sessions with an ID 655 in the range of sessid_min through sessid_max. As a special 656 case, this will return session descriptor block for a 657 single session when sessid_min and sessid_max are the same. 659 Input parameters: 661 nat_id - The identifier that uniquely identifies the NAT 662 instance. 664 agent_id - The agent Identifier that uniquely identifies the 665 agent to NAT. 667 sessid_min, sessid_max - The range of session IDs that the 668 agent is interested in knowing about. 670 Output Parameters: 672 sess_count - Number of sessions being returned through 673 sess_info pointer. 675 sess_info - Return one or more sessions maintained by NAT, 676 with an ID in the given range. 678 Return Value: 680 No-Error(0) - A return value of 0 implies successful 681 session termination. 683 INVALID-NAT-ID - The specified NAT-ID is not operational 684 or is incorrect. 686 INVALID-AGENT-ID - The specified Agent-ID is not currently 687 registered with NAT. 689 4.1.5. int nat_register_agent (nat_id, &agent_info) 691 Purpose: 693 This function is used by external agents to register with NAT. 695 Input parameters: 697 nat_id - The identifier that uniquely identifies the NAT 698 instance. 700 agent_info - The agent is required to provide all the requisite 701 information (with the exception of agent_id) as 702 described in section 3.0. This ID may be used by 703 the caller to influence NAT operation. 705 Output Parameters: 707 agent_info - NAT will return the agent_id in agent_info structure 708 when registration is successful. 710 Return Value: 712 No-Error(0) - A return value of 0 implies successful 713 registration. 715 AGENT-TYPE-NOT-SUPPORTED - Notify the caller that NAT does not 716 support API requirements of the agent. 718 TUNNEL-TYPE-NOT-SUPPORTED - Notify caller that NAT does not 719 support the RSIP tunnel type 720 requested. 722 INVALID-NAT-ID - The specified NAT-ID is not operational 723 or is incorrect. 725 4.1.6. int nat_set_bind (nat_id, agent_id, &bind_info) 727 Purpose: 729 This function is used by external agents to create a new Address 730 Bind or set certain parameters of an existing Bind. 732 Input parameters: 734 nat_id - The identifier that uniquely identifies the NAT 735 instance. 737 agent_id - The agent Identifier that uniquely identifies the 738 agent to NAT. 740 bind_info - The caller supplies the specifics of a new BIND or 741 sets a selected number of parameters of an existing 742 BIND to influence NAT operation. The BIND can be 743 an address BIND or transport BIND. A new BIND 744 request is made by setting the BIND ID within 745 bind_info structure to 0. A non-Zero Bind-ID would 746 be interpreted by NAT to mean that the agent is 747 attempting to set some BIND parameters. 749 Output Parameters: 751 bind_info - If the caller requested for a BIND creation and NAT 752 was successful in creating a new BIND, NAT will 753 fill the structure with the assigned BIND ID and 754 any other NAT assigned parameter values. If the 755 caller requested to set some BIND parameters and 756 NAT succeeded in doing so, the bind_info would 757 be filled with the values that NAT holds. 759 Return Value: 761 No-Error(0) - A return value of 0 implies successful 762 BIND creation or parameter setting. 764 BIND-MAKE-FAILED - When NAT was unable to create BIND 765 or was unable to set the requested 766 parameter(s). 768 INVALID-BIND-INFO - When NAT finds that one or all of the 769 parameters specified is not valid. 771 INVALID-NAT-ID - The specified NAT-ID is not operational 772 or is incorrect. 774 INVALID-AGENT-ID - The specified Agent-ID is not currently 775 registered with NAT. 777 4.1.7. int nat_set_sess(nat_id, agent_id, &sess_info) 779 Purpose: 781 This function is used by external agents to create a new session 782 state or set certain parameters of an existing session. 784 Input parameters: 786 nat_id - The identifier that uniquely identifies the NAT 787 instance. 789 agent_id - The agent Identifier that uniquely identifies the 790 agent to NAT. 792 sess_info - The caller supplies the specifics of a new session 793 parameters or sets a selected number of parameters 794 of an existing session to influence NAT operation. 795 A new session request is made by setting the 796 session-ID within sess_info structure to 0. A 797 non-Zero session-ID would be interpreted by NAT to 798 mean that the agent is attempting to set some 799 session specific parameters. 801 Output Parameters: 803 sess_info - If the caller requested for a session creation and 804 NAT was successful in creating a new session, NAT 805 will fill the structure with the assigned session-ID 806 and any other NAT assigned parameter values. If the 807 caller requested to set some session parameters and 808 NAT succeeded in doing so, the sess_info would 809 be filled with the values that NAT holds. 811 Return Value: 813 No-Error(0) - A return value of 0 implies successful 814 session creation or parameter setting. 816 SESS-MAKE-FAILED - When NAT was unable to create session 817 or was unable to set the requested 818 parameter(s). 820 INVALID-SESS-INFO - When NAT finds that one or all of the 821 parameters specified is not valid. 823 INVALID-NAT-ID - The specified NAT-ID is not operational 824 or is incorrect. 826 INVALID-AGENT-ID - The specified Agent-ID is not currently 827 registered with NAT. 829 4.1.8. int nat_free_bind(nat_id, agent_id, bind_id) 831 Purpose: 833 This function is used by external agents to terminate 834 the specified BIND and any sessions that are based on 835 this BIND. 837 Input parameters: 839 nat_id - The identifier that uniquely identifies the NAT 840 instance. 842 agent_id - The agent Identifier that uniquely identifies the 843 agent to NAT. 845 bind_id - The ID of the BIND that needs to be terminated. 847 Output Parameters: 849 none. 851 Return Value: 853 No-Error(0) - A return value of 0 implies successful 854 BIND termination. 856 INVALID-BIND-ID - The specified BIND ID does not exist. 858 INVALID-NAT-ID - The specified NAT-ID is not operational 859 or is incorrect. 861 INVALID-AGENT-ID - The specified Agent-ID is not currently 862 registered with NAT. 864 4.1.9. int nat_free_sess(nat_id, agent_id, sess_id) 866 Purpose: 868 This function is used by external agents to terminate 869 the specified session. 871 Input parameters: 873 nat_id - The identifier that uniquely identifies the NAT 874 instance. 876 agent_id - The agent Identifier that uniquely identifies the 877 agent to NAT. 879 sess_id - The ID of the session that needs to be terminated. 881 Output Parameters: 883 none. 885 Return Value: 887 No-Error(0) - A return value of 0 implies successful 888 session termination. 890 INVALID-SESS-ID - The specified session ID does not exist. 892 INVALID-NAT-ID - The specified NAT-ID is not operational 893 or is incorrect. 895 INVALID-AGENT-ID - The specified Agent-ID is not currently 896 registered with NAT. 898 4.1.10. int nat_free_sess_bundle(nat_id, agent_id, bundle_id) 900 Purpose: 902 This function is used by external agents to terminate 903 a bundle of sessions identified by the same bundle ID. 905 Input parameters: 907 nat_id - The identifier that uniquely identifies the NAT 908 instance. 910 agent_id - The agent Identifier that uniquely identifies the 911 agent to NAT. 913 bundle_id - The ID of the session bundle (group of sessions) 914 that needs to be terminated. 916 Output Parameters: 918 none. 920 Return Value: 922 No-Error(0) - A return value of 0 implies successful 923 session termination. 925 INVALID-BUNDLE-ID - The specified bundle ID does not exist. 927 INVALID-NAT-ID - The specified NAT-ID is not operational 928 or is incorrect. 930 INVALID-AGENT-ID - The specified Agent-ID is not currently 931 registered with NAT. 933 4.2. Call-back functions within an external agent 935 4.2.1. void agent_callback_event(nat_id, agent_id, event_type, 936 &event_info) 938 Purpose: 940 This function is used by NAT to notify an agent of an 941 event status. 943 Input parameters: 945 nat_id - The identifier that uniquely identifies the NAT 946 instance. 948 agent_id - The agent Identifier that uniquely identifies the 949 agent to NAT. 951 event_type - The event can be one of BIND creation, BIND 952 termination, session Creation, and session 953 termination. 955 event_info - This will return the BIND or session description 956 structure that contains the specific instance 957 identifier and other pertinent information. 959 4.2.2. void agent_callback_periodic(nat_id, agent_id, info_type, 960 info_length, &periodic_info) 962 Purpose: 964 This function is used by NAT to notify an agent of a 965 certain piece of information periodically. 967 Input parameters: 969 nat_id - The identifier that uniquely identifies the NAT 970 instance. 972 agent_id - The agent Identifier that uniquely identifies the 973 agent to NAT. 975 info_type - NAT may have been requested to periodically 976 notify the agent many types of information. 977 Possible values for this parameter would be 978 statistics update, Incremental BIND update 979 Incremental session update, Incremental 980 BIND termination, Incremental session 981 termination etc.. 983 info_length- Number of bytes included in periodic info block. 985 periodic_info - This point to the actual periodic information 986 being sent to the agent. 988 4.2.3. void agent_callback_packet(nat_id, agent_id, sess_id, 989 pkt_direction, packet) 991 Purpose: 993 This function is used by NAT to notify an agent of a 994 data packet for processing. The agent is expected to 995 process the packet and forward to the actual destination 996 in the first-in-first-out (FIFO) order. The processing 997 performed by the agent may be limited to just the payload 998 or the entire packet, as set by the agent at session 999 setup time. 1001 Input parameters: 1003 nat_id - The identifier that uniquely identifies the NAT 1004 instance. 1006 agent_id - The agent Identifier that uniquely identifies the 1007 agent to NAT. 1009 sess_id - The Identifier if NAT session to which the packet 1010 belongs. 1012 pkt_direction - This can be inbound or outbound. 1014 packet - IP packet that needs to be processed by the agent. 1015 If NAT was required to perform header translation, 1016 this packet is post-NAT-translated version of 1017 the packet. In the case the agent selected to 1018 perform the entire translation, the original 1019 packet is sent as is to the agent, without any 1020 NAT transformation. 1022 5. An illustration of the use of Interface framework 1024 The following is an illustration of how an FTP-ALG could use 1025 the API specified to interface with NAT and provide 1026 application level transparency for FTP application. Note, 1027 this is not meant to be a detailed description of how an 1028 FTP-ALG would work. But, rather an illustration of how the 1029 FTP-ALG could use the API to interface with NAT. The section 1030 is divided into three sub-sections to illustrate (a) ALG 1031 registration with NAT, (b) NAT interface with ALG while an FTP 1032 session is active, and (c) NAT notifocation to ALG when the 1033 FTP session terminates. 1035 5.1. FTP-ALG registration with NAT 1037 FTP-ALG will first probe NAT device to understand the type of 1038 service provided by NAT and obtain NAT-ID. Once the service 1039 type is agreeable, the ALG will register itself as a client 1040 with the NAT device with callback functions (as described 1041 below) and obtain an agent-ID from the NAT. The tuple of 1042 (nat-id, agent-id) uniquely identifies the interface 1043 between NAT and ALG. 1045 ftp_alg_pkt_notify() will be registered to process FTP 1046 session (TCP port 21) traffic. ftp_alg_event_notify() will 1047 be registered to process session or NAT termination. 1049 FTP-ALG NAT 1050 ------- --- 1052 1. Obtain NAT descriptor Info 1054 nat_enquire_IDentity( 1055 0, **nat_descriptor) 1056 ------------------------> 1057 NAT will fill a descriptor 1058 block with pertinent information, 1059 specifically NAT-type and NAT-ID 1060 and supply the pointer to the 1061 descriptor block. 1063 OK 1064 <------------------------------ 1066 2. Register with NAT as ALG for 1067 FTP (TCP port 21) and obtain 1068 agent-ID from the NAT. 1070 nat_register_agent(nat_id, 1071 &ftp_alg_info) 1072 ------------------------> 1074 NAT will assign an agent-ID. 1076 OK 1077 <------------------------------ 1079 5.2. NAT interface with the ALG during FTP session operation 1081 When NAT sees the first packet of an FTP session, it sets up 1082 a BIND descriptor and a session descriptor and tags the 1083 session descriptor as FTP-Type (i.e., TCP port 21). NAT 1084 will then redirect the packet to FTP-ALG by invoking the 1085 ALG supplied callback function - ftp_alg_pkt_notify(). 1086 The ALG will obtain session descriptor and BIND descriptor 1087 info from the NAT. 1089 Subsequent to this, when NAT redirects FTP packets, the 1090 ALG would parse the payload for PORT command or response to 1091 "PASV" to determine ensuing data sessions and interact with 1092 NAT, as necessary, to obtain the requisite translation 1093 parameters. The ALG may modify the FTP packet with 1094 translation parameters prior to resending to NAT for 1095 forwarding. 1097 FTP-ALG NAT 1098 ------- --- 1100 1. NAT sees the first packet 1101 of an FTP session. NAT will 1102 set up a session state and 1103 notify the agent as follows. 1105 ftp_alg_pkt-notify(nat-id, 1106 agent-ID, session-ID, 1107 packet-direction, pkt) 1108 <------------------------ 1110 The ALG may optionally make 1111 calls to the NAT to find out 1112 about the session and BIND 1113 characteristics of the FTP. 1114 Further, additional calls may 1115 be made to change the control 1116 parameters in these blocks. 1118 nat_enquire_sess_range( 1119 nat_id, agent-id, 1120 session_id, session_id, 1121 &sess_count, **sess_info) 1122 ------------------------------> 1123 Find the session descriptor 1124 block matching session_id and 1125 return Pointer to this. Bind-id 1126 is one of the items in the block. 1128 OK 1129 <------------------------------ 1130 ... 1132 nat_enquire_address_bind( 1133 nat_id, pvt_address, 1134 external_address, &bind_info) 1135 ------------------------------> 1136 ... 1138 nat_set_bind( 1139 nat_id, agent_id, &bind_info) 1140 ------------------------------> 1142 ............. 1144 n. NAT will forward all 1145 subsequent FTP packets to 1146 the agent as follows. 1148 ftp_alg_pkt-notify(nat-id, 1149 agent-ID, session-ID, 1150 packet-direction, pkt) 1151 <------------------------ 1153 The ALG will parse for PORT 1154 command and PASV response in 1155 the payload and track any deltas 1156 to TCP sequence and acknowledge 1157 numbers. The ALG will interact 1158 with NAT, as necessary, to obtain 1159 BIND parameters for the data 1160 session, setup data session state 1161 ahead of time and modify the FTP 1162 packet (as necessary) prior to 1163 resending to NAT for forwarding. 1165 Request BIND parameters for the 1166 new data session such that there 1167 is no leased-time set for it. 1169 nat_set_bind(nat_id, agent-id, 1170 &bind_info) 1171 ------------------------------> 1173 .... 1175 Setup a new state for the data 1176 session such that the Bundle-ID 1177 is set to be the session ID of 1178 the controlling FTP session. 1180 nat_set_sess(nat-id, agent-id, 1181 &sess-info) 1182 ----------------------------> 1184 5.3. Session termination notification 1186 When the FTP control session is ready to be terminated 1187 by the NAT, NAT will notifiy the event to FTP-ALG as follows. 1189 FTP-ALG NAT 1190 ------- --- 1192 1. NAT determines the FTP 1193 session is to be 1194 terminated. 1196 ftp_alg_notify(nat-id, 1197 agent-id, 1198 SESSION-TERMINATED, 1199 session-ID) 1200 <------------------------ 1202 The ALG will in turn clean up any 1203 data sessions that may be based on 1204 the FTP session prior to freeing 1205 the control session itself. 1207 nat_free_sess(nat-id, agent-id, 1208 sess-id) 1209 ----------------------------> 1211 6. Acknowledgement 1213 The author would like to express sincere appreciation and thanks 1214 to Yakov Rekhter for his valuable advice and contribution in the 1215 presentation of this document. 1217 7. Security considerations. 1219 The security considerations described in [Ref 1] for all variations 1220 of NATs are applicable here. 1222 REFERENCES 1224 [1] P. Srisuresh, M. Holdrege, "IP Network Address Translator 1225 (NAT) Terminology and Considerations", RFC 2663 1227 [2] Y. Rekhter, B. Moskowitz, D. Karrenberg, G. de Groot, and, 1228 E. Lear, "Address Allocation for Private Internets", RFC 1918 1230 [3] J. Reynolds and J. Postel, "Assigned Numbers", RFC 1700 1232 [4] R. Braden, "Requirements for Internet Hosts -- Communication 1233 Layers", RFC 1122 1235 [5] R. Braden, "Requirements for Internet Hosts -- Application 1236 and Support", RFC 1123 1238 [6] F. Baker, "Requirements for IP Version 4 Routers", RFC 1812 1240 [7] J. Postel, J. Reynolds, "FILE TRANSFER PROTOCOL (FTP)", 1241 RFC 959 1243 [8] "TRANSMISSION CONTROL PROTOCOL (TCP) SPECIFICATION", RFC 793 1245 [9] J. Postel, "INTERNET CONTROL MESSAGE (ICMP) SPECIFICATION", 1246 RFC 792 1248 [10] J. Postel, "User Datagram Protocol (UDP)", RFC 768 1250 [11] J. Mogul, J. Postel, "Internet Standard Subnetting Procedure", 1251 RFC 950 1253 [12] Brian carpenter, Jon Crowcroft, Yakov Rekhter, "IPv4 Address 1254 Behaviour Today", RFC 2101 1256 Author's Address: 1258 Pyda Srisuresh 1259 Consultant 1260 849 Erie Circle 1261 Milpitas, CA 95035 1262 U.S.A. 1264 Voice: (408) 263-7527 1265 EMail: srisuresh@yahoo.com