NAT Working Group P. Srisuresh
INTERNET-DRAFT Consultant
Category: Informational November, 2000
Expires on May 24, 2001
Framework for interfacing with Network Address Translator
<draft-ietf-nat-interface-framework-02.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 is a stateful network device, providing routing transparency
for hosts in disparate address realms to communicate with each
other. External agents such as Application Level Gateways (ALGs),
Realm Specific IP (RSIP) clients and Management applications may
need to interact with the device to influence its operation. The
document identifies the parameters external agents can attempt to
monitor and influence. While the document is focused on describing
how to control a device that supports NAT, the description is
applicable to any network device that maintains soft-state of
some kind. The resource control mechanism is illustrated
through an Application Programming Interface (API). However, the
intent is not to standardize the API. Rather, use the API as basis
for the development of one or more protocols by which external
agents could interact with NAT. NAT resources identified can also
form the basis to generate NAT Management Information Base (MIB).
Srisuresh [Page 1]
Internet Draft NAT Interface Framework November 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 can be other kinds of external agents
that choose to influence NAT operation. Section 3 identifies
these agents. 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 API to influence NAT operation.
The intent of the document is two-fold. First, an illustration
through an API on how to control NAT resource/operation to form
a basis for the development of a protocol by which external
agents could communicate with NAT. A portion of the communication
interface is generic enough that it can be applied to any
stateful device. Further, there are extensions that are NAT
specific. A protocol designed to meet the interface requirements
would need to authenticate peering nodes, 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 illustration
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, NAT controlled resource description specified in the
document may be used as the basis to develop NAT Management
Information Base (MIB).
Srisuresh [Page 2]
Internet Draft NAT Interface Framework November 2000
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 elements managed
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. Service Descriptor
Of the fields listed below to describe the service, items 2.1.1
through 2.1.2 are independent of the service the devise supports.
The remaining items are NAT service specific. All flavors of NAT
are designed to provide routing transparency to hosts in
disparate address realms. A device may have multiple NAT
instances or there may be multiple NAT devices associated with a
specific realm. The following attributes identify a specific
instance of a device supporting NAT function.
2.1.1. Service IDentifier
A service identifier uniquely identifies service instantiation
within a network device. The external interface address may be
one way to uniquely describe this Identifier.
2.1.2. Service type
The service supported on the intermediate node could be one of
Basic-NAT, NAPT, Bi-directional-NAT, Twice-NAT, RSA-IP server,
RSAP-IP-server or a combination of the above. Service type is
an indication of the direction in which new sessions are
permitted and the extent of translation done within the IP and
transport headers. [Ref 1] has a discussion on NAT flavors and
the extent of their translations.
2.1.3. 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.
2.1.4. 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
Srisuresh [Page 3]
Internet Draft NAT Interface Framework November 2000
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
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.
2.1.5. 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.
2.1.6. 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
Hereafter, the term BIND will be used in place of BINDing, for ease
of use. BIND descriptor is specific to NAT service. These BINDs
can be static or dynamic. 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 attributes describe the BIND
object(s) maintained by a NAT device.
2.2.1. Bind ID
A number (say, in the range of 1 through 0xFFFFFFFF) assigned
to BIND to uniquely identify this BIND from a different BIND
Srisuresh [Page 4]
Internet Draft NAT Interface Framework November 2000
on the same NAT.
2.2.2. 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.
2.2.3. 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.
2.2.4. Private and External addresses (and Transport-IDs)
These parameters specify the BINDing items in private and
external realms.
2.2.5. 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.2.6. 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.
2.2.7. 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.
2.2.8. 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
Srisuresh [Page 5]
Internet Draft NAT Interface Framework November 2000
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.
2.2.9. 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.
2.3. Session State descriptor
NAT device maintains soft-state for the sessions it tracks.
These states are created dynamically during NAT operation
and are referenced for translation of packets pertaining to the
session. The entries maintained in a session state are specific
to the service type supported (e.g., Basic NAT, NAPT, twice-NAT
etc.). For instance, twice-NAT service will require two BINDs,
unlike other NAT variations which use just one BIND. The
following attributes identify various parameters tracked with a
session. Items 2.3.1 through 2.3.9 below are service independent.
The remaining items are NAT service specific. Not all services
need to track all parameters.
2.3.1. 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 device.
2.3.2. Direction of Session.
Direction of first packet of the session. As specified
earlier, direction is with reference to private realm.
2.3.3. 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).
Srisuresh [Page 6]
Internet Draft NAT Interface Framework November 2000
2.3.4. Controlling Agent IDentification
This indicates the last external Agent who has tried to
control parameters for this session. A value of 0 indicates
that no external agent is registered to control the session.
2.3.5. Application tag
Sessions are assigned an application tag, so that sessions
bearing the same tag can be handled the same way by an
external application agent. Application tag may be specified
as a tuple of (<IP-protocol>, <session-Port>). For example,
an FTP-ALG may register with NAT to control sessions with
an FTP application tag.
2.3.6. Session Termination heuristic
Session-Idle-time is typically used as a heuristic to
determine if the session has ended. There may be other
heuristic approaches. A value of zero indicates that no
session termination heuristic is used. The controlling
agent may take responsibility for session termination
in that case. With or without a termination heuristic,
TCP sessions may be terminated based on FIN and RST
options in TCP header [Ref1].
2.3.7. Maximum Idle time
This parameter indicates maximum amount of time this session
is allowed to remain valid, even as there is no activity.
This parameter is relevant only when session-Idle-time is used
as the heuristic to determine session termination. There may
be other heuristic approaches. As a special case, a value of 0
implies a that the device should run the default timer
configured for all native sessions (that have no controlling
agent registered).
2.3.8. Current Idle Time
This parameter is of relevance only when session termination
heuristic is set to session-idle-time. Typically, the device
monitors 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.
2.3.9. Bundle ID
Srisuresh [Page 7]
Internet Draft NAT Interface Framework November 2000
Applications that deal with a bundle of sessions may cause
multiple sessions to be managed by the device. Even though these
sessions constitute a single session from application stand
point, the device is not cognizant of the relation. In such
cases, it is not uncommon for controlling agents to store
session ID of the initial session in all subsequent sessions
spawned in that incarnation of the application. Note, Bundle ID
need not be the initial session ID, just a unique ID for all
sessions of the bundle.
2.3.10. 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.
2.3.11. 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.
2.3.12. 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 and the Second Bind Identifier refers to
the binding of the destination address(of the first packet).
2.3.13. 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.
Srisuresh [Page 8]
Internet Draft NAT Interface Framework November 2000
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,
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 management 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
Srisuresh [Page 9]
Internet Draft NAT Interface Framework November 2000
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
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
+----------------------------------------+
| External Agent API |
+----------------------------------------+
| NAT Service |
|(Resource management, Packet translation|
| and External agent interface) |
+----------------------------------------+
| NAT managed resources |
| (sessions, BINDs, Address maps etc.) |
+----------------------------------------+
figure 1. External agents interfacing with NAT
The following attributes uniquely identify an external agent
to NAT device. Items 3.1 through 3.4 are service independent,
and the remaining items are NAT specific.
3.1. Agent IDentifier
A number (say, in the range of 1 through 0xFFFFFFFF) assigned
to the agent by the controlling device to distinguish from
other agents. Typically, this handle may be assigned when the
Srisuresh [Page 10]
Internet Draft NAT Interface Framework November 2000
agent registers with the device.
3.2. Agent type
Based on the categories of external agents described thus far,
it is clear the API requirements amongst the agents differ
considerably. The interface supported by a device may not meet
all the agent requirements. Hence, it is beneficial for the
device 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.
3.3. Agent accessibility information
When an agent is resident on a different physical device than
the controlling device, this parameter specifies means by
which the controlling device can access the agent. This can
be a combination of Agent's IP address, IP protocol (e.g.,
TCP or UDP), well-known port etc. A value of 0 for
agent's IP address indicates that the agent is co-resident
with the controlling device.
3.4. Periodic Notification interval
This parameter would be required only when the agent calls
for periodic notification from the device. This may be
specified in units of seconds.
3.5. Agent call-back requirements
An agent will typically require the device to invoke a
call-back function supplied by the agent upon the occurrence
of specific events. Events for which an agent needs
notification depends on agent type.
An ALG will require NAT to call back when a data packet is
received on a session with a certain application-tag (say,
FTP). 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 - session termination,
service termination and BIND termination.
3.6. 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 the device. Below are three different call-back
Srisuresh [Page 11]
Internet Draft NAT Interface Framework November 2000
function prototypes.
Event notification - void agent_callback_event(service_id,
agent_id, event, event_info)
Periodic notification - void agent_callback_periodic(service_id,
agent_id, info_type, info_length,
information)
Packet notification - void agent_callback_packet(service_id,
agent_id, sess_id,
pkt_direction, packet)
3.7. 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.
4. External Agent Programming Interface
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 the networking device
to return back a value. The second sub-section lists functions
required to be provided by external agents in order for the
NAT device to call-back upon some events.
4.1. API functions available to an external agent
Functions 4.1.1 through 4.1.6 below are service independent and
are prefixed with "service_". Remaining functions are NAT service
specific and are prefixed with "nat_".
4.1.1. int service_enquire_IDentity(service_type, **service_info)
Purpose:
This function is used by external agents to obtain NAT-ID
and its characteristics, as described in section 2.1
Input parameters:
Srisuresh [Page 12]
Internet Draft NAT Interface Framework November 2000
service_type - This parameter is filled to verify if
the device supports a certain service type
(Refer section 2.1.2). A value of 0 requires
the device to report all service types supported.
Output Parameters:
service_info - The device will fill up a descriptor block with
it characteristics (refer section 2.1) for the
matching service_type and return pointer to the
descriptor block. The descriptor block would
specifically include a service identifier (refer
section 2.1.1) that uniquely identifies service
instance. This is referred as service_id throughout
the document.
Multiple pieces of this information may be returned,
if the device supports multiple instances of the
same service type. Multiple instances of descriptor
blocks may also be returned when service_type is set
to 0 and the device supports multiple service types.
Return Value:
No-Error(0) - A return value of 0 implies success
and that service_info may be examined
for service description.
SERVICE-TYPE-NOT-SUPPORTED - Notify the agent that the
device does not support the requested
service type.
4.1.2. int service_register_agent (service_id, &agent_info)
Purpose:
This function is used by external agents to register with the
device.
Input parameters:
service_id - The identifier that uniquely identifies the service
instance (ex: 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
Srisuresh [Page 13]
Internet Draft NAT Interface Framework November 2000
the caller to influence NAT operation.
Output Parameters:
agent_info - NAT will set agent_id in agent_info structure
when registration is successful.
Return Value:
No-Error(0) - A return value of 0 implies successful
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-SERVICE-ID - The specified service_id is not
operational or is incorrect.
4.1.3. int service_enquire_sess_range(service_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:
service_id - The identifier that uniquely identifies the NAT
instance.
agent_id - The agent Identifier that uniquely identifies the
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.
Srisuresh [Page 14]
Internet Draft NAT Interface Framework November 2000
sess_info - Return one or more sessions with an ID in the
given range.
Return Value:
No-Error(0) - A return value of 0 implies successful
session termination.
INVALID-SERVICE-ID- The specified service_id is not operational
or is incorrect.
INVALID-AGENT-ID - The specified Agent_ID is not currently
registered with NAT.
4.1.4. int service_set_sess(service_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:
service_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
be filled with the values that NAT holds.
Srisuresh [Page 15]
Internet Draft NAT Interface Framework November 2000
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-SERVICE-ID- The specified service_id is not operational
or is incorrect.
INVALID-AGENT-ID - The specified Agent_id is not currently
registered with the device.
4.1.5. int service_free_sess(service_id, agent_id, sess_id)
Purpose:
This function is used by external agents to terminate
the specified session.
Input parameters:
service_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-SERVICE-ID- The specified service_id is not operational
Srisuresh [Page 16]
Internet Draft NAT Interface Framework November 2000
or is incorrect.
INVALID-AGENT-ID - The specified Agent_id is not currently
registered with the device.
4.1.6. int service_free_sess_bundle(service_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.
Input parameters:
service_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-SERVICE-ID - The specified service_id is not operational
or is incorrect.
INVALID-AGENT-ID - The specified Agent_id is not currently
registered with the device.
4.1.7. int nat_enquire_address_bind (service_id, pvt_address,
ext_address, &bind_info)
Purpose:
This function is used by external agents to obtain
Address BIND information.
Srisuresh [Page 17]
Internet Draft NAT Interface Framework November 2000
Input parameters:
service_id - This 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-SERVICE-ID - The specified service_id is not operational
or is incorrect.
4.1.8. int nat_enquire_transport_bind(service_id, pvt_address, pvt_port,
transport_protocol, ext_address, ext_port, &bind_info)
Purpose:
This function is used by external agents to obtain
Transport ID BIND information.
Input parameters:
service_id - This 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
Srisuresh [Page 18]
Internet Draft NAT Interface Framework November 2000
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-SERVICE-ID- The specified service_id is not operational
or is incorrect.
4.1.9. int nat_set_bind (service_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:
service_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 19]
Internet Draft NAT Interface Framework November 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-SERVICE-ID- The specified service_id is not operational
or is incorrect.
INVALID-AGENT-ID - The specified Agent_id is not currently
registered with the device.
4.1.10. int nat_free_bind(service_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:
service_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.
INVALID-SERVICE-ID- The specified service_id is not operational
or is incorrect.
Srisuresh [Page 20]
Internet Draft NAT Interface Framework November 2000
INVALID-AGENT-ID - The specified Agent_id is not currently
registered with the device.
4.2. Call-back functions within an external agent
The callback functions listed can be the same independent of the
NAT service supported on the device or the agent that controls
the device. However, the individual parameters supplied will be
specific to the tuple of (service_type, agent_type).
4.2.1. void agent_callback_event(service_id, agent_id, event_type,
&event_info)
Purpose:
This function is used by the device to notify an agent of an
event status.
Input parameters:
service_id - The identifier that uniquely identifies the NAT
instance.
agent_id - The agent Identifier that uniquely identifies the
agent to the device.
event_type - The event can be one of session Creation, session
termination, BIND creation or BIND termination
for a NAT device.
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(service_id, agent_id, info_type,
info_length, &periodic_info)
Purpose:
This function is used by the device to notify an agent of a
certain piece of information periodically.
Input parameters:
service_id - The identifier that uniquely identifies the NAT
instance.
Srisuresh [Page 21]
Internet Draft NAT Interface Framework November 2000
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(service_id, agent_id, sess_id,
pkt_direction, packet)
Purpose:
This function is used by the device 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
setup time.
Input parameters:
service_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
Srisuresh [Page 22]
Internet Draft NAT Interface Framework November 2000
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 ALG for FTP application
([Ref 7]) could use the API specified to interface with NAT to
provide application level transparency. This is not meant to be a
detailed description of how an FTP-ALG would work. But, rather an
illustration of how an ALG could use the interface with NAT to
accomplish the desired application transparency. 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
(service_id, agent_id) uniquely identifies the interface
between NAT and ALG.
ftp_alg_pkt_notify() will be registered to process FTP
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
service_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
<------------------------------
Srisuresh [Page 23]
Internet Draft NAT Interface Framework November 2000
2. Register with NAT as ALG for
FTP (TCP port 21) and obtain
agent_ID from the NAT.
service_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
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, sess_ID,
packet_direction, pkt)
<------------------------
The ALG may optionally make
calls to the NAT to find out
Srisuresh [Page 24]
Internet Draft NAT Interface Framework November 2000
about the session and BIND
characteristics of the FTP.
Further, additional calls may
be made to change the control
parameters in these blocks.
service_enquire_sess_range(
nat_id, agent_id,
sess_id, sess_id,
&sess_count, **sess_info)
------------------------------>
Find the session descriptor
block matching sess_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(
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, sess_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
Srisuresh [Page 25]
Internet Draft NAT Interface Framework November 2000
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.
service_set_sess(nat_id, agent_id,
&sess_info)
---------------------------->
5.3. Session termination notification
When the FTP control session is ready to be terminated
by the NAT, NAT will notify 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,
sess_ID)
<------------------------
The ALG will in turn clean up any
data sessions that may be based on
the FTP session prior to freeing
Srisuresh [Page 26]
Internet Draft NAT Interface Framework November 2000
the control session itself.
service_free_sess(nat_id, agent_id,
sess_id)
---------------------------->
6. Acknowledgement
The author would like to thank Yakov Rekhter for his valuable advice
and contribution in the organization of this document.
7. Security considerations.
The security considerations described in [Ref 1] for all variations
of NATs are applicable here. The interface between NAT and external
agents must be trusted as the API influences the session operation
on the NAT device.
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,
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",
Srisuresh [Page 27]
Internet Draft NAT Interface Framework November 2000
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
849 Erie circle
Milpitas, CA 95035
U.S.A.
Voice: (408) 263-7527
EMail: srisuresh@yahoo.com
Srisuresh [Page 28]
