idnits 2.17.1 draft-ietf-nat-interface-framework-03.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: ---------------------------------------------------------------------------- ** 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 28 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 319 has weird spacing: '...l Agent who h...' == Line 450 has weird spacing: '...l state for t...' -- 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.) -- The document date (October 9, 2001) is 8233 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: 'Ref 1' on line 1326 -- Looks like a reference, but probably isn't: 'Ref1' on line 340 -- Looks like a reference, but probably isn't: 'Ref 7' on line 1133 == Unused Reference: '1' is defined on line 1336, but no explicit reference was found in the text == Unused Reference: '2' is defined on line 1339, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 1342, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 1344, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 1347, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 1350, but no explicit reference was found in the text == Unused Reference: '7' is defined on line 1352, but no explicit reference was found in the text == Unused Reference: '8' is defined on line 1355, but no explicit reference was found in the text == Unused Reference: '9' is defined on line 1357, but no explicit reference was found in the text == Unused Reference: '10' is defined on line 1360, but no explicit reference was found in the text == Unused Reference: '11' is defined on line 1362, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 1365, 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: 8 errors (**), 0 flaws (~~), 14 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NAT Working Group P. Srisuresh 3 INTERNET-DRAFT Jasmine Networks 4 Category: Informational April, 2000 5 Expires on October 9, 2001 7 Framework for interfacing with Network Address Translator 8 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance 13 with all provisions of Section 10 of RFC2026. Internet-Drafts 14 are working documents of the Internet Engineering Task Force 15 (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other 20 documents at any time. It is inappropriate to use Internet- 21 Drafts as reference material or to cite them other than as 22 "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Abstract 32 NAT is a stateful network device, providing routing transparency 33 for hosts in disparate address realms to communicate with each 34 other. External agents such as Application Level Gateways (ALGs), 35 Realm Specific IP (RSIP) clients and Management applications may 36 need to interact with NAT to influence its operation. The document 37 identifies resources that may be exposed to external agents and 38 illustrates resource control through an Application Programming 39 Interface (API). While the document is focused on describing how 40 to interface with a middlebox supporting NAT function, the 41 description may be applicable to any middlebox that keeps 42 soft-state for sessions. The intent is not to standardize the 43 API. Rather, use API as the basis for the development of a 44 middlebox communication (MIDCOM) protocol by which MIDCOM agents 45 can interface with NAT. NAT resources identified can also form 46 the basis to generate NAT Management Information Base (MIB). 48 1. Introduction 50 NAT provides routing transparency for hosts in disparate address 51 realms to communicate with each other. [Ref 1] details the various 52 flavors of NAT that abound. Many internet applications use IP 53 address as host identifier rather than just as a way to locate a 54 host. For this reason, routing transparency by NAT alone is not 55 sufficient to provide end-to-end transparency for applications 56 operating across realms. Application specific ALGs are required 57 in conjunction with NAT to provide end-to-end transparency for 58 some applications. 60 In addition to ALGs, there can be other kinds of external agents 61 that choose to influence NAT operation. Section 3 identifies 62 these agents. Section 2 below is devoted to describing the 63 resources controlled by NAT. The requirements of external 64 agents, combined with the nature of NAT resources provide the 65 basis to illustrate the resource control mechanism functionally 66 through an API in section 4. Section 5 illustrates how an 67 external agent could use the API to influence NAT operation. 69 The intent of the document is two-fold. First, an illustration 70 through an API on how to control NAT resource/operation to form 71 a basis for the development of a protocol by which external 72 agents could communicate with NAT. A portion of the communication 73 interface is generic enough that it can be applied to any 74 stateful middlebox. Further, there are extensions that are NAT 75 specific. The API illustration assumes a trusted environment and 76 does not address authentication, authorization or discovery of 77 middlebox location. It is also important to note that the 78 illustration does not assume or require external agents to reside 79 on the same physical device as NAT. In reality, some agents may 80 be co-located with middlebox on the same device and others reside 81 on external devices. Discussion of a communication protocol for 82 use by external agents to interface with middlebox is outside 83 the purview of this document. 85 Second, NAT controlled resource description specified in the 86 document may be used as the basis to develop NAT Management 87 Information Base (MIB). 89 2. Terminology 91 Definitions for majority of terms used in this document may be found 92 in NAT Terminology and Considerations document [Ref 1]. Below are 93 terms defined specifically for this document. 95 2.1. MiddleBox and Middlebox services 97 Middlebox is a network intermediate device implementing a 98 middlebox service. Middlebox service is characterized as a 99 networking function requiring application intelligence for 100 its operation. A middlebox service is also referred as 101 Middlebox function throughout this document. Examples of 102 middlebox functions include NAT, firewall, intrusion 103 detection, load balancing, policy based tunneling and 104 IPsec security Gateway enforcement. A middlebox may 105 implement one or more of these functions. 107 Clearly, NAT is a specific middlebox function and NAT device 108 is a specific Middlebox device. 110 2.2. MIDCOM Agents 112 MIDCOM agents are entities performing ALG function, logically 113 external to a middlebox. MIDCOM agents possess a combination of 114 application awareness and knowledge of the middlebox function. 115 A MIDCOM agent may communicate with one or more middleboxes. 116 A MIDCOM agent is also referred as "external agent" throughout 117 the document. 119 2.3. Middlebox Communication (MIDCOM) protocol 121 The protocol used by MIDCOM agents to interface with the middlebox 122 and its resources to influence its operation. This is a protocol 123 yet to be devised. The interface API presented in the document, 124 while focused on NAT function, may be used as the basis for the 125 development of such a protocol, extensible to other middlebox 126 functions. 128 3. Elements of NAT operation 130 In order to identify an API for use by external agents, it is 131 important to understand the resources and other elements managed 132 by NAT. This would help identify the extent to which an external 133 agent may influence NAT operation. This section describes objects 134 within NAT, that could be externalized via Management Information 135 Base (MIB). 137 3.1. Service Descriptor 139 Of the fields listed below to describe the service, items 3.1.1 140 through 3.1.2 are independent of the service the devise supports. 141 The remaining items are NAT service specific. All flavors of NAT 142 are designed to provide routing transparency to hosts in 143 disparate address realms. A middlebox may have multiple NAT 144 instances or there may be multiple NAT middleboxs associated 145 with a specific realm. The following attributes identify a 146 specific instance of a middlebox supporting NAT function. 148 3.1.1. Service IDentifier 150 A service identifier uniquely identifies service instantiation 151 within a middlebox. The external interface address may be 152 one way to uniquely describe this Identifier. 154 3.1.2. Service type 156 The service supported on the intermediate node could be one of 157 Basic-NAT, NAPT, Bi-directional-NAT, Twice-NAT, RSA-IP server, 158 RSAP-IP-server or a combination of the above. Service type is 159 an indication of the direction in which new sessions are 160 permitted and the extent of translation done within the IP and 161 transport headers. [Ref 1] has a discussion on NAT flavors and 162 the extent of their translations. 164 3.1.3. Private and External realm types 166 Every NAT device will have a minimum of two routing 167 interfaces, one connecting to a private realm and one 168 connecting to external realm. An IPv4 NAT device will 169 have both its realm types set to IPv4. 171 3.1.4. Address(and Transport-ID) maps 173 Address map on a NAT device is constituted of one or more of 174 static/ dynamic Address maps. Transport-ID mapping, on 175 the other hand, constitutes one or more of static/dynamic 176 transport-ID maps. Transport-ID maps a specific TCP/UDP port 177 (or port range) pertaining to an address in external realm 178 to a specific TCP/UDP port (or port range) in private realm 179 or vice versa. Address (and Transport-ID) maps may be 180 defined for both inbound and outbound directions. Outbound 181 address map refers to mapping a selected set of addresses 182 from private realm to a selected set of addresses in 183 external realm; whereas inbound address map refers to 184 mapping a set of addresses from the external realm to 185 private realm. 187 3.1.5. Miscellaneous parameters 189 NAT may optionally provide TCP, UDP and other types of session 190 Idle-times used to terminate sessions. It may also provide the 191 current range (and, the maximum range) of session IDs and 192 Bind IDs (to be covered in the follow on sub-sections); and 193 the actual count of session IDs and BIND IDs. Specifically, 194 this information will be of relevance to another NAT (backup 195 NAT) that intends to emulate this NAT, in case of failure. 196 Lastly, NAT may choose to supply any other vendor specific 197 parameters such as log options, session direction failure 198 actions and so forth. 200 3.1.6. Realm Specific IP (RSIP) parameters 202 A NAT device offering RSIP-Server capability may specify the 203 RSIP tunnel types it supports. 205 3.2. Address (and Transport-ID) BIND Descriptor 207 Hereafter, the term BIND will be used in place of BINDing, for ease 208 of use. BIND descriptor is specific to NAT service. These BINDs 209 can be static or dynamic. When external agents do not intervene, 210 dynamic address(and transport-ID) binding is determined by NAT 211 based on the first packet of a session, as described in [Ref 1]. 212 Address binding is between an address in private realm and an 213 address from external realm. Transport-ID BIND is an extension of 214 the same concept to the tuple of Address and transport ID (such as 215 TCP/UDP port no.). The following attributes describe the BIND 216 object(s) maintained by a NAT device. 218 3.2.1. Bind ID 220 A number (say, in the range of 1 through 0xFFFFFFFF) assigned 221 to BIND to uniquely identify the BIND on a NAT middlebox. 223 3.2.2. Direction of Bind 225 A bind can be uni-directional or bi-directional, same as the 226 orientation of address map based on which this BIND is formed. 227 As before, the direction is with reference to private realm. 229 3.2.3. Bind type 231 Indicates whether the BIND is Address-BIND (between a pair of 232 addresses) or Transport-ID-Bind (between a pair of Address, 233 transport ID tuples). Further, this also indicates if the Bind 234 is static or dynamically generated. 236 3.2.4. Private and External addresses (and Transport-IDs) 238 These parameters specify the BINDing items in private and 239 external realms. 241 3.2.5. MIDCOM Agent IDentification 243 This indicates the last external Agent that registered to 244 control (i.e., set) parameters for this BIND. A value of 0 245 indicates that native NAT is the responsible agent. 247 3.2.6. Maximum lease time 249 The validity of a BIND may be limited by the duration of lease 250 time it is allowed. Unless the lease time is renewed, a BIND 251 will not be valid past the lease time. As a special case, a 252 value of 0 may be assumed to indicate no lease time limit. 253 Typically, this attribute is of relevance only in conjunction 254 with Realm-Specific-IP(RSIP) operation. 256 3.2.7. Available lease time 258 This parameter is of relevance only when Maximum lease time is 259 a non-zero value. At any given instance of time, this parameter 260 indicates the real-time left for a BIND to remain valid. 261 Typically, this attribute is of relevance only in conjunction 262 with Realm-Specific-IP(RSIP) operation. 264 3.2.8. Maximum Idle time 266 This parameter indicates maximum amount of time a dynamic BIND 267 is allowed to remain valid, with no NAT session hanging off this 268 BIND. Typically, a dynamic Bind is established when NAT notices 269 the first session that needs such a binding. Subsequent to 270 this, multiple NAT sessions can be maintained using the same 271 binding. When the last of these sessions is terminated, the 272 bind is also terminated. In other words, Maximum Idle time is 0, 273 by default, for native NAT. External agents could control this 274 parameter differently. Static Binds and lease time limited BINDs 275 are not effected by this parameter. 277 3.2.9. Current Idle time 279 This parameter is of relevance only when Maximum Idle time is 280 set to a non-zero value. At any given instance of time, this 281 parameter indicates the real-time the BIND has been idle with 282 no sessions attached to it. 284 3.3. Session descriptor 286 NAT device maintains soft-state for the sessions it tracks. 287 These states may be created dynamically during NAT operation 288 and are referenced for translation of packets pertaining to the 289 session. The entries maintained in a session state are specific 290 to the service type supported (e.g., Basic NAT, NAPT, twice-NAT 291 etc.). For instance, twice-NAT service will require two BINDs, 292 unlike other NAT variations which use just one BIND. The 293 following attributes identify various parameters tracked with a 294 session. Items 2.3.1 through 2.3.9 below are service independent. 295 The remaining items are NAT service specific. Not all services 296 need to track all parameters. 298 3.3.1. Session IDentifier 300 A unique number (say, in the range of 1 through 0xFFFFFFFF) 301 assigned by middlebox to a session to uniquely identify this 302 from other sessions on the same device. 304 3.3.2. Direction of Session 306 Direction of first packet of the session. As specified 307 earlier, direction is with reference to private realm. 309 3.3.3. Original Session parameters 311 These parameters identify the session level parameters as 312 they appear in the first packet of session. These parameters 313 include src and dest IP addresses, IP protocol and transport 314 IDentifier info (such as TCP/UDP port numbers or ICMP Query 315 Identifier). 317 3.3.4. Controlling Agent IDentification 319 This indicates the last external Agent who has tried to 320 control parameters for this session. A value of 0 indicates 321 that no external agent is registered to control the session. 323 3.3.5. Application tag 324 Sessions are assigned an application tag, so that sessions 325 bearing the same tag can be handled the same way by an 326 external application agent. Application tag may be specified 327 as a tuple of (, ). For example, 328 an FTP-ALG may register with NAT to control sessions with 329 an FTP application tag. 331 3.3.6. Session Termination heuristic 333 Session-Idle-time is typically used as a heuristic to 334 determine if the session has ended. There may be other 335 heuristic approaches. A value of zero indicates that no 336 session termination heuristic is used. The controlling 337 agent may take responsibility for session termination 338 in that case. With or without a termination heuristic, 339 TCP sessions may be terminated based on FIN and RST 340 options in TCP header [Ref1]. 342 3.3.7. Maximum Idle time 344 This parameter indicates maximum amount of time this session 345 is allowed to remain valid, even as there is no activity. 346 This parameter is relevant only when session-Idle-time is used 347 as the heuristic to determine session termination. There may 348 be other heuristic approaches. As a special case, a value of 0 349 implies a that the device should run the default timer 350 configured for all native sessions (that have no controlling 351 agent registered). 353 3.3.8. Current Idle Time 355 This parameter is of relevance only when session termination 356 heuristic is set to session-idle-time. Typically, the device 357 monitors idle time on the sessions it manages periodically 358 and updates this variable. When the idle time exceeds the 359 maximum allowed idle time, the session is terminated. 361 3.3.9. Bundle ID 363 Applications that deal with a bundle of sessions may cause 364 multiple sessions to be managed by the middlebox. Even though 365 these sessions constitute a single session from application 366 stand point, the middlebox is not cognizant of the relation. 367 In such cases, it is not uncommon for controlling agents to 368 store session ID of the initial session in all subsequent 369 sessions spawned in that incarnation of the application. Note, 370 Bundle ID need not be the initial session ID, just a 371 unique ID for all sessions of the bundle. 373 3.3.10. Bind IDentifier 375 Identifies the Bind based on which this session is created. 376 The Direction of BIND must be same as that of the session, 377 if the BIND is uni-directional. Typically, if a Bind supporting 378 the session translation does not already exist, a Bind is 379 created prior to creating new session state. However, this 380 Identifier may be set to 0, when BIND creation is unnecessary 381 for the session. For example, there can be no more than one 382 ICMP Query session using am ICMP Query based transport-ID-bind. 383 In such a case, it suffices to do away with BIND and keep all 384 requisite information within the session state itself. 386 3.3.11. Translated Session parameters 388 These parameters identify the session level parameters as 389 the first packet of session is translated. These parameters 390 are derived from the BIND ID(s) off which this session hangs. 392 3.3.12. Second Bind IDentifier 394 This is of relevance only to Twice-NAT. For all other flavors 395 of NAT, this parameter may be set to zero. In the case of 396 Twice-NAT, the Primary Bind Identifier refers to the binding 397 of source address and the Second Bind Identifier refers to 398 the binding of the destination address(of the first packet). 400 3.3.13. Packet modifier functions 402 Typically, NAT modifies IP header and sometimes the transport 403 header. External agents may choose to assume responsibility 404 for payload modification alone, or the entire packet 405 modification. In the case an external agent assumes 406 responsibility for the entire packet modification, NAT will 407 simply redirect the original packet as is to external 408 translation agent. Otherwise, NAT will perform its share of 409 translation (i.e., IP and transport header translation) and 410 direct the translated packet to external agent. 412 4. External agents interfacing with NAT 414 Many network applications assume the IP address of their host to be 415 host Identifier and embed the Identifier information in application 416 specific payload. When packets from such an application traverse 417 NAT, the IP address of private host remains uncorrected in the 418 payload, as the packet is delivered to hosts in external realm. An 419 Application Level Gateway (ALG) is required to re-interpret such a 420 payload as the payload traverses realms. 422 In addition, there are applications such as H.323 that use 423 out-of-band signaling to dynamically create newer sessions. While 424 a signaling session itself may be directed to a well-known port, 425 sessions created by it need not be that way. Once again, an ALG may 426 be required to process payload in the signaling sessions and notify 427 NAT to recognize the newly created sessions. 429 There may be other instances where an ALG may be required to 430 provide application level transparency. In all cases, there is a 431 need for the ALGs to interface with NAT. The ALGs may reside 432 on the NAT device or on an external device. Independent of where 433 an ALG resides, NAT interface requirements remain the same. 435 In a multi-homed NAT configuration, there is a need for a backup NAT 436 to communicate with the primary and keep in sync, so that when the 437 primary goes away, the backup NAT could instantly assume support for 438 the sessions that primary NAT was responsible for. This is yet 439 another case where an external agent (i.e., backup NAT) has a need 440 to interface with NAT. 442 A NAT device is uniquely qualified to serve as Realm-Specific-IP 443 Server (i.e., RSA-IP-Server or RSAP-IP-Server) for Realm-Specific-IP 444 clients (i.e., RSA-IP clients or RSAP-IP clients). [Ref 1] has a 445 description of RSIP terminology. RSA-IP clients and RSAP-IP clients 446 need to interface with the server node to obtain an external address 447 (or a tuple of address and TCP/UDP port) while communicating with 448 hosts in external realms. In addition, if NAT were to act as tunnel 449 end-point, RSIP clients will need to interface with NAT to setup 450 tunnel state for the lifetime of RSIP-client address assignment. 451 So, once again, there is a need for an API for use by an external 452 agent(i.e., RSIP client) to communicate with NAT, acting as 453 RSIP-server. 455 Lastly, a management utility would be useful to interface with NAT 456 for configuration and monitor purposes and to enforce NAT policies. 457 For example, reconfigure a NAT device to switch over from NAPT to 458 Basic-NAT configuration or vice versa. Or, add, terminate and 459 monitor ALGs and other external agents on a NAT box. Such a program 460 would also be useful to notify NAT about the status and setup 461 information concerning ALGs, backup NATs and RSIP clients. 463 Clearly, agents such as RSIP clients and Backup-NATs are likely 464 to reside on a different physical device than the NAT device. Some 465 of the ALG agents may also reside on an external device. The API 466 presented in the follow-on section will form a basis for the 467 development of a MIDCOM protocol. 469 The following diagram identifies a selected list of external agents 470 that might interact with NAT via an API or an yet to be devised 471 protocol. 473 +--------------+ +------+ +-------------+ +------------------+ 474 | RSIP Clients | | ALGs | | Pri/Sec NAT | | Management Appl. | 475 +--------------+ +------+ +-------------+ +------------------+ 476 ^ ^ ^ ^ 477 | | | | 478 | | | | 479 v v v v 480 +----------------------------------------+ 481 | Middlebox Communication (MIDCOM) API | 482 +----------------------------------------+ 483 | NAT Service | 484 |(Resource management, Packet translation| 485 | and External agent interface) | 486 +----------------------------------------+ 487 | NAT managed resources | 488 | (sessions, BINDs, Address maps etc.) | 489 +----------------------------------------+ 491 Figure 1. External agents interfacing with NAT Middlebox 493 The following attributes uniquely identify an external agent 494 to a middlebox. Items 4.1 through 4.4 are service 495 independent, while the remaining items are NAT specific. 497 4.1. Agent IDentifier 499 A unique number (say, in the range of 1 through 0xFFFFFFFF) 500 assigned to the agent by middlebox so as to distinguish from 501 other agents. Typically, this ID is issued during the agent 502 registration with middlebox. 504 4.2. Agent type 506 The Agent type can be one of ALG or RSIP-Client or Backup-NAT 507 or Management-Application or something else. The agent type 508 may be a criterion used by middlebox to accept or deny 509 registration. 511 4.3. Agent accessibility information 512 When an agent is resident on a different physical device than 513 middlebox, this parameter specifies means by which the 514 middlebox can access the agent. This can be a combination of 515 Agent's IP address, IP protocol (e.g., TCP or UDP), 516 well-known port etc. A value of 0 for agent's IP address 517 indicates that the agent is co-resident with middlebox. 519 4.4. Periodic Notification interval 521 This parameter would be required only when the agent calls 522 for periodic notification from the middlebox. This may be 523 specified in units of seconds. 525 4.5. Agent call-back requirements 527 An agent will typically require the middlebox to invoke a 528 call-back function supplied by the agent upon the occurrence 529 of specific events. Events for which an agent needs 530 notification depends on agent type. 532 An ALG will require NAT to call back when a data packet is 533 received on a session with a certain application-tag (say, 534 FTP). Management applications and Backup-NAT might require 535 NAT to periodically invoke a call-back function. Events all 536 agents might require to be notified of (through 537 a call-back function) would be - session termination, 538 service termination and BIND termination. 540 4.6. Agent call-back functions 542 Depending upon call-back requirements, the agent will be 543 required to register one or more call-back function entry 544 points with the middlebox. Below are three different call-back 545 function prototypes. 547 Event notification - void agent_callback_event(service_id, 548 agent_id, event, event_info) 550 Periodic notification - void agent_callback_periodic(service_id, 551 agent_id, info_type, info_length, 552 information) 553 Packet notification - void agent_callback_packet(service_id, 554 agent_id, sess_id, 555 pkt_direction, packet) 557 4.7. RSIP Server tunnel type requirement 559 An RSIP client may have a requirement for NAT, acting as 560 RSIP server to support a certain type of tunneling. In 561 such a case, the agent will specify the tunneling 562 requirement through this parameter. 564 5. External Agent Programming Interface 566 A resource control mechanism by which external agents could 567 interface with a NAT device is illustrated in this section 568 through an Application Programming Interface (API) in pseudo 569 C language. The API is by no means exhaustive in coverage. 571 This section is divided into three sub-sections. The first 572 two sub-sections list function calls that may be made 573 available to external agents. These calls are synchronous 574 and require the middlebox to return back a value. Functions 575 in the first sub-section are service independent and are 576 prefixed with "middlebox_", whereas functions in the second 577 subsection are NAT service specific and are prefixed with 578 "nat_". The third sub-section lists functions required to 579 be provided by external agents in order for the middlebox 580 to call-back upon some events. 582 5.1. Service-independent middlebox API functions 584 The following functions in a middlebox may be made available to 585 external agents needing to interface with NAT. However, these 586 functions are not NAT specific and may be equally applicable to 587 middleboxes supporting other types of services such as firewall. 588 As such, all functions in this subsection are prefixed with 589 "middlebox_" to highlight the service-neutral nature of these 590 APIs. 592 The functions listed may be broadly divided into three 593 categories - Service-Query functions, Agent-Registration 594 functions and Session management functions. Session Identifiers 595 are used as the basis for middelbox resource interface. While 596 Session Identifier is service-neutral, some of the resources 597 associated with a session-id can be service specific. 599 5.1.1. int middlebox_query_IDentity(service_type, **service_info) 601 Purpose: 603 This function is used to obtain the services and 604 the individual characteristics of the services supported on 605 a middlebox. Characteristics of a NAT service are described 606 in section 3.1 608 Input parameters: 610 service_type - This parameter is filled to verify if the 611 middlebox supports a certain service type 612 (Refer section 3.1.2). A value of 0 may be used 613 to request the middlebox to report all service 614 types supported. 616 Output Parameters: 618 service_info - Middlebox will fill up a descriptor block with 619 all the characteristics for the matching 620 service_type (refer section 3.1 for NAT 621 characteristics) and return pointer to the 622 descriptor block. The descriptor block would 623 specifically include a service identifier (refer 624 section 3.1.1) that uniquely identifies service 625 instance. This is referred as service_id 626 throughout the document. 628 Multiple pieces of this information may be returned, 629 if the middlebox supports multiple instances of the 630 same service type. Multiple instances of descriptor 631 blocks may also be returned when service_type is set 632 to 0 and the middlebox supports multiple service 633 types. 635 Return Value: 637 No-Error(0) - Function processing successful. 638 Service_info may be examined 639 for service description. 641 SERVICE-TYPE-NOT-SUPPORTED - Middlebox does not support the 642 requested service type. 644 5.1.2. int middlebox_register_agent (service_id, &agent_info) 646 Purpose: 648 This function is used by external agents to register with the 649 middlebox. 651 Input parameters: 653 service_id - The identifier that uniquely identifies a specific 654 service instance on a middlebox. 656 agent_info - The agent is required to provide all the requisite 657 information (with the exception of agent_id) as 658 described in section 4.0. This ID may be used by 659 the caller to influence middlebox operation. 661 Output Parameters: 663 agent_info - NAT will set agent_id in agent_info structure 664 when registration is successful. 666 Return Value: 668 No-Error(0) - Registration successful. 670 AGENT-TYPE-NOT-SUPPORTED - Notify the caller that middlebox does 671 not support API requirements of the 672 agent. 674 TUNNEL-TYPE-NOT-SUPPORTED - Notify caller that middlebox does not 675 support the RSIP tunnel type 676 requested. 678 INVALID-SERVICE-ID - The specified service_id is not 679 operational or is incorrect. 681 AGENT-NOT-AUTHORIZED - The specified agent is not authorized 682 to register with the middlebox. 684 5.1.3. int middlebox_unregister_agent (service_id, agent_id) 686 Purpose: 688 This function is used by external agents to unregister with the 689 middlebox. 691 Input parameters: 693 service_id - The identifier that uniquely identifies a specific 694 service instance on a middlebox. 696 agent_id - The agent Identifier that uniquely identifies the 697 agent to middlebox. 699 Output Parameters: 701 None. 703 Return Value: 705 No-Error(0) - Successful unregistration. 707 AGENT-ID-NOT-SUPPORTED - Agent ID unknown to middlebox. 709 INVALID-SERVICE-ID - The specified service_id is not 710 operational or is incorrect. 712 5.1.4. int middlebox_query_sess_range(service_id, agent_id, sessid_min, 713 sessid_max, &sess_count, &sess_info) 715 Purpose: 717 This function is used to request a middlebox to send valid 718 session information for all sessions with an ID in the range 719 of sessid_min through sessid_max. As a special case, this will 720 return session descriptor block for a single session when 721 sessid_min and sessid_max are the same. 723 Input parameters: 725 service_id - The identifier that uniquely identifies a specific 726 service instance on a middlebox. 728 agent_id - The agent Identifier that uniquely identifies the 729 agent to middlebox. 731 sessid_min, sessid_max - The range of session IDs that the 732 agent is interested in knowing about. 734 Output Parameters: 736 sess_count - Number of sessions being returned through 737 sess_info pointer. 739 sess_info - Return one or more sessions with an ID in the 740 given range. 742 Return Value: 744 No-Error(0) - Session termination successful. 746 INVALID-SERVICE-ID- The specified service_id is not operational 747 or is incorrect. 749 INVALID-AGENT-ID - The specified Agent_ID is not currently 750 registered with the middlebox. 752 5.1.5. int middlebox_set_sess(service_id, agent_id, &sess_info) 754 Purpose: 756 This function is used to create a new session state on a middlebox 757 or to set parameters of an existing session. 759 Input parameters: 761 service_id - The identifier that uniquely identifies a specific 762 service instance on a middlebox. 764 agent_id - The agent Identifier that uniquely identifies the 765 agent to middlebox. 767 sess_info - The caller supplies the specifics of a new session 768 parameters or sets a selected number of parameters 769 of an existing session to influence NAT operation. 770 A new session request is made by setting the 771 session-ID within sess_info structure to 0. A 772 non-Zero session-ID would be interpreted by NAT to 773 mean that the agent is attempting to set some 774 session specific parameters. 776 Output Parameters: 778 sess_info - If the caller requested for a session creation and 779 NAT was successful in creating a new session, NAT 780 will fill the structure with the assigned session-ID 781 and any other NAT assigned parameter values. If the 782 caller requested to set some session parameters and 783 NAT succeeded in doing so, the sess_info would 784 be filled with the values that NAT holds. 786 Return Value: 788 No-Error(0) - Successful session creation or parameter 789 setting. 791 SESS-MAKE-FAILED - When middlebox was unable to create session 792 state or was unable to set the requested 793 parameter(s). 795 INVALID-SESS-INFO - When NAT finds that one or all of the 796 parameters specified is not valid. 798 INVALID-SERVICE-ID- The specified service_id is not operational 799 or is incorrect. 801 INVALID-AGENT-ID - The specified Agent_id is not currently 802 registered with the middlebox. 804 5.1.6. int middlebox_free_sess(service_id, agent_id, sess_id) 806 Purpose: 808 This function is used to terminate a session on middlebox. 810 Input parameters: 812 service_id - The identifier that uniquely identifies a specific 813 service instance on a middlebox. 815 agent_id - The agent Identifier that uniquely identifies the 816 agent to NAT. 818 sess_id - The ID of the session that needs to be terminated. 820 Output Parameters: 822 none. 824 Return Value: 826 No-Error(0) - A return value of 0 implies successful 827 session termination. 829 INVALID-SESS-ID - The specified session ID does not exist. 831 INVALID-SERVICE-ID- The specified service_id is not operational 832 or is incorrect. 834 INVALID-AGENT-ID - The specified Agent_id is not currently 835 registered with the middlebox. 837 5.1.7. int middlebox_free_sess_bundle(service_id, agent_id, bundle_id) 839 Purpose: 841 This function is used to terminate a bundle of sessions, 842 identified by the same bundle ID. 844 Input parameters: 846 service_id - The identifier that uniquely identifies a specific 847 service instance on a middlebox. 849 agent_id - The agent Identifier that uniquely identifies the 850 agent to middlebox. 852 bundle_id - The ID of the session bundle (group of sessions) 853 that needs to be terminated. 855 Output Parameters: 857 none. 859 Return Value: 861 No-Error(0) - Successful session termination. 863 INVALID-BUNDLE-ID - The specified bundle ID does not exist. 865 INVALID-SERVICE-ID - The specified service_id is not operational 866 or is incorrect. 868 INVALID-AGENT-ID - The specified Agent_id is not currently 869 registered with the middlebox. 871 5.2. NAT specific API functions 873 The following functions in a middlebox may be made available to 874 external agents needing to interface with NAT. These functions 875 are necessary to manipulate NAT specific resources such as NAT 876 address Binds, Address Maps and session parameters. NAT specific 877 session parameters include translated session tuples, Bind ID 878 and Packet modification functions. As such, all functions in 879 this subsection are prefixed with "nat_" to highlight NAT 880 specific nature of these APIs. 882 5.2.1. int nat_query_address_bind (service_id, pvt_address, 883 ext_address, &bind_info) 885 Purpose: 887 This function is used by external agents to obtain 888 Address BIND information. 890 Input parameters: 892 service_id - This uniquely identifies the NAT instance. 894 pvt_address, ext_address - The caller might specify both or just 895 one of either private address or external address and 896 set the other to zero. 898 Output Parameters: 900 bind_info - NAT will fill up the bind_info data structure 901 with info as described in section 2.2, if NAT were 902 to find a match for the addresses specified. 904 Return Value: 906 No-Error(0) - Successful in finding a match. 908 NO-MATCHING_BIND - Notify the client that there isn't a BIND 909 matching the specified addresses. 911 INVALID-SERVICE-ID - The specified service_id is not operational 912 or is incorrect. 914 5.2.2. int nat_query_transport_bind(service_id, pvt_address, pvt_port, 915 transport_protocol, ext_address, ext_port, &bind_info) 917 Purpose: 919 This function is used by external agents to obtain 920 Transport ID BIND information. 922 Input parameters: 924 service_id - The identifier that uniquely identifies a specific 925 service instance on a middlebox. 927 pvt_address, pvt_port, 928 ext_address, ext_port - The caller might specify both or just 929 one of either (private address and the port no.) or 930 external address and the port number. 932 transport_protocol - This must be one of TCP, UDP or ICMP Query 934 Output Parameters: 936 bind_info - NAT will fill up the bind_info data structure 937 with info as described in section 2.2, if NAT were 938 to find a match for the addresses specified. 940 Return Value: 942 No-Error(0) - A return value of 0 implies success 943 in finding a match. 945 NO-MATCHING_BIND - Notify the client that there isn't a BIND 946 matching the specified addresses. 948 INVALID-SERVICE-ID- The specified service_id is not operational 949 or is incorrect. 951 5.2.3. int nat_set_bind (service_id, agent_id, &bind_info) 953 Purpose: 955 This function is used to create a new Address Bind or set 956 parameters of an existing Bind. 958 Input parameters: 960 service_id - The identifier that uniquely identifies the NAT 961 instance. 963 agent_id - The agent Identifier that uniquely identifies the 964 agent to NAT. 966 bind_info - The caller supplies the specifics of a new BIND or 967 sets a selected number of parameters of an existing 968 BIND to influence NAT operation. The BIND can be 969 an address BIND or transport BIND. A new BIND 970 request is made by setting the BIND ID within 971 bind_info structure to 0. A non-Zero Bind-ID would 972 be interpreted by NAT to mean that the agent is 973 attempting to set some BIND parameters. 975 Output Parameters: 977 bind_info - If the caller requested for a BIND creation and NAT 978 was successful in creating a new BIND, NAT will 979 fill the structure with the assigned BIND ID and 980 any other NAT assigned parameter values. If the 981 caller requested to set some BIND parameters and 982 NAT succeeded in doing so, the bind_info would 983 be filled with the values that NAT holds. 985 Return Value: 987 No-Error(0) - Successful BIND creation or parameter setting. 989 BIND-MAKE-FAILED - NAT was unable to create BIND or was unable 990 to set the requested parameter(s). 992 INVALID-BIND-INFO - One or all of the parameters specified is 993 not valid. 995 INVALID-SERVICE-ID- The specified service_id is not operational 996 or is incorrect. 998 INVALID-AGENT-ID - The specified Agent_id is not currently 999 registered with the middlebox. 1001 5.2.4. int nat_free_bind(service_id, agent_id, bind_id) 1003 Purpose: 1005 This function is used to terminate the specified BIND and any 1006 sessions that are based on this BIND. 1008 Input parameters: 1010 service_id - The identifier that uniquely identifies the NAT 1011 instance. 1013 agent_id - The agent Identifier that uniquely identifies the 1014 agent to NAT. 1016 bind_id - The ID of the BIND that needs to be terminated. 1018 Output Parameters: 1020 none. 1022 Return Value: 1024 No-Error(0) - Successful BIND termination. 1026 INVALID-BIND-ID - The specified bind_id does not exist. 1028 INVALID-SERVICE-ID- The specified service_id is not operational 1029 or is incorrect. 1031 INVALID-AGENT-ID - The specified Agent_id is not currently 1032 registered with the middlebox. 1034 5.3. Call-back functions into an external agent 1035 The callback functions listed can be the same independent of the 1036 middlebox function or the agent that interfaces with the middlebox. 1037 Parameters supplied to these functions may however be specific to 1038 the tuple of (service_type, agent_type). The asynchronous callback 1039 functions may be used to redirect packets to MIDCOM agents (or) to 1040 notify a MIDCOM agent of significant events such as BIND creations 1041 or to notify MIDCOM agent of periodic statistical data. 1043 5.3.1. void agent_callback_event(service_id, agent_id, event_type, 1044 &event_info) 1046 Purpose: 1048 This function is invoked by the middlebox to notify an agent 1049 of an event status. 1051 Input parameters: 1053 service_id - The identifier that uniquely identifies a specific 1054 service instance on a middlebox. 1056 agent_id - The agent Identifier that uniquely identifies the 1057 agent to the middlebox. 1059 event_type - The event can be one of session Creation, session 1060 termination, BIND creation or BIND termination 1061 for a NAT middlebox. 1063 event_info - This will return the BIND or session description 1064 structure that contains the specific instance 1065 identifier and other pertinent information. 1067 5.3.2. void agent_callback_periodic(service_id, agent_id, info_type, 1068 info_length, &periodic_info) 1070 Purpose: 1072 This function is used by the middlebox to notify an agent of a 1073 certain piece of information periodically. 1075 Input parameters: 1077 service_id - The identifier that uniquely identifies a specific 1078 service instance on a middlebox. 1080 agent_id - The agent Identifier that uniquely identifies the 1081 agent to the middlebox. 1083 info_type - Middlebox may have been requested to periodically 1084 notify the agent many types of information. 1085 Possible values for this parameter would be 1086 statistics update, Incremental BIND update 1087 Incremental session update, Incremental 1088 BIND termination, Incremental session 1089 termination etc.. 1091 info_length- Number of bytes included in periodic info block. 1093 periodic_info - This point to the actual periodic information 1094 being sent to the agent. 1096 5.3.3. void agent_callback_packet(service_id, agent_id, sess_id, 1097 pkt_direction, packet) 1099 Purpose: 1101 This function is used by the middlebox to notify an agent of a 1102 data packet for processing. The agent is expected to 1103 process the packet and forward to the actual destination 1104 in the first-in-first-out (FIFO) order. The processing 1105 performed by the agent may be limited to just the payload 1106 or the entire packet, as set by the agent at session 1107 setup time. 1109 Input parameters: 1111 service_id - The identifier that uniquely identifies a specific 1112 service instance on a middlebox. 1114 agent_id - The agent Identifier that uniquely identifies the 1115 agent to the middlebox. 1117 sess_id - The Identifier of session to which the packet 1118 belongs. 1120 pkt_direction - This can be inbound or outbound. 1122 packet - IP packet that needs to be processed by the agent. 1123 If NAT was required to perform header translation, 1124 this packet is post-NAT-translated version of 1125 the packet. In the case the agent selected to 1126 perform the entire translation, the original 1127 packet is sent as is to the agent, without any 1128 NAT transformation. 1130 6. An illustration of the use of NAT Resource Control Mechanism 1132 The following is an illustration of how an ALG for FTP application 1133 ([Ref 7]) could use the API specified to interface with NAT to 1134 provide application level transparency. This is not meant to be a 1135 detailed description of how an FTP-ALG would work. But, rather an 1136 illustration of how an ALG could use the interface with NAT to 1137 accomplish the desired application transparency. The section is 1138 divided into three sub-sections to illustrate (a) ALG 1139 registration with NAT, (b) NAT interface with ALG while an FTP 1140 session is active, and (c) Notification to ALG when the FTP 1141 session terminates. 1143 6.1. FTP-ALG registration with NAT 1145 FTP-ALG will first probe NAT middlebox to understand the type of 1146 service provided by NAT and obtain NAT-ID. Once the service 1147 type is agreeable, the ALG will register itself as a client 1148 with the NAT middlebox with callback functions (as described 1149 below) and obtain an agent-ID from the NAT. The tuple of 1150 (service_id, agent_id) uniquely identifies the interface 1151 between NAT and ALG. 1153 ftp_alg_pkt_notify() will be registered to process FTP 1154 session (TCP port 21) traffic. ftp_alg_event_notify() will 1155 be registered to process session or NAT termination. 1157 FTP-ALG NAT 1158 ------- --- 1160 1. Obtain NAT descriptor Info 1162 middlebox_query_IDentity( 1163 0, **nat_descriptor) 1164 ------------------------> 1165 NAT will fill a descriptor 1166 block with pertinent information, 1167 specifically NAT-type and nat_ID 1168 and supply the pointer to the 1169 descriptor block. 1171 OK 1172 <------------------------------ 1174 2. Register with NAT as ALG for 1175 FTP (TCP port 21) and obtain 1176 agent_ID from the NAT. 1178 middlebox_register_agent(nat_id, 1179 &ftp_alg_info) 1180 ------------------------> 1182 NAT will assign an agent_ID. 1184 OK 1185 <------------------------------ 1187 6.2. NAT interface with the ALG during FTP session operation 1189 When NAT sees the first packet of an FTP session, it sets up 1190 a BIND descriptor and a session descriptor and tags the 1191 session descriptor as FTP-Type (i.e., TCP port 21). NAT 1192 will then redirect the packet to FTP-ALG by invoking the 1193 ALG supplied callback function - ftp_alg_pkt_notify(). 1194 The ALG will obtain session descriptor and BIND descriptor 1195 info from the NAT. 1197 Subsequent to this, when NAT redirects FTP packets, the 1198 ALG would parse the payload for PORT command or response to 1199 "PASV" to determine ensuing data sessions and interact with 1200 NAT, as necessary, to obtain the requisite translation 1201 parameters. The ALG may modify the FTP packet with 1202 translation parameters prior to resending to NAT for 1203 forwarding. 1205 FTP-ALG NAT 1206 ------- --- 1208 1. NAT sees the first packet 1209 of an FTP session. NAT will 1210 set up a session state and 1211 notify the agent as follows. 1213 ftp_alg_pkt_notify(nat_id, 1214 agent_ID, sess_ID, 1215 packet_direction, pkt) 1216 <------------------------ 1218 The ALG may optionally make 1219 calls to the NAT to find out 1220 about the session and BIND 1221 characteristics of the FTP. 1222 Further, additional calls may 1223 be made to change the control 1224 parameters in these blocks. 1226 middlebox_query_sess_range( 1227 nat_id, agent_id, 1228 sess_id, sess_id, 1229 &sess_count, **sess_info) 1230 ------------------------------> 1231 Find the session descriptor 1232 block matching sess_id and 1233 return Pointer to this. Bind_id 1234 is one of the items in the block. 1236 OK 1237 <------------------------------ 1238 ... 1240 nat_query_address_bind( 1241 nat_id, pvt_address, 1242 external_address, &bind_info) 1243 ------------------------------> 1244 ... 1246 nat_set_bind( 1247 nat_id, agent_id, &bind_info) 1248 ------------------------------> 1250 ............. 1252 n. NAT will forward all 1253 subsequent FTP packets to 1254 the agent as follows. 1256 ftp_alg_pkt_notify(nat_id, 1257 agent_ID, sess_ID, 1258 packet_direction, pkt) 1259 <------------------------ 1261 The ALG will parse for PORT 1262 command and PASV response in 1263 the payload and track any deltas 1264 to TCP sequence and acknowledge 1265 numbers. The ALG will interact 1266 with NAT, as necessary, to obtain 1267 BIND parameters for the data 1268 session, setup data session state 1269 ahead of time and modify the FTP 1270 packet (as necessary) prior to 1271 resending to NAT for forwarding. 1273 Request BIND parameters for the 1274 new data session such that there 1275 is no leased-time set for it. 1277 nat_set_bind(nat_id, agent_id, 1278 &bind_info) 1279 ------------------------------> 1281 .... 1283 Setup a new state for the data 1284 session such that the Bundle-ID 1285 is set to be the session ID of 1286 the controlling FTP session. 1288 middlebox_set_sess(nat_id, agent_id, 1289 &sess_info) 1290 ----------------------------> 1292 6.3. Session termination notification 1294 When the FTP control session is ready to be terminated 1295 by the NAT, NAT will notify the event to FTP-ALG as follows. 1297 FTP-ALG NAT 1298 ------- --- 1300 1. NAT determines the FTP 1301 session is to be 1302 terminated. 1304 ftp_alg_notify(nat_id, 1305 agent_id, 1306 SESSION_TERMINATED, 1307 sess_ID) 1308 <------------------------ 1310 The ALG will in turn clean up any 1311 data sessions that may be based on 1312 the FTP session prior to freeing 1313 the control session itself. 1315 middlebox_sess_free(nat_id, agent_id, 1316 sess_id) 1317 ----------------------------> 1319 7. Acknowledgement 1321 The author would like to thank Yakov Rekhter for his valuable advice 1322 and contribution in the organization of this document. 1324 8. Security considerations. 1326 The security considerations described in [Ref 1] for all variations 1327 of NATs are applicable here. There can be security vulnerabilities 1328 to a middlebox, if external agents are allowed to interface with 1329 a NAT middlebox without proper authentication and authorization. It 1330 is possible that a NAT middlebox may be abruptly disrupted due to 1331 malicious manipulation of the resource by an agent purporting to 1332 offer ALG service. 1334 REFERENCES 1336 [1] P. Srisuresh, M. Holdrege, "IP Network Address Translator 1337 (NAT) Terminology and Considerations", RFC 2663 1339 [2] Y. Rekhter, B. Moskowitz, D. Karrenberg, G. de Groot, and, 1340 E. Lear, "Address Allocation for Private Internets", RFC 1918 1342 [3] J. Reynolds and J. Postel, "Assigned Numbers", RFC 1700 1344 [4] R. Braden, "Requirements for Internet Hosts -- Communication 1345 Layers", RFC 1122 1347 [5] R. Braden, "Requirements for Internet Hosts -- Application 1348 and Support", RFC 1123 1350 [6] F. Baker, "Requirements for IP Version 4 Routers", RFC 1812 1352 [7] J. Postel, J. Reynolds, "FILE TRANSFER PROTOCOL (FTP)", 1353 RFC 959 1355 [8] "TRANSMISSION CONTROL PROTOCOL (TCP) SPECIFICATION", RFC 793 1357 [9] J. Postel, "INTERNET CONTROL MESSAGE (ICMP) SPECIFICATION", 1358 RFC 792 1360 [10] J. Postel, "User Datagram Protocol (UDP)", RFC 768 1362 [11] J. Mogul, J. Postel, "Internet Standard Subnetting Procedure", 1363 RFC 950 1365 [12] Brian carpenter, Jon Crowcroft, Yakov Rekhter, "IPv4 Address 1366 Behaviour Today", RFC 2101 1368 Author's Address: 1370 Pyda Srisuresh 1371 jasmine Networks 1372 3061 Zanker Road, Suite B. 1373 San Jose, CA 95134 1374 U.S.A. 1376 Voice: (408) 895-5032 1377 EMail: srisuresh@yahoo.com