NRL IPv6/IPsec Software Distribution
Alpha Release 3        Release Notes                                July, 1996
====================================                                ==========

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

	The NRL IPv6/IPsec Software Distribution is a reference implementation
of IPv6 and IP Security for the 4.4BSD-Lite 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 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 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.

	* There is a specific known bug when ESP is used with IPv4 and
	  fragmentation occurs. The outbound processing seems fine. The
	  inbound processing seems to go OK until the packet is handed
	  up to an upper-layer protocol (UDP or TCP). At that level, the
	  UDP or TCP checksum fails because there are 8-24 bytes of
	  corrupted data beginning about (first fragment size) bytes into
	  the packet. We are are not sure if the problem is still there.

	* 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 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.

	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'd 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.

	We'd like to thank 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.

	We'd also like to thank Cisco Systems (and, specifically, Dan
Harkins) for making an ISAKMP/Oakley daemon freely available that works
with our code via PF_KEY. Cisco is providing the networking community a
critical piece of a complete IP Security solution. This daemon can be
obtained from http://web.mit.edu/network/isakmp or by telnetting to
ftp-eng.cisco.com port 7600 and following the instructions given.

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.

	The license on the SHA code provided by NIST is not the same as the
NRL license on the rest of the code. Please see netsec/sha.c for more
information on that license.

	Phil considers his DES code to be in the public domain. However,
he requests that anyone who uses the code give him an appropriate credit for
his work.

	Portions of the file netkey/osdep_linux.c were modified from
source files in the Linux kernel distribution and are subject to the GNU
General Public License, Version 2.

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-requests@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 Content
---------------

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

README		- This file.

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

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

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

diff.bsdi	- Context diffs of kernel source files needed to get 
		  IPv6/IPsec to work on BSD/OS.

diff.netbsd	- Context diffs of kernel sources needed to get 
		  IPv6/IPsec to work on NetBSD.

diff.ucb	- Context diffs of kernel source files needed to get 
		  IPv6/IPsec to work on a 4.4BSD system.

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.
