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

     X.509 - Version 1.4.8

Contents

   1. Summary
   2. Acknowledgements
   3. Installation
	3.1 The X.509 distribution
	3.2 Installing the X.509 patch
	3.3 Enabling dynamic LDAP URL fetching
	3.4 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
	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 Update of certificates and CRLs
	5.4 CRL policy
	5.5 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  (NEW)
	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. Smartcard Support
	8.1 Compiling FreeS/WAN with smartcard support
	8.2 Configuring a smartcard-based connection
	8.3 Entering the PIN code
	8.4 Configuring a smartcard using pkcs15-init
   9. Configuring the clients
	9.1 FreeS/WAN
	9.2 PGPnet
	9.3 Safenet/Soft-PK/Soft-Remote
	9.4 SSH Sentinel
	9.5 Windows 2000/XP
  10. Monitoring functions
  11. Firewall support functions
       11.1 Environment variables in the updown script
       11.2 Sample updown script for iptables
  12. Using the patch with standard FreeS/WAN
  13. Using the patch with OpenPGP certificates
       13.1 OpenPGP certificates
       13.2 OpenPGP private keys
       13.3 Monitoring functions
       13.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
    section 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 brings smartcard support. The functionality is base on
    the PKCS#15 cryptotoken interface provided by the OpenSC project.
    For details see section 8.

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.


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

Major contributions to the X.509 patch for Linux FreeS/WAN have come from
Marco Bertossa, Andreas Hess, Patric Lichtsteiner, Andreas Schleiss, and
Roger Wegmann, all present or former students of the Zurich University of
Applied Sciences in Winterthur (Switzerland). The support of Virtual IPs
and the DHCP-over-IPsec protocol has been developed and coded by Mario Strasser,
former research assistant at the ZHW. Smartcard support has been provided
by the ZHW students Christoph Gysin and Simon Zwahlen.
 
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.

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 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 LDAP URL fetching
    ----------------------------------
    
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.

'http', 'ftp', and 'file' URLs are fetched using the 'curl' command line
tool. LDAP source code support is not required for these URLs.



3.4 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

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 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,
please refer to section 7.2.

If you don't want to mess with subjectAltNames, you can use the certificate's
Distinguished Name (DN) instead, which is an identifier of type DER_ASN1_DN
and which can be written e.g. in the LDAP-type format

conn rw
     right=%any
     leftid="C=CH, O=strongSec GmbH, CN=pulpo.strongsec.com"

Since the subject's DN is part of the certificate, the leftid does not have to
be declared explicitly. Thus the entry

conn rw
     right=%any

automatically assumes the subject DN of leftcert to be the host ID.


4.2 Multiple certificates
    ---------------------

Starting with version 0.9.10, the X.509 patch supports multiple local host
certificates and corresponding RSA private keys:

conn rw1
     right=%any
     rightid=@peer1.domain1
     leftcert=myCert1.pem
     # leftid is DN of myCert1

conn rw2
     right=%any
     rightid=@peer2.domain2
     leftcert=myCert2.pem
     # leftid is DN of myCert2

When peer1 initiates a connection then FreeS/WAN will send myCert1 and will
sign with myKey1 defined in /etc/ipsec.secrets (see section 6.2) whereas
myCert2 and myKey2 will be used in a connection setup started from peer2.


4.3 Configuring the peer side using CA certificates
    -----------------------------------------------

Now we can proceed to define our connections. In many applications we might
have dozens of mostly Windows-based road warriors connecting to a central
FreeS/WAN security gateway. The following most simple statement:

conn rw
     right=%any

defines the general roadwarrior case. The line right=%any literally means that
any IPSec peer is accepted, regardless of its current IP source address and its
ID, as long as the peer presents a valid X.509 certificate signed by a CA the
FreeS/WAN security gateway puts explicit trust in. Additionally the signature
during IKE main mode gives proof that the peer is in possession of the private
RSA key matching the public key contained in the transmitted certificate.

The ID by which a peer is identifying itself during IKE main mode can by any of
the ID types IPV4_ADDR, FQDN, USER_FQDN or DER_ASN1_DN. If one of the first
three ID types is used, then the accompanying X.509 certificate of the peer
must contain a matching subjectAltName field of the type ipAddress (IP:),
dnsName (DNS:) or rfc822Name (email:), respectively. With the fourth type
DER_ASN1_DN the identifier must completely match the subject field of the
peer's certificate. One of the two possible representations of a
Distinguished Name (DN) is the LDAP-type format

     rightid="C=CH, O=strongSec GmbH, CN=wroclaw.strongsec.com"

Additional whitespace can be added everywhere as desired since it will be
automatically eliminated by the X.509 parser. An exception is the single
whitespace between individual words , like e.g. in strongSec GmbH, which is
preserved by the parser.

The Relative Distinguished Names (RDNs) can alternatively be separated by a
slash '/' instead of a comma ','

     rightid="/C=CH/O=strongSec GmbH/CN=wroclaw.strongsec.com"

This is the representation extracted from the certificate by the OpenSSL
command line option

     openssl x509 -in wroclawCert.pem -noout -subject

The following RDNs are supported by the X.509 patch

+-----------------------------------------------+
| DC           Domain Component                 |
|-----------------------------------------------|
| C            Country                          |
|-----------------------------------------------|
| ST           State or province                |
|-----------------------------------------------|
| L            Locality or town                 |
|-----------------------------------------------|
| O            Organisation                     |
|-----------------------------------------------|
| OU           Organisational Unit              |
|-----------------------------------------------|
| CN           Common Name                      |
|-----------------------------------------------|
| ND           NameDistinguisher, used with CN  |
|-----------------------------------------------|
| N            Name                             |
|-----------------------------------------------|
| G            Given name                       |
|-----------------------------------------------|
| S            Surname                          |
|-----------------------------------------------|
| I            Initials                         |
|-----------------------------------------------|
| T            Personal title                   |
|-----------------------------------------------|
| E            E-mail                           |
|-----------------------------------------------|
| Email        E-mail                           |
|-----------------------------------------------|
| emailAddress E-mail                           |
|-----------------------------------------------|
| SN           Serial number                    |
|-----------------------------------------------|
| serialNumber Serial number                    |
|-----------------------------------------------|
| D            Description                      |
|-----------------------------------------------|
| ID           X.500 Unique Identifier          |
|-----------------------------------------------|
| UID          User ID                          |
|-----------------------------------------------|
| TCGID        [Siemens] Trust Center Global ID |
+-----------------------------------------------+

