2007/449 Detangle IPsec NAT Traversal

[Bill Sommerfeld]

I'm sponsoring the following fast-track for Dan McDonald.  Case times
out on 08/09/2007.  Proposed release binding is Patch; it removes a
Project Private interface and introduces several Committed interfaces.


Title:  "detangle" - Elimination of nattymod for IPsec NAT-Traversal, plus
	new public interfaces for NAT-Traversal.

Description:
============

IPsec NAT Traversal (PSARC 2004/042) includes a nattymod STREAMS module
as a Project Private component, which intercepts inbound packets in the
kernel and shuffles them directly to ESP.  This is tightly tied to our
IKE implementation and requires the use of undocumented and private
interfaces to plumb and initialize nattymod.

We have need for a Public interface to allow the use of NAT Traversal
with other key management daemons (see 6558864 and 6481450).

This project proposes to remove nattymod, and in its place add a Committed
interface to permit IPsec key management applications to enable
NAT-Traversal security associations they manage.  The overall reduction in ON
code is approximately 575 lines (not including deleted Makefiles).


Interface Table:
================

Interface	Commitment level	Description
---------	----------------	-----------

UDP_NAT_T_-	Committed		If applied to a UDP/IPv4 socket,
ENDPOINT				outbound packets send via the socket
socket option				will have the 0-SPI inserted and only
       					packets with a 0-SPI will be
					delivered to the socket after it has
					been stripped (per RFC 3948).

					Also, non-0-SPI inbound packets will
					be shuffled off to ESP for processing
					if this socket option is enabled.

PF_KEY *_NATT_	Committed		These will be better documented in
address exten-				the pf_key(7P) man page to show
sions.					how ESP-in-UDP SAs can be managed.

"nat_t_port"	Project Private		Test tool for UDP ports *other* than
ike.config(4)				the specified UDP port 4500.
parameter.
					NOTE:  BOTH sides speaking IKE must
					have matching nat_t_port settings for
					this to work.

"ipsec-nat-t"	Committed		Per IANA.  This should've been done
in /etc/services			with 2004/042.


Documentation diffs:
====================

<Changes to pf_key(7P), udp(7P), ipsec(7P), and ipseckey(1M) will be needed,
and will be produced.>

pf_key(7P) additional text
--------------------------

     The address extensions are represented  with  one  to  three
     letters after the word "address," representing (S)RC, (D)ST,
     (Nl)NAT-T local, (Nr)NAT-T  remote,  (Is)Inner  source,  and
     (Id)Inner destination.

+    Source and destination address extensions reflect outer-header selectors
+    for an IPsec SA.  An SA is inbound or outbound depending on which of
+    the source or destination address is local to the node.  Inner-source
+    and inner-destination selectors represent inner-header selectors for
+    Tunnel Mode SAs.  A Tunnel Mode SA MUST have in its outer-headers either
+    IPPROTO_ENCAP or IPPROTO_IPV6 as its protocol selector, in addition to
+    filled-in Inner-address extensions. 
+
+    NAT-T local and NAT-T remote addresses store local and remote ports
+    used for ESP-in-UDP encapsulation.  A non-zero local NAT-T address
+    extensions represents the local node's external IP address if it is not
+    equivalent to the SA's local address.  A non-zero remote NAT-T address
+    represents a peer's behind-a-NAT address if it is not equivalent to the
+    SA's remote address.  An SA with NAT-T extensions will be able to
+    protect-and-transmit outbound traffic.  Processing of inbound NAT-T
+    traffic requires a UDP socket bound to the appropriate local port and it
+    MUST have the UDP_NAT_T_ENDPOINT (see udp(7P)) socket option enabled.
+
     Note that when an error occurs,  only  the  base  header  is
     sent. Typical errors include:

<Add udp(7P) to SEE_ALSO.>

udp(7P) additional text
-----------------------

     Options at the IP level may be used with UDP; see ip(7P)  or
|    ip6(7p).  Additionally, there is one UDP-level option of interest
+    to IPsec Key Management applications (see ipsec(7P) and pf_key(7P):
+
+        UDP_NAT_T_ENDPOINT
+
+        If this boolean option is set, datagrams sent via this socket
+        will have a non-ESP marker inserted between the UDP header and
+	 the data.  Likewise, inbound packets that match the endpoint's
+	 local-port will be demultiplexed between ESP or the endpoint itself
+	 if a non-ESP marker is present.  This option is only available on
+	 IPv4 sockets (AF_INET), and the application must have sufficient
+	 privilege to use PF_KEY sockets to also enable this option.

     There are a variety of ways that a UDP packet can be lost or

<Add RFC 3948, pf_key(7P), and ipsec(7P) to SEE ALSO.>

ipsec(7P) additional text
-------------------------

  NAT Traversal
     IPsec's ESP can also encapsulate itself in UDP if  IKE  (see
     in.iked(1M))  discovers  a  Network Address Translator (NAT)
     between two communicating endpoints.

+    A UDP socket can be specified to be a NAT-Traversal endpoint.
+    See udp(7P) for details.

  Security Associations
     AH and ESP use Security Associations (SA). SA's are entities


<And add udp(7P) to the SEE ALSO list.>


ipseckey(1M)
------------

Replace nat_{loc,rem,lport,rport} keyword descriptions with these:

     nat_loc <address>|<name>

         If the local address in the SA (source  or  destination)
         is behind a NAT, this extension indicates the NAT node's
         globally-routable address.

	 This can match the SA's local address if there is a nat_lport (see
	 below) specified.

     nat_rem <address>|<name>

         If the remote address in the SA (source or  destination)
         is  behind  a  NAT, this extension indicates that node's
         internal (that is, behind-the-NAT) address.

	 This can match the SA's remote address if there is a nat_lport (see
	 below) specified.

     nat_lport <portnum>

         Identifies the local UDP port on which encapsulation of ESP occurs.

     nat_rport <portnum>

         Identifies the remote UDP port on which encapsulation of ESP occurs.