strongSwan

h1. strongSwan smart card configuration HOWTO

{{>toc}}

!{float:left;margin-right:10px}strongswan-smartcard.png!

Smart cards are a mature technology which prevent your PKI(Public Key Infrastructure) from getting easily compromised by theft.

With the [[pkcs11plugin|pkcs11 plugin]] strongSwan can use any PKCS#11 library to access smart cards, for instance, the one provided by "OpenSC":http://www.opensc-project.org.

In this HOWTO, we give minimal information how to use a reader, initialize cards and configure strongSwan.

h2. Compatible hardware

You need a USB smart card reader and a blank smart card, or a USB token that combines the two in a convenient form factor, preferably with support of 2048-bit RSA keys.

h3. Compatible card readers

Thanks to "OpenSC":http://www.opensc-project.org, GNU/Linux supports most "CCID":http://www.opensc-project.org/openct/wiki/ccid smart card readers, using the "PCSC-Lite":http://pcsclite.alioth.debian.org library.

Most recent USB card readers are compatible. You may refer to the "matrix of supported smartcard readers":http://pcsclite.alioth.debian.org/section.html published by the PCSC-Lite project.

These Omnikey readers are quite popular:

* Second hand Omnikey 3121 CardMan USB smart card readers can be found on eBay for less than 10€. These are good units for testing a setup.

* Smart card readers with an integrated PIN pad offer an increased security level because the PIN entry cannot be sniffed on the host computer e.g. by a surreptitiously installed key logger. The Omnikey 3821 secure smart card reader with LCD display and keypad for secure PIN entry may be a good choice.

h3. Compatible smart cards and tokens

You may use blank cards with support for 1024/2048 bit RSA to store credentials:

* Feitian PKI card. The original author of this HOWTO recommends using Feitian PKI cards. Feitian PKI cards allow 2048 bit RSA key and are very well supported by GNU/Linux.

* STARCOS SPK 2.4 cards are compatible, but cannot be erased, therefore any error may be fatal. You may buy developer versions which can be erased.

* Siemens Card OS 4.3 B may be a good choice, but OpenSC does not know how to initialize them. You have to blank them using Windows software.

* ACOS5 PKI cards are cheap, but unsupported. With a little work, OpenSC could support them.

Tested USB tokens include the Feitian ePass2003.

The OpenSC project maintains a "list of compatible cards and USB tokens":http://www.opensc-project.org/opensc/wiki/SupportedHardware.

You may also use read-only, pre-personalized read-only cards:

* eID cards. Many European countries offer them and you don't need to buy extra cards for VPN use.

* [fix-me] Please provide us with names of providers.

Where to buy: in Europe, you may try:

* "Cryptoshop":http://www.cryptoshop.com sells cards and readers from multiple manufacturers (Gemalto, STARCOS SPK, Siemens Card OS).

* "Smartcard Focus":http://www.smartcardfocus.com also sells cards and readers from several different manufacturers.

These shops are not related to the strongSwan community in any way.

h2. Preparation

h3. Smart card reader

To install pcsc-tools with ccid support, under Debian based distributions use:

<pre>

sudo apt-get install pcsc-tools libccid

</pre>

strongSwan supports the PKCS#11 standard, which specifies how to access cryptographic information on devices. Thus, any shared object file that provides a PKCS#11 interface may be used. In this HOWTO we use "OpenSC":http://www.opensc-project.org.

To install OpenSC use:

<pre>

sudo apt-get install opensc

</pre>

Do not install the OpenCT package, as it is incompatible with the pcsc-lite package.

Check that the card reader is correctly recognized by OpenSC:

<pre>

$ opensc-tool -l

Readers known about:

Nr.    Driver     Name

0      pcsc       OmniKey CardMan 3121 00 00

</pre>

At Nr. 0 we have our recognized Omnikey CardMan 3121 reader. Let's insert our smart card in the reader (note that when buying the card you'll also receive the TRANSPORT KEY. Make sure that the transport key proposed by OpenSC matches the one you got in the mail. You will destroy the card by entering the wrong Key three times).

Let's double check that the card is recognized by printing its ATR:

<pre>

$ opensc-tool -r0 -a

3b:9f:95:81:31:fe:9f:00:65:46:53:05:30:06:71:df:00:00:00:81:61:10:c6

</pre>

We can also check the name of the card with the -n switch (we can omit the -r0 since we only have one reader connected):

<pre>

$ opensc-tool -n

Using reader with a card: OmniKey CardMan 3121 00 00

entersafe

</pre>

At this point we know both the card and reader are fully recognized and functional, and we can proceed to erase the card (you will be asked for the transport key you got in your mail).

h3. Certification Authority

To set up your CA you may use OpenSSL or our own [[IpsecPKI|PKI tool]]. To simplify things you may also use a [[CAmanagementGUIs|graphical user interface]] to set up your CA. One important thing to keep in mind is that you shouldn't create private keys with a length not supported by your smart card (check the specs to be sure). Keys with a maximum length of 2048 bits are known to work.

