[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03                                                   
NAT Working Group                                           P. Srisuresh
INTERNET-DRAFT                                     Campio Communications
Category: Informational                                       July, 2000
Expires on January 12, 2001


         Framework for interfacing with Network Address Translator
             <draft-ietf-nat-interface-framework-01.txt>

Status of this Memo

   This document is an Internet-Draft and is in full conformance
   with all provisions of Section 10 of RFC2026.  Internet-Drafts
   are working documents of the Internet Engineering Task Force
   (IETF), its areas, and its working groups.  Note that other
   groups may also distribute working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six
   months and may be updated, replaced, or obsoleted by other
   documents at any time.  It is inappropriate to use Internet-
   Drafts as reference material or to cite them other than as
   "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.


Abstract

   NAT provides routing transparency for hosts in disparate address
   realms to communicate with each other. However, external agents
   such as Application Level Gateways (ALGs), Realm Specific IP
   (RSIP) clients and Management applications need to interact with
   NAT and influence its operations. The document identifies NAT
   managed resources and ways by which these resources may be
   controlled from external agents. The resource control mechanism
   is illustrated functionally through an Application Programming
   Interface (API). However, it is not the intent of this document
   to standardize the API. Rather, use the API as basis to
   illustrate and provide a basis for the development of one or
   more protocols by which external agents could interact with NAT.
   Identification of NAT controlled resources also provides a basis
   to generate NAT Management Information Base (MIB).




Srisuresh                                                       [Page 1]


Internet Draft           NAT Interface Framework               July 2000



1. Introduction

   NAT provides routing transparency for hosts in disparate address
   realms to communicate with each other. [Ref 1] details the various
   flavors of NAT that abound. Many internet applications use IP
   address as host identifier rather than just as a way to locate a
   host.  For this reason, routing transparency by NAT alone is not
   sufficient to provide end-to-end transparency for applications
   operating across realms.  Application specific ALGs are required
   in conjunction with NAT to provide end-to-end transparency for
   some applications.

   In addition to ALGs, there are other kinds of external agents that
   may need to influence NAT operation. Section 3 below identifies a
   list of external agents that may likely interface with NAT.
   Section 2 below is devoted to describing the resources controlled
   by NAT. The requirements of external agents, combined with the
   nature of NAT resources provide the basis to illustrate the
   resource control mechanism functionally through an API in
   section 4. Section 5 illustrates how an external agent could use
   the resource control mechanism to influence NAT operation.

   The intent of the document is two-fold. First, the resource
   control mechanism, illustrated through an API, provides a basis
   for the development of one or more protocols by which external
   agents (specified in section 3 below) could communicate with
   NAT. Such a protocol would need to authenticate clients, locate
   NAT devices and exchange data elements. The API illustration
   assumes a trusted environment and does not address
   authentication and Service location. It is also important to
   note that the illustartion does not assume or require external
   agents to reside on the same physical device as NAT, even
   though assuming they reside on the same physical device might
   help in understanding. In reality, some agents may be
   co-located with NAT on the same device and others reside
   on external devices. Discussion of a communication protocol
   that may be used by external agents to interface with NAT
   is outside the purview of this document.

   Second, the document identifies the NAT controlled resources.
   This may be used as a basis to develop NAT Management
   Information Base (MIB).

2. Elements of NAT operation

   In order to identify an API for use by external agents, it is
   important to understand the resources and other elments managed



Srisuresh                                                       [Page 2]


Internet Draft           NAT Interface Framework               July 2000


   by NAT. This would help identify the extent to which an external
   agent may influence NAT operation. This section describes objects
   within NAT, that could be externalized via Management Information
   Base (MIB).

2.1. NAT Descriptor

   All flavors of NAT are designed to provide routing transparency
   to hosts in disparate address realms. A physical device may have
   multiple NAT instances or there may be multiple NAT devices
   associated with a specific realm. The following list of attributes
   identify a specific instance of NAT.

      a. NAT IDentifier:

         A NAT Identifier uniquely identifies a NAT instantiation.
         The External interface address may be one way to uniquely
         describe NAT Identifier.

      b. Private and External realm types:

         Every NAT device will have a minimum of two routing
         interfaces, one connecting to a private realm and one
         connecting to external realm. An IPv4 NAT device will
         have both its realm types set to IPv4.

      c. NAT type

         NAT type could be one of Basic-NAT, NAPT, Bi-directional-NAT,
         Twice-NAT, RSA-IP server, RSAP-IP-server or a combination
         of the above.  NAT type is an indication of the direction in
         which NAT sessions are allowed and the extent of translation
         within the IP and transport headers. [Ref 1] has a discussion
         on the nature of various NAT flavors and the extent of their
         translations.

      d. Address(and Transport-ID) maps

         Address map on a NAT device could consist of one or more of
         static and dynamic Address maps. Likewise, Transport-ID
         mapping could consists of one or more of static and dynamic
         transport-ID maps. Transport-ID mapping is more specific
         than address mapping in that a specific TCP/UDP port (or
         port range) pertaining to an address in external realm is
         mapped to a specific TCP/UDP port (or port range) in private
         realm or vice versa. Address (and Transport-ID) maps may be
         defined for both inbound and outbound directions. Outbound
         address map refers to mapping a selected set of addresses



Srisuresh                                                       [Page 3]


Internet Draft           NAT Interface Framework               July 2000


         from private realm to a selected set of addresses in
         external realm; whereas inbound address map refers to
         mapping a set of addresses from the external realm to
         private realm.

      e. Miscellaneous parameters

         NAT may optionally provide TCP, UDP and other types of session
         Idle-times used to terminate sessions. It may also provide the
         current range (and, the maximum range) of session IDs and
         Bind IDs (to be covered in the follow on sub-sections); and
         the actual count of session IDs and BIND IDs. Specifically,
         this information will be of relevance to another NAT (backup
         NAT) that intends to emulate this NAT, in case of failure.
         Lastly, NAT may choose to supply any other vendor specific
         parameters such as log options, session direction failure
         actions and so forth.

      f. Realm Specific IP (RSIP) parameters

         A NAT device offering RSIP-Server capability may specify the
         RSIP tunnel types it supports.


2.2. Address (and Transport-ID) BINDing Descriptor

   These bindings can be static or dynamic. Hereafter, the term BIND
   will be used in place of BINDing, for ease of use. When external
   agents do not intervene, dynamic address(and transport-ID) binding
   is determined by NAT based on the first packet of a session, as
   described in [Ref 1].  Address binding is between an address in
   private realm and an address from external realm. Transport-ID BIND
   is an extension of the same concept to the tuple of Address and
   transport ID (such as TCP/UDP port no.). The following list of
   attributes describe the BIND object(s) maintained by a NAT device.

      a. Bind ID

         A number (say, in the range of 1 through 0xFFFFFFFF) assigned
         to BIND to uniquely identify this BIND from a different BIND
         on the same NAT.

      b. Direction of Bind

         A bind can be uni-directional or bi-directional, same as the
         orientation of address map based on which this BIND is formed.
         As before, the direction is with reference to private realm.




Srisuresh                                                       [Page 4]


Internet Draft           NAT Interface Framework               July 2000


      c. Bind type

         Indicates whether the BIND is Address-BIND (between a pair of
         addresses) or Transport-ID-Bind (between a pair of Address,
         transport ID tuples). Further, this also indicates if the Bind
         is static or dynamically generated.

      d. Private and External addresses (and Transport-IDs)

         Theese parameters specify the BINDing items in private and
         external realms.

      e. Maximum lease time

         The validity of a BIND may be limited by the duration of lease
         time it is allowed. Unless the lease time is renewed, a BIND
         will not be valid past the lease time. As a special case, a
         value of 0 may be assumed to indicate no lease time limit.
         Typically, this attribute is of relevance only in conjunction
         with Realm-Specific-IP(RSIP) operation.

      f. Available lease time

         This parameter is of relevance only when Maximum lease time is
         a non-zero value. At any given instance of time, this parameter
         indicates the real-time left for a BIND to remain valid.
         Typically, this attribute is of relevance only in conjunction
         with Realm-Specific-IP(RSIP) operation.

      g. Maximum Idle time

         This parameter indicates maximum amount of time a dynamic BIND
         is allowed to remain valid, with no NAT session hanging off this
         BIND. Typically, a dynamic Bind is established when NAT notices
         the first session that needs such a binding. Subsequent to
         this, multiple NAT sessions can be maintained using the same
         binding. When the last of these sessions is terminated, the
         bind is also terminated. In other words, Maximum Idle time is 0,
         by default, for native NAT. External agents could control this
         parameter differently. Static Binds and lease time limited BINDs
         are not effected by this parameter.

      h. Current Idle time

         This parameter is of relevance only when Maximum Idle time is
         set to a non-zero value. At any given instance of time, this
         parameter indicates the real-time the BIND has been idle with
         no sessions attached to it.



Srisuresh                                                       [Page 5]


Internet Draft           NAT Interface Framework               July 2000



      i. Controlling Agent IDentification

         This indicates the last external Agent  who has tried to
         control (i.e., set) parameters for this BIND. A value of 0
         indicates that native NAT is the responsible agent.

2.3. Session State descriptor

   NAT maintains soft-state for the sessions it tracks. Typically, these
   states are created dynamically during NAT operation and are
   referenced for translation of packets pertaining to the session. The
   translation of a packet is based on the bind(two binds in case of
   twice-nat) the session state points to.  The following list of
   attributes identify a session state (or, simply session) within NAT.

      a. Session IDentifier

         A number (say, in the range of 1 through 0xFFFFFFFF) assigned
         to session to uniquely identify this from other sessions on
         the same NAT.

      b. Direction of Session.

         Direction of first packet of the session. As specified
         earlier, direction is with reference to private realm.

      c. Bind IDentifier

         Identifies the Bind based on which this session is created.
         The Direction of BIND must be same as that of the session,
         if the BIND is uni-directional. Typically, if a Bind supporting
         the session translation does not already exist, a Bind is
         created prior to creating new session state. However, this
         Identifier may be set to 0, when BIND creation is unnecessary
         for the session. For example, there can be no more than one
         ICMP Query session using am ICMP Query based transport-ID-bind.
         In such a case, it suffices to do away with BIND and keep all
         requisite information within the session state itself.

      d. Second Bind IDentifier

         This is of relevance only to Twice-NAT. For all other flavors
         of NAT, this parameter may be set to zero. In the case of
         Twice-NAT, the Primary Bind Identifier refers to the binding
         of source address (of the first packet) and the Second Bind
         Identifier refers to the binding of the destination address.




Srisuresh                                                       [Page 6]


Internet Draft           NAT Interface Framework               July 2000


      e. Original Session parameters

         These parameters identify the session level parameters as
         they appear in the first packet of session. These parameters
         include src and dest IP addresses, IP protocol and transport
         IDentifier info (such as TCP/UDP port numbers or ICMP Query
         Identifier).

      f. Translated Session parameters

         These parameters identify the session level parameters as
         the first packet of session is translated. These parameters
         are derived from the BIND ID(s) off which this session hangs.

      g. Session tag

         NAT managed sessions are assigned a session tag, so that
         sessions  bearing the same tag (session bundle) are handled
         the same way. A session tag may be identified as a tuple of
         (<IP-protocol>, <session-Port>). This tag value is of
         significance to NAT or an external agent controlling the
         session. NAT retains control of all sessions, unless an
         agent registers to control the session. For example, an
         FTP-ALG may choose to take control of all sessions with
         an FTP (TCP port 21) session tag.

      h. Session Termination heuristic

         Session-Idle-time is typically used as a heuristic means by NAT
         to determine if the session has ended. There may other heuristic
         approaches. A value of zero is an indication that NAT would not
         use any heuristic to session termination, unless it is a TCP
         session and the session has noticeable ended with FIN or RST
         options. The agent may take the responsibility for terminating
         the session.

      i. Maximum Idle time

         This parameter indicates maximum amount of time this session
         is allowed to remain valid, even as there is no activity.
         Idle time is typically used as a heuristic means to determine
         session termination. There may be other heuristic approaches.
         As a special case, a value of 0 implies that NAT should run
         the same timer as used for native sessions.

      j. Current Idle Time

         This parameter is of relevance only when session termination



Srisuresh                                                       [Page 7]


Internet Draft           NAT Interface Framework               July 2000


         heuristic is set to session-idle-time.  Typically, NAT would
         examine the idle time on the sessions it manages periodically
         and updates this variable. When the idle time exceeds the
         maximum allowed idle time, the session is terminated.

      k. Packet modifier functions

         Typically, NAT modifies IP header and sometimes the transport
         header. External agents may choose to assume responsibility
         for payload modification alone, or the entire packet
         modification. In the case an external agent assumes
         responsibility for the entire packet modification, NAT will
         simply redirect the original packet as is to external
         translation agent. Otherwise, NAT will perform its share of
         translation (i.e., IP and transport header translation) and
         direct the translated packet to external agent.

      l. Bundle ID

         Applications that deal with a bundle of sessions may cause
         multiple sessions to be managed by NAT. Even though these
         sessions constitute a single session from application stand
         point, NAT is not congnizant of the relation. In such cases,
         it is not uncommon for external agents to store a unique
         application ID (say, the session ID of the first NAT session
         the application originated) in all sessions it spawns in its
         incarnation. By default, this would be same as the session-id.

      m. Controlling Agent IDentification

         This indicates the last external Agent  who has tried to
         control parameters for this session. A value of 0 indicates
         that native NAT is the responsible agent.


3. External agents interfacing with NAT

   Many network applications assume the IP address of their host to be
   host Identifier and embed the Identifier information in application
   specific payload. When packets from such an application traverse
   NAT, the IP address of private host remains uncorrected in the
   payload, as the packet is delivered to hosts in external realm. An
   Application Level Gateway (ALG) is required to re-interpret such a
   payload as the payload traverses realms.

   In addition, there are applications such as H.323 that use
   out-of-band signaling to dynamically create newer sessions. While
   a signaling session itself may be directed to a well-known port,



Srisuresh                                                       [Page 8]


Internet Draft           NAT Interface Framework               July 2000


   sessions created by it need not be that way. Once again, an ALG may
   be required to process payload in the signaling sessions and notify
   NAT to recognize the newly created sessions.

   There may be other instances where an ALG may be required to
   provide application level transparency.  In all cases, there is a
   need for the ALGs to interface with NAT. The ALGs may reside
   on the NAT device or on an external device. Independent of where
   an ALG resides, NAT interface requirements remain the same.

   In a multi-homed NAT configuration, there is a need for a backup NAT
   to communicate with the primary and keep in sync, so that when the
   primary goes away, the backup NAT could instantly assume support for
   the sessions that primary NAT was responsible for. This is yet
   another case where an external agent (i.e., backup NAT) has a need
   to interface with NAT.

   A NAT device is uniquely qualified to serve as Realm-Specific-IP
   Server (i.e., RSA-IP-Server or RSAP-IP-Server) for Realm-Specific-IP
   clients (i.e., RSA-IP clients or RSAP-IP clients). [Ref 1] has a
   description of RSIP terminology.  RSA-IP clients and RSAP-IP clients
   need to interface with the server node to obtain an external address
   (or a tuple of address and TCP/UDP port) while communicating with
   hosts in external realms. In addition, if NAT were to act as tunnel
   end-point, RSIP clients will need to interface with NAT to setup
   tunnel state  for the lifetime of RSIP-client address assignment.
   So, once again, there is a need for an API for use by an external
   agent(i.e., RSIP client) to communicate with NAT, acting as
   RSIP-server.

   Lastly, a mangement utility would be useful to interface with NAT
   for configuration and monitor purposes and to enforce NAT policies.
   For example, reconfigure a NAT device to switch over from NAPT to
   Basic-NAT configuration or vice versa. Or, add, terminate and
   monitor ALGs and other external agents on a NAT box. Such a program
   would also be useful to notify NAT about the status and setup
   information concerning ALGs, backup NATs and RSIP clients.

   Clearly, agents such as RSIP clients and Backup-NATs are likely
   to reside on a different physical device than the NAT device. Some
   of the ALG agents may also reside on an external device. The API
   presented in the follow-on section will provide a base to identify
   requirements for the development of one or more protocols by which
   each of these external agents could communicate with NAT. It may be
   a single protocol applicable to all external agents (or) multiple
   protocols, specific to each agent type.

   The following diagram identifies a selected list of external agents



Srisuresh                                                       [Page 9]


Internet Draft           NAT Interface Framework               July 2000


   that might interact with NAT via an API or an yet to be devised
   protocol.

      +--------------+  +------+  +-------------+  +------------------+
      | RSIP Clients |  | ALGs |  | Pri/Sec NAT |  | Management Appl. |
      +--------------+  +------+  +-------------+  +------------------+
                  ^        ^              ^                ^
                  |        |              |                |
                  |        |              |                |
                  v        v              v                v
                +---------------------------------------------+
                | NAT Application Program Interface (NAT-API) |
                +---------------------------------------------+
                |                     N A T                   |
                +---------------------------------------------+

    figure 1. External agents interfacing with NAT


   The following list of attributes uniquely identify an external
   agent with reference to a NAT.

      a. Agent IDentifier

         A number (say, in the range of 1 through 0xFFFFFFFF) assigned
         to the agent by the NAT device to distinguish from other
         agents. Typically, this handle may be assigned when the
         agent registers with NAT.

      b. Agent type

         Based on the categories of external agents described thus far,
         it is clear that the API requirements differ considerably
         amongst them. A native NAT API may or may not be able to
         support the requirements of all these agents. It is beneficial
         for NAT to know the agent type to be one of ALG or
         RSIP Client or Backup-NAT or Management Application or
         something else, so it can accept or deny registration.

      c. Agent call-back requirements

         An agent will typically require NAT to invoke a call-back
         function supplied by the agent upon the occurrence of
         specific events. However, events for which an agent
         wants to be notified of varies based on agent type.

         An ALG will require NAT to call back when a data packet is
         received on a session with a certain session-tag (say, FTP



Srisuresh                                                      [Page 10]


Internet Draft           NAT Interface Framework               July 2000


         session). Management applications and Backup-NAT might
         require NAT to periodically invoke a call-back function.
         Events all agents might require to be notified of (through
         a call-back function) would be -  termination of a session
         with certain session-tag or session-ID, termination of a
         Bind and termination of NAT itself.

      d. Agent call-back functions

         Depending upon call-back requirements, the agent will be
         required to register one or more call-back function entry
         points with NAT. Below are three different call-back
         function prototypes.

         Event notification - void agent_callback_event(nat_id,
                                    agent_id, event, event_info)

         Periodic notification - void agent_callback_periodic(nat_id,
                                    agent_id, info_type, info_length,
                                                        information)

         Packet notification - void agent_callback_packet(nat_id,
                                    agent_id, session_id,
                                    pkt_direction, packet)

      e. Periodic Notification interval

         This parameter would be required only when the agent calls
         for periodic notification. This may be specified in units of
         seconds.

      f. RSIP Server tunnel type requirement

         An RSIP client may have a requirement for NAT, acting as
         RSIP server to support a certain type of tunneling. In
         such a case, the agent will specify the tunneling
         requirement through this parameter.

      g. Agent access information

         In the case the agent is resident on a different physical
         device than NAT, this parameter is used by the agent to
         specify a means by which NAT can access the agent. This
         will include a combination of Agent's IP address,
         IP protocol (e.g., TCP or UDP), well-known port etc.
         As a special case, a value of 0 to agent_ip_address would
         indicate that the agent is on the same device as NAT and
         a proprietary mechanism may be assumed to exist to access



Srisuresh                                                      [Page 11]


Internet Draft           NAT Interface Framework               July 2000


         the agent.


4. NAT Application Programming Interface (NAT API)

   A resource control mechanism by which external agents could
   interface with a NAT device is illustrated in this section
   through an Application Programming Interface (API) in pseudo
   C language. The API is by no means exhaustive in coverage.

   This section is divided into two sub-sections. The first
   sub-section lists function calls available to external agents.
   These calls are synchronous and require NAT to return back
   a value. The second sub-section lists functions required to be
   provided by external agents in order for NAT to call-back upon
   some events.

4.1. NAT API functions

4.1.1. int nat_enquire_IDentity(nat_type, **natid_info)

   Purpose:

      This function is used by external agents to obtain NAT-ID
      and its characteristics, as described in section 2.1

   Input parameters:

      nat_type  - This parameter is specified to verify if NAT
                  device supports a certain flavor of NAT.
                  A value of 0 requires all instances of NAT
                  to be reported

   Output Parameters:

      natid_info - NAT will fill up a descriptor block with its
                   characteristics (as described in section 2.1)
                   for the matching nat_type and return pointer
                   to the descriptor block. The descriptor
                   block would specifically include an identifier
                   (nat_id) that uniquely identifies NAT instance.

                   Multiple pieces of this information may be returned,
                   if NAT supports multiple instances of the same NAT
                   type. Multiple instances of NAT descriptor blocks
                   may also be returned when nat_type is set to 0 and
                   the NAT device supports multiple NAT instances.




Srisuresh                                                      [Page 12]


Internet Draft           NAT Interface Framework               July 2000


   Return Value:

      No-Error(0)            - A return value of 0 implies success
                               and that natid_info may be examined
                               for NAT description.

      NAT-TYPE-NOT-SUPPORTED - Notify the client that the
                               requested NAT device does not
                               support the specified NAT type.

4.1.2. int nat_enquire_address_bind (nat_id, pvt_address,
                                        ext_address, &bind_info)

   Purpose:

      This function is used by external agents to obtain
      Address BIND information.

   Input parameters:

      nat_id - The identifier that uniquely identifies the NAT instance.

      pvt_address, ext_address - The caller might specify both or just
               one of either private address or external address and
               set the other to zero.

   Output Parameters:

      bind_info - NAT will fill up the bind_info data structure
                  with info as described in section 2.2, if NAT were
                  to find a match for the addresses specified.

   Return Value:

      No-Error(0)       - A return value of 0 implies success
                          in finding a match.

      NO-MATCHING_BIND  - Notify the client that there isn't a BIND
                          matching the specified addresses.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

4.1.3.  int nat_enquire_transport_bind(nat_id, pvt_address, pvt_port,
                transport_protocol, ext_address, ext_port, &bind_info)

   Purpose:




Srisuresh                                                      [Page 13]


Internet Draft           NAT Interface Framework               July 2000


      This function is used by external agents to obtain
      Transport ID BIND information.

   Input parameters:

      nat_id - The identifier that uniquely identifies the NAT instance.

      pvt_address, pvt_port,
      ext_address, ext_port - The caller might specify both or just
               one of either (private address and the port no.) or
               external address and the port number.

      transport_protocol - This must be one of TCP, UDP or ICMP Query

   Output Parameters:

      bind_info - NAT will fill up the bind_info data structure
                  with info as described in section 2.2, if NAT were
                  to find a match for the addresses specified.

   Return Value:

      No-Error(0)       - A return value of 0 implies success
                          in finding a match.

      NO-MATCHING_BIND  - Notify the client that there isn't a BIND
                          matching the specified addresses.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

4.1.4. int nat_enquire_sess_range(nat_id, agent_id, sessid_min,
                          sessid_max, &sess_count, &sess_info)

   Purpose:

      This function is used by external agents to request NAT to
      send valid session information for all sessions with an ID
      in the range of sessid_min through sessid_max. As a special
      case, this will return session descriptor block for a
      single session when sessid_min and sessid_max are the same.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the



Srisuresh                                                      [Page 14]


Internet Draft           NAT Interface Framework               July 2000


                   agent to NAT.

      sessid_min, sessid_max - The range of session IDs that the
                   agent is interested in knowing about.

   Output Parameters:

      sess_count - Number of sessions being returned through
                   sess_info pointer.

      sess_info  - Return one or more sessions maintained by NAT,
                   with an ID in the given range.

   Return Value:

      No-Error(0)       - A return value of 0 implies successful
                          session termination.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

      INVALID-AGENT-ID  - The specified Agent-ID is not currently
                          registered with NAT.

4.1.5. int nat_register_agent (nat_id, &agent_info)

   Purpose:

      This function is used by external agents to register with NAT.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_info - The agent is required to provide all the requisite
                   information (with the exception of agent_id) as
                   described in section 3.0. This ID may be used by
                   the caller to influence NAT operation.

   Output Parameters:

      agent_info - NAT will return the agent_id in agent_info structure
                   when registration is successful.

   Return Value:

      No-Error(0)       - A return value of 0 implies successful



Srisuresh                                                      [Page 15]


Internet Draft           NAT Interface Framework               July 2000


                          registration.

      AGENT-TYPE-NOT-SUPPORTED - Notify the caller that NAT does not
                                 support API requirements of the agent.

      TUNNEL-TYPE-NOT-SUPPORTED - Notify caller that NAT does not
                                  support the RSIP tunnel type
                                  requested.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

4.1.6.  int nat_set_bind (nat_id, agent_id, &bind_info)

   Purpose:

      This function is used by external agents to create a new Address
      Bind or set certain parameters of an existing Bind.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      bind_info  - The caller supplies the specifics of a new BIND or
                   sets a selected number of parameters of an existing
                   BIND to influence NAT operation. The BIND can be
                   an address BIND or transport BIND. A new BIND
                   request is made by setting the BIND ID within
                   bind_info structure to 0. A non-Zero Bind-ID would
                   be interpreted by NAT to mean that the agent is
                   attempting to set some BIND parameters.

   Output Parameters:

      bind_info  - If the caller requested for a BIND creation and NAT
                   was successful in creating a new BIND, NAT will
                   fill the structure with the assigned BIND ID and
                   any other NAT assigned parameter values. If the
                   caller requested to set some BIND parameters and
                   NAT succeeded in doing so, the bind_info would
                   be filled with the values that NAT holds.

   Return Value:




Srisuresh                                                      [Page 16]


Internet Draft           NAT Interface Framework               July 2000


      No-Error(0)       - A return value of 0 implies successful
                          BIND creation or parameter setting.

      BIND-MAKE-FAILED  - When NAT was unable to create BIND
                          or was unable to set the requested
                          parameter(s).

      INVALID-BIND-INFO - When NAT finds that one or all of the
                          parameters specified is not valid.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

      INVALID-AGENT-ID  - The specified Agent-ID is not currently
                          registered with NAT.

4.1.7. int nat_set_sess(nat_id, agent_id, &sess_info)

   Purpose:

      This function is used by external agents to create a new session
      state or set certain parameters of an existing session.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      sess_info  - The caller supplies the specifics of a new session
                   parameters or sets a selected number of parameters
                   of an existing session to influence NAT operation.
                   A new session request is made by setting the
                   session-ID within sess_info structure to 0. A
                   non-Zero session-ID would be interpreted by NAT to
                   mean that the agent is attempting to set some
                   session specific parameters.

   Output Parameters:

      sess_info  - If the caller requested for a session creation and
                   NAT was successful in creating a new session, NAT
                   will fill the structure with the assigned session-ID
                   and any other NAT assigned parameter values. If the
                   caller requested to set some session parameters and
                   NAT succeeded in doing so, the sess_info would



Srisuresh                                                      [Page 17]


Internet Draft           NAT Interface Framework               July 2000


                   be filled with the values that NAT holds.

   Return Value:

      No-Error(0)       - A return value of 0 implies successful
                          session creation or parameter setting.

      SESS-MAKE-FAILED  - When NAT was unable to create session
                          or was unable to set the requested
                          parameter(s).

      INVALID-SESS-INFO - When NAT finds that one or all of the
                          parameters specified is not valid.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

      INVALID-AGENT-ID  - The specified Agent-ID is not currently
                          registered with NAT.

4.1.8.  int nat_free_bind(nat_id, agent_id, bind_id)

   Purpose:

      This function is used by external agents to terminate
      the specified BIND and any sessions that are based on
      this BIND.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      bind_id    - The ID of the BIND that needs to be terminated.

   Output Parameters:

      none.

   Return Value:

      No-Error(0)       - A return value of 0 implies successful
                          BIND termination.

      INVALID-BIND-ID   - The specified BIND ID does not exist.



Srisuresh                                                      [Page 18]


Internet Draft           NAT Interface Framework               July 2000



      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

      INVALID-AGENT-ID  - The specified Agent-ID is not currently
                          registered with NAT.

4.1.9.  int nat_free_sess(nat_id, agent_id, sess_id)

   Purpose:

      This function is used by external agents to terminate
      the specified session.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      sess_id    - The ID of the session that needs to be terminated.

   Output Parameters:

      none.

   Return Value:

      No-Error(0)       - A return value of 0 implies successful
                          session termination.

      INVALID-SESS-ID   - The specified session ID does not exist.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

      INVALID-AGENT-ID  - The specified Agent-ID is not currently
                          registered with NAT.

4.1.10. int nat_free_sess_bundle(nat_id, agent_id, bundle_id)

   Purpose:

      This function is used by external agents to terminate
      a bundle of sessions identified by the same bundle ID.




Srisuresh                                                      [Page 19]


Internet Draft           NAT Interface Framework               July 2000


   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      bundle_id  - The ID of the session bundle (group of sessions)
                   that needs to be terminated.

   Output Parameters:

      none.

   Return Value:

      No-Error(0)       - A return value of 0 implies successful
                          session termination.

      INVALID-BUNDLE-ID   - The specified bundle ID does not exist.

      INVALID-NAT-ID    - The specified NAT-ID is not operational
                          or is incorrect.

      INVALID-AGENT-ID  - The specified Agent-ID is not currently
                          registered with NAT.

4.2. Call-back functions within an external agent

4.2.1. void agent_callback_event(nat_id, agent_id, event_type,
                                          &event_info)

   Purpose:

      This function is used by NAT to notify an agent of an
      event status.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      event_type - The event can be one of BIND creation, BIND
                   termination, session Creation, and session



Srisuresh                                                      [Page 20]


Internet Draft           NAT Interface Framework               July 2000


                   termination.

      event_info - This will return the BIND or session description
                   structure that contains the specific instance
                   identifier and other pertinent information.

4.2.2. void agent_callback_periodic(nat_id, agent_id, info_type,
                                    info_length, &periodic_info)

   Purpose:

      This function is used by NAT to notify an agent of a
      certain piece of information periodically.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      info_type  - NAT may have been requested to periodically
                   notify the agent many types of information.
                   Possible values for this parameter would be
                   statistics update, Incremental BIND update
                   Incremental session update, Incremental
                   BIND termination, Incremental session
                   termination etc..

      info_length- Number of bytes included in periodic info block.

      periodic_info - This point to the actual periodic information
                      being sent to the agent.



4.2.3. void agent_callback_packet(nat_id, agent_id, sess_id,
                                  pkt_direction, packet)

   Purpose:

      This function is used by NAT to notify an agent of a
      data packet for processing. The agent is expected to
      process the packet and forward to the actual destination
      in the first-in-first-out (FIFO) order. The processing
      performed by the agent may be limited to just the payload
      or the entire packet, as set by the agent at session



Srisuresh                                                      [Page 21]


Internet Draft           NAT Interface Framework               July 2000


      setup time.

   Input parameters:

      nat_id     - The identifier that uniquely identifies the NAT
                   instance.

      agent_id   - The agent Identifier that uniquely identifies the
                   agent to NAT.

      sess_id    - The Identifier if NAT session to which the packet
                   belongs.

      pkt_direction - This can be inbound or outbound.

      packet     - IP packet that needs to be processed by the agent.
                   If NAT was required to perform header translation,
                   this packet is post-NAT-translated version of
                   the packet. In the case the agent selected to
                   perform the entire translation, the original
                   packet is sent as is to the agent, without any
                   NAT transformation.


5. An illustration of the use of NAT Resource Control Mechanism

   The following is an illustration of how an FTP-ALG could use
   the API specified to interface with NAT and provide
   application level transparency for FTP application. Note,
   this is not meant to be a detailed description of how an
   FTP-ALG would work. But, rather an illustration of how the
   FTP-ALG could use the resource control mechanims to interface
   with NAT. The section is divided into three sub-sections to
   illustrate (a) ALG registration with NAT, (b) NAT interface
   with ALG while an FTP session is active, and (c) Notification
   to ALG when the FTP session terminates.

5.1. FTP-ALG registration with NAT

   FTP-ALG will first probe NAT device to understand the type of
   service provided by NAT and obtain NAT-ID. Once the service
   type is agreeable, the ALG will register itself as a client
   with the NAT device with callback functions (as described
   below) and obtain an agent-ID from the NAT. The tuple of
   (nat-id, agent-id) uniquely identifies the interface
   between NAT and ALG.

   ftp_alg_pkt_notify() will be registered to process FTP



Srisuresh                                                      [Page 22]


Internet Draft           NAT Interface Framework               July 2000


   session (TCP port 21) traffic. ftp_alg_event_notify() will
   be registered to process session or NAT termination.


        FTP-ALG                             NAT
        -------                             ---

   1. Obtain NAT descriptor Info

        nat_enquire_IDentity(
           0, **nat_descriptor)
        ------------------------>
                                   NAT will fill a descriptor
                                   block with pertinent information,
                                   specifically NAT-type and NAT-ID
                                   and supply the pointer to the
                                   descriptor block.

                                   OK
                                 <------------------------------

   2. Register with NAT as ALG for
      FTP (TCP port 21) and obtain
      agent-ID from the NAT.

        nat_register_agent(nat_id,
             &ftp_alg_info)
        ------------------------>

                                   NAT will assign an agent-ID.

                                   OK
                                 <------------------------------


5.2. NAT interface with the ALG during FTP session operation

   When NAT sees the first packet of an FTP session, it sets up
   a BIND descriptor and a session descriptor and tags the
   session descriptor as FTP-Type (i.e., TCP port 21). NAT
   will then redirect the packet to FTP-ALG by invoking the
   ALG supplied callback function - ftp_alg_pkt_notify().
   The ALG will obtain session descriptor and BIND descriptor
   info from the NAT.

   Subsequent to this, when NAT redirects FTP packets, the
   ALG would parse the payload for PORT command or response to
   "PASV" to determine ensuing data sessions and interact with



Srisuresh                                                      [Page 23]


Internet Draft           NAT Interface Framework               July 2000


   NAT, as necessary, to obtain the requisite translation
   parameters. The ALG may modify the FTP packet with
   translation parameters prior to resending to NAT for
   forwarding.

        FTP-ALG                             NAT
        -------                             ---

                                   1. NAT sees the first packet
                                      of an FTP session. NAT will
                                      set up a session state and
                                      notify the agent as follows.

                                      ftp_alg_pkt-notify(nat-id,
                                          agent-ID, session-ID,
                                          packet-direction, pkt)
                                  <------------------------

    The ALG may optionally make
    calls to the NAT to find out
    about the session and BIND
    characteristics of the FTP.
    Further, additional calls may
    be made to change the control
    parameters in these blocks.


    nat_enquire_sess_range(
        nat_id, agent-id,
        session_id, session_id,
        &sess_count, **sess_info)
    ------------------------------>
                                      Find the session descriptor
                                      block matching session_id and
                                      return Pointer to this. Bind-id
                                      is one of the items in the block.

                                   OK
                                 <------------------------------
         ...

    nat_enquire_address_bind(
        nat_id, pvt_address,
        external_address, &bind_info)
    ------------------------------>
         ...

    nat_set_bind(



Srisuresh                                                      [Page 24]


Internet Draft           NAT Interface Framework               July 2000


        nat_id, agent_id, &bind_info)
    ------------------------------>

                             .............

                                   n. NAT will forward all
                                      subsequent FTP packets to
                                      the agent as follows.

                                      ftp_alg_pkt-notify(nat-id,
                                          agent-ID, session-ID,
                                          packet-direction, pkt)
                                  <------------------------

    The ALG will parse for PORT
    command and PASV response in
    the payload and track any deltas
    to TCP sequence and acknowledge
    numbers. The ALG will interact
    with NAT, as necessary, to obtain
    BIND parameters for the data
    session, setup data session state
    ahead of time and modify the FTP
    packet (as necessary) prior to
    resending to NAT for forwarding.


    Request BIND parameters for the
    new data session such that there
    is no leased-time set for it.

    nat_set_bind(nat_id, agent-id,
                 &bind_info)
    ------------------------------>

             ....

    Setup a new state for the data
    session such that the Bundle-ID
    is set to be the session ID of
    the controlling FTP session.

    nat_set_sess(nat-id, agent-id,
                &sess-info)
    ---------------------------->


5.3. Session termination notification



Srisuresh                                                      [Page 25]


Internet Draft           NAT Interface Framework               July 2000



   When the FTP control session is ready to be terminated
   by the NAT, NAT will notifiy the event to FTP-ALG as follows.

        FTP-ALG                             NAT
        -------                             ---

                                   1. NAT determines the FTP
                                      session is to be
                                      terminated.

                                      ftp_alg_notify(nat-id,
                                          agent-id,
                                          SESSION-TERMINATED,
                                          session-ID)
                                  <------------------------

    The ALG will in turn clean up any
    data sessions that may be based on
    the FTP session prior to freeing
    the control session itself.

    nat_free_sess(nat-id, agent-id,
                sess-id)
    ---------------------------->




6. Acknowledgement

   The author would like to express sincere appreciation and thanks
   to Yakov Rekhter for his valuable advice and contribution in the
   presentation of this document.


7. Security considerations.

   The security considerations described in [Ref 1] for all variations
   of NATs are applicable here.


REFERENCES

   [1] P. Srisuresh, M. Holdrege, "IP Network Address Translator
       (NAT) Terminology and Considerations", RFC 2663

   [2] Y. Rekhter, B. Moskowitz, D. Karrenberg, G. de Groot, and,



Srisuresh                                                      [Page 26]


Internet Draft           NAT Interface Framework               July 2000


       E. Lear,  "Address Allocation for Private Internets", RFC 1918

   [3] J. Reynolds and J. Postel, "Assigned Numbers", RFC 1700

   [4] R. Braden, "Requirements for Internet Hosts -- Communication
       Layers", RFC 1122

   [5] R. Braden, "Requirements for Internet Hosts -- Application
       and Support", RFC 1123

   [6] F. Baker, "Requirements for IP Version 4 Routers",  RFC 1812

   [7] J. Postel, J. Reynolds, "FILE TRANSFER PROTOCOL (FTP)",
       RFC 959

   [8] "TRANSMISSION CONTROL PROTOCOL (TCP) SPECIFICATION",  RFC 793

   [9] J. Postel, "INTERNET CONTROL MESSAGE (ICMP) SPECIFICATION",
       RFC 792

   [10] J. Postel, "User Datagram Protocol (UDP)",  RFC 768

   [11] J. Mogul, J. Postel, "Internet Standard Subnetting Procedure",
        RFC 950

   [12] Brian carpenter, Jon Crowcroft, Yakov Rekhter, "IPv4 Address
        Behaviour Today", RFC 2101


Author's Address:

   Pyda Srisuresh
   Campio Communications
   630 Alder Drive
   Milpitas, CA 95035
   U.S.A.

   Voice: (408) 519-3849
   EMail: srisuresh@yahoo.com












Srisuresh                                                      [Page 27]