diff -Naur libreswan-3.8-orig/README libreswan-3.8/README
--- libreswan-3.8-orig/README 2014-01-16 02:46:24.000000000 -0500
+++ libreswan-3.8/README 2014-02-21 18:41:44.887838212 -0500
@@ -2,28 +2,48 @@
# Libreswan 3.X Release Notes
#########################################################################
+The Libreswan Project https://libreswan.org/
+
Libreswan is an IPsec implementation for Linux. It has support for most
of the extensions (RFC + IETF drafts) related to IPsec, including
IKEv2, X.509 Digital Certificates, NAT Traversal, and many others.
+Libreswan uses the native Linux IPsec stack (NETKEY/XFRM) per default.
+For more information about the alternative Libreswan kernel IPsec stack,
+see README.KLIPS.
-Libreswan has been forked from Openswan 2.6.38, which was forked from
-FreeS/WAN 1.99.
+Libreswan was forked from Openswan 2.6.38, which was forked from
+FreeS/WAN 1.99. See the CREDITS files for contributor acknowledgments.
-Download it from
+It can be downloaded from various locations:
https://download.libreswan.org/
ftp://ftp.libreswan.org/
+A git repository is available at:
+
+ https://github.com/libreswan/libreswan/
+
+#########################################################################
+# LICENSE
+#########################################################################
+
+The bulk of libreswan is licensed under the GNU General Public License
+version 2; see the LICENSE and CREDIT.* files. Some smaller parts have
+a different license.
+
#########################################################################
# REQUIREMENTS
#########################################################################
A recent Linux distribution based on either Kernel 2.4.x, 2.6.x or 3.x
-are the currently supported platforms.
+are the currently supported platforms. Libreswan has been ported to
+Win2k/BSD/OSX as well.
-Most recent distributions have package support for libreswan. Unless
-a source based build is truly needed, it is often best to use the pre-built
-distributions packaged version.
+Most distributions have native packaged support for libreswan. Libreswan is
+available for RHEL, Fedora, Ubuntu, Debian, Arch, openwrt and more.
+
+Unless a source based build is truly needed, it is often best to use
+the pre-built version of the distribution you are using.
There are a few packages required for Libreswan to compile from source:
@@ -45,7 +65,7 @@
Runtime requirements (usually already present on the system)
- iproute2, iptables, sed, awk, bash, cut and possible other tools
+ nss, iproute2, iptables, sed, awk, bash, cut
(note: the busybox version of "ip" does not support 'ip xfrm', so
ensure you enable the iproute(2) package for busybox)
@@ -53,106 +73,72 @@
python is used for "ipsec verify", which helps debugging problems
#########################################################################
-# HOW TO INSTALL on Kernel 2.6 and higher
+# Compiling the userland and IKE daemon
#########################################################################
-NETKEY/XFRM (Native linux IPsec stack)
----------------------------------
-
-To use Libreswan with the linux native (builtin) IPsec stack, the
-following steps should be all that are needed. Please use at least kernel
-version 2.6.9, as prior versions of the kernel have serious bugs in the
-native IPsec stack. From the libreswan directory:
-
make programs
sudo make install
-Note: The ipsec-tools package or setkey is not needed. Instead iproute2 >= 2.6.8
-is required. Run 'ipsec verify' to determine if your system misses anything.
-of the requirements.
-
-KLIPS/KLIPSNG (Libreswan IPsec stack)
-------------------------------------
-
-To use the Libreswan KLIPS IPsec stack (ipsec0 devices) for Linux
-Kernels 2.4 and higher, the following steps should work. From the
-libreswan directory:
-
- make programs
- make module
- sudo make module_install
-
-This builds a module against the running kernel. To compile a module for
-another kernel (for which the headers are installed), use:
-
- make KERNELSRC=/lib/modules/`uname -r`/build module
- sudo make KERNELSRC=/lib/modules/`uname -r`/build module_install
+Note: The ipsec-tools package or setkey is not needed. Instead the iproute2
+pacakge (>= 2.6.8) is required. Run 'ipsec verify' to determine if your
+system misses any of the requirements. This will also tell you if any of
+the kernel sysctl values needs changing.
-For Linux 2.6 Kernels before 2.6.23, including 2.4 linux systems, the kernel
-requires patching if NAT-T support or SAref tracking is required. Full kernel
-source will be required as the kernel sources are being patched, built and
-installed. It is good practice to build and install an unpatched kernel
-before starting to ensure the process is correct. See your distribution
-documentation on how to build and install a new kernel
-
- Determine the linux source directory, for example /usr/src/linux on
- most full source installs. It may also be /usr/src/linux-2.[46].X
-
- Add NAT-T support (if required).
-
- From the Libreswan source directory:
-
- make KERNELSRC=/usr/src/linux nattpatch | patch -d /usr/src/linux -p1
-
- Add SAref tracking support (if required).
+#########################################################################
+# Starting Libreswan
+#########################################################################
- Premade patches for some distributions kernels can be found in
- patches/kernel/ It is recommended that kernel 2.6.32 or higher is
- used. Documentation on SAref/MAST can be found in docs/HACKING/Mast*
- and doc/klips/mast.xml. To understand what SAref tracking does, see
- doc/ipsecsaref.png and the overlapip= entry in the ipsec.conf man page.
+The install will detect the init system used (systemd, upstart, sysvinit,
+openrc) and should integrate with the linux distribution. The service
+name is called "ipsec". For example, on RHEL7, one would use:
- From the Libreswan source directory:
+ systemctl enable ipsec.service
+ systemctl start ipsec.service
- make KERNELSRC=/usr/src/linux sarefpatch | patch -d /usr/src/linux -p1
+If unsure, the "ipsec" command can also be used to start or stop the ipsec
+service:
- Add OCF HW offloading support
+ ipsec setup start
+ ipsec setup stop
- For OCF HW offloading support, you need also need a patched kernel
- See: http://ocf-linux.sourceforge.net/ for more details.
+#########################################################################
+# Configuration
+#########################################################################
- Build and install a new kernel
+Most of the libreswan configuration is stored in /etc/ipsec.conf and
+/etc/ipsec.secrets. See their respective man pages for more information.
- See your distribution documentation on how to install a new kernel.
- It should be something similar to:
+#########################################################################
+# NSS initialisation
+#########################################################################
- cd /usr/src/linux
- make oldconfig
- make dep - this step is ignore on 2.6 systems)
- make bzImage install
+Libreswan uses NSS to store private keys and X.509 certificates. The NSS
+database should have been initialised by the package installer. If not,
+the NSS database can be initialised using:
- Build Libreswan
+ ipsec initnss
- From the Libreswan source directory:
+PKCS#12 certificates (.p12 files) can be imported using:
- make programs
- make KERNELSRC=/usr/src/linux module
- sudo make KERNELSRC=/usr/src/linux install minstall
+ ipsec import /path/to/your.p12
-The Libreswan configuration file can select which ipsec stack to use at
-runtime by using the "protostack=<klips|netkey|mast>" options in ipsec.conf.
-See the ipsec.conf man page for more information on configuration options.
+See README.NSS and 'certutil --help' for more details on using NSS and
+migrating from the old openswan /etc/ipsec.d/ directories to using NSS.
#########################################################################
# UPGRADING
#########################################################################
-1. If you are upgrading from FreeS/WAN 1.x or Openswan 2.x to Libreswan 3.x,
- you might need to adjust your config files. See 'man ipsec.conf.
- details on what has changed.
-
-2. You can run 'make install' on top of your old version - it will not
- overwrite your your /etc/ipsec.* config files
+If you are upgrading from FreeS/WAN 1.x or Openswan 2.x to Libreswan 3.x,
+you might need to adjust your config files, although great care has been
+put into making the configuration files full backwards compatible.
+
+See 'man ipsec.conf' for the list of options to find any new features.
+
+You can run 'make install' on top of your old version - it will not
+overwrite your your /etc/ipsec.* configuration files. The default install
+target installs in /usr/local. Ensure you do not install libreswan twice,
+one from a distribution package in /usr and once manually in /usr/local.
#########################################################################
# SUPPORT
@@ -160,12 +146,12 @@
Mailing Lists:
- https://lists.libreswan.org is home of the mailing lists
+ https://lists.libreswan.org/ is home of all our the mailing lists
Wiki:
https://libreswan.org is home to the Libreswan WIKI. It has the most
- up to date documentation, interop guides and other related information.
+ up to date documentation, interop guides and other useful information.
IRC:
@@ -176,35 +162,37 @@
# BUGS
#########################################################################
-Bugs with the package can be filed into our bug tracking system, at
-https://bugs.libreswan.org
+Bugs can be reported on the mailing list or using our bug tracking system,
+at https://bugs.libreswan.org/
#########################################################################
-# SECURITY HOLES
+# SECURITY INFORMATION
#########################################################################
-All security vulnerabilities found that require public disclosure will
-receive proper CVE tracking numbers (see http://mitre.org/) and co-ordinated
-via the vendor-sec (or successor) mailing list. A complete list of known
-security vulnerabilities is available at: https://www.libreswan.org/security/
+All security issues found that require public disclosure will
+receive proper CVE tracking numbers (see http://mitre.org/) and
+will be co-ordinated via the vendor-sec / oss-security lists. A
+complete list of known security vulnerabilities is available at:
+
+https://www.libreswan.org/security/
#########################################################################
# DEVELOPMENT
#########################################################################
-Those interested in the development, patches, beta releases of Libreswan
-can join the development mailing list (http://lists.libreswan.org -
-dev@lists.libreswan.org) or join the development team on IRC in #swan
-on irc.freenode.net
+Those interested in the development, patches, and beta releases of
+Libreswan can join the development mailing list "swan-dev" or talk to the
+development team on IRC in #swan on irc.freenode.net
For those who want to track things a bit more closely, the
-commits@lists.libreswan.org mailinglist will mail all the commit messages.
+commits@lists.libreswan.org mailinglist will mail all the commit messages
+when they happen. This list is quite busy during active development
+periods.
#########################################################################
# DOCUMENTATION
#########################################################################
-The most up to date docs are in the man pages and at https://libreswan.org/
+The most up to date docs are in the man pages that come with the software
+and at https://libreswan.org/
-The bulk of this software is under the GNU General Public License; see
-LICENSE. Some parts of it are not; see CREDITS for the details.
diff -Naur libreswan-3.8-orig/README.nss libreswan-3.8/README.nss
--- libreswan-3.8-orig/README.nss 1969-12-31 19:00:00.000000000 -0500
+++ libreswan-3.8/README.nss 2014-02-21 18:42:01.769172404 -0500
@@ -0,0 +1,265 @@
+
+#########################################################################
+# Using the NSS crypto library with Pluto (Libreswan)
+# Based on initial documentation by Avesh Agarwal <avagarwa@redhat.com>
+#########################################################################
+
+For detailed developer information about NSS, see
+http://www.mozilla.org/projects/security/pki/nss/
+
+The NSS crypto library is user space library. It is only used with the
+libreswan userspace IKE daemon pluto for cryptographic operations. NSS
+does not perform IPsec crypto operations inside the kernel (KLIPS
+nor NETKEY)
+
+The NSS library exports a PKCS#11 API for the application to
+communicate to a cryptographic device. The cryptographic device is
+usually the "soft token" but can also be a Hardware Security Module
+(HSM).
+
+The advantage of using NSS is that pluto does need to know in detail how
+the cryptographic device works. Pluto does not access any private keys or
+data itself. Instead, it uses the PK11 wrapper API of NSS irrespective
+of the cryptographic device used. Pluto hands over work using the PK11
+interface to NSS and never has direct access to the private key material
+itself. Both IKEv1 and IKEv2 operations are performed using NSS. Private
+RSA keys (raw RSA as well as X.509 based private RSA keys) are stored
+inside NSS. RSA keys are still referenced in /etc/ipsec.secrets. X.509
+keys and certificates are referenced using their "nickname" instead of
+their filename in /etc/ipsec.conf.
+
+While PreShared Key (PSK) calculations are done using NSS, the actual
+preshared key ("secret") is still stored in /etc/ipsec.secrets.
+
+NSS as shipped by Red Hat is a FIPS certified library. Libreswan is
+currently being FIPS certified for RHEL7.
+
+#########################################################################
+# The NSS command line tools used with libreswan
+#########################################################################
+
+- certutil: Look and modify the NSS db. "ipsec initnss" and "ipsec look"
+ use certutil under the hood.
+
+http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
+
+- pk12util: import and export certificates and keys from and to the NSS db.
+ The "ipsec import" command is a simple wrapper around this utility.
+
+http://www.mozilla.org/projects/security/pki/nss/tools/pk12util.html
+
+- modutil: Put NSS into FIPS mode
+
+http://www.mozilla.org/projects/security/pki/nss/tools/modutil.html
+
+#########################################################################
+# Creating the NSS db for use with libreswan's pluto IKE daemon
+#########################################################################
+
+If you are not using a packaged libreswan version, you might need to
+create a new NSS db before you can start libreswan. This can be done
+using:
+
+ ipsec initnss
+
+By default the NSS db is created in /etc/ipsec.d/
+
+When creating a database, you are prompted for a password. The default
+libreswan package install for RHEL/Fedora/CentOS uses an empty password.
+It is up to the administrator to decide on whether to use a password
+or not. However, a non-empty database password must be provided when
+running in FIPS mode.
+
+To change the empty password, run:
+
+ certutil -W -d /etc/ipsec.d
+
+Enter return for the "old password", then enter your new password.
+
+If you create the database with a password, and want to run NSS in FIPS
+mode, you must create a password file with the name "nsspassword" in
+the /etc/ipsec.d direcotry before starting libreswan. The "nsspassword"
+file must contain the password you provided when creating NSS database.
+
+If the NSS db is protected with a non-empty password, the "nsspassword"
+file must exist for pluto to start.
+
+The syntax of the "nsspassword" file is:
+
+token_1_name:the_password
+token_2_name:the_password
+
+The name of NSS softtoken (the default software NSS db) when NOT running
+in FIPS mode is "NSS Certificate DB". If you wish to use software NSS
+db with password "secret", you would have the following entry in the
+nsspassword file:
+
+NSS Certificate DB:secret
+
+If running NSS in FIPS mode, the name of NSS softtoken is
+"NSS FIPS 140-2 Certificate DB". If there are smartcards in the system, the
+entries for passwords should be entered in this file as well.
+
+Note: do not enter any spaces before or after the token name or password.
+
+#########################################################################
+# Using raw RSA keys with NSS
+#########################################################################
+
+The "ipsec newhostkey" and "ipsec rsasigkey" utilities are used for
+creating raw RSA keys. If a non-default NSS directory is used, this can
+be specified using the -d option.
+
+ ipsec newhostkey --configdir /etc/ipsec.d [--password password] --output \
+ /etc/ipsec.secrets
+
+The password is only required if the NSS database is protected with a
+non-empty password. All "private" compontents of the raw RSA key in
+/etc/ipsec.secrets such as the exponents and primes are filled in with
+the CKA ID, which serves as an identifier for NSS to look up the proper
+information in the NSS db during the IKE negotiation.
+
+Public key information is directly available in /etc/ipsec.secrets and the
+"ipsec showhostkey" command can be used to generate left/rightrsasigkey=
+entries for /etc/ipsec.conf.
+
+#########################################################################
+# Using certificates with NSS
+#########################################################################
+
+Any X.509 certificate management system can be used to generate Certificate
+Agencies, certificates, pkcs12 files and CRLs. Common tools people use are
+the openssl command, the GTK utility tinyca2, or the NSS certutil command.
+
+An example using openssl can be found as part of the libreswan test suite at
+https://github.com/libreswan/libreswan/tree/master/testing/x509
+
+Below, we will be using the nss tools to generate certificates
+
+* To create a certificate authority (CA certficate):
+
+certutil -S -k rsa -n "ExampleCA" -s "CN=Example CA Inc" -w 12 \
+ -d . -t "C,C,C" -x -d /etc/ipsec.d
+
+It creates a certificate with RSA keys (-k rsa) with the nick name
+"ExampleCA", and with common name "Example CA Inc". The option
+"-w" specifies the certificates validy period. "-t" specifies the attributes
+of the certificate. "C" is required for creating a CA certificate. "-x" mean
+self signed. "-d" specifies the path of the database directory.
+
+NOTE: It is not a requirement to create the CA in NSS database. The CA
+certificate can be obtained from anywhere in the world.
+
+* To create a user certificate signed by the above CA
+
+certutil -S -k rsa -c "ExampleCA" -n "user1" \
+ -s "CN=User Common Name" -w 12 -t "u,u,u" -d /etc/ipsec.d
+
+It creates a user cert with nick name "user1" with attributes
+"u,u,u" signed by the CA cert "ExampleCA".
+
+NOTE: You must provide a nick name when creating a user
+certificate, because pluto reads the user certificate from the NSS database based on
+the user certificate's nickname.
+
+
+#########################################################################
+# Configuring certificates in ipsec.conf and ipsec.secrets
+#########################################################################
+
+In ipsec.conf, the leftcert= option takes a certificate nickname as argument. For
+example if the nickname of the user cert is "hugh", then it can be
+"leftcert=hugh".
+
+NOTE: if you are migrating from openswan, you are used to specifying a filename for the leftcert= option. Filenames
+are not valid for the left/rightcert= options in libreswan.
+
+In ipsec.secrets, we need to list the certificate nickname to inform pluto there is a certificate within the NSS db.
+This is specified using:
+
+ : RSA nickname
+
+NOTE: In openswan and freeswan it was required to specify a file name or password. With libreswan, this is not required.
+NOTE: openswan and freeswan stored private keys in /etc/ipsec.d/private/ This directory does not exist for libreswan.
+
+The directories /etc/ipsec.d/cacerts/ and /etc/ipsec.d/crls/ can still be used.
+
+NOTE: the freeswan and openswan directories /etc/ipsec.d/aacerts/ and /etc/ipsec.d/acerts/ are not used with libreswan.
+
+If you use an external CA certificate, you can either import it into the NSS db or place it in the /etc/ipsec.d/cacerts/
+directory. Note that the preferred method is to store it inside the NSS db.
+
+#########################################################################
+# Importing third-party certificates into NSS
+#########################################################################
+
+If you do not have the third-party certificate in PKCS#12 format, use openssl
+to create a PKCS#12 file:
+
+ openssl pkcs12 -export -in cert.pem -inkey key.pem -certfile cacert.pem \
+ -out certkey.p12 [-name YourName]
+
+Now you can import the file into the NSS db:
+
+ ipsec import certkey.p12
+
+NOTE: the ipsec command uses "pk12util -i certkey.p12 -d /etc/ipsec.d"
+
+If you did not pick a name using the -name option, you can use certutil -L -d /etc/ipsec.d
+to figure out the name NSS picked durnig the import.
+
+Add following to /etc/ipsec.secrets file:
+
+ : RSA "YourName"
+
+To specify the certificate in ipsec.conf, use a line like:
+
+ leftcert=YourName
+
+#########################################################################
+# Exporting a CA(?) certificate to load on another libreswan machine
+#########################################################################
+
+
+Paul: wouldn't this also include the private key which we don't want?????
+Paul: add "ipsec export" ?
+
+To export the CA certificate:
+
+ pk12util -o cacert1.p12 -n cacert1 -d /etc/ipsec.d
+
+Copy the file "cacert1.p12" to the new machine and import it using:
+
+ ipsec import cacert1.p12
+ certutil -M -n cacert1 -t "C,C,C" -d /etc/ipsec.d
+
+
+Example connection for ipsec.conf:
+
+conn pluto-1-2
+ left=1.2.3.4
+ leftid="CN=usercert1"
+ leftrsasigkey=%cert
+ leftcert=usercert1
+ right=5.6.7.8
+ rightid="CN=usercert2"
+ rightrsasigkey=%cert
+ auto=add
+
+#########################################################################
+# Configuring a smartcard with NSS
+#########################################################################
+
+Required library: libcoolkey
+
+To make smartcard tokens visible through NSS
+
+modutil -add <module_name> -libfile libcoolkeypk11.so -dbdir \
+ <nss_database_dir_name> -mechanisms <mechanisms_separted_by_colons>
+
+An example of mechanisms can be
+RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES:CAMELLIA.
+
+To check whether the token is visible or not, please run
+
+modutil -list -dbdir <nss_database_dir_name>
diff -Naur libreswan-3.8-orig/README.x509 libreswan-3.8/README.x509
--- libreswan-3.8-orig/README.x509 1969-12-31 19:00:00.000000000 -0500
+++ libreswan-3.8/README.x509 2014-02-21 18:42:04.673229900 -0500
@@ -0,0 +1,3 @@
+
+See README.NSS or check the wiki at https://libreswan.org/
+