Make a backup of your keys/certificates and store it in a safe place.

With most cards/tokens it is also possible to generate the private keys directly on the device. This way you can ensure nobody can get their hands on the keys, but you also can't create a backup, so any information encrypted with the corresponding public key will be inaccessible if the card is lost/stolen.

h3. Configuring a smart card with pkcsc15-init

Credentials on smart cards are usually stored according to the PKCS#15 Cryptographic Token Information Format Standard fully supported by OpenSC.

The following command erases the card and removes the existing PKCS#15 structure and all stored cryptographic objects:

<pre>

    pkcs15-init --erase-card

</pre>

This may result in a error if the card is already blank.

With the next command a fresh PKCS#15 file structure is created on a smart card or crypto token:

<pre>

pkcs15-init  --create-pkcs15 --profile pkcs15+onepin \

             --use-default-transport-key \

             --pin 0000 --puk 111111 \

             --label "Test"

</pre>

A secret PIN code is stored in an irretrievable location on the smart card. The PIN will protect the signing operation. If the PIN is entered incorrectly more than three times then the smart card will be locked and the PUK code can be used to unlock the card again.

Next the private key is transferred to the smart card

<pre>

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

               [--id 45]

</pre>

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

At last we load the matching X.509 certificate onto the smart card

<pre>

    pkcs15-init --auth-id 1 --store-certificate myCert.pem

               [--id 45]

</pre>

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

<pre>

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

</pre>

h2. strongSwan configuration

h3. pkcs11 plugin

To use smart cards with strongSwan the [[PKCS11plugin|pkcs11 plugin]] has to be enabled and configured.

If you [[InstallationDocumentation|installed strongSwan]] with your Linux distribution and the pkcs11 plugin is not provided, you'll need to compile strongSwan from sources:

<pre>

./configure <add your options there> --enable-pkcs11

make

sudo make install

</pre>

Next you need to configure the PKCS#11 library provided by "OpenSC":http://www.opensc-project.org in [[strongswan.conf]], as described in the [[pkcs11plugin|pkcs11 plugin documentation]].

Since version:5.1.2 the plugin is configured in [[strongswandirectory|/etc/strongswan.d]]@/charon/pkcs11.conf@:

<pre>

pkcs11 {

	modules {

		opensc {

			path = /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

		}

	}

}

</pre>

h3. Entering the PIN code

Since the smart card signing operation needed during authentication is protected by a PIN code, the secret PIN must be made available to the IKE daemon.

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 [[PinSecret|ipsec.secrets]]:

<pre>

: PIN %smartcard:45 "12345678"

</pre>

or with the general notation

<pre>

: PIN %smartcard<slotnr>:<keyid> "<PIN code>"

</pre>

or if multiple PKCS#11 modules are loaded

<pre>

: PIN %smartcard<slotnr>@<module>:<keyid> "<PIN code>"

</pre>

On a personal notebook computer that could get stolen, you wouldn't want to store your PIN in [[PinSecret|ipsec.secrets]].

Thus the alternative form

<pre>

: PIN %smartcard:45 %prompt

</pre>

will prompt you for the PIN when triggered with the command

<pre>

ipsec rereadsecrets

</pre>

or the alias

<pre>

ipsec secrets

</pre>

h3. Configuring certificates/connections

The [[Pkcs11plugin|pkcs11 plugin]] will automatically load all certificates from the smart card when the daemon initializes it. CA certificates are also automatically available as trust anchors without the need to copy them into the [[IpsecDirectoryCacerts|/etc/ipsec.d/cacerts]] directory first.

Therefore, it is usually not necessary to configure _leftcert_ in [[ipsec.conf]], instead _leftid_ is configured to either the subject distinguished name, or one of the _subjectAltNames_ contained in the certificate.

For instance, if @alice@strongswan.org@ is contained in the certificate as _subjectAltName_ extension simply configure:

<pre>

leftid=alice@strongswan.org

</pre>

In situations where multiple certificates match the same identity configuring _leftcert_ might be necessary.  This can be the case with some eID cards that contain separate signature and encryption certificates with the same identities.

The syntax is the same like that for [[PINSecret|PIN secrets]] in ipsec.secrets:

<pre>

leftcert=%smartcard[<slotnr>[@<module>]]:<keyid>

</pre>

Thus

<pre>

leftcert=%smartcard:50

</pre>

will look in all available modules and slots for ID 0x50 starting with the first slot whereas

<pre>

leftcert=%smartcard4:50

</pre>

will directly check slot 4 (which is usually the first slot on the second reader/token when using the OpenSC library) for a key with ID 0x50.

h2. Acknowledgements and other resources

* This article was originally adapted from "Smartcard HOWTO":http://michele.pupazzo.org/docs/smart-cards-openvpn.html written by Michele Baldessari. Permission granted by Michele Baldessari to reproduce the text here.