With the roadwarrior connection definition listed above, an IPsec SA for
the FreeS/WAN security gateway pulpo.strongsec.com itself can be established.
If any roadwarrior should be able to reach e.g. the two subnets 10.0.1.0/24
and 10.0.3.0/24 behind the security gateway then the following connection
definitions will make this possible

conn rw1
     right=%any
     leftsubnet=10.0.1.0/24

conn rw3
     right=%any
     leftsubnet=10.0.3.0/24

If not all peers in possession of a X.509 certificate signed by a specific
certificate authority shall be given access to the Linux security gateway,
then either a subset of them can be barred by listing the serial numbers of
their certificates in a certificate revocation list (CRL) as specified in
section 5.2 or as an alternative, access can be controlled by explicitly
putting a roadwarrior entry for each eligible peer into ipsec.conf:

conn soggy
     right=%any
     rightid=@soggy.strongsec.com

conn ewa
     right=%any
     rightid=ewa@strongsec.com

conn wroclaw
     right=%any
     rightid="C=CH, O=strongSec GmbH, CN=wroclaw.strongsec.com"

When the IP address of a peer is known to be stable, it can be specified as
well. This entry is mandatory when the FreeS/WAN host wants to act as the
initiator an IPSec connection.

conn soggy
     right=160.85.22.3
     rightid=@soggy.strongsec.com

conn ewa
     right=160.85.22.8
     rightid=ewa@strongsec.com

conn wroclaw
     right=160.85.22.8
     rightid="C=CH, O=strongSec GmbH, CN=wroclaw.strongsec.com"

conn frosch
     right=160.85.22.5

In the last example the ID types FQDN, USER_FQDN, DER_ASN1_DN and IPV4_ADDR,
respectively, were used. Of course all connection definitions presented so far
have included the lines in the conn %defaults section, comprising among other
a left and leftcert entry, as well as a  rightrsasigkey parameter set to the
magic value %cert , signifying that the public key will be extracted from a
X.509 certificates sent by the peer.


4.4 Handling Virtual IPs and wildcard subnets
    -----------------------------------------

Often roadwarriors are behind NAT-boxes with IPsec passthrough, which causes
the inner IP source address of an IPsec tunnel to be different from the
outer IP source address usually assigned dynamically by the ISP.
Whereas the varying outer IP address can be handled by the right=%any
construct, the inner IP address or subnet must always be declared in a
connection definition. Therefore for the three roadwarriors rw1 to rw3
connecting to a FreeS/WAN security gateway the following entries are
required in /etc/ipsec.conf:

conn rw1
	right=%any
	righsubnet=10.0.1.5/32

conn rw2
	right=%any
	rightsubnet=10.0.1.5.47/32

conn rw3
	right=%any
	rightsubnet=10.0.1.128/28

With the wildcard parameter rightsubnetwithin these three entries can be
reduced to the single connection definition

conn rw
	right=%any
	rightsubnetwithin=10.0.1.0/24

