readme

ike协商阶段证书认证补丁 for freeswan

Installation and Configuration Guide
------------------------------------

     X.509 - Version 1.6.3

Contents

   1. Summary
   2. Acknowledgements
   3. Installation
	3.1 The X.509 distribution
	3.2 Installing the X.509 patch
	3.3 Enabling dynamic CRL fetching via LDAP
	3.4 Enabling dynamic CRL or OCSP fetching via cURL  (NEW)
	3.5 Compiling and installing FreeS/WAN with X.509
   4. Configuring the connections - ipsec.conf
	4.1 Configuring my side
	4.2 Multiple certificates
	4.3 Configuring the peer side using CA certificates
	4.4 Handling Virtual IPs and wildcard subnets
	4.5 Protocol and port selectors  (NEW)
	4.6 IPsec policies based on wildcards
	4.7 IPsec policies based on CA certificates
	4.8 Sending certificate requests
   5. Configuring certificates and CRLs
	5.1 Installing CA certificates
	5.2 Installing optional Certificate Revocation Lists (CRLs)
	5.3 Dynamic update of certificates and CRLs
	5.4 Online Certificate Status Protocol (OCSP) (NEW)
	5.5 CRL policy
	5.6 Configuring the peer side using locally stored certificates
   6. Configuring the private keys - ipsec.secrets
	6.1 Loading private key files in PKCS#1 format
	6.2 Entering passphrases interactively
	6.3 Multiple private keys
   7. Generating X.509 certificates and CRLs with OpenSSL
	7.1 Generating a CA certificate
	7.2 Generating a host or user certificate
	7.3 Generating a CRL
	7.4 Revoking a certificate
   8. Configuring CA properties - ipsec.conf (NEW)
   9. Smartcard Support
	9.1 Compiling FreeS/WAN with smartcard support
	9.2 Configuring a smartcard-based connection
	9.3 Entering the PIN code
	9.4 Configuring a smartcard using pkcs15-init
  10. Configuring the clients
	10.1 FreeS/WAN
	10.2 PGPnet
	10.3 Safenet/Soft-Remote
	10.4 SSH Sentinel
	10.5 Windows 2000/XP
  11. Monitoring functions
  12. Firewall support functions
       12.1 Environment variables in the updown script
       12.2 Sample updown script for iptables
  13. Using the patch with standard FreeS/WAN and raw RSA keys
  14. Using the patch with OpenPGP certificates
       14.1 OpenPGP certificates
       14.2 OpenPGP private keys
       14.3 Monitoring functions
       14.4 Suppression of certificate request messages


1. Summary
   -------

The X.509 patch supports RSA-based authentication using X.509 or OpenPGP
certificates between a Linux FreeS/WAN security gateway and an unlimited
number of IPsec peers.

  - Version 0.9 of the patch introduced Certification Authorities (CAs),
    hierarchical trust chains and Certificate Revocation Lists (CRLs),
    thereby eliminating the need to store peer certificates locally on
    the Linux security gateway.

  - Version 0.9.10 introduced support of multiple certificates and
    corresponding private keys as described in sections 4.2 and 6.2.

  - Version 1.0.0 improved the support of OpenPGP certificates which
    can now be used concurrently with X.509 certificates. For details
    consult section 13.

  - Version 1.1.0 introduced  dynamic CRL fetching supporting http,
    ftp, file and ldap crlDistributionPoints. For details refer to
    sections 3.3 and 5.3.

  - Version 1.1.1 introduced protocol and port selectors for outbound
    IPsec SAs.

  - Version 1.2.0 brought IPsec policies based on wildcards(*)
    in distinguished names (ID_DER_ASN1_DN). For details see section 4.6.

  - Version 1.3.0 introduced IPsec policies based on certification
    authorities (several root and/or intermediate CAs). This feature
    facilitates the setup of extranets giving restricted VPN access to third
    parties (e.g. customers or suppliers). For details refer to section 4.7.
    
  - Version 1.4.0 brought smartcard support. The functionality is based on
    the PKCS#15 cryptotoken interface provided by the OpenSC project.
    For details see section 8.
    
  - Version 1.5.0 introduces full support of the Online Certificate Status
    Protocol (OCSP) defined by RFC 2560 which can serve as an alternative to
    CRLS.

Compatibility has successfully been tested with peers running the following
IPsec clients:

  FreeS/WAN, PGPnet, SafeNet/Soft-PK, SafeNet/SoftRemote, SSH Sentinel,
  Microsoft Windows 2000/XP, CheckPoint VPN-1 NG.

Furthermore, interoperability with the following VPN gateways
has been demonstrated during the IPsec 2001 Conference in Paris:

  Cisco IOS Routers, Cisco PIX firewall, Cisco VPN3000,
  Nortel Contivity VPN Switch, NetScreen (FreeS/WAN as responder only),
  OpenBSD with isakmpd, Netasq, Netcelo, and 6WIND.

Potentially any IPsec implementation with X.509 certificate support can
be made to cooperate with X.509-enabled FreeS/WAN. The latest addition has 
been the successful interoperability with the Check Point VPN-1 NG gateway.


2. Acknowledgements
   ----------------

