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.
