< draft-ietf-nat-interface-framework-02.txt		draft-ietf-nat-interface-framework-03.txt >
	NAT Working Group P. Srisuresh		NAT Working Group P. Srisuresh
	INTERNET-DRAFT Consultant		INTERNET-DRAFT Jasmine Networks
	Category: Informational November, 2000		Category: Informational April, 2000
	Expires on May 24, 2001		Expires on October 9, 2001
	Framework for interfacing with Network Address Translator		Framework for interfacing with Network Address Translator
	<draft-ietf-nat-interface-framework-02.txt>		<draft-ietf-nat-interface-framework-03.txt>
	Status of this Memo		Status of this Memo
	This document is an Internet-Draft and is in full conformance		This document is an Internet-Draft and is in full conformance
	with all provisions of Section 10 of RFC2026. Internet-Drafts		with all provisions of Section 10 of RFC2026. Internet-Drafts
	are working documents of the Internet Engineering Task Force		are working documents of the Internet Engineering Task Force
	(IETF), its areas, and its working groups. Note that other		(IETF), its areas, and its working groups. Note that other
	groups may also distribute working documents as Internet-Drafts.		groups may also distribute working documents as Internet-Drafts.
	Internet-Drafts are draft documents valid for a maximum of six		Internet-Drafts are draft documents valid for a maximum of six
	skipping to change at page 1, line 37 ¶		skipping to change at page 1, line 37 ¶
	The list of Internet-Draft Shadow Directories can be accessed at		The list of Internet-Draft Shadow Directories can be accessed at
	http://www.ietf.org/shadow.html.		http://www.ietf.org/shadow.html.
	Abstract		Abstract
	NAT is a stateful network device, providing routing transparency		NAT is a stateful network device, providing routing transparency
	for hosts in disparate address realms to communicate with each		for hosts in disparate address realms to communicate with each
	other. External agents such as Application Level Gateways (ALGs),		other. External agents such as Application Level Gateways (ALGs),
	Realm Specific IP (RSIP) clients and Management applications may		Realm Specific IP (RSIP) clients and Management applications may
	need to interact with the device to influence its operation. The		need to interact with NAT to influence its operation. The document
	document identifies the parameters external agents can attempt to		identifies resources that may be exposed to external agents and
	monitor and influence. While the document is focused on describing		illustrates resource control through an Application Programming
	how to control a device that supports NAT, the description is		Interface (API). While the document is focused on describing how
	applicable to any network device that maintains soft-state of		to interface with a middlebox supporting NAT function, the
	some kind. The resource control mechanism is illustrated		description may be applicable to any middlebox that keeps
	through an Application Programming Interface (API). However, the		soft-state for sessions. The intent is not to standardize the
	intent is not to standardize the API. Rather, use the API as basis		API. Rather, use API as the basis for the development of a
	for the development of one or more protocols by which external		middlebox communication (MIDCOM) protocol by which MIDCOM agents
	agents could interact with NAT. NAT resources identified can also		can interface with NAT. NAT resources identified can also form
	form the basis to generate NAT Management Information Base (MIB).		the basis to generate NAT Management Information Base (MIB).
	1. Introduction		1. Introduction
	NAT provides routing transparency for hosts in disparate address		NAT provides routing transparency for hosts in disparate address
	realms to communicate with each other. [Ref 1] details the various		realms to communicate with each other. [Ref 1] details the various
	flavors of NAT that abound. Many internet applications use IP		flavors of NAT that abound. Many internet applications use IP
	address as host identifier rather than just as a way to locate a		address as host identifier rather than just as a way to locate a
	host. For this reason, routing transparency by NAT alone is not		host. For this reason, routing transparency by NAT alone is not
	sufficient to provide end-to-end transparency for applications		sufficient to provide end-to-end transparency for applications
	operating across realms. Application specific ALGs are required		operating across realms. Application specific ALGs are required
	skipping to change at page 2, line 31 ¶		skipping to change at page 2, line 31 ¶
	agents, combined with the nature of NAT resources provide the		agents, combined with the nature of NAT resources provide the
	basis to illustrate the resource control mechanism functionally		basis to illustrate the resource control mechanism functionally
	through an API in section 4. Section 5 illustrates how an		through an API in section 4. Section 5 illustrates how an
	external agent could use the API to influence NAT operation.		external agent could use the API to influence NAT operation.
	The intent of the document is two-fold. First, an illustration		The intent of the document is two-fold. First, an illustration
	through an API on how to control NAT resource/operation to form		through an API on how to control NAT resource/operation to form
	a basis for the development of a protocol by which external		a basis for the development of a protocol by which external
	agents could communicate with NAT. A portion of the communication		agents could communicate with NAT. A portion of the communication
	interface is generic enough that it can be applied to any		interface is generic enough that it can be applied to any
	stateful device. Further, there are extensions that are NAT		stateful middlebox. Further, there are extensions that are NAT
	specific. A protocol designed to meet the interface requirements		specific. The API illustration assumes a trusted environment and
	would need to authenticate peering nodes, locate NAT devices and		does not address authentication, authorization or discovery of
	exchange data elements. The API illustration assumes a trusted		middlebox location. It is also important to note that the
	environment and does not address authentication and Service		illustration does not assume or require external agents to reside
	location. It is also important to note that the illustration		on the same physical device as NAT. In reality, some agents may
	does not assume or require external agents to reside on the same		be co-located with middlebox on the same device and others reside
	physical device as NAT, even though assuming they reside on the		on external devices. Discussion of a communication protocol for
	same physical device might help in understanding. In reality,		use by external agents to interface with middlebox is outside
	some agents may be co-located with NAT on the same device and		the purview of this document.
	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		Second, NAT controlled resource description specified in the
	document may be used as the basis to develop NAT Management		document may be used as the basis to develop NAT Management
	Information Base (MIB).		Information Base (MIB).
	2. Elements of NAT operation		2. Terminology
			Definitions for majority of terms used in this document may be found
			in NAT Terminology and Considerations document [Ref 1]. Below are
			terms defined specifically for this document.
			2.1. MiddleBox and Middlebox services
			Middlebox is a network intermediate device implementing a
			middlebox service. Middlebox service is characterized as a
			networking function requiring application intelligence for
			its operation. A middlebox service is also referred as
			Middlebox function throughout this document. Examples of
			middlebox functions include NAT, firewall, intrusion
			detection, load balancing, policy based tunneling and
			IPsec security Gateway enforcement. A middlebox may
			implement one or more of these functions.
			Clearly, NAT is a specific middlebox function and NAT device
			is a specific Middlebox device.
			2.2. MIDCOM Agents
			MIDCOM agents are entities performing ALG function, logically
			external to a middlebox. MIDCOM agents possess a combination of
			application awareness and knowledge of the middlebox function.
			A MIDCOM agent may communicate with one or more middleboxes.
			A MIDCOM agent is also referred as "external agent" throughout
			the document.
			2.3. Middlebox Communication (MIDCOM) protocol
			The protocol used by MIDCOM agents to interface with the middlebox
			and its resources to influence its operation. This is a protocol
			yet to be devised. The interface API presented in the document,
			while focused on NAT function, may be used as the basis for the
			development of such a protocol, extensible to other middlebox
			functions.
			3. Elements of NAT operation
	In order to identify an API for use by external agents, it is		In order to identify an API for use by external agents, it is
	important to understand the resources and other elements managed		important to understand the resources and other elements managed
	by NAT. This would help identify the extent to which an external		by NAT. This would help identify the extent to which an external
	agent may influence NAT operation. This section describes objects		agent may influence NAT operation. This section describes objects
	within NAT, that could be externalized via Management Information		within NAT, that could be externalized via Management Information
	Base (MIB).		Base (MIB).
	2.1. Service Descriptor		3.1. Service Descriptor
	Of the fields listed below to describe the service, items 2.1.1		Of the fields listed below to describe the service, items 3.1.1
	through 2.1.2 are independent of the service the devise supports.		through 3.1.2 are independent of the service the devise supports.
	The remaining items are NAT service specific. All flavors of NAT		The remaining items are NAT service specific. All flavors of NAT
	are designed to provide routing transparency to hosts in		are designed to provide routing transparency to hosts in
	disparate address realms. A device may have multiple NAT		disparate address realms. A middlebox may have multiple NAT
	instances or there may be multiple NAT devices associated with a		instances or there may be multiple NAT middleboxs associated
	specific realm. The following attributes identify a specific		with a specific realm. The following attributes identify a
	instance of a device supporting NAT function.		specific instance of a middlebox supporting NAT function.
	2.1.1. Service IDentifier		3.1.1. Service IDentifier
	A service identifier uniquely identifies service instantiation		A service identifier uniquely identifies service instantiation
	within a network device. The external interface address may be		within a middlebox. The external interface address may be
	one way to uniquely describe this Identifier.		one way to uniquely describe this Identifier.
	2.1.2. Service type		3.1.2. Service type
	The service supported on the intermediate node could be one of		The service supported on the intermediate node could be one of
	Basic-NAT, NAPT, Bi-directional-NAT, Twice-NAT, RSA-IP server,		Basic-NAT, NAPT, Bi-directional-NAT, Twice-NAT, RSA-IP server,
	RSAP-IP-server or a combination of the above. Service type is		RSAP-IP-server or a combination of the above. Service type is
	an indication of the direction in which new sessions are		an indication of the direction in which new sessions are
	permitted and the extent of translation done within the IP and		permitted and the extent of translation done within the IP and
	transport headers. [Ref 1] has a discussion on NAT flavors and		transport headers. [Ref 1] has a discussion on NAT flavors and
	the extent of their translations.		the extent of their translations.
	2.1.3. Private and External realm types		3.1.3. Private and External realm types
	Every NAT device will have a minimum of two routing		Every NAT device will have a minimum of two routing
	interfaces, one connecting to a private realm and one		interfaces, one connecting to a private realm and one
	connecting to external realm. An IPv4 NAT device will		connecting to external realm. An IPv4 NAT device will
	have both its realm types set to IPv4.		have both its realm types set to IPv4.
	2.1.4. Address(and Transport-ID) maps		3.1.4. Address(and Transport-ID) maps
	Address map on a NAT device could consist of one or more of		Address map on a NAT device is constituted of one or more of
	static and dynamic Address maps. Likewise, Transport-ID		static/ dynamic Address maps. Transport-ID mapping, on
	mapping could consists of one or more of static and dynamic		the other hand, constitutes one or more of static/dynamic
	transport-ID maps. Transport-ID mapping is more specific		transport-ID maps. Transport-ID maps a specific TCP/UDP port
	than address mapping in that a specific TCP/UDP port (or		(or port range) pertaining to an address in external realm
	port range) pertaining to an address in external realm is		to a specific TCP/UDP port (or port range) in private realm
	mapped to a specific TCP/UDP port (or port range) in private		or vice versa. Address (and Transport-ID) maps may be
	realm or vice versa. Address (and Transport-ID) maps may be
	defined for both inbound and outbound directions. Outbound		defined for both inbound and outbound directions. Outbound
	address map refers to mapping a selected set of addresses		address map refers to mapping a selected set of addresses
	from private realm to a selected set of addresses in		from private realm to a selected set of addresses in
	external realm; whereas inbound address map refers to		external realm; whereas inbound address map refers to
	mapping a set of addresses from the external realm to		mapping a set of addresses from the external realm to
	private realm.		private realm.
	2.1.5. Miscellaneous parameters		3.1.5. Miscellaneous parameters
	NAT may optionally provide TCP, UDP and other types of session		NAT may optionally provide TCP, UDP and other types of session
	Idle-times used to terminate sessions. It may also provide the		Idle-times used to terminate sessions. It may also provide the
	current range (and, the maximum range) of session IDs and		current range (and, the maximum range) of session IDs and
	Bind IDs (to be covered in the follow on sub-sections); and		Bind IDs (to be covered in the follow on sub-sections); and
	the actual count of session IDs and BIND IDs. Specifically,		the actual count of session IDs and BIND IDs. Specifically,
	this information will be of relevance to another NAT (backup		this information will be of relevance to another NAT (backup
	NAT) that intends to emulate this NAT, in case of failure.		NAT) that intends to emulate this NAT, in case of failure.
	Lastly, NAT may choose to supply any other vendor specific		Lastly, NAT may choose to supply any other vendor specific
	parameters such as log options, session direction failure		parameters such as log options, session direction failure
	actions and so forth.		actions and so forth.
	2.1.6. Realm Specific IP (RSIP) parameters		3.1.6. Realm Specific IP (RSIP) parameters
	A NAT device offering RSIP-Server capability may specify the		A NAT device offering RSIP-Server capability may specify the
	RSIP tunnel types it supports.		RSIP tunnel types it supports.
	2.2. Address (and Transport-ID) BINDing Descriptor		3.2. Address (and Transport-ID) BIND Descriptor
	Hereafter, the term BIND will be used in place of BINDing, for ease		Hereafter, the term BIND will be used in place of BINDing, for ease
	of use. BIND descriptor is specific to NAT service. These BINDs		of use. BIND descriptor is specific to NAT service. These BINDs
	can be static or dynamic. When external agents do not intervene,		can be static or dynamic. When external agents do not intervene,
	dynamic address(and transport-ID) binding is determined by NAT		dynamic address(and transport-ID) binding is determined by NAT
	based on the first packet of a session, as described in [Ref 1].		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 binding is between an address in private realm and an
	address from external realm. Transport-ID BIND is an extension of		address from external realm. Transport-ID BIND is an extension of
	the same concept to the tuple of Address and transport ID (such as		the same concept to the tuple of Address and transport ID (such as
	TCP/UDP port no.). The following attributes describe the BIND		TCP/UDP port no.). The following attributes describe the BIND
	object(s) maintained by a NAT device.		object(s) maintained by a NAT device.
	2.2.1. Bind ID		3.2.1. Bind ID
	A number (say, in the range of 1 through 0xFFFFFFFF) assigned		A number (say, in the range of 1 through 0xFFFFFFFF) assigned
	to BIND to uniquely identify this BIND from a different BIND		to BIND to uniquely identify the BIND on a NAT middlebox.
	on the same NAT.
	2.2.2. Direction of Bind		3.2.2. Direction of Bind
	A bind can be uni-directional or bi-directional, same as the		A bind can be uni-directional or bi-directional, same as the
	orientation of address map based on which this BIND is formed.		orientation of address map based on which this BIND is formed.
	As before, the direction is with reference to private realm.		As before, the direction is with reference to private realm.
	2.2.3. Bind type		3.2.3. Bind type
	Indicates whether the BIND is Address-BIND (between a pair of		Indicates whether the BIND is Address-BIND (between a pair of
	addresses) or Transport-ID-Bind (between a pair of Address,		addresses) or Transport-ID-Bind (between a pair of Address,
	transport ID tuples). Further, this also indicates if the Bind		transport ID tuples). Further, this also indicates if the Bind
	is static or dynamically generated.		is static or dynamically generated.
	2.2.4. Private and External addresses (and Transport-IDs)		3.2.4. Private and External addresses (and Transport-IDs)
	These parameters specify the BINDing items in private and		These parameters specify the BINDing items in private and
	external realms.		external realms.
	2.2.5. Controlling Agent IDentification		3.2.5. MIDCOM Agent IDentification
	This indicates the last external Agent who has tried to		This indicates the last external Agent that registered to
	control (i.e., set) parameters for this BIND. A value of 0		control (i.e., set) parameters for this BIND. A value of 0
	indicates that native NAT is the responsible agent.		indicates that native NAT is the responsible agent.
	2.2.6. Maximum lease time		3.2.6. Maximum lease time
	The validity of a BIND may be limited by the duration of lease		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		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		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.		value of 0 may be assumed to indicate no lease time limit.
	Typically, this attribute is of relevance only in conjunction		Typically, this attribute is of relevance only in conjunction
	with Realm-Specific-IP(RSIP) operation.		with Realm-Specific-IP(RSIP) operation.
	2.2.7. Available lease time		3.2.7. Available lease time
	This parameter is of relevance only when Maximum lease time is		This parameter is of relevance only when Maximum lease time is
	a non-zero value. At any given instance of time, this parameter		a non-zero value. At any given instance of time, this parameter
	indicates the real-time left for a BIND to remain valid.		indicates the real-time left for a BIND to remain valid.
	Typically, this attribute is of relevance only in conjunction		Typically, this attribute is of relevance only in conjunction
	with Realm-Specific-IP(RSIP) operation.		with Realm-Specific-IP(RSIP) operation.
	2.2.8. Maximum Idle time		3.2.8. Maximum Idle time
	This parameter indicates maximum amount of time a dynamic BIND		This parameter indicates maximum amount of time a dynamic BIND
	is allowed to remain valid, with no NAT session hanging off this		is allowed to remain valid, with no NAT session hanging off this
	BIND. Typically, a dynamic Bind is established when NAT notices		BIND. Typically, a dynamic Bind is established when NAT notices
	the first session that needs such a binding. Subsequent to		the first session that needs such a binding. Subsequent to
	this, multiple NAT sessions can be maintained using the same		this, multiple NAT sessions can be maintained using the same
	binding. When the last of these sessions is terminated, the		binding. When the last of these sessions is terminated, the
	bind is also terminated. In other words, Maximum Idle time is 0,		bind is also terminated. In other words, Maximum Idle time is 0,
	by default, for native NAT. External agents could control this		by default, for native NAT. External agents could control this
	parameter differently. Static Binds and lease time limited BINDs		parameter differently. Static Binds and lease time limited BINDs
	are not effected by this parameter.		are not effected by this parameter.
	2.2.9. Current Idle time		3.2.9. Current Idle time
	This parameter is of relevance only when Maximum Idle time is		This parameter is of relevance only when Maximum Idle time is
	set to a non-zero value. At any given instance of time, this		set to a non-zero value. At any given instance of time, this
	parameter indicates the real-time the BIND has been idle with		parameter indicates the real-time the BIND has been idle with
	no sessions attached to it.		no sessions attached to it.
	2.3. Session State descriptor		3.3. Session descriptor
	NAT device maintains soft-state for the sessions it tracks.		NAT device maintains soft-state for the sessions it tracks.
	These states are created dynamically during NAT operation		These states may be created dynamically during NAT operation
	and are referenced for translation of packets pertaining to the		and are referenced for translation of packets pertaining to the
	session. The entries maintained in a session state are specific		session. The entries maintained in a session state are specific
	to the service type supported (e.g., Basic NAT, NAPT, twice-NAT		to the service type supported (e.g., Basic NAT, NAPT, twice-NAT
	etc.). For instance, twice-NAT service will require two BINDs,		etc.). For instance, twice-NAT service will require two BINDs,
	unlike other NAT variations which use just one BIND. The		unlike other NAT variations which use just one BIND. The
	following attributes identify various parameters tracked with a		following attributes identify various parameters tracked with a
	session. Items 2.3.1 through 2.3.9 below are service independent.		session. Items 2.3.1 through 2.3.9 below are service independent.
	The remaining items are NAT service specific. Not all services		The remaining items are NAT service specific. Not all services
	need to track all parameters.		need to track all parameters.
	2.3.1. Session IDentifier		3.3.1. Session IDentifier
	A number (say, in the range of 1 through 0xFFFFFFFF) assigned		A unique number (say, in the range of 1 through 0xFFFFFFFF)
	to session to uniquely identify this from other sessions on		assigned by middlebox to a session to uniquely identify this
	the same device.		from other sessions on the same device.
	2.3.2. Direction of Session.		3.3.2. Direction of Session
	Direction of first packet of the session. As specified		Direction of first packet of the session. As specified
	earlier, direction is with reference to private realm.		earlier, direction is with reference to private realm.
	2.3.3. Original Session parameters		3.3.3. Original Session parameters
	These parameters identify the session level parameters as		These parameters identify the session level parameters as
	they appear in the first packet of session. These parameters		they appear in the first packet of session. These parameters
	include src and dest IP addresses, IP protocol and transport		include src and dest IP addresses, IP protocol and transport
	IDentifier info (such as TCP/UDP port numbers or ICMP Query		IDentifier info (such as TCP/UDP port numbers or ICMP Query
	Identifier).		Identifier).
	2.3.4. Controlling Agent IDentification		3.3.4. Controlling Agent IDentification
	This indicates the last external Agent who has tried to		This indicates the last external Agent who has tried to
	control parameters for this session. A value of 0 indicates		control parameters for this session. A value of 0 indicates
	that no external agent is registered to control the session.		that no external agent is registered to control the session.
	2.3.5. Application tag		3.3.5. Application tag
	Sessions are assigned an application tag, so that sessions		Sessions are assigned an application tag, so that sessions
	bearing the same tag can be handled the same way by an		bearing the same tag can be handled the same way by an
	external application agent. Application tag may be specified		external application agent. Application tag may be specified
	as a tuple of (<IP-protocol>, <session-Port>). For example,		as a tuple of (<IP-protocol>, <session-Port>). For example,
	an FTP-ALG may register with NAT to control sessions with		an FTP-ALG may register with NAT to control sessions with
	an FTP application tag.		an FTP application tag.
	2.3.6. Session Termination heuristic		3.3.6. Session Termination heuristic
	Session-Idle-time is typically used as a heuristic to		Session-Idle-time is typically used as a heuristic to
	determine if the session has ended. There may be other		determine if the session has ended. There may be other
	heuristic approaches. A value of zero indicates that no		heuristic approaches. A value of zero indicates that no
	session termination heuristic is used. The controlling		session termination heuristic is used. The controlling
	agent may take responsibility for session termination		agent may take responsibility for session termination
	in that case. With or without a termination heuristic,		in that case. With or without a termination heuristic,
	TCP sessions may be terminated based on FIN and RST		TCP sessions may be terminated based on FIN and RST
	options in TCP header [Ref1].		options in TCP header [Ref1].
	2.3.7. Maximum Idle time		3.3.7. Maximum Idle time
	This parameter indicates maximum amount of time this session		This parameter indicates maximum amount of time this session
	is allowed to remain valid, even as there is no activity.		is allowed to remain valid, even as there is no activity.
	This parameter is relevant only when session-Idle-time is used		This parameter is relevant only when session-Idle-time is used
	as the heuristic to determine session termination. There may		as the heuristic to determine session termination. There may
	be other heuristic approaches. As a special case, a value of 0		be other heuristic approaches. As a special case, a value of 0
	implies a that the device should run the default timer		implies a that the device should run the default timer
	configured for all native sessions (that have no controlling		configured for all native sessions (that have no controlling
	agent registered).		agent registered).
	2.3.8. Current Idle Time		3.3.8. Current Idle Time
	This parameter is of relevance only when session termination		This parameter is of relevance only when session termination
	heuristic is set to session-idle-time. Typically, the device		heuristic is set to session-idle-time. Typically, the device
	monitors idle time on the sessions it manages periodically		monitors idle time on the sessions it manages periodically
	and updates this variable. When the idle time exceeds the		and updates this variable. When the idle time exceeds the
	maximum allowed idle time, the session is terminated.		maximum allowed idle time, the session is terminated.
	2.3.9. Bundle ID		3.3.9. Bundle ID
	Applications that deal with a bundle of sessions may cause		Applications that deal with a bundle of sessions may cause
	multiple sessions to be managed by the device. Even though these		multiple sessions to be managed by the middlebox. Even though
	sessions constitute a single session from application stand		these sessions constitute a single session from application
	point, the device is not cognizant of the relation. In such		stand point, the middlebox is not cognizant of the relation.
	cases, it is not uncommon for controlling agents to store		In such cases, it is not uncommon for controlling agents to
	session ID of the initial session in all subsequent sessions		store session ID of the initial session in all subsequent
	spawned in that incarnation of the application. Note, Bundle ID		sessions spawned in that incarnation of the application. Note,
	need not be the initial session ID, just a unique ID for all		Bundle ID need not be the initial session ID, just a
	sessions of the bundle.		unique ID for all sessions of the bundle.
	2.3.10. Bind IDentifier		3.3.10. Bind IDentifier
	Identifies the Bind based on which this session is created.		Identifies the Bind based on which this session is created.
	The Direction of BIND must be same as that of the session,		The Direction of BIND must be same as that of the session,
	if the BIND is uni-directional. Typically, if a Bind supporting		if the BIND is uni-directional. Typically, if a Bind supporting
	the session translation does not already exist, a Bind is		the session translation does not already exist, a Bind is
	created prior to creating new session state. However, this		created prior to creating new session state. However, this
	Identifier may be set to 0, when BIND creation is unnecessary		Identifier may be set to 0, when BIND creation is unnecessary
	for the session. For example, there can be no more than one		for the session. For example, there can be no more than one
	ICMP Query session using am ICMP Query based transport-ID-bind.		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		In such a case, it suffices to do away with BIND and keep all
	requisite information within the session state itself.		requisite information within the session state itself.
	2.3.11. Translated Session parameters		3.3.11. Translated Session parameters
	These parameters identify the session level parameters as		These parameters identify the session level parameters as
	the first packet of session is translated. These parameters		the first packet of session is translated. These parameters
	are derived from the BIND ID(s) off which this session hangs.		are derived from the BIND ID(s) off which this session hangs.
	2.3.12. Second Bind IDentifier		3.3.12. Second Bind IDentifier
	This is of relevance only to Twice-NAT. For all other flavors		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		of NAT, this parameter may be set to zero. In the case of
	Twice-NAT, the Primary Bind Identifier refers to the binding		Twice-NAT, the Primary Bind Identifier refers to the binding
	of source address and the Second Bind Identifier refers to		of source address and the Second Bind Identifier refers to
	the binding of the destination address(of the first packet).		the binding of the destination address(of the first packet).
	2.3.13. Packet modifier functions		3.3.13. Packet modifier functions
	Typically, NAT modifies IP header and sometimes the transport		Typically, NAT modifies IP header and sometimes the transport
	header. External agents may choose to assume responsibility		header. External agents may choose to assume responsibility
	for payload modification alone, or the entire packet		for payload modification alone, or the entire packet
	modification. In the case an external agent assumes		modification. In the case an external agent assumes
	responsibility for the entire packet modification, NAT will		responsibility for the entire packet modification, NAT will
	simply redirect the original packet as is to external		simply redirect the original packet as is to external
	translation agent. Otherwise, NAT will perform its share of		translation agent. Otherwise, NAT will perform its share of
	translation (i.e., IP and transport header translation) and		translation (i.e., IP and transport header translation) and
	direct the translated packet to external agent.		direct the translated packet to external agent.
	3. External agents interfacing with NAT		4. External agents interfacing with NAT
	Many network applications assume the IP address of their host to be		Many network applications assume the IP address of their host to be
	host Identifier and embed the Identifier information in application		host Identifier and embed the Identifier information in application
	specific payload. When packets from such an application traverse		specific payload. When packets from such an application traverse
	NAT, the IP address of private host remains uncorrected in the		NAT, the IP address of private host remains uncorrected in the
	payload, as the packet is delivered to hosts in external realm. An		payload, as the packet is delivered to hosts in external realm. An
	Application Level Gateway (ALG) is required to re-interpret such a		Application Level Gateway (ALG) is required to re-interpret such a
	payload as the payload traverses realms.		payload as the payload traverses realms.
	In addition, there are applications such as H.323 that use		In addition, there are applications such as H.323 that use
	skipping to change at page 10, line 12 ¶		skipping to change at page 11, line 4 ¶
	for configuration and monitor purposes and to enforce NAT policies.		for configuration and monitor purposes and to enforce NAT policies.
	For example, reconfigure a NAT device to switch over from NAPT to		For example, reconfigure a NAT device to switch over from NAPT to
	Basic-NAT configuration or vice versa. Or, add, terminate and		Basic-NAT configuration or vice versa. Or, add, terminate and
	monitor ALGs and other external agents on a NAT box. Such a program		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		would also be useful to notify NAT about the status and setup
	information concerning ALGs, backup NATs and RSIP clients.		information concerning ALGs, backup NATs and RSIP clients.
	Clearly, agents such as RSIP clients and Backup-NATs are likely		Clearly, agents such as RSIP clients and Backup-NATs are likely
	to reside on a different physical device than the NAT device. Some		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		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		presented in the follow-on section will form a basis for the
	requirements for the development of one or more protocols by which		development of a MIDCOM protocol.
	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		The following diagram identifies a selected list of external agents
	that might interact with NAT via an API or an yet to be devised		that might interact with NAT via an API or an yet to be devised
	protocol.		protocol.
	+--------------+ +------+ +-------------+ +------------------+		+--------------+ +------+ +-------------+ +------------------+
	| RSIP Clients | | ALGs | | Pri/Sec NAT | | Management Appl. |		| RSIP Clients | | ALGs | | Pri/Sec NAT | | Management Appl. |
	+--------------+ +------+ +-------------+ +------------------+		+--------------+ +------+ +-------------+ +------------------+
	^ ^ ^ ^		^ ^ ^ ^
	| | | |		| | | |
	| | | |		| | | |
	v v v v		v v v v
	+----------------------------------------+		+----------------------------------------+
	| External Agent API |		| Middlebox Communication (MIDCOM) API |
	+----------------------------------------+		+----------------------------------------+
	| NAT Service |		| NAT Service |
	|(Resource management, Packet translation|		|(Resource management, Packet translation|
	| and External agent interface) |		| and External agent interface) |
	+----------------------------------------+		+----------------------------------------+
	| NAT managed resources |		| NAT managed resources |
	| (sessions, BINDs, Address maps etc.) |		| (sessions, BINDs, Address maps etc.) |
	+----------------------------------------+		+----------------------------------------+
	figure 1. External agents interfacing with NAT		Figure 1. External agents interfacing with NAT Middlebox
	The following attributes uniquely identify an external agent		The following attributes uniquely identify an external agent
	to NAT device. Items 3.1 through 3.4 are service independent,		to a middlebox. Items 4.1 through 4.4 are service
	and the remaining items are NAT specific.		independent, while the remaining items are NAT specific.
	3.1. Agent IDentifier
	A number (say, in the range of 1 through 0xFFFFFFFF) assigned		4.1. Agent IDentifier
	to the agent by the controlling device to distinguish from
	other agents. Typically, this handle may be assigned when the
	agent registers with the device.
	3.2. Agent type		A unique number (say, in the range of 1 through 0xFFFFFFFF)
			assigned to the agent by middlebox so as to distinguish from
			other agents. Typically, this ID is issued during the agent
			registration with middlebox.
	Based on the categories of external agents described thus far,		4.2. Agent type
	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		The Agent type can be one of ALG or RSIP-Client or Backup-NAT
			or Management-Application or something else. The agent type
			may be a criterion used by middlebox to accept or deny
			registration.
			4.3. Agent accessibility information
	When an agent is resident on a different physical device than		When an agent is resident on a different physical device than
	the controlling device, this parameter specifies means by		middlebox, this parameter specifies means by which the
	which the controlling device can access the agent. This can		middlebox can access the agent. This can be a combination of
	be a combination of Agent's IP address, IP protocol (e.g.,		Agent's IP address, IP protocol (e.g., TCP or UDP),
	TCP or UDP), well-known port etc. A value of 0 for		well-known port etc. A value of 0 for agent's IP address
	agent's IP address indicates that the agent is co-resident		indicates that the agent is co-resident with middlebox.
	with the controlling device.
	3.4. Periodic Notification interval		4.4. Periodic Notification interval
	This parameter would be required only when the agent calls		This parameter would be required only when the agent calls
	for periodic notification from the device. This may be		for periodic notification from the middlebox. This may be
	specified in units of seconds.		specified in units of seconds.
	3.5. Agent call-back requirements		4.5. Agent call-back requirements
	An agent will typically require the device to invoke a		An agent will typically require the middlebox to invoke a
	call-back function supplied by the agent upon the occurrence		call-back function supplied by the agent upon the occurrence
	of specific events. Events for which an agent needs		of specific events. Events for which an agent needs
	notification depends on agent type.		notification depends on agent type.
	An ALG will require NAT to call back when a data packet is		An ALG will require NAT to call back when a data packet is
	received on a session with a certain application-tag (say,		received on a session with a certain application-tag (say,
	FTP). Management applications and Backup-NAT might require		FTP). Management applications and Backup-NAT might require
	NAT to periodically invoke a call-back function. Events all		NAT to periodically invoke a call-back function. Events all
	agents might require to be notified of (through		agents might require to be notified of (through
	a call-back function) would be - session termination,		a call-back function) would be - session termination,
	service termination and BIND termination.		service termination and BIND termination.
	3.6. Agent call-back functions		4.6. Agent call-back functions
	Depending upon call-back requirements, the agent will be		Depending upon call-back requirements, the agent will be
	required to register one or more call-back function entry		required to register one or more call-back function entry
	points with the device. Below are three different call-back		points with the middlebox. Below are three different call-back
	function prototypes.		function prototypes.
	Event notification - void agent_callback_event(service_id,		Event notification - void agent_callback_event(service_id,
	agent_id, event, event_info)		agent_id, event, event_info)
	Periodic notification - void agent_callback_periodic(service_id,		Periodic notification - void agent_callback_periodic(service_id,
	agent_id, info_type, info_length,		agent_id, info_type, info_length,
	information)		information)
	Packet notification - void agent_callback_packet(service_id,		Packet notification - void agent_callback_packet(service_id,
	agent_id, sess_id,		agent_id, sess_id,
	pkt_direction, packet)		pkt_direction, packet)
	3.7. RSIP Server tunnel type requirement		4.7. RSIP Server tunnel type requirement
	An RSIP client may have a requirement for NAT, acting as		An RSIP client may have a requirement for NAT, acting as
	RSIP server to support a certain type of tunneling. In		RSIP server to support a certain type of tunneling. In
	such a case, the agent will specify the tunneling		such a case, the agent will specify the tunneling
	requirement through this parameter.		requirement through this parameter.
	4. External Agent Programming Interface		5. External Agent Programming Interface
	A resource control mechanism by which external agents could		A resource control mechanism by which external agents could
	interface with a NAT device is illustrated in this section		interface with a NAT device is illustrated in this section
	through an Application Programming Interface (API) in pseudo		through an Application Programming Interface (API) in pseudo
	C language. The API is by no means exhaustive in coverage.		C language. The API is by no means exhaustive in coverage.
	This section is divided into two sub-sections. The first		This section is divided into three sub-sections. The first
	sub-section lists function calls available to external agents.		two sub-sections list function calls that may be made
	These calls are synchronous and require the networking device		available to external agents. These calls are synchronous
	to return back a value. The second sub-section lists functions		and require the middlebox to return back a value. Functions
	required to be provided by external agents in order for the		in the first sub-section are service independent and are
	NAT device to call-back upon some events.		prefixed with "middlebox_", whereas functions in the second
			subsection are NAT service specific and are prefixed with
			"nat_". The third sub-section lists functions required to
			be provided by external agents in order for the middlebox
			to call-back upon some events.
	4.1. API functions available to an external agent		5.1. Service-independent middlebox API functions
	Functions 4.1.1 through 4.1.6 below are service independent and		The following functions in a middlebox may be made available to
	are prefixed with "service_". Remaining functions are NAT service		external agents needing to interface with NAT. However, these
	specific and are prefixed with "nat_".		functions are not NAT specific and may be equally applicable to
			middleboxes supporting other types of services such as firewall.
			As such, all functions in this subsection are prefixed with
			"middlebox_" to highlight the service-neutral nature of these
			APIs.
	4.1.1. int service_enquire_IDentity(service_type, **service_info)		The functions listed may be broadly divided into three
			categories - Service-Query functions, Agent-Registration
			functions and Session management functions. Session Identifiers
			are used as the basis for middelbox resource interface. While
			Session Identifier is service-neutral, some of the resources
			associated with a session-id can be service specific.
			5.1.1. int middlebox_query_IDentity(service_type, **service_info)
	Purpose:		Purpose:
	This function is used by external agents to obtain NAT-ID		This function is used to obtain the services and
	and its characteristics, as described in section 2.1		the individual characteristics of the services supported on
			a middlebox. Characteristics of a NAT service are described
			in section 3.1
	Input parameters:		Input parameters:
	service_type - This parameter is filled to verify if		service_type - This parameter is filled to verify if the
	the device supports a certain service type		middlebox supports a certain service type
	(Refer section 2.1.2). A value of 0 requires		(Refer section 3.1.2). A value of 0 may be used
	the device to report all service types supported.		to request the middlebox to report all service
			types supported.
	Output Parameters:		Output Parameters:
	service_info - The device will fill up a descriptor block with		service_info - Middlebox will fill up a descriptor block with
	it characteristics (refer section 2.1) for the		all the characteristics for the matching
	matching service_type and return pointer to the		service_type (refer section 3.1 for NAT
			characteristics) and return pointer to the
	descriptor block. The descriptor block would		descriptor block. The descriptor block would
	specifically include a service identifier (refer		specifically include a service identifier (refer
	section 2.1.1) that uniquely identifies service		section 3.1.1) that uniquely identifies service
	instance. This is referred as service_id throughout		instance. This is referred as service_id
	the document.		throughout the document.
	Multiple pieces of this information may be returned,		Multiple pieces of this information may be returned,
	if the device supports multiple instances of the		if the middlebox supports multiple instances of the
	same service type. Multiple instances of descriptor		same service type. Multiple instances of descriptor
	blocks may also be returned when service_type is set		blocks may also be returned when service_type is set
	to 0 and the device supports multiple service types.		to 0 and the middlebox supports multiple service
			types.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies success		No-Error(0) - Function processing successful.
	and that service_info may be examined		Service_info may be examined
	for service description.		for service description.
	SERVICE-TYPE-NOT-SUPPORTED - Notify the agent that the		SERVICE-TYPE-NOT-SUPPORTED - Middlebox does not support the
	device does not support the requested		requested service type.
	service type.
	4.1.2. int service_register_agent (service_id, &agent_info)		5.1.2. int middlebox_register_agent (service_id, &agent_info)
	Purpose:		Purpose:
	This function is used by external agents to register with the		This function is used by external agents to register with the
	device.		middlebox.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the service		service_id - The identifier that uniquely identifies a specific
	instance (ex: NAT instance).		service instance on a middlebox.
	agent_info - The agent is required to provide all the requisite		agent_info - The agent is required to provide all the requisite
	information (with the exception of agent_id) as		information (with the exception of agent_id) as
	described in section 3.0. This ID may be used by		described in section 4.0. This ID may be used by
	the caller to influence NAT operation.		the caller to influence middlebox operation.
	Output Parameters:		Output Parameters:
	agent_info - NAT will set agent_id in agent_info structure		agent_info - NAT will set agent_id in agent_info structure
	when registration is successful.		when registration is successful.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - Registration successful.
	registration.
	AGENT-TYPE-NOT-SUPPORTED - Notify the caller that NAT does not		AGENT-TYPE-NOT-SUPPORTED - Notify the caller that middlebox does
	support API requirements of the agent.		not support API requirements of the
			agent.
	TUNNEL-TYPE-NOT-SUPPORTED - Notify caller that NAT does not		TUNNEL-TYPE-NOT-SUPPORTED - Notify caller that middlebox does not
	support the RSIP tunnel type		support the RSIP tunnel type
	requested.		requested.
	INVALID-SERVICE-ID - The specified service_id is not		INVALID-SERVICE-ID - The specified service_id is not
	operational or is incorrect.		operational or is incorrect.
	4.1.3. int service_enquire_sess_range(service_id, agent_id, sessid_min,		AGENT-NOT-AUTHORIZED - The specified agent is not authorized
			to register with the middlebox.
			5.1.3. int middlebox_unregister_agent (service_id, agent_id)
			Purpose:
			This function is used by external agents to unregister with the
			middlebox.
			Input parameters:
			service_id - The identifier that uniquely identifies a specific
			service instance on a middlebox.
			agent_id - The agent Identifier that uniquely identifies the
			agent to middlebox.
			Output Parameters:
			None.
			Return Value:
			No-Error(0) - Successful unregistration.
			AGENT-ID-NOT-SUPPORTED - Agent ID unknown to middlebox.
			INVALID-SERVICE-ID - The specified service_id is not
			operational or is incorrect.
			5.1.4. int middlebox_query_sess_range(service_id, agent_id, sessid_min,
	sessid_max, &sess_count, &sess_info)		sessid_max, &sess_count, &sess_info)
	Purpose:		Purpose:
	This function is used by external agents to request NAT to		This function is used to request a middlebox to send valid
	send valid session information for all sessions with an ID		session information for all sessions with an ID in the range
	in the range of sessid_min through sessid_max. As a special		of sessid_min through sessid_max. As a special case, this will
	case, this will return session descriptor block for a		return session descriptor block for a single session when
	single session when sessid_min and sessid_max are the same.		sessid_min and sessid_max are the same.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to middlebox.
	sessid_min, sessid_max - The range of session IDs that the		sessid_min, sessid_max - The range of session IDs that the
	agent is interested in knowing about.		agent is interested in knowing about.
	Output Parameters:		Output Parameters:
	sess_count - Number of sessions being returned through		sess_count - Number of sessions being returned through
	sess_info pointer.		sess_info pointer.
	sess_info - Return one or more sessions with an ID in the		sess_info - Return one or more sessions with an ID in the
	given range.		given range.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - Session termination successful.
	session termination.
	INVALID-SERVICE-ID- The specified service_id is not operational		INVALID-SERVICE-ID- The specified service_id is not operational
	or is incorrect.		or is incorrect.
	INVALID-AGENT-ID - The specified Agent_ID is not currently		INVALID-AGENT-ID - The specified Agent_ID is not currently
	registered with NAT.		registered with the middlebox.
	4.1.4. int service_set_sess(service_id, agent_id, &sess_info)		5.1.5. int middlebox_set_sess(service_id, agent_id, &sess_info)
	Purpose:		Purpose:
	This function is used by external agents to create a new session		This function is used to create a new session state on a middlebox
	state or set certain parameters of an existing session.		or to set parameters of an existing session.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to middlebox.
	sess_info - The caller supplies the specifics of a new session		sess_info - The caller supplies the specifics of a new session
	parameters or sets a selected number of parameters		parameters or sets a selected number of parameters
	of an existing session to influence NAT operation.		of an existing session to influence NAT operation.
	A new session request is made by setting the		A new session request is made by setting the
	session-ID within sess_info structure to 0. A		session-ID within sess_info structure to 0. A
	non-Zero session-ID would be interpreted by NAT to		non-Zero session-ID would be interpreted by NAT to
	mean that the agent is attempting to set some		mean that the agent is attempting to set some
	session specific parameters.		session specific parameters.
	Output Parameters:		Output Parameters:
	sess_info - If the caller requested for a session creation and		sess_info - If the caller requested for a session creation and
	NAT was successful in creating a new session, NAT		NAT was successful in creating a new session, NAT
	will fill the structure with the assigned session-ID		will fill the structure with the assigned session-ID
	and any other NAT assigned parameter values. If the		and any other NAT assigned parameter values. If the
	caller requested to set some session parameters and		caller requested to set some session parameters and
	NAT succeeded in doing so, the sess_info would		NAT succeeded in doing so, the sess_info would
	be filled with the values that NAT holds.		be filled with the values that NAT holds.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - Successful session creation or parameter
	session creation or parameter setting.		setting.
	SESS-MAKE-FAILED - When NAT was unable to create session		SESS-MAKE-FAILED - When middlebox was unable to create session
	or was unable to set the requested		state or was unable to set the requested
	parameter(s).		parameter(s).
	INVALID-SESS-INFO - When NAT finds that one or all of the		INVALID-SESS-INFO - When NAT finds that one or all of the
	parameters specified is not valid.		parameters specified is not valid.
	INVALID-SERVICE-ID- The specified service_id is not operational		INVALID-SERVICE-ID- The specified service_id is not operational
	or is incorrect.		or is incorrect.
	INVALID-AGENT-ID - The specified Agent_id is not currently		INVALID-AGENT-ID - The specified Agent_id is not currently
	registered with the device.		registered with the middlebox.
	4.1.5. int service_free_sess(service_id, agent_id, sess_id)		5.1.6. int middlebox_free_sess(service_id, agent_id, sess_id)
	Purpose:		Purpose:
	This function is used by external agents to terminate		This function is used to terminate a session on middlebox.
	the specified session.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to NAT.
	sess_id - The ID of the session that needs to be terminated.		sess_id - The ID of the session that needs to be terminated.
	Output Parameters:		Output Parameters:
	none.		none.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - A return value of 0 implies successful
	session termination.		session termination.
	INVALID-SESS-ID - The specified session ID does not exist.		INVALID-SESS-ID - The specified session ID does not exist.
	INVALID-SERVICE-ID- The specified service_id is not operational		INVALID-SERVICE-ID- The specified service_id is not operational
			or is incorrect.
	or is incorrect.
	INVALID-AGENT-ID - The specified Agent_id is not currently		INVALID-AGENT-ID - The specified Agent_id is not currently
	registered with the device.		registered with the middlebox.
	4.1.6. int service_free_sess_bundle(service_id, agent_id, bundle_id)		5.1.7. int middlebox_free_sess_bundle(service_id, agent_id, bundle_id)
	Purpose:		Purpose:
	This function is used by external agents to terminate		This function is used to terminate a bundle of sessions,
	a bundle of sessions identified by the same bundle ID.		identified by the same bundle ID.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to middlebox.
	bundle_id - The ID of the session bundle (group of sessions)		bundle_id - The ID of the session bundle (group of sessions)
	that needs to be terminated.		that needs to be terminated.
	Output Parameters:		Output Parameters:
	none.		none.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - Successful session termination.
	session termination.
	INVALID-BUNDLE-ID - The specified bundle ID does not exist.		INVALID-BUNDLE-ID - The specified bundle ID does not exist.
	INVALID-SERVICE-ID - The specified service_id is not operational		INVALID-SERVICE-ID - The specified service_id is not operational
	or is incorrect.		or is incorrect.
	INVALID-AGENT-ID - The specified Agent_id is not currently		INVALID-AGENT-ID - The specified Agent_id is not currently
	registered with the device.		registered with the middlebox.
	4.1.7. int nat_enquire_address_bind (service_id, pvt_address,		5.2. NAT specific API functions
			The following functions in a middlebox may be made available to
			external agents needing to interface with NAT. These functions
			are necessary to manipulate NAT specific resources such as NAT
			address Binds, Address Maps and session parameters. NAT specific
			session parameters include translated session tuples, Bind ID
			and Packet modification functions. As such, all functions in
			this subsection are prefixed with "nat_" to highlight NAT
			specific nature of these APIs.
			5.2.1. int nat_query_address_bind (service_id, pvt_address,
	ext_address, &bind_info)		ext_address, &bind_info)
	Purpose:		Purpose:
	This function is used by external agents to obtain		This function is used by external agents to obtain
	Address BIND information.		Address BIND information.
	Input parameters:		Input parameters:
	service_id - This uniquely identifies the NAT instance.		service_id - This uniquely identifies the NAT instance.
	pvt_address, ext_address - The caller might specify both or just		pvt_address, ext_address - The caller might specify both or just
	one of either private address or external address and		one of either private address or external address and
	set the other to zero.		set the other to zero.
	Output Parameters:		Output Parameters:
	bind_info - NAT will fill up the bind_info data structure		bind_info - NAT will fill up the bind_info data structure
	with info as described in section 2.2, if NAT were		with info as described in section 2.2, if NAT were
	to find a match for the addresses specified.		to find a match for the addresses specified.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies success		No-Error(0) - Successful in finding a match.
	in finding a match.
	NO-MATCHING_BIND - Notify the client that there isn't a BIND		NO-MATCHING_BIND - Notify the client that there isn't a BIND
	matching the specified addresses.		matching the specified addresses.
	INVALID-SERVICE-ID - The specified service_id is not operational		INVALID-SERVICE-ID - The specified service_id is not operational
	or is incorrect.		or is incorrect.
	4.1.8. int nat_enquire_transport_bind(service_id, pvt_address, pvt_port,		5.2.2. int nat_query_transport_bind(service_id, pvt_address, pvt_port,
	transport_protocol, ext_address, ext_port, &bind_info)		transport_protocol, ext_address, ext_port, &bind_info)
	Purpose:		Purpose:
	This function is used by external agents to obtain		This function is used by external agents to obtain
	Transport ID BIND information.		Transport ID BIND information.
	Input parameters:		Input parameters:
	service_id - This uniquely identifies the NAT instance.		service_id - The identifier that uniquely identifies a specific
			service instance on a middlebox.
	pvt_address, pvt_port,		pvt_address, pvt_port,
	ext_address, ext_port - The caller might specify both or just		ext_address, ext_port - The caller might specify both or just
	one of either (private address and the port no.) or		one of either (private address and the port no.) or
	external address and the port number.		external address and the port number.
	transport_protocol - This must be one of TCP, UDP or ICMP Query		transport_protocol - This must be one of TCP, UDP or ICMP Query
	Output Parameters:		Output Parameters:
	bind_info - NAT will fill up the bind_info data structure		bind_info - NAT will fill up the bind_info data structure
	with info as described in section 2.2, if NAT were		with info as described in section 2.2, if NAT were
	to find a match for the addresses specified.		to find a match for the addresses specified.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies success		No-Error(0) - A return value of 0 implies success
	in finding a match.		in finding a match.
	NO-MATCHING_BIND - Notify the client that there isn't a BIND		NO-MATCHING_BIND - Notify the client that there isn't a BIND
	matching the specified addresses.		matching the specified addresses.
	INVALID-SERVICE-ID- The specified service_id is not operational		INVALID-SERVICE-ID- The specified service_id is not operational
	or is incorrect.		or is incorrect.
	4.1.9. int nat_set_bind (service_id, agent_id, &bind_info)		5.2.3. int nat_set_bind (service_id, agent_id, &bind_info)
	Purpose:		Purpose:
	This function is used by external agents to create a new Address		This function is used to create a new Address Bind or set
	Bind or set certain parameters of an existing Bind.		parameters of an existing Bind.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies the NAT
	instance.		instance.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to NAT.
	bind_info - The caller supplies the specifics of a new BIND or		bind_info - The caller supplies the specifics of a new BIND or
	sets a selected number of parameters of an existing		sets a selected number of parameters of an existing
	BIND to influence NAT operation. The BIND can be		BIND to influence NAT operation. The BIND can be
	an address BIND or transport BIND. A new BIND		an address BIND or transport BIND. A new BIND
	request is made by setting the BIND ID within		request is made by setting the BIND ID within
	bind_info structure to 0. A non-Zero Bind-ID would		bind_info structure to 0. A non-Zero Bind-ID would
	be interpreted by NAT to mean that the agent is		be interpreted by NAT to mean that the agent is
	attempting to set some BIND parameters.		attempting to set some BIND parameters.
	Output Parameters:		Output Parameters:
	bind_info - If the caller requested for a BIND creation and NAT		bind_info - If the caller requested for a BIND creation and NAT
	was successful in creating a new BIND, NAT will		was successful in creating a new BIND, NAT will
	fill the structure with the assigned BIND ID and		fill the structure with the assigned BIND ID and
	any other NAT assigned parameter values. If the		any other NAT assigned parameter values. If the
	caller requested to set some BIND parameters and		caller requested to set some BIND parameters and
	NAT succeeded in doing so, the bind_info would		NAT succeeded in doing so, the bind_info would
	be filled with the values that NAT holds.		be filled with the values that NAT holds.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - Successful BIND creation or parameter setting.
	BIND creation or parameter setting.
	BIND-MAKE-FAILED - When NAT was unable to create BIND		BIND-MAKE-FAILED - NAT was unable to create BIND or was unable
	or was unable to set the requested		to set the requested parameter(s).
	parameter(s).
	INVALID-BIND-INFO - When NAT finds that one or all of the		INVALID-BIND-INFO - One or all of the parameters specified is
	parameters specified is not valid.		not valid.
	INVALID-SERVICE-ID- The specified service_id is not operational		INVALID-SERVICE-ID- The specified service_id is not operational
	or is incorrect.		or is incorrect.
	INVALID-AGENT-ID - The specified Agent_id is not currently		INVALID-AGENT-ID - The specified Agent_id is not currently
	registered with the device.		registered with the middlebox.
	4.1.10. int nat_free_bind(service_id, agent_id, bind_id)		5.2.4. int nat_free_bind(service_id, agent_id, bind_id)
	Purpose:		Purpose:
	This function is used by external agents to terminate		This function is used to terminate the specified BIND and any
	the specified BIND and any sessions that are based on		sessions that are based on this BIND.
	this BIND.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies the NAT
	instance.		instance.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to NAT.
	bind_id - The ID of the BIND that needs to be terminated.		bind_id - The ID of the BIND that needs to be terminated.
	Output Parameters:		Output Parameters:
	none.		none.
	Return Value:		Return Value:
	No-Error(0) - A return value of 0 implies successful		No-Error(0) - Successful BIND termination.
	BIND termination.
	INVALID-BIND-ID - The specified bind_id does not exist.		INVALID-BIND-ID - The specified bind_id does not exist.
	INVALID-SERVICE-ID- The specified service_id is not operational		INVALID-SERVICE-ID- The specified service_id is not operational
	or is incorrect.		or is incorrect.
	INVALID-AGENT-ID - The specified Agent_id is not currently		INVALID-AGENT-ID - The specified Agent_id is not currently
	registered with the device.		registered with the middlebox.
	4.2. Call-back functions within an external agent
			5.3. Call-back functions into an external agent
	The callback functions listed can be the same independent of the		The callback functions listed can be the same independent of the
	NAT service supported on the device or the agent that controls		middlebox function or the agent that interfaces with the middlebox.
	the device. However, the individual parameters supplied will be		Parameters supplied to these functions may however be specific to
	specific to the tuple of (service_type, agent_type).		the tuple of (service_type, agent_type). The asynchronous callback
			functions may be used to redirect packets to MIDCOM agents (or) to
			notify a MIDCOM agent of significant events such as BIND creations
			or to notify MIDCOM agent of periodic statistical data.
	4.2.1. void agent_callback_event(service_id, agent_id, event_type,		5.3.1. void agent_callback_event(service_id, agent_id, event_type,
	&event_info)		&event_info)
	Purpose:		Purpose:
	This function is used by the device to notify an agent of an		This function is invoked by the middlebox to notify an agent
	event status.		of an event status.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to the device.		agent to the middlebox.
	event_type - The event can be one of session Creation, session		event_type - The event can be one of session Creation, session
	termination, BIND creation or BIND termination		termination, BIND creation or BIND termination
	for a NAT device.		for a NAT middlebox.
	event_info - This will return the BIND or session description		event_info - This will return the BIND or session description
	structure that contains the specific instance		structure that contains the specific instance
	identifier and other pertinent information.		identifier and other pertinent information.
	4.2.2. void agent_callback_periodic(service_id, agent_id, info_type,		5.3.2. void agent_callback_periodic(service_id, agent_id, info_type,
	info_length, &periodic_info)		info_length, &periodic_info)
	Purpose:		Purpose:
	This function is used by the device to notify an agent of a		This function is used by the middlebox to notify an agent of a
	certain piece of information periodically.		certain piece of information periodically.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to the middlebox.
	info_type - NAT may have been requested to periodically		info_type - Middlebox may have been requested to periodically
	notify the agent many types of information.		notify the agent many types of information.
	Possible values for this parameter would be		Possible values for this parameter would be
	statistics update, Incremental BIND update		statistics update, Incremental BIND update
	Incremental session update, Incremental		Incremental session update, Incremental
	BIND termination, Incremental session		BIND termination, Incremental session
	termination etc..		termination etc..
	info_length- Number of bytes included in periodic info block.		info_length- Number of bytes included in periodic info block.
	periodic_info - This point to the actual periodic information		periodic_info - This point to the actual periodic information
	being sent to the agent.		being sent to the agent.
	4.2.3. void agent_callback_packet(service_id, agent_id, sess_id,		5.3.3. void agent_callback_packet(service_id, agent_id, sess_id,
	pkt_direction, packet)		pkt_direction, packet)
	Purpose:		Purpose:
	This function is used by the device to notify an agent of a		This function is used by the middlebox to notify an agent of a
	data packet for processing. The agent is expected to		data packet for processing. The agent is expected to
	process the packet and forward to the actual destination		process the packet and forward to the actual destination
	in the first-in-first-out (FIFO) order. The processing		in the first-in-first-out (FIFO) order. The processing
	performed by the agent may be limited to just the payload		performed by the agent may be limited to just the payload
	or the entire packet, as set by the agent at session		or the entire packet, as set by the agent at session
	setup time.		setup time.
	Input parameters:		Input parameters:
	service_id - The identifier that uniquely identifies the NAT		service_id - The identifier that uniquely identifies a specific
	instance.		service instance on a middlebox.
	agent_id - The agent Identifier that uniquely identifies the		agent_id - The agent Identifier that uniquely identifies the
	agent to NAT.		agent to the middlebox.
	sess_id - The Identifier if NAT session to which the packet		sess_id - The Identifier of session to which the packet
	belongs.		belongs.
	pkt_direction - This can be inbound or outbound.		pkt_direction - This can be inbound or outbound.
	packet - IP packet that needs to be processed by the agent.		packet - IP packet that needs to be processed by the agent.
	If NAT was required to perform header translation,		If NAT was required to perform header translation,
	this packet is post-NAT-translated version of		this packet is post-NAT-translated version of
	the packet. In the case the agent selected to		the packet. In the case the agent selected to
	perform the entire translation, the original		perform the entire translation, the original
	packet is sent as is to the agent, without any		packet is sent as is to the agent, without any
	NAT transformation.		NAT transformation.
	5. An illustration of the use of NAT Resource Control Mechanism		6. An illustration of the use of NAT Resource Control Mechanism
	The following is an illustration of how an ALG for FTP application		The following is an illustration of how an ALG for FTP application
	([Ref 7]) could use the API specified to interface with NAT to		([Ref 7]) could use the API specified to interface with NAT to
	provide application level transparency. This is not meant to be a		provide application level transparency. This is not meant to be a
	detailed description of how an FTP-ALG would work. But, rather an		detailed description of how an FTP-ALG would work. But, rather an
	illustration of how an ALG could use the interface with NAT to		illustration of how an ALG could use the interface with NAT to
	accomplish the desired application transparency. The section is		accomplish the desired application transparency. The section is
	divided into three sub-sections to illustrate (a) ALG		divided into three sub-sections to illustrate (a) ALG
	registration with NAT, (b) NAT interface with ALG while an FTP		registration with NAT, (b) NAT interface with ALG while an FTP
	session is active, and (c) Notification to ALG when the FTP		session is active, and (c) Notification to ALG when the FTP
	session terminates.		session terminates.
	5.1. FTP-ALG registration with NAT		6.1. FTP-ALG registration with NAT
	FTP-ALG will first probe NAT device to understand the type of		FTP-ALG will first probe NAT middlebox to understand the type of
	service provided by NAT and obtain NAT-ID. Once the service		service provided by NAT and obtain NAT-ID. Once the service
	type is agreeable, the ALG will register itself as a client		type is agreeable, the ALG will register itself as a client
	with the NAT device with callback functions (as described		with the NAT middlebox with callback functions (as described
	below) and obtain an agent-ID from the NAT. The tuple of		below) and obtain an agent-ID from the NAT. The tuple of
	(service_id, agent_id) uniquely identifies the interface		(service_id, agent_id) uniquely identifies the interface
	between NAT and ALG.		between NAT and ALG.
	ftp_alg_pkt_notify() will be registered to process FTP		ftp_alg_pkt_notify() will be registered to process FTP
	session (TCP port 21) traffic. ftp_alg_event_notify() will		session (TCP port 21) traffic. ftp_alg_event_notify() will
	be registered to process session or NAT termination.		be registered to process session or NAT termination.
	FTP-ALG NAT		FTP-ALG NAT
	------- ---		------- ---
	1. Obtain NAT descriptor Info		1. Obtain NAT descriptor Info
	service_enquire_IDentity(		middlebox_query_IDentity(
	0, **nat_descriptor)		0, **nat_descriptor)
	------------------------>		------------------------>
	NAT will fill a descriptor		NAT will fill a descriptor
	block with pertinent information,		block with pertinent information,
	specifically NAT-type and nat_ID		specifically NAT-type and nat_ID
	and supply the pointer to the		and supply the pointer to the
	descriptor block.		descriptor block.
	OK		OK
	<------------------------------		<------------------------------
	2. Register with NAT as ALG for		2. Register with NAT as ALG for
	FTP (TCP port 21) and obtain		FTP (TCP port 21) and obtain
	agent_ID from the NAT.		agent_ID from the NAT.
	service_register_agent(nat_id,		middlebox_register_agent(nat_id,
	&ftp_alg_info)		&ftp_alg_info)
	------------------------>		------------------------>
	NAT will assign an agent_ID.		NAT will assign an agent_ID.
	OK		OK
	<------------------------------		<------------------------------
	5.2. NAT interface with the ALG during FTP session operation		6.2. NAT interface with the ALG during FTP session operation
	When NAT sees the first packet of an FTP session, it sets up		When NAT sees the first packet of an FTP session, it sets up
	a BIND descriptor and a session descriptor and tags the		a BIND descriptor and a session descriptor and tags the
	session descriptor as FTP-Type (i.e., TCP port 21). NAT		session descriptor as FTP-Type (i.e., TCP port 21). NAT
	will then redirect the packet to FTP-ALG by invoking the		will then redirect the packet to FTP-ALG by invoking the
	ALG supplied callback function - ftp_alg_pkt_notify().		ALG supplied callback function - ftp_alg_pkt_notify().
	The ALG will obtain session descriptor and BIND descriptor		The ALG will obtain session descriptor and BIND descriptor
	info from the NAT.		info from the NAT.
	Subsequent to this, when NAT redirects FTP packets, the		Subsequent to this, when NAT redirects FTP packets, the
	ALG would parse the payload for PORT command or response to		ALG would parse the payload for PORT command or response to
	"PASV" to determine ensuing data sessions and interact with		"PASV" to determine ensuing data sessions and interact with
	NAT, as necessary, to obtain the requisite translation		NAT, as necessary, to obtain the requisite translation
	parameters. The ALG may modify the FTP packet with		parameters. The ALG may modify the FTP packet with
	translation parameters prior to resending to NAT for		translation parameters prior to resending to NAT for
	forwarding.		forwarding.
	FTP-ALG NAT		FTP-ALG NAT
	------- ---		------- ---
	1. NAT sees the first packet		1. NAT sees the first packet
	of an FTP session. NAT will		of an FTP session. NAT will
	set up a session state and		set up a session state and
	notify the agent as follows.		notify the agent as follows.
	ftp_alg_pkt-notify(nat_id,		ftp_alg_pkt_notify(nat_id,
	agent_ID, sess_ID,		agent_ID, sess_ID,
	packet_direction, pkt)		packet_direction, pkt)
	<------------------------		<------------------------
	The ALG may optionally make		The ALG may optionally make
	calls to the NAT to find out		calls to the NAT to find out
	about the session and BIND		about the session and BIND
	characteristics of the FTP.		characteristics of the FTP.
	Further, additional calls may		Further, additional calls may
	be made to change the control		be made to change the control
	parameters in these blocks.		parameters in these blocks.
	service_enquire_sess_range(		middlebox_query_sess_range(
	nat_id, agent_id,		nat_id, agent_id,
	sess_id, sess_id,		sess_id, sess_id,
	&sess_count, **sess_info)		&sess_count, **sess_info)
	------------------------------>		------------------------------>
	Find the session descriptor		Find the session descriptor
	block matching sess_id and		block matching sess_id and
	return Pointer to this. Bind_id		return Pointer to this. Bind_id
	is one of the items in the block.		is one of the items in the block.
	OK		OK
	<------------------------------		<------------------------------
	...		...
	nat_enquire_address_bind(		nat_query_address_bind(
	nat_id, pvt_address,		nat_id, pvt_address,
	external_address, &bind_info)		external_address, &bind_info)
	------------------------------>		------------------------------>
	...		...
	nat_set_bind(		nat_set_bind(
	nat_id, agent_id, &bind_info)		nat_id, agent_id, &bind_info)
	------------------------------>		------------------------------>
	.............		.............
	n. NAT will forward all		n. NAT will forward all
	subsequent FTP packets to		subsequent FTP packets to
	the agent as follows.		the agent as follows.
	ftp_alg_pkt-notify(nat_id,		ftp_alg_pkt_notify(nat_id,
	agent_ID, sess_ID,		agent_ID, sess_ID,
	packet_direction, pkt)		packet_direction, pkt)
	<------------------------		<------------------------
	The ALG will parse for PORT		The ALG will parse for PORT
	command and PASV response in		command and PASV response in
	the payload and track any deltas		the payload and track any deltas
	to TCP sequence and acknowledge		to TCP sequence and acknowledge
	numbers. The ALG will interact		numbers. The ALG will interact
	with NAT, as necessary, to obtain		with NAT, as necessary, to obtain
	skipping to change at page 26, line 25 ¶		skipping to change at page 28, line 22 ¶
	&bind_info)		&bind_info)
	------------------------------>		------------------------------>
	....		....
	Setup a new state for the data		Setup a new state for the data
	session such that the Bundle-ID		session such that the Bundle-ID
	is set to be the session ID of		is set to be the session ID of
	the controlling FTP session.		the controlling FTP session.
	service_set_sess(nat_id, agent_id,		middlebox_set_sess(nat_id, agent_id,
	&sess_info)		&sess_info)
	---------------------------->		---------------------------->
	5.3. Session termination notification		6.3. Session termination notification
	When the FTP control session is ready to be terminated		When the FTP control session is ready to be terminated
	by the NAT, NAT will notify the event to FTP-ALG as follows.		by the NAT, NAT will notify the event to FTP-ALG as follows.
	FTP-ALG NAT		FTP-ALG NAT
	------- ---		------- ---
	1. NAT determines the FTP		1. NAT determines the FTP
	session is to be		session is to be
	terminated.		terminated.
	ftp_alg_notify(nat_id,		ftp_alg_notify(nat_id,
	agent_id,		agent_id,
	SESSION_TERMINATED,		SESSION_TERMINATED,
	sess_ID)		sess_ID)
	<------------------------		<------------------------
	The ALG will in turn clean up any		The ALG will in turn clean up any
	data sessions that may be based on		data sessions that may be based on
	the FTP session prior to freeing		the FTP session prior to freeing
	the control session itself.		the control session itself.
	service_free_sess(nat_id, agent_id,		middlebox_sess_free(nat_id, agent_id,
	sess_id)		sess_id)
	---------------------------->		---------------------------->
	6. Acknowledgement		7. Acknowledgement
	The author would like to thank Yakov Rekhter for his valuable advice		The author would like to thank Yakov Rekhter for his valuable advice
	and contribution in the organization of this document.		and contribution in the organization of this document.
	7. Security considerations.		8. Security considerations.
	The security considerations described in [Ref 1] for all variations		The security considerations described in [Ref 1] for all variations
	of NATs are applicable here. The interface between NAT and external		of NATs are applicable here. There can be security vulnerabilities
	agents must be trusted as the API influences the session operation		to a middlebox, if external agents are allowed to interface with
	on the NAT device.		a NAT middlebox without proper authentication and authorization. It
			is possible that a NAT middlebox may be abruptly disrupted due to
			malicious manipulation of the resource by an agent purporting to
			offer ALG service.
	REFERENCES		REFERENCES
	[1] P. Srisuresh, M. Holdrege, "IP Network Address Translator		[1] P. Srisuresh, M. Holdrege, "IP Network Address Translator
	(NAT) Terminology and Considerations", RFC 2663		(NAT) Terminology and Considerations", RFC 2663
	[2] Y. Rekhter, B. Moskowitz, D. Karrenberg, G. de Groot, and,		[2] Y. Rekhter, B. Moskowitz, D. Karrenberg, G. de Groot, and,
	E. Lear, "Address Allocation for Private Internets", RFC 1918		E. Lear, "Address Allocation for Private Internets", RFC 1918
	[3] J. Reynolds and J. Postel, "Assigned Numbers", RFC 1700		[3] J. Reynolds and J. Postel, "Assigned Numbers", RFC 1700
	skipping to change at page 28, line 17 ¶		skipping to change at page 30, line 17 ¶
	[11] J. Mogul, J. Postel, "Internet Standard Subnetting Procedure",		[11] J. Mogul, J. Postel, "Internet Standard Subnetting Procedure",
	RFC 950		RFC 950
	[12] Brian carpenter, Jon Crowcroft, Yakov Rekhter, "IPv4 Address		[12] Brian carpenter, Jon Crowcroft, Yakov Rekhter, "IPv4 Address
	Behaviour Today", RFC 2101		Behaviour Today", RFC 2101
	Author's Address:		Author's Address:
	Pyda Srisuresh		Pyda Srisuresh
	849 Erie circle		jasmine Networks
	Milpitas, CA 95035		3061 Zanker Road, Suite B.
			San Jose, CA 95134
	U.S.A.		U.S.A.
	Voice: (408) 263-7527		Voice: (408) 895-5032
	EMail: srisuresh@yahoo.com		EMail: srisuresh@yahoo.com
End of changes. 191 change blocks.
	363 lines changed or deleted		448 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/