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

     X.509 Patch - Version 0.9.11

Contents

   1. Summary
   2. Acknowledgements
   3. Installation
	3.1 The X.509 distribution
	3.2 Installing the X.509 patch
	3.3 Installing FreeS/WAN with X.509 on a fresh kernel
	3.4 Adding X.509 on top of a running FreeS/WAN IPsec stack
   4. Configuring the connections - ipsec.conf
	4.1 Configuring my side
	4.2 Multiple certificates  (NEW)
	4.3 Configuring the peer side using CA certificates
	4.4 Installing CA certificates
	4.5 Installing optional certificate revocation lists (CRLs)
	4.6 Dynamic update of certificates and CRLs
	4.7 Configuring the peer side using locally stored certificates
   5. Configuring the private keys - ipsec.secrets
	5.1 Loading private key files in PKCS#1 format
	5.2 Multiple private keys  (NEW)
   6. Generating X.509 certificates and CRLs with OpenSSL
	6.1 Generating a CA certificate
	6.2 Generating a host or user certificate
	6.3 Generating a CRL
	6.4 Revoking a certificate
   7. Configuring the clients
	7.1 FreeS/WAN
	7.2 PGPnet
	7.3 Safenet/Soft-PK/Soft-Remote
	7.4 SSH Sentinel
	7.5 Windows 2000/XP
   8. Monitoring functions
   9. Using the patch with OpenPGP certificates


1. Summary
   -------

The X.509 patch supports RSA-based authentication using X.509 certificates
between a Linux FreeS/WAN security gateway and an unlimited number of IPsec
peers. Starting with version 0.9 of the patch, certification authority (CA)
trust chains and certificate revocation lists (CRLs) have been introduced,
thereby eliminating the need to store peer certificates locally on the
Linux host. Version 0.9.10 now introduces support of multiple certificates
and corresponding private keys as described in sections 4.2 and 5.2.

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 and Windows XP.

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 development of the patch
is coordinated by Andreas Steffen, professor for Communications Systems at
the ZHW.

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.


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 pluto directory as well as
to the scripts utils/auto and utils/_confread.


3.3 Installing FreeS/WAN with X.509 on a fresh kernel
    -------------------------------------------------

If you are installing the X.509 features together with FreeS/WAN on a
fresh Linux Kernel, then after having applied the patch freeswan.diff as
described in section 3.2 you can start the normal FreeS/WAN compilation and
installation process by typing one of the commands

    make menugo             # use menuconfig
    make xgo                # use xconfig
    make ogo                # use config
    make oldgo              # use oldconfig

or

    make menumod            # install FreeS/WAN as a kernel module

in the FreeS/WAN directory. The X.509 functionality will be automatically
included and everything will be copied to the right place by typing

    make kinstall


3.4 Adding X.509 on top of a working FreeS/WAN IPsec stack
    ------------------------------------------------------

If you already have a FreeS/WAN enhanced Linux Kernel running and want to
add X.509 functionality afterwards, then you must apply the patch
freeswan.diff as described in section 3.2. In a next step you must
recompile the userland progams by staying in the FreeS/WAN top source
directory and typing

    make programs

followed by

    make install.

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. In order to distinguish 
FreeS/WAN's own certificates from locally stored trusted peer certificates
(see section 4.7 for details), they could also be stored in a subdirectory
below /etc/ipsec.d 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 6.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 5.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 X.501 RDNs are supported by the X.509 patch

+---------------------------------------------+
| C          Country                          |
|---------------------------------------------|
| ST         State or province                |
|---------------------------------------------|
| L          Locality or town                 |
|---------------------------------------------|
| O          Organisation                     |
|---------------------------------------------|
| OU         Organisational Unit              |
|---------------------------------------------|
| CN         Common Name                      |
|---------------------------------------------|
| N          Name                             |
|---------------------------------------------|
| G          Given name                       |
|---------------------------------------------|
| S          Surname                          |
|---------------------------------------------|
| I          Initials                         |
|---------------------------------------------|
| T          Personal title                   |
|---------------------------------------------|
| E          E-mail                           |
|---------------------------------------------|
| Email      E-mail                           |
|---------------------------------------------|
| SN         Serial number                    |
|---------------------------------------------|
| D          Description                      |
|---------------------------------------------|
| 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 4.5 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 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.


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


4.6 Dynamic 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 dynamic replacement
of the various files:

+----------------------------------------------------------------------------+
| ipsec auto --rereadsecrets  reload file /etc/ipsec.secrets                 |
|----------------------------------------------------------------------------|
| ipsec auto --rereadmycert   reload file /etc/x509cert.der  (deprecated)    |
|----------------------------------------------------------------------------|
| 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                     |
|                                        --rereadmycert                      |
|                                        --rereadcacerts                     |
|                                        --rereadcrls                        |
+----------------------------------------------------------------------------+


4.7 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.2 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.2
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


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

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


5.2 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>"


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


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


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

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


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


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


7. Configuring the clients
   -----------------------

7.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_D       -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


7.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_D       -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


7.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_D       -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


7.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_D       -              |
|                              FQDN             DNS:           |
|                              USER_FQDN        email:         |
|                              IPV4_ADDR        IP:            |
+--------------------------------------------------------------+


7.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:            |
+--------------------------------------------------------------+


8. 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'
  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'
  Apr 09 20:57:49 2002, 1024 RSA Key AwEAAbl5j,
         until Feb 13 11:19:25 2003 ok
         ID_USER_FQDN 'sna@zhwin.ch'

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.

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

  May 01 07:09:46 2002, revoked certs: 15                                                                                                    issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         issuer:  'C=CH, O=strongSec GmbH, CN=strongSec Root CA'
         updates:  this Nov 28 08:15:52 2001
                   next Dec 28 08:15:52 2001 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 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 or
   a warning message, since CRL updates are currently not
   enforced by the X.509 patch.


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


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

The X.509 patch also supports RSA based authentication using OpenPGP
certificates and PGP's proprietary KEY_ID specified as a HEX string
in /etc/ipsec.conf as

    rightid=@#5ec4fa14...

This specific authentication mode is automatically chosen when you put the
OpenPGP certificate of the FreeS/WAN security gateway into the file

    /etc/pgpcert.pgp

Since the file /etc/x509cert.der has precedence, it must not be present.
The keyextractor tool written by Kai Martius and currently available from
http://www.zengl.net/freeswan is required to extract public and private
keys from OpenPGP certificates.

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

  Copyright (c) 2000, Andreas Hess, Patric Lichtsteiner, Roger Wegmann
  Copyright (c) 2001, Marco Bertossa, Andreas Schleiss
  Copyright (c) 2000-2002, Andreas Steffen <andreas.steffen@zhwin.ch>

      Zurich University of Applied Sciences in Winterthur, Switzerland

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


