NRL IPv6/IPsec Software Distribution
Alpha Release 4        Release Notes                            September, 1996
====================================                            ===============

Introduction
------------

	The NRL IPv6/IPsec Software Distribution is a reference implementation
of IPv6 and IP Security for the 4.4BSD-Lite2 networking software. It is freely
distributable (subject to U.S. export controls) and usable for commercial and
non-commercial purposes as long as the NRL and UC Berkeley license terms are
adhered to.

	We have tested this software on SPARC systems using the UC Berkeley
4.4 BSD UNIX operating system with 4.4-Lite updates. We have also tested this
software on x86 systems running NetBSD 1.2, SPARC systems running NetBSD 1.2,
and x86 systems using BSDI 2.1. We believe that our code should be easily
portable to reasonable 4.4BSD-Lite derived systems (BSDI, NetBSD, OpenBSD, and
Lites). We believe that it would be difficult, though not impossible, to port
our code to other systems.

	This implementation includes kernel networking software, a small
IPv6 support library, and several applications (e.g. telnet, telnetd, ping,
tftp, tftpd, socktest, netstat, ifconfig, ping, route, tcpdump) modified to
support IPv6/IPsec. This implementation also includes the NRL Key Engine
(aka PF_KEY) and applications to interface with it. There are manual pages
for the modified and new software, but they might not yet be as detailed as
one might like.
 
	This "alpha-quality" release of the IPv6 software is intended to be
used by kernel hackers and implementers who want to get early access and
experience with IPv6 and IPsec. Use at your own risk. It is complete enough to
use for experimenting but it is not entirely complete. In some areas this is
because the IPv6 specifications are not yet stable.

What's New
----------

	Alpha 4 (September, 1996)
	-------------------------

	* Bug fixes

	* We now support the IPv6 BSD API specified in draft 5. We also
	  provide homegrown functions that have proven useful (these start
	  with the prefix 'nrl_').

	* POSIX bit-types (e.g., u_int32_t) instead of our homegrown types
	  (e.g., u_int32). This should be a portability win.

	* More tunnel support.  We now support encapsulating IPv6 over IPv4
	  and IPv4 over IPv6 with or without security.  IPv6 over IPv6 and
	  IPv4 over IPv4 support (with or without security) is incomplete 
	  and has not been thoroughly tested.  See the route(8) man page 
	  for more details.

	* An implementation of the POSIX p1003.1g draft 6.4 getaddrinfo()
	  function contributed by Craig Metz.

	* Applications that use getaddrinfo() and [nrl_]getnameinfo() where
	  possible.

	* Because our getaddrinfo() and [nrl_]getnameinfo() functions support
	  (IPv6 and IPv4) DNS as well as a local host table, so do our apps.

	* FTP client and server. Both automagically support SPORT/SPASV (NRL
	  proposed), PORT/PASV (old IPv4 only), and LPRT/LPASV (RFC 1639, aka
	  FOOBAR) data connection addressing. Both also support separate
	  security requests for control and data connections and incorporate
	  fixes to plug several security holes.

	* Finger client and server. Both incorporate fixes to plug several
	  security holes.

	* Updated libpcap and tcpdump, now including a Linux port.

	* Apps that deal with networks (e.g., ifconfig, route, and netstat)
	  now understand and use CIDR-style address formatting (e.g.,
	  1234::5678/64) for IPv6. They can optionally also do this for IPv4
	  (e.g., 127.0.0.0/8).

	* Many of our apps can automagically figure out which address
	  family to use without the need to specify it explicitly. (Note: they
	  favor IPv6 over IPv4)

	* Improved Makefiles contributed by Joe Konczal of NIST.

	* User apps upgraded to 4.4BSD-Lite2.

	* Linux portability patches contributed by Craig Metz.

	* Lots of user-space code cleanups.

	Alpha 3 (July, 1996)
	--------------------

	* Bug fixes

	* Lots of code cleanups. The code now compiles with almost
	  no warnings.

	* Sysctl adjustment of debugging verbosity levels. Look for
	  new variables named debug.inet6 and debug.key.

	* The 4.4BSD-Lite2 changes to the netinet code.

	* Eric Young's DES code has been replaced with Phil Karn's
          DES code. Phil's code is better and his licensing terms are
	  more reasonable.

	* HMAC-MD5, SHA, and HMAC-SHA AH transforms contributed by
	  Larry Bassham and NIST.

	* key(8) now uses hexadecimal SPIs instead of decimal. N.B.

	* The latest versions of tcpdump and telnet.

	* A port to NetBSD 1.2.

	* A port to BSDI 2.1.

	* A Linux port of the Key Engine and key(8) to Linux 2.0.

	* Minor mods to keep the code in sync with the current specs.

	Alpha 2 (January, 1996)
	-----------------------

	* Bug fixes

	* Better multihomed support

	* Improvements to IPsec, and a step toward separating the IPsec/v6
	  dependency in this implementation.

	* Forwarding engine, and a crude router advertisement program.

	* Router advertisement handling.

	* Better route handlers, including default routes, network routes, and
	  cloning for easy Path MTU discovery.

	* Path MTU discovery.

	* Stateless address configuration, though with permanent lifetimes.

	* Up-to-date neighbor discovery.

	* Multicast option support (though no ICMP/IGMP messages yet)

	Alpha 1 (September, 1995)
	-------------------------

	* Initial release

