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=" 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 +######################################################################### + +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 -libfile libcoolkeypk11.so -dbdir \ + -mechanisms + +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 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/ +