Major contributions to the X.509 patch for Linux FreeS/WAN have come from

  - Marco Bertossa, Christoph Gysin, Andreas Hess, Patric Lichtsteiner
    Andreas Schleiss, Roger Wegmann, and Simon Zwahlen, all former students
    of the Zurich University of Applied Sciences in Winterthur (Switzerland).
     
  - The support of Virtual IPs and the DHCP-over-IPsec protocol was
    implemented by Mario Strasser, former research assistant at the ZHW.

  - Stephane Laroche from Colubris has contributed dynamic CRL fetching.

  - Stephen J. Bevan has contributed the enforcement of port and protocol
    selectors on outbound traffic based on extended eroutes.

  - Mathieu Lafon contributed the exchange of Notification messages.

  - The X.509 patch also integrates the original contribution by Kai Martius
    supporting RSA based authentication using OpenPGP certificates and PGP's
    proprietary Key IDs.

The development of the X.509 patch is coordinated by Andreas Steffen,
professor for security and communications at the ZHW.


3. Installation
   ------------

3.1 The X.509 distribution
    ----------------------

The X.509 patch distribution contains the following files:

+----------------------------------------------------------------------------+
| README                   This installation and configuration guide         |
|----------------------------------------------------------------------------|
| CHANGES                  Change history for the X.509 patch                |
|----------------------------------------------------------------------------|
| freeswan.diff            Patch for the freeswan directory                  |
|----------------------------------------------------------------------------|
| ipsec.secrets.template   Template for /etc/ipsec.secrets                   |
+----------------------------------------------------------------------------+


3.2. Installing the X.509 patch
     --------------------------

Copy the patch freeswan.diff to the FreeS/WAN directory and type:

     patch -p1 < freeswan.diff

This applies all necessary changes to the FreeS/WAN source code.



3.3 Enabling dynamic CRL fetching via LDAP
    --------------------------------------
    
By default LDAP support will not be compiled into Pluto. In order to
enable dynamic LDAP URL fetching on of the two following lines must be
uncommented in the programs/pluto/Makefile:

  # Uncomment this line to enable dynamic CRL fetching using LDAP V3
  LDAP_VERSION=3
  # Uncomment this line to enable dynamic CRL fetching using LDAP V2
  #LDAP_VERSION=2

Compilation will be successful only if the OpenLDAP 2.x header files
and the ldap library are present. The latest OpenLDAP releases require
the LDAP V3 protocol whereas older versions use LDAP V2.


3.4 Enabling dynamic CRL or OCSP fetching via cURL
    ----------------------------------------------

Dynamic CRL fetching via file, http, and ftp URLs, as well as OCSP queries
transported via http require the libcurl library available from
"http://curl.haxx.se". Since libcurl support is not compiled into Pluto by
default, it must be activated explicitly by uncommenting the following line

in programs/pluto/Makefile:

  # Uncomment this line to enable OCSP and dynamic CRL fetching using HTTP
  LIBCURL=1


3.5 Compiling and Installing FreeS/WAN with X.509
    ---------------------------------------------

After you have applied the X.509 patch, compilation and installation is done
in exactly the same way as with standard FreeS/WAN. Please consult the
FreeS/WAN documentation for the details.

In order to compile and install the userland programs, change into the
FreeS/WAN top source directory and type

    make programs

followed by

    make install.

With the introduction of the protocol and port selectors in version 0.9.16
it is now also necessary to recompile the kernel part of FreeS/WAN. If
you want to build KLIPS as a module then you can do this with the command

    make module

After successful module compilation, copy the module

   ./linux/net/ipsec/ipsec.o

into the directory

   /lib/modules/<kernel version>/kernel/net/ipsec

As a last step you must restart IPsec to enable the X.509 features

    ipsec setup restart


4. Configuring the connections - ipsec.conf
   ----------------------------------------

4.1 Configuring my side
    -------------------

Usually the local side is the same for all connections. Therefore it makes
sense to put the definitions characterizing the FreeS/WAN security gateway into
the conn %default section of the configuration file /etc/ipsec.conf. If we
assume throughout this document that the FreeS/WAN security gateway is left and
the peer is right then we can write

conn %default
     # use RSA based authentication with certificates
     authby=rsasig
     rightrsasigkey=%cert
     # my side is left - the freeswan security gateway
     left=160.85.22.2
     leftcert=pulpoCert.pem
     # load connection definitions automatically
     auto=add

The X.509 certificate by which the FreeS/WAN security gateway will authenticate
itself by sending it in binary form to its peers as part of the Internet Key
Exchange (IKE) is specified in the line

     leftcert=pulpoCert.pem

The certificate can either be stored in base64 PEM-format or in the binary
DER-format. Irrespective of the file suffix, Pluto "automagically" determines
the correct format. Therefore

     leftcert=pulpoCert.der

or

     leftcert=pulpoCert.cer

would also be valid alternatives.

When using relative pathnames as in the examples above, the certificate files
must be stored in in the directory /etc/ipsec.d/certs. In order to distinguish
FreeS/WAN's own certificates from locally stored trusted peer certificates
(see section 5.5 for details), they could also be stored in a subdirectory
below /etc/ipsec.d/certs as e.g. in

    leftcert=mycerts/pulpoCert.pem

Absolute pathnames are also possible as in

    leftcert=/usr/ssl/certs/pulpoCert.pem

As an ID for the VPN gateway we recommend the use of a Fully Qualified Domain
Name (FQDN) of the form

conn rw
     right=%any
     leftid=@pulpo.strongsec.com

Important: When an FQDN identifier is used it must be explicitly included as a
so called subjectAltName of type dnsName (DNS:) in the certificate indicated
by leftcert. For details on how to generate certificates with subjectAltNames,