Known Problems
--------------

	* This is alpha-quality code. N.B.

	* We have not used any formal software assurance techniques in
	  developing our implementation. We believe that our security
	  implementation mostly works as intended, but we do NOT claim
	  that it provides adequate security for any user. Users who
	  plan to rely on the security of our implementation need to
	  make their own efforts to verify that our code does what they
	  want it to do.

	* Performance is slower over IPv6 than over IPv4. This is expected
	  for alpha-test releases. We will enhance performance in future
	  releases. Known reasons that we are slower right now include:

		ipv6_preparse()
		Lack of any optimization efforts in the IPv6 code
		Years of optimization by others in the IPv4 code
		ipv6_preparse()

	* If an IPv4 socket is listening on a port with a wildcard address,
	  an IPv6 socket cannot listen on the same port. This may be more 
	  of a feature than a bug, given that IPv6 sockets can communicate
	  using IPv4 and the ::FFFF:<v4-address> address format.

	* Expiration of keys has yet to be implemented. Once a key has been
	  added to the kernel, it remains in the kernel and is usable until
	  it is explicitly deleted by a user-level program like key(8). There
	  is an exception, however, for keys allocated to sockets requesting 
	  unique-keying. Since these keys cannot be used by any other sockets,
	  they are deleted from the kernel key table when the requesting
	  socket is closed and freed.

	* Prefixes snarfed from router advertisements are permanent.

	* The SHA code included in the netsec directory causes GCC 2.3.3
	  on our SPARC systems to hang if it is compiled with GCC's optimizer
	  turned on. 

	* If an AH transform generates an odd number of 32 bit words, the
	  code will ALWAYS pad this out to the next 64 bit boundary on
	  output. The code will accept padded or non-padded input. There
	  is a symbol in ipsec_ah.c that can be tweaked if you don't want
	  the code to pad. This should really be an option negotiated by
	  key management, though.

	* There are still some memory leaks in the kernel code.

	* Some parts of the code (incorrectly) modify freed data. This is
	  non-fatal, though some systems (such as NetBSD) will give you
	  warnings about it.

	* The key engine will sometimes acquire more keys than are needed.

	* The routing tree will sometimes reject IPv6 routes that appear
	  to be properly specified.

	* Some tunnel configurations are currently not supported or has
	  yet to be tested.  Use of these configurations can lead to
	  unpredictable results and kernel crashes.  N.B.

	* Some of our options aren't really optional (e.g., the DEBUG
	  options).

	* Some options native to the host OS won't work with our code.
	  For example, including network families such as ISO and CCITT
	  will probably cause your build to fail.

	* Our IPsec code doesn't always deal properly with packets
	  with more than 2030 bytes of transport header(s) + data.

	If you find bugs, please send detailed reports (and fixes!) to
the <ipv6-bugs@itd.nrl.navy.mil>. PLEASE DO NOT SEND ANYTHING OTHER THAN
BUG REPORTS AND BUG FIXES TO THIS ADDRESS.

Credits
-------

	The NRL IPv6 software development team included (at one time or
another) Randall Atkinson, Ken Chin, Dan McDonald, Ron Lee, Craig Metz, and
Bao Phan. Most of the code has had more than one person working on it.

	This work was sponsored by the Information Security Program Office
(PMW-161), U.S. Space & Naval Warfare Systems Command (SPAWAR) and the
Computing Systems Technology Office, Defense Advanced Research Projects Agency
(DARPA/CSTO). We really appreciate their sponsorship of our efforts.

	We would also like to thank:

	* Phil Karn, for making his excellent DES code freely available.
	  We include his code (with some very minor changes) as the part
	  of our ESP DES-CBC implementation. The assembly code is the
	  fastest x86 DES code we know of, and the portable C code is
	  still pretty fast.

	* Larry Bassham and NIST, for contributing the AH HMAC-MD5, SHA,
	  and HMAC-SHA transforms and the core SHA code. Thanks to their
	  efforts, our IPsec implementation is still up-to-date with the
	  current proposed standards as of the release of this code.

	* Joe Konczal of NIST, for contributing improved Makefiles. We
	  hacked on them a little bit, and the result is that it should
	  be a lot easier to configure and install the user apps in the
	  distribution.

	* Paul Vixie, for including IPv6 address record support in
	  BIND and for allowing us to include the BIND 4.9.4 resolver
	  here.

	* Dan Harkins and Cisco Systems for producing a free ISAKMP/Oakley
	  daemon that works with our code via PF_KEY. Cisco is providing
	  the community with a critical piece of a complete IP Security
	  solution. A copy of the daemon is included with this distribution.
	  This daemon can also be obtained by telnetting to
	  ftp-eng.cisco.com port 7600 and following the instructions, 
	  or from http://web.mit.edu/network/isakmp.