Any host will be accepted (of course after successful authentication based on
the peer's X.509 certificate only) if it declares a client subnet lying totally
within the brackets defined by the wildcard subnet definition (in our example
10.0.1.0/24). For each roadwarrior a connection instance tailored to the
subnet of the particular client will be created,based on the generic
rightsubnetwithin template.

This new feature introduced with version 0.9.12 of the X.509 patch can also be
helpful with VPN clients getting a dynamically assigned inner IP from a DHCP
server located on the NAT router box.


4.5 Protocol and Port Selectors
    ---------------------------

The X.509 patch has been combined with the selectors patch to offer the
possibility to restrict the protocol and optionally the ports in an IPsec
SA using the rightprotoport and leftprotoport parameter. Some examples:

    conn icmp
         right=%any
         rightprotoport=icmp
         left=%defaultroute
         leftid=@pluto.strongsec.com
         leftprotoport=icmp

    conn http
         right=%any
         rightprotoport=6
         left=%defaultroute
         leftid=@pluto.strongsec.com
         leftprotoport=6/80

    conn dhcp
         right=%any
         rightprotoport=udp/bootpc
         left=%defaultroute
         leftid=@pluto.strongsec.com
         leftsubnet=0.0.0.0/0  #allows DHCP discovery broadcast
         leftprotoport=udp/bootps
         rekey=no
         keylife=20s
         rekeymargin=10s
         auto=add

Protocols and ports can be designated either by their numerical values
or by their acronyms defined in /etc/services.

    ipsec auto --status

shows the following connection definitions:

"icmp": 160.85.106.10[@pulpo.strongsec.com]:1/0...%any:1/0
"http": 160.85.106.10[@pulpo.strongsec.com]:6/80...%any:6/0
"dhcp": 0.0.0.0/0===160.85.106.10[@pulpo.strongsec.com]:17/67...%any:17/68

Based on the protocol and port selectors appropriate eroutes will be set
up, so that only the specified payload types will pass through the IPsec
tunnel.


4.6 IPsec policies based on wildcards
    ---------------------------------

In large VPN-based remote access networks there is often a requirement that
access to the various parts of an internal network must be granted selectively,
e.g. depending on the group membership of the remote access user. Version 0.9.24
of the X.509 patch makes this possible by applying wildcard filtering on the
VPN user's distinguished name (ID_DER_ASN1_DN).

Let's make a practical example:
 
An organization has a sales department (OU=Sales) and a research group
(OU=Research). In the company intranet there are separate subnets for Sales
(10.0.0.0/24) and Research (10.0.1.0/24) but both groups share a common web
server (10.0.2.100). The VPN clients use Virtual IP addresses that are either
assigned statically or via DHCP-over-IPsec. The sales and research departments
use IP addresses from separate DHCP address pools (10.1.0.0/24) and (10.1.1.0/24),
respectively. An X.509 certificate is issued to each employee, containing in its
subject distinguished name the country (C=CH), the company (O=ACME),
the group membership(OU=Sales or OU=Research) and the common name (e.g.
CN=Bart Simpson).

The IPsec policy defined above can now be enforced with the following three
IPsec security associations:

    conn sales
         right=%any
	 rightid="C=CH, O=ACME, OU=Sales, CN=*"
	 rightsubnetwithin=10.1.0.0/24  # Sales DHCP range
	 leftsubnet=10.0.0.0/24         # Sales subnet

   conn research
	right=%any
	rightid="C=CH, O=ACME, OU=Research, CN=*"
	rightsubnetwithin=10.1.1.0/24   # Research DHCP range
	leftsubnet=10.0.1.0/24          # Research subnet

   conn web
	right=%any
	rightid="C=CH, O=ACME, OU=*, CN=*"
	rightsubnetwithin=10.1.0.0/23   # Remote access DHCP range
	leftsubnet=10.0.2.100/32        # Web server
	rightprotoport=tcp              # TCP protocol only
	leftprotoport=tcp/http          # TCP port 80 only

Of course group specific tunneling could be implemented on the
basis of the Virtual IP range specified by the rightsubnetwithin
parameter alone, but the wildcard matching mechanism guarantees that
only authorized user can access the corresponding subnets.

The '*' character is used as a wildcard in relative distinguished names (RDNs).
In order to match a wildcard template, the ID_DER_ASN1_DN of a peer must contain
the same number of RDNs (selected from the list in section 4.3) appearing in the
exact order defined by the template.

    "C=CH, O=ACME, OU=Research, OU=Special Effects, CN=Bart Simpson"

matches the templates

    "C=CH, O=ACME, OU=Research, OU=*, CN=*"

    "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*"

    "C=CH, O=ACME, OU=*, OU=*, CN=*"

but not the template

    "C=CH, O=ACME, OU=*, CN=*"

which doesn't have the same number of RDNs.


4.7 IPsec policies based on CA certificates
    ---------------------------------------

As an alternative to the wildcard based IPsec policies described in section 4.6,
access to specific client host and subnets can abe controlled on the basis of
the CA that issued the peer certificate


   conn sales
         right=%any
	 rightca="C=CH, O=ACME, OU=Sales, CN=Sales CA"
	 rightsubnetwithin=10.1.0.0/24  # Sales DHCP range
	 leftsubnet=10.0.0.0/24         # Sales subnet

   conn research
	right=%any
	rightca="C=CH, O=ACME, OU=Research, CN=Research CA"
	rightsubnetwithin=10.1.1.0/24   # Research DHCP range
	leftsubnet=10.0.1.0/24          # Research subnet

   conn web
	right=%any
	rightca="C=CH, O=ACME, CN=ACME Root CA"
	rightsubnetwithin=10.1.0.0/23   # Remote access DHCP range
	leftsubnet=10.0.2.100/32        # Web server
	rightprotoport=tcp              # TCP protocol only
	leftprotoport=tcp/http          # TCP port 80 only

In the example above, the connection "sales" can be used by peers
presenting certificates issued by the Sales CA, only. In the same way,
the use of the connection "research" is restricted to owners of certificates
issued by the Research CA. The connection "web" is open to both "Sales" and
"Research" peers because the required "ACME Root CA" is the issuer of the
Research and Sales intermediate CAs. If no rightca parameter is present
then any valid certificate issued by one of the trusted CAs in
/etc/ipsec.d/cacerts can be used by the peer.

The leftca parameter usually doesn't have to be set explicitely because
by default it is set to the issuer field of the certificate loaded via
leftcert. The statement

   rightca=%same
    
sets the CA requested from the peer to the CA used by the left side itself
as e.g. in

   conn sales
        right=%any
	rightca=%same
	leftcert=mySalesCert.pem


4.8 Sending certificate requests
    ----------------------------

The presence of a rightca parameter also causes the CA to be sent as
part of the certificate request message when FreeS/WAN is the initiator.
As a responder FreeS/WAN sends the desired CA only for non-roadwarrior
connections.


5. Configuring certificates and CRLs
   ---------------------------------


5.1 Installing the CA certificates
    ------------------------------

X.509 certificates received by FreeS/WAN during the IKE protocol are
automatically authenticated by going up the trust chain until a self-signed
root CA certificate is reached. Usually host certificates are directly signed
by a root CA, but the X.509 patch version 0.9 also supports multi-level
hierarchies with intermediate CAs in between. All CA certificates belonging
to a trust chain must be copied in either binary DER or base64 PEM format
into the directory

     /etc/ipsec.d/cacerts

Multiple CAs are supported, but presently they just create a large pool of
valid user or host certificates and cannot be assigned to specific connection
definitions in /etc/ipsec.conf.


5.2 Installing optional certificate revocation lists (CRLs)
    -------------------------------------------------------

By copying a CA certificate into /etc/ipsec.d/cacerts, automatically all user
or host certificates issued by this CA are declared valid. Unfortunately
private keys might get compromised inadvertently or intentionally, personal
certificates of users leaving a company have to be blocked immediately, etc.
To this purpose certificate revocation lists (CRLs) have been created. CRLs
contain the serial numbers of all user or host certificates that have been
revoked due to various reasons.

After successful verification of the X.509 trust chain, Pluto searches the
directory

     /etc/ipsec.d/crls

for the presence of a CRL issued by the CA that has signed the certificate.
If the serial number of the certificate is found in the CRL then the public key
contained in the certificate is declared invalid and the IPSec SA will not be
established. If no CRL is found in the crls directory or if the deadline
defined in the nextUpdate field of the CRL has been reached, a warning is
issued but the public key will nevertheless be accepted. CRLs must be stored
either in binary DER or base64 PEM format in the crls directory.
Section 7.3 will explain in detail how CRLs can be created using OpenSSL.


5.3 Update of certificates and CRLs
    -------------------------------

Pluto reads certificates and CRLs from their respective files during system
startup and keeps them in memory in the form of chained lists. X.509
certificates have a finite life span defined by their validity field. Therefore
it must be possible to replace host and CA certificates kept in system memory
without disturbing established ISAKMP SAs. Certificate revocation lists should
also be updated in the regular intervals indicated by the nextUpdate field in
the CRL body. The following interactive commands allow the manual replacement
of the various files:

+----------------------------------------------------------------------------+
| ipsec auto --rereadsecrets  reload file /etc/ipsec.secrets                 |
|----------------------------------------------------------------------------|
| ipsec auto --rereadcacerts  reload files in /etc/ipsec.d/cacerts directory |
|----------------------------------------------------------------------------|
| ipsec auto --rereadcrls     reload files in /etc/ipsec.d/crls directory    |
|----------------------------------------------------------------------------|
| ipsec auto --rereadall      ipsec auto --rereadsecrets                     |
|                                        --rereadcacerts                     |
|                                        --rereadcrls                        |
+----------------------------------------------------------------------------+

Starting with version 1.1.0 of the X.509 patch, CRLs can be automatically
fetched from an HTTP or LDAP server using the CRL distribution points contained
in X.509 certificates. The command

    ipsec auto --listcrls
    
shows any pending fetch requests:

  Oct 31 00:29:53 2002, trials: 2
         issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         distPts: 'http://www.strongsec.com/ca/cert.crl'
	          'ldap://ldap.strongsec.com/o=strongSec GmbH, c=CH
		     ?certificateRevocationList?base
		     ?(objectClass=certificationAuthority)'

In the example above, an http and an ldap URL were extracted from a received
end certificate. An independent thread then tries to fetch a CRL from the
designated distribution points. The same thread also periodically checks
if any loaded CRLs are about to expire. The check interval can be defined in
the "config setup" section of the ipsec.conf file:

    config setup
        crlcheckinterval=600

In our example the thread wakes up every 600 seconds or 10 minutes in order
to check the validity of the CRLs or to retry any pending fetch requests:

  List of X.509 CRLs:
  
  Dec 19 09:35:31 2002, revoked certs: 40
         issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         distPts: 'http://www.strongsec.com/ca/cert.crl'
         updates:  this Dec 19 09:35:00 2002
                   next Dec 19 10:35:00 2002 warning (expires in 19 minutes)

  List of fetch requests:

  Dec 19 10:15:31 2002, trials: 1
        issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
        distPts: 'http://www.strongsec.com/ca/cert.crl'

The first trial to update a CRL is started 2*crlcheckinterval before the
nextUpdate time, i.e. when less than 20 minutes are left in our practical
example. When crlcheckinterval is set to 0 (this is also the default value
when the parameter is not set in ipsec.conf) then the CRL checking and updating 
thread is not started and dynamic CRL fetching is disabled.


5.4 CRL Policy
    ----------

By default Pluto is quite tolerant concerning the handling of CRLs. It is not
mandatory for a CRL to be present in /etc/ipsec.d/crls and if the expiration
date defined by the nextUpdate field of a CRL has been reached just a warning
is issued but a peer certificate will always be accepted if it has not been
revoked.

If you want to enforce a stricter CRL policy then you can do this by setting
the "strictcrlpolicy" option. This is done in the "config setup" section
of the ipsec.conf file:

    config setup
          strictcrlpolicy=yes
          ...

A certificate received from a peer will not be accepted if no corresponding
CRL is present in /etc/ipsec.conf. And if an ISAKMP SA re-negotiation takes
place after the nextUpdate deadline has been reached, the peer certificate
will be declared invalid and the cached RSA public key will be deleted
causing the connection in question to fail. Therefore if you are going to use
the "strictcrlpolicy=yes" option make sure that the CRLs will always be updated
in time. Otherwise a total standstill would ensue.

As mentioned earlier the default setting is "strictcrlpolicy=no"


5.5 Configuring the peer side using locally stored certificates
    -----------------------------------------------------------

If you don't want to use trust chains based on CA certificates as proposed in
section 4.3 you can alternatively import trusted peer certificates directly
into Pluto. Thus you do not have to rely on the certificate to be transmitted
by the peer as part of the IKE protocol.

With the conn %default section defined in section 4.1 and the use of the
rightcert keyword for the peer side, the connection definitions in section 4.3
can alternatively be written as

    conn soggy
          right=%any
          rightid=@soggy.strongsec.com
          rightcert=soggyCert.cer

     conn wroclaw
          right=160.85.22.8
          rightcert=wroclawCert.der

If a peer certificate contains a subjectAltName extension, then an alternative
rightid type can be used, as the example "conn soggy" shows. If no rightid
entry is present then the subject distinguished name contained in the
certificate is taken as the ID.

Using the same rules concerning pathnames that apply to FreeS/WAN's own
certificates, the following two definitions are also valid for trusted peer
certificates:

    rightcert=peercerts/wroclawCert.der

or 

    rightcert=/usr/ssl/certs/wroclawCert.der


6. Installing the private key - ipsec.secrets
   ------------------------------------------

6.1 Loading private key files in PKCS#1 format
    ------------------------------------------

Starting with version 0.9.8 of the X.509 patch, Pluto has been enabled to
load RSA private keys in the PKCS#1 file format. The key files can be
optionally secured with a passphrase.

RSA private key files are declared in /etc/ipsec.secrets using the syntax

    : RSA <my keyfile> "<optional passphrase>"

The key file can be either in base64 PEM-format or binary DER-format. The
actual coding is detected "automagically" by Pluto. The example

    : RSA pulpoKey.pem

uses a relative pathname. In this case Pluto will look for the key file
in the directory

    /etc/ipsec.d/private

As an alternative an absolute pathname can be given as in

    : RSA /usr/ssl/private/pulpoKey.pem

In both cases make sure that the key files are root readable only.

Often a private key must be transported from the Certification Authority
where it was generated to the target security gateway where it is going
to be used. In order to protect the key it can be encrypted with 3DES
using a symmetric transport key derived from a cryptographically strong
passphrase.

    openssl genrsa -des3 -out pulpoKey.pem 1024

Because of the weak security, key files protected by single DES will not
be accepted by Pluto!!!

Once on the security gateway the private key can either be permanently
unlocked so that it can be used by Pluto without having to know a
passphrase

    openssl rsa -in pulpoKey.pem -out pulpoKey.pem

or as an option the key file can remain secured. In this case the passphrase
unlocking the private key must be added after the pathname in
/etc/ipsec.secrets

    : RSA pulpoKey.pem "This is my passphrase"

Some CAs distribute private keys embedded in a PKCS#12 file. Since Pluto
is not able yet to read this format directly, the private key part must
first be extracted using the command

     openssl pkcs12 -nocerts -in pulpoCert.p12 -out pulpoKey.pem

if the key file pulpoKey.pem is to be secured again by a passphrase, or

     openssl pkcs12 -nocerts  -nodes -in pulpoCert.p12 -out pulpoKey.pem

if the private key is to be stored unlocked.


6.2 Entering passphrases interactively
    ----------------------------------
    
On a VPN gateway you would want to put the passphrase protecting the private
key file right into /etc/ipsec.secrets as described in the previous paragraph,
so that the gateway can be booted in unattended mode. The risk of keeping
unencrypted secrets on a server can be minimized by putting the box into a
locked room. As long as no one can get root access on the machine the private
keys are safe.
    
On a mobile laptop computer the situation is quite different. The computer can
be stolen or the user is leaving it unattended so that unauthorized persons
can get access to it. In theses cases it would be preferable not to keep any
passphrases openly in /etc/ipsec.secrets but to prompt for them interactively
instead. This is easily done by defining

    : RSA pulpoKey.pem %prompt
    
Since FreeS/WAN is usually started during the boot process, usually no
interactive console windows is available which can be used by Pluto to
prompt for the passphrase. This must be initiated by the user by typing

    ipsec secrets
    
which actually is an alias for the existing command

    ipsec auto --rereadsecrets

and which causes the prompt

    need passphrase for '/etc/ipsec.d/private/pulpoKey.pem'
    Enter:

to appear. If the passphrase was correct and the private key file could be
successfully decrypted then

    valid passphrase
    
results. Otherwise the prompt

   invalid passphrase, please try again
   Enter:

will give you another try. Entering a carriage return will abort the
the passphrase prompting.


6.3 Multiple private keys
    ---------------------

Starting with version 0.9.10 of the X.509 patch, multiple private keys are
supported. Since the connections defined in ipsec.conf can find the correct
private key based on the public key contained in the certificate assigned by
leftcert, default private key definitions without specific IDs can be used

    : RSA myKey1.pem "<optional passphrase1>"

    : RSA myKey2.pem "<optional passphrase2>"


7. Generating certificates and CRLs with OpenSSL
   ---------------------------------------------

This section is not a full-blown tutorial on how to use OpenSSL. It just lists
a few points that are relevant if you want to generate your own certificates
and CRLs for use with FreeS/WAN.


7.1 Generating a CA certificate
    ---------------------------

The OpenSSL statement

     openssl req -x509 -days 1460 -newkey rsa:2048 \
                 -keyout caKey.pem -out caCert.pem

creates a 2048 bit RSA private key caKey.pem and a self-signed CA certificate
caCert.pem with a validity of 4 years (1460 days).

     openssl x509 -in cert.pem -noout -text

lists the properties of  a X.509 certificate cert.pem. It allows you to verify
whether the configuration defaults in openssl.cnf have been inserted correctly.

If you prefer the CA certificate to be in binary DER format then the following
command achieves this transformation:

     openssl x509 -in caCert.pem -outform DER -out caCert.der

The directory /etc/ipsec.d/cacerts contains all required CA certificates either
in binary DER or in base64 PEM format. Irrespective of the file suffix, Pluto
"automagically" determines the correct format.


7.2 Generating a host or user certificate
    -------------------------------------

The OpenSSL statement

     openssl req -newkey rsa:1024 -keyout hostKey.pem \
                 -out hostReq.pem

generates a 1024 bit RSA private key hostKey.pem and a certificate request
hostReq.pem which has to be signed by the CA.

If you want to add a subjectAltName field to the host certificate you must edit
the OpenSSL configuration file openssl.cnf and add the following line in the
[ usr_cert ] section:

     subjectAltName=DNS:soggy.strongsec.com

if you want to identify the host by its Fully Qualified Domain Name (FQDN ), or

     subjectAltName=IP:160.85.22.3

if you want the ID to be of type IPV4_ADDR. Of course you could include both
ID types with

     subjectAltName=DNS:soggy.strongsec.com,IP:160.85.22.3

but the use of an IP address for the identification of a host should be
discouraged anyway.

For user certificates the appropriate ID type is USER_FQDN which can be
specified as

     subjectAltName=email:ewa@strongsec.com

or if the user's e-mail address is part of the subject's distinguished name

     subjectAltName=email:copy

Now the certificate request can be signed by the CA with the command

     openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext

If you omit the -days option then the default_days value (365 days) specified
in openssl.cnf is used. The -notext option avoids that a human readable
listing of the certificate is prepended to the base64 encoded certificate
body.

If you want to use the dynamic CRL fetching feature described in section 4.7
then you must include one or several crlDistributionPoints in your end
certificates. This can be done in the [ usr_cert ] section of the openssl.cnf
configuration file:

    crlDistributionPoints= @crl_dp

    [ crl_dp ]

    URI.1="http://www.strongsec.com/ca/cert.crl"
    URI.2="ldap://ldap.strongsec.com/o=strongSec GmbH, c=CH
      ?certificateRevocationList?base?(objectClass=certificationAuthority)"

If you have only a single http distribution point then the short form

    crlDistributionPoints="URI:http://www.strongsec.com/ca/cert.crl"

also works. Due to a known bug in OpenSSL this notation fails with ldap URIs.

Usually a Windows-based VPN client needs its private key, its host or
user certificate, and the CA certificate. The most convenient way to load
this information is to put everything into a  PKCS#12 file:

     openssl pkcs12 -export -inkey hostKey.pem \
                    -in hostCert.pem -name "soggy" \
                    -certfile caCert.pem -caname "Root CA" \
                    -out hostCert.p12


7.3 Generating a CRL
    ----------------

An empty CRL that is signed by the CA can be generated with the command

     openssl ca -gencrl -crldays 15 -out crl.pem

If you omit the -crldays option then the default_crl_days value (30 days)
specified in openssl.cnf is used.

If you prefer the CRL to be in binary DER format then this conversion
can be achieved with

     openssl crl -in crl.pem -outform DER -out cert.crl

The directory /etc/ipsec.d/crls contains all CRLs either in binary DER
or in base64 PEM format. Irrespective of the file suffix, Pluto
"automagically" determines the correct format.


7.4 Revoking a certificate
    ----------------------

A specific host certificate stored in the file host.pem is revoked with the
command

     openssl ca -revoke host.pem

Next the CRL file must be updated

     openssl ca -gencrl -crldays 60 -out crl.pem

The content of the CRL file can be listed with the command

     openssl crl -in crl.pem -noout -text

in the case of a base64 CRL, or alternatively for a CRL in DER format

     openssl crl -inform DER -in cert.crl -noout -text


8. Smartcard Support
   -----------------

8.1 Compiling FreeS/WAN with smartcard support
    ------------------------------------------

By default smartcard support will not be compiled into Pluto. In order to
enable smartcard-based authentication the following line must be uncommented
in the programs/pluto/Makefile:

  #Uncomment this line to enable smartcard support
  SMARTCARD=1

Compilation will be successful only if the OpenSC header files and the opensc
library available from http://www.opensc.org are present. Currently
opensc-0.7.0 and opensc-0.8.0 using pcsc-lite, usbtoken or openct drivers
are supported.


8.2 Configuring a smartcard-based connection
    ----------------------------------------
    
Defining a smartcard-based connection in ipsec.conf is easy:

    conn tandoori
         right=160.85.22.10
	 rightid=@tandoori.strongsec.com
	 rightrsasigkey=%cert
	 left=%defaultroute
	 leftcert=%smartcard
	 auto=add

In most cases there is a single smartcard reader or cryptotoken and only one
RSA private key safely stored on the crypto device. Thus the default entry

    leftcert=%smartcard
     
which stands for the full notation
    
    leftcert=%smartcard0:45
    
is sufficient. The general notation

   leftcert=%smartcard<reader nr>:<PKCS#15 key id>

supports the simultaneous use of several smartcard readers and cryptotoken
and can access multiple RSA private keys and corresponding X.509 certificates
stored on a crypto device.


8.3 Entering the PIN code
    ---------------------
    
Since the smartcard signing operation needed to sign the hash with the
RSA private key during IKE Main Mode is protected by a PIN code,
the secret PIN must be made available to Pluto.

For gateways that must be able to start IPsec tunnels automatically in
unattended mode after a reboot, the secret PIN  can be stored statically
in ipsec.secrets

   : PIN %smartcard "12345678"
  
or with the general notation

   : PIN %smartcard<reader nr>:<PKCS#15 key id> "<PIN code>"
  
On personal notebooks that could get stolen, you wouldn't want to store
your PIN in ipsec.secrets. Thus the alternative form

   : PIN %smartcard %prompt
  
will prompt you for the PIN when you start up the first IPsec connection
using the command

   ipsec auto --up tandoori
  
The auto command calls the whack function which in turn communicates with
Pluto over a socket. Since the whack function call is executed from a command
window, Pluto can prompt you for the PIN over this socket connection.
Unfortunately roadwarrior connections which just wait passively for peers
cannot be initiated via the command window:

   conn rw
         right=%any
	 rightrsasigkey=%cert
	 left=%defaultroute
	 leftcert=%smartcard1:50
	 auto=add

But if there is a corresponding entry

   : PIN %smartcard1:50 %prompt
  
in ipsec.secrets, then the standard command

   ipsec auto --rereadsecrets
  
or the alias

   ipsec secrets
   
can be used to enter the PIN code for this connection interactively.

The command

   ipsec auto --listcards

can be executed at any time to check the current status of the PIN code[s].


8.4 Configuring a smartcard with pkcsc15-init
    -----------------------------------------

FreeS/WAN's smartcard solution is based on the PKCS#15 "Cryptographic Token
Information Format Standard" fully supported by OpenSC library functions.
Using the command

    pkcs15-init --create-pkcs15 --profile pkcs15

a fresh PKCS#15 file structure is created on a smartcard or cryptotoken.
With the next command

    pkcs15-init --auth-id 1 --store-pin --pin "12345678" --puk "87654321"
                --label "my PIN"

a secret PIN code with auth-id 1 is stored in an unretrievable location on
the smart card. The PIN will protect the RSA signing operation. If the PIN
is entered incorrectly more than three times the smartcard will be locked
and the PUK code can be used to unlock the card again.

Next the RSA private key is transferred to the smartcard

    pkcs15-init --auth-id 1 --store-private-key myKey.pem [--id 45]

By default the PKCS#15 smartcard record will be assigned the id 45.
Using the --id option multiple key records can be stored on a smartcard.

At last we load the matching X.509 certificate onto the smartcard

    pkcs15-init --auth-id 1 --store-certificate myCert.pem [--id 45]

The pkcs15-tool can now be used to verify the contents of the smartcard.

   pkcs15-tool --list-pins --list-keys --list-certificates

If everything is ok then you are ready to use the generated PKCS#15
structure with FreeS/WAN.


9. Configuring the clients
   -----------------------

9.1 FreeS/WAN
    ---------

A FreeS/WAN to FreeS/WAN connection is symmetrical. Any of the four defined
ID types can be used, even different types on either end of the connection,
although this wouldn't make much sense.

+--------------------------------------------------------------+
| Connection Definition        ID type          subjectAltName |
|--------------------------------------------------------------|
| rightid  (FreeS/WAN)         DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
|--------------------------------------------------------------|
| leftid   (FreeS/WAN)         DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


9.2 PGPnet
    ------

Use the file peerCert.p12 to import PGPnet's X.509 certificate, the CA
certificate, plus the encrypted private key in binary PKCS#12 format into the
PGPkey tool. You will be prompted for the passphrase securing the private key.

Use the file myCert.pem to import the X.509 certificate of the FreeS/WAN
security gateway into the PGPkey tool. The PGPkeyTool does not accept X.509
certificates in binary DER format, so it must be imported in base64 format:

     -----BEGIN CERTIFICATE-----
     M...

     ...
     -----END CERTIFICATE-----

Make sure that there is no human-readable listing of the X.509 certificate in
front of the line

     -----BEGIN CERTIFICATE-----

otherwise PGPnet will refuse to load the *.PEM file. Any surplus lines can
either be deleted by loading the certificate into a text editor or you can
apply the command

     openssl x509 -in myCert.pem -out myCert.pem

to achieve the same effect.

With authentication based on X.509 certificates, PGPnet always sends the ID
type DER_ASN1_DN, therefore rightid in the connection definition of the
FreeS/WAN security gateway must be an ASN.1 distinguished name.

In the receiving direction PGPnet accepts all four ID types from FreeS/WAN.

+--------------------------------------------------------------+
| Connection Definition        ID type          subjectAltName |
|--------------------------------------------------------------|
| rightid  (PGPnet)            DER_ASN1_DN      -              |
|--------------------------------------------------------------|
| leftid   (FreeS/WAN)         DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


9.3 SafeNet/Soft-PK/Soft-Remote
    ---------------------------

SafeNet/Soft-PK and SafeNet/Soft-Remote can be configured to send their
identity either as DER_ASN1_DN, IPV4_ADDR, FQDN, or USER_FQDN.
In the receiving direction SafeNet/Soft-PK and SafeNet/Soft-Remote
accept all four ID types coming from FreeS/WAN.

+--------------------------------------------------------------+
| Connection Definition        ID type          subjectAltName |
|--------------------------------------------------------------|
| rightid  (SafeNet/Soft-PK)   DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
|--------------------------------------------------------------|
| leftid  (FreeS/WAN)          DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


9.4 SSH Sentinel
    ------------

SSH Sentinel sends its identity as DER_ASN1_DN if the subjectAltName field of
its certificate is empty. If a subjectAltName field is present, then the
corresponding type IPV4_ADDR, FQDN, or USER_FQDN is automatically chosen.
With several subjectAltName entries, the precedence of the different ID types
is not quite clear. In the receiving direction SSH Sentinel accepts all four
ID types from FreeS/WAN.

+--------------------------------------------------------------+
| Connection Definition        ID type          subjectAltName |
|--------------------------------------------------------------|
| rightid  (SSH Sentinel)      DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
|--------------------------------------------------------------|
| leftid  (FreeS/WAN)          DER_ASN1_DN      -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


9.5 Windows 2000/XP
    ---------------

Windows 2000 and Windows XP always send the ID type DER_ASN1_DN,
therefore rightid in the connection definition of the FreeS/WAN
security gateway must be an ASN.1 distinguished name.In the
receiving direction Windows 2000/XP accepts all four ID types
from FreeS/WAN.

+--------------------------------------------------------------+
| Connection Definition        ID type          subjectAltName |
|--------------------------------------------------------------|
| rightid  (Windows 2000/XP)   DER_ASN1_DN      -              |
|--------------------------------------------------------------|
| leftid   (FreeS/WAN)         DER_ASN1_D       -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


10. Monitoring functions
    --------------------

The X.509 patch offers the following monitoring functions:

    ipsec auto [--utc] --listpubkeys

This command lists all public keys currently installed in the
chained list of public keys. These keys were statically loaded
from ipsec.conf or aquired either from received certificates
or retrieved from secure DNS servers using opportunistic mode.

The public key listing has the following form:

  Apr 10 00:10:31 2002, 1024 RSA Key AwEAAb8F/,
         until Jun 09 18:29:32 2002 ok
         ID_DER_ASN1_DN 'C=CH, O=strongSec GmbH, CN=soggy.strongsec.com'
         Issuer 'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
  Apr 09 20:57:49 2002, 1024 RSA Key AwEAAbl5j,
         until Feb 13 11:19:25 2003 ok
         ID_USER_FQDN 'Andreas.Steffen@zhwin.ch'
         Issuer 'C=CH, O=ZHW, CN=ZHW Root CA'
  Apr 09 20:57:49 2002, 1024 RSA Key AwEAAbl5j,
         until Feb 13 11:19:25 2003 ok
         ID_USER_FQDN 'sna@zhwin.ch'
         Issuer 'C=CH, O=ZHW, CN=ZHW Root CA'

It consists of

 - the date the public key was installed either in local time or UTC (--utc)
 - the modulus size of the RSA key in bits
 - a keyID consisting of 9 base64 symbols representing the public exponent
   and the most significant bits of the modulus
 - the expiration date of the public key (extracted from the certificate)
 - the type and value of the ID associated with the public key.
 - the issuer of the certificate the public key was extracted from.

A public key can be associated with several IDs, e.g. using subjectAltNames
in certificates and an ID can possess several public keys, e.g. retrieved
from a secure DNS server.


The command

    ipsec auto [--utc] --listcerts

lists all local certificates, both FreeS/WAN's own and those of
trusted peer loaded via leftcert and rightcert, respectively.

The output has the form

  May 01 07:09:47 2002, count: 2
         subject: 'C=CH, O=ZHW, OU=IKT, CN=Andreas Steffen'
         issuer:  'C=CH, O=ZHW, OU=IKT, CN=ZHW Root CA'
	 pubkey:   1024 RSA Key AwEAAbl5j
         validity: not before Feb 13 11:19:25 2002 ok
                   not after  Feb 13 11:19:25 2003 ok
  May 01 07:09:47 2002, count: 10
         subject: 'C=CH, O=strongSec GmbH, CN=pulpo.strongsec.com'
         issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         pubkey:   1024 RSA Key AwEAAfic+, has private key
         validity: not before Jun 09 18:38:04 2001 ok
                   not after  Jun 09 18:38:04 2002 ok

and shows

 - the date the certificate was installed either in local time or UTC (--utc)
 - the count shows how many connections refer to this certificate
 - the subject of the CA certificate
 - the issuer of the CA certificate
 - the size and keyid of the RSA public key contained in the certificate.
   the label "has private key" indicates that a matching RSA private key
   has been found, defined or loaded in ipsec.secrets.
 - the label "on smartcard" indicates that the certificate was loaded from
   a smartcard or cryptotoken and that most probably a matching RSA private
   key also resides on-card.
 - the validity of the CA certificate expressed either in local time or
   UTC (--utc). The validity is checked automatically resulting either
   in an "ok" message or a "fatal" error message.


The command

    ipsec auto [--utc] --listcacerts

lists all CA certificates that have been loaded from /etc/ipsec.d/cacerts.
The output has the form

  May 01 07:09:47 2002, count: 1
         subject: 'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         pubkey:   2048 RSA Key AwEAAcLG1
         validity: not before May 02 23:02:35 2001 ok
                   not after  May 01 23:02:35 2005 ok

and shows

 - the date the CA certificate was installed either in local time or UTC (--utc)
 - the count is always set to 1
 - the subject of the CA certificate
 - the issuer of the CA certificate
 - the size and keyid of the RSA public key contained in the certificate.
 - the validity of the CA certificate expressed either in local time or
   UTC (--utc). The validity is checked automatically resulting either
   in an "ok" message or a "fatal" error message.


The command

    ipsec auto [--utc] --listcrls

lists all CRLs that have been loaded from /etc/ipsec.d/crls.
The output has the form

  Oct 30 22:57:51 2002, revoked certs: 37
         issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         distPts: 'http://www.strongsec.com/ca/cert.crl'
         updates:  this Oct 15 23:42:12 2002
                   next Nov 14 22:42:12 2002 ok

and shows

 - the date the CRL was installed either in local time or UTC (--utc)
 - the number revoked certificates
 - the issuer of the CRL
 - the URLs of the distribution points where the CRL can be fetched from.
 - the dates when the CRL was issued and when the next update
   is expected, respectively, expressed either in local time or
   UTC (--utc). It is automatically checked if the next update
   deadline has passed, resulting either in an "ok" message, a
   a "warning" message when strictcrlpolicy=no or a "fatal" message when
   strictcrlpolicy=yes.


The command

    ipsec auto [--utc] --listcards
    
lists all smartcard records that are currently in use by Pluto.
The output has the form

  Jul 08 17:12:49 2003, count: 2
         reader: 0, id: 50, has no pin
  Jul 08 17:12:50 2003, count: 6
         reader: 0, id: 45, has valid pin

and shows

- the date the certificate was read from the smartcard record
- the count shows how many connections and secret pin entries point
  to the smartcard record
- the smartcard reader or cryptotoken number. With a single reader
  or cryptotoken this number is usually 0.
- the ID of the certificate/private key record. With a single
  certificate this ID is usually 45
- the status of the PIN: no | valid | invalid


The command

    ipsec auto [--utc] -listall

is equivalent to

    ipsec auto [--utc] -listpubkeys
    ipsec auto [--utc] -listcerts
    ipsec auto [--utc] -listcacerts
    ipsec auto [--utc] -listcrls
    ipsec auto [--utc] -listcards


11. Firewall support functions
    --------------------------


11.1 Environment variables in the updown script
     ------------------------------------------

The X.509 patch makes the following environment variables available
in the updown script indicated by the leftupdown option:

+------------------------------------------------------------------+
| Variable               Example                    Comment        |
|------------------------------------------------------------------|
| $PLUTO_PEER_ID         ewa@strongsec.com          USER_FQDN  (1) |
|------------------------------------------------------------------|
| $PLUTO_PEER_PROTOCOL   17                         udp        (2) |
|------------------------------------------------------------------|
| $PLUTO_PEER_PORT       68                         bootpc     (3) |
|------------------------------------------------------------------|
| $PLUTO_PEER_CA         C=CH, O=ACME, CN=Sales CA             (4) |
|------------------------------------------------------------------|
| $PLUTO_MY_ID           @pulpo.strongsec.com       FQDN       (1) |
|------------------------------------------------------------------|
| $PLUTO_MY_PROTOCOL     17                         udp        (2) |
|------------------------------------------------------------------|
| $PLUTO_MY_PORT         67                         bootps     (3) |
+------------------------------------------------------------------+

(1) $PLUTO_PEER_ID/$PLUTO_MY_ID contain the IDs of the two ends
    of an established connection. In our examples these
    correspond to the strings defined by rightid and leftid,
    respectively.

(2) $PLUTO_PEER_PROTOCOL/$PLUTO_MY_PROTOCOL contain the protocol
    defined by the rightprotoport and leftprotoport options,
    respectively. Both variables contain the same protocol value.
    The variables take on the value '0' if no protocol has been defined.

(3) $PLUTO_PEER_PORT/$PLUTO_MY_PORT contain the ports defined by
    the rightprotoport and leftprotoport options, respectively.
    The variables take on the value '0' if no port has been defined.

(4) $PLUTO_PEER_CA contains the distinguished name of the CA that
    issued the peer's certificate.


11.2 Sample updown script for iptables
     ---------------------------------

The template "_updown.x509" that can be found in the
 
   programs/_updown_x509
   
directory of the FreeS/WAN distribution after applying the X.509 patch, can
be used as an updown script to dynamically insert and delete iptables
firewall rules. The script also features a logging facility which
will register the creation (+) and the expiration (-) of each successfully
established VPN connection in a special syslog file in the following
concise and easily readable format:

Jul 19 18:58:38 firewall vpn:
    + @wroclaw.strongsec.com  160.85.106.2 -- 160.85.106.1 == 0.0.0.0/0
Jul 19 22:15:17 firewall vpn:
    - @wroclaw.strongsec.com  160.85.106.2 -- 160.85.106.1 == 0.0.0.0/0


12. Using the patch with standard FreeS/WAN
    ---------------------------------------

Standard FreeS/WAN, as it is available from www.freeswan.org does public
key authentication with raw RSA public keys that are directly defined in
/etc/ipsec.conf

    rightrsasigkey=0sAq4c....

When standard FreeS/WAN receives a certificate request (CR), it immediately
drops the negotiation because it does not know how to answer the request.
As a workaround X.509 enabled FreeS/WAN does not send a CR if the RSA
key has been statically loaded using [right/left]rsasigkey. A problem
remains with roadwarriors initiating a connection. Since X.509 enabled
FreeS/WAN does not know the identity of the initiating peer in advance ,
it will always send a CR, causing the rupture of the IKE negotiation if
the peer is a standard FreeS/WAN host. To circumvent this problem the
configuration parameter 'nocrsend' can be set in the config setup section
of /etc/ipsec.conf:

    config setup:
        nocrsend=yes

With this entry no certificate request is sent in any connection. The default
setting is nocrsend=no.


13. Using the patch with OpenPGP certificates
    -----------------------------------------

The X.509 patch also supports RSA based authentication using OpenPGP
certificates and OpenPGP V3 fingerprints used as an KEY_ID identifier.


13.1 OpenPGP certificates
     --------------------
     
OpenPGP certificates containing RSA public keys can now directly be loaded
in ASCII armored PGP format using the leftcert and rightcert parameters
in /etc/ipsec.conf:

  conn pgp
       right=%any
       righcert=peerCert.asc
       left=%defaultroute
       leftcert=gatewayCert.asc

The peer certificate must be stored locally (the default directory is
/etc/ipsec.d/certs) since currently no trust can be established for
PGP certificates received from a peer via the IKE protocol.


13.2 OpenPGP private keys
     --------------------
     
PGP private keys in unencrypted form can now directly be loaded in ASCII
armored PGP format via an entry in /etc/ipsec.secrets:

  : RSA gatewayKey.asc

Existing IDEA-encrypted RSA private keys can be unlocked with GnuPG and
the IDEA extension (see http://www.gnupg.org/gph/en/pgp2x.html) using
the commands

  gpg --import gatewayCert.asc

  gpg --allow-secret-key-import --import gatewayKey.asc

  gpg --edit-key <gateway ID>
  > passwd                    #change to empty password
  > save

  gpg -a --export-secret-key <gateway ID> gatewayKey.asc


13.3 Monitoring functions
     --------------------

The command ipsec auto --listcerts shows all loaded PGP certificates
in the following format:

  Aug 28 09:51:55 2002, count: 1
         fingerprint:  0x1ccfca12d93467ffa9d5093d87a465dc
         pubkey:   1024 RSA Key ARHso6uKQ
         created:  Aug 27 08:51:39 2002
         until:    --- -- --:--:-- ---- ok (expires never)

The entries are

 - the date the certificate was loaded either in local time or UTC (--utc)
 - the V3 fingerprint consisting of the 16 byte MD5 hash of the public key
   which is used as an ID of type KEY_ID
 - the modulus size of the RSA key in bits
 - a keyID consisting of 9 base64 symbols representing the public exponent
   and the most significant bits of the modulus
 - the creation date of the public key (extracted from the certificate)
 - the optional expiration date of the public key (extracted from the
   certificate)


13.4 Suppression of certificate request messages
     -------------------------------------------

PGPnet configured to work with OpenPGP certificates aborts the IKE
negotiation when it receives a X.509 certificate. Therefore it is recommended
(mandatory for roadwarrior connections) to set

    config setup:
        nocrsend=yes

in /etc/ipsec.conf.

-----------------------------------------------------------------------------
                           X.509 FreeS/WAN patch:

  Copyright (c) 2000, Andreas Hess, Patric Lichtsteiner, Roger Wegmann
  Copyright (c) 2001, Marco Bertossa, Andreas Schleiss
  Copyright (c) 2002, Mario Strasser <mast@gmx.ch>
  Copyright (c) 2003, Christoph Gysin, Simon Zwahlen
  Copyright (c) 2000-2003, Andreas Steffen <andreas.steffen@zhwin.ch>

      Zurich University of Applied Sciences in Winterthur, Switzerland

                         Dynamic CRL fetching

     Copyright (c) 2002 Stephane Laroche <stephane.laroche@colubris.com>

            Port and protocol selectors for outbound traffic

      Copyright (c) 2002, Stephen J. Bevan <stephen_bevan@yahoo.com>

 			  PGPnet-RSA parts of patch:

             Copyright (c) 2000, Kai Martius <kai@secunet.de >

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version. See http://www.fsf.org/copyleft/gpl.txt.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  for more details.
-----------------------------------------------------------------------------