strongSwan

{{title(Setting-up a Simple CA Using the strongSwan PKI Tool)}}

h1. Setting-up a Simple CA Using the strongSwan PKI Tool

{{>toc}}

This how-to sets up a Certificate Authority using strongSwan's [[IpsecPKI|PKI tool]] (available since version:4.3.5), keeping it as simple as possible.

h2. CA Certificate

First, [[IpsecPKIGen|generate]] a private key, the default generates a 2048 bit RSA key, use @--type@ and/or @--size@ to specify other key types and lengths (if this command blocks, refer to [[IpsecPKIGen#Problems-on-Hosts-with-Low-Entropy|this note about hosts with low entropy]]):

<pre>

pki --gen > caKey.der

</pre>

For a real-world setup, make sure to keep this key absolutely private.

Now [[IpsecPKISelf|self-sign]] a CA certificate using the generated key:

<pre>

pki --self --in caKey.der --dn "C=CH, O=strongSwan, CN=strongSwan CA" --ca > caCert.der

</pre>

Adjust the _distinguished name (DN)_ to your needs (refer to [[IdentityParsing#Supported-RDN-Types|the list of supported RDN types]]), it will be included in all issued certificates.

That's it, your CA is ready to issue end-entity certificates.

h2. End Entity Certificates

For *each* peer, i.e. for all VPN clients and VPN gateways in your network, [[IpsecPKIgen|generate]] an individual private key and [[IpsecPKIIssue|issue]] a matching certificate using your new CA:

<pre>

pki --gen > peerKey.der

pki --issue --in peerKey.der --type priv --cacert caCert.der --cakey caKey.der \

            --dn "C=CH, O=strongSwan, CN=peer" --san peer > peerCert.der

or when using older versions

pki --pub --in peerKey.der | pki --issue --cacert caCert.der --cakey caKey.der \

                                         --dn "C=CH, O=strongSwan, CN=peer" --san peer > peerCert.der

</pre>

The second command [[IpsecPKIPub|extracts the public key]] and [[IpsecPKIIssue|issues a certificate]] using your CA.

Again, adjust the DN and SAN to your needs ([[IdentityParsing#Supported-RDN-Types|supported RDN types]]).

If you want to add _subjectAltName_ extensions to your certificates use the _--san_ option (can be provided multiple times), for instance, @--san vpn.strongswan.org@ or @--san peer@strongswan.org@. It is recommended to include the hostname of a gateway as _subjectAltName_ in its certificate.

Depending on your clients there may be additional requirements imposed on gateway certificates, for instance, the [[Win7CertReq|Windows 7 certificate requirements]] or those for [[IOS_(Apple)#Certificate-requirements-for-iOS-interoperability|iOS and Mac OS X clients]].

Distribute each private key and matching certificate to the corresponding peer.

h3. Generating Certificate Requests and Signing them

If you don't want to generate all private keys centrally to distribute them, but instead want decentralized private key generation, please see the section "Generating a Host or User End Entity Certificate":https://github.com/strongswan/strongswan/blob/master/README.md#generating-a-host-or-user-end-entity-certificate in the file README.md in the strongswan source tree.

h2. Certificate Revocation Lists (CRL)

In case end entity certificates have to be revoked, Certificate Revocation Lists (CRLs) may be generated with the [[IpsecPkiSigncrl|ipsec pki --signcrl]] command:

<pre>

pki --signcrl --cacert caCert.der --cakey caKey.der --reason superseded --cert peerCert.der > crl.der

</pre>

The certificate given with @--cacert@ must be either a CA certificate or a certificate with the _crlSign_ extended key usage (@--flag crlSign@).

When [[IpsecPKIIssue|issuing certificates]] an URL to a CRL may be added with the @--crl@ argument.

h2. Install certificates

On *each* peer store *its own* credentials as follows.

Never store the private key *caKey.der* of the Certification Authority (CA) on a host with constant direct access to the Internet (e.g. a VPN gateway), since a theft of this master signing key will completely compromise your PKI.

h3. Configuration with [[swanctl.conf]]

Store the certificates and keys in the [[SwanctlDirectory|/etc/swanctl/]] tree:

* */etc/swanctl/(rsa|ecdsa|pkcs8)/peerKey.der* holds the private key of the given peer (directory depends on the type of key), gets loaded automatically. Passwords may be configured in [[swanctl.conf]].

* */etc/swanctl/x509/peerCert.der* holds the end-entity certificate of the given peer, gets loaded automatically. Reference it in [[swanctl.conf]] to explicitly use it.

* */etc/swanctl/x509ca/caCert.der* holds the CA certificate which issued and signed all peer certificates, gets loaded automatically.

Optionally, the CRL may be stored in the following directory (if the certificate contains an URL to a CRL, it will be fetched on demand):

* */etc/swanctl/x509crl/crl.der* holds the CRL signed by the CA (or by a certificate containing the _crlSign_ EKU).

h3. Configuration with [[ipsec.conf]]/[[ipsec.secrets]]

Store the certificates and keys in the [[IpsecDirectory|/etc/ipsec.d/]] tree:

* *[[IpsecDirectoryPrivate|/etc/ipsec.d/private/]]peerKey.der* holds the private key of the given peer. Configure it in [[ipsec.secrets]] to load it.

* *[[IpsecDirectoryCerts|/etc/ipsec.d/certs/]]peerCert.der* holds the end-entity certificate of the given peer. Reference it in [[ipsec.conf]] to use it.

* *[[IpsecDirectoryCacerts|/etc/ipsec.d/cacerts/]]caCert.der* holds the CA certificate which issued and signed all peer certificates, gets loaded automatically.

Optionally, the CRL may be stored in the following directory (if the certificate contains an URL to a CRL, it will be fetched on demand):

* *[[IpsecDirectoryCrls|/etc/ipsec.d/crls/]]crl.der* holds the CRL signed by the CA (or by a certificate containing the _crlSign_ EKU).

h3. Install certificates in other platforms

To import certificates on most other systems, they must be bundled together with the required CA certificate and private key into a PKCS#12 file.

The certificates and the private key have to be in PEM format for @openssl pkcs12@ to find them acceptable. DER format is not accepted by it.

Either use @--outform pem@ with the @pki@ commands above to generate the files in PEM format (@pki@ accepts both formats) or convert with

the commands below. The files can be bundled into a PKCS#12 file by replacing the file names in the following examples:

To convert an X.509 certificate from DER to PEM

<pre>

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

</pre>

To convert an RSA key from DER to PEM

<pre>

openssl rsa -inform der -outform pem -in peerKey.der -out peerKey.pem

</pre>

To package all of the files into a PKCS#12 container

<pre>

openssl pkcs12 -in peerCert.pem -inkey peerKey.pem -certfile caCert.pem -export -out peer.p12

</pre>

The @peer.p12@ file contains everything needed and is ready for the import on other systems.

On Android 4.4 and later, you may get a warning ("Network may be monitored by an unknown third party") if the @peer.p12@ file contains

the CA certificate. To avoid that create the PKCS#12 file without the CA certificate by omitting the @-certfile caCert.pem@ argument.

Then import the @peer.p12@ file into the Android trust store as usual and the @caCert.pem@ file directly [[AndroidVPNClient|into the strongSwan app]].