Legal
-----

	UNIX is a trademark of X/Open.
	NRL is a trademark of the US Naval Research Laboratory.
	All other trademarks are property of their respective owners.

	This software distribution (including its documentation) is
copyrighted. See the COPYRIGHT file in this directory and also the various
copyright notices in the software itself for more information on this and on
the applicable license terms.

	The key engine has a patent pending but has been licensed on similar
no-cost terms because ARPA has written that into our Statement of Work. See
the netkey/key.c file for more information on that license.

	Some contributed code segments have license other than the NRL
license. However, modifications that we have made to those code segments
are made available under the NRL license terms. You must follow the terms of
all licenses on such code, including ours and those of the original license.
Specific cases where this is an issue are:

	* The SHA code provided by NIST (sys.common/netsec/sha.[ch]) has a
	  special license listed at the top of sha.c.

	* Phil considers his DES code (sys.common/netsec/des*) to be in the
	  public domain. However, he requests (and we do also) that anyone
	  who uses the code give him an appropriate credit for his work.

	* The PF_KEY port for Linux (sys.common/netkey/osdep_linux.c) was
	  derived in part source files in the Linux kernel distribution and
	  is also subject to the GNU General Public License, Version 2.

	* The getaddrinfo() code and driver program (support/getaddrinfo.[ch],
	  support/gai.c) provided by Craig Metz has a special license. This
	  license is provided in the file License.TIN.

	* The resolver code (support/res/*) is included almost verbatim from
	  the BIND 4.9.4 distribution. This code is subject to several
	  copyrights and licenses. Please read the source files for more
	  information.

What now?
---------

	There is a specific README file for each of the three platforms
this distribution supports that contains notes and installation
instructions.

	We have set up a mailing list for users of the NRL IPv6+IPsec
code so they can discuss the code and so that we can keep in touch with
people who are actually using our code.

	The mailing list address is:

	<ipv6-users@itd.nrl.navy.mil>

	Subscription requests should be sent to our list server at:

	<ipv6-users-request@itd.nrl.navy.mil>

	We will interpret subscription/administrative requests sent to the
mailing lists, advertisements, conference announcements, or other inappropriate
discussion as a request to be permanently banned from the list. We would like
to keep the list volume low and its S/N ratio high.

Release Overview
----------------

COPYRIGHT	- General copyright information for the release.  See the
		  appropriate file(s) for copyright/licensing information
		  for specific contributed software.

README		- This file.

README.BSDI	- Info on building this release on a BSD/OS system.

README.Linux	- Info on building parts of this release on a Linux system.

README.NetBSD	- Info on building this release on a NetBSD system.

README.UCB	- Info on building this release on a 4.4BSD system.

contrib		- Contributed software.  

diff.bsdi	- Patches to BSDI kernel source files.

diff.linux	- Patches to Linux kernel source files.

diff.netbsd	- Patches to NetBSD kernel source files.

diff.ucb	- Patches to 4.4BSD kernel source files.

etc		- Some sample IPv6/IPsec configuration files.

libexec		- IPv6/IPsec replacements for binaries found in /usr/libexec .

prepare-kernel	- Simple shell script to create an IPv6 source tree from
		  this release.

sbin		- IPv6/IPsec replacements for binaries found in /sbin .

scripts 	- Some useful shell scripts.

share		- IPv6/IPsec-specific man pages.

support		- IPv6 support library routines.  Build the library first,
		  place it in /usr/inet6/lib, and copy the header files to
		  /usr/inet6/include, before building the user binaries.  
		  If the library and associated header files are placed 
		  elsewhere, you will need to change the library and include 
		  paths in the Makefiles to build the user binaries.

sys.common	- Contains the IPv6/IPsec kernel networking code:
			netinet 	IPv4 networking code
			netinet6	IPv6 networking code
			netkey		Key engine (PF_KEY) code
			netsec		IP security code

test		- Some test programs, most of which have no manual pages.

usr.bin		- IPv6/IPsec replacements for binaries found in /usr/bin.

usr.sbin	- IPv6/IPsec replacements for binaries found in /usr/sbin.
