strongSwan

h1. strongSwan Smartcard configuration HOWTO

{{>toc}}

!strongswan-smartcard.png!

Smartcards are a mature technology which avoid your PKIs from being stolen by a theft. 

strongSwan relies on "OpenSC":http://www.opensc-project.org to query the smartcard according to PKCS#11 RSA standard.

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

h2. Compatible hardware

You need a USB smartcard reader and a blank smart card, preferably with support of 2048-bit RSA key.

Since 768-bit RSA keys have been broken, the NSA recommends using 2048-bit RSA key.

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 "pcsclite":http://pcsclite.alioth.debian.org libraries. 

Most USB card readers sold today are supported by GNU/Linux. You may refer to the "matrix of supported smartcard readers":http://pcsclite.alioth.debian.org/section.html published by pcsclite project.

These Ominikey readers are quite popular:

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

* Smartcard 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 surrepticiously installed key logger. The Omnikey 3821 secure smartcard reader with LCD display and keypad for secure PIN entry may be a good choice.

h3. Compatible smartcards

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

* *Feitian PKI card*. The author of this HOWTO received an evaluation kit. Feitian PKI cards work great and are fully supported by OpenSC svn version.

* Cryptoflex E-Gate 32k were the best choice (but no longer available).

* 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 bank them using Windows software.

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

We recommend bying a smartcard with support of 2048 RSA key, as recommended by NSA.

Avoid Java cards as they may need MUSCLE framework, which is still experimental.

Read the Acknowledgements section for more information on Java cards.

A list of compatible cards is listed "here":http://www.opensc-project.org/opensc/wiki#SmartCards.

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

* eID cards. Many European countries offer them and 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 STARCOS SPK 2.3 and Siemens Card OS 4.3 B cards.

* "Smartcardfocus":http://www.smartcardfocus.com sells STARCOS SPK 2.4.

Fix-me, please provide more IT shops. We are still looking for a 10€ compatible card.

h2. Preparation

h3. Smartcard reader

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

<pre>

apt-get install pcsc-tools libccid

</pre>

strongSwan supports PKCS#11 RSA standard using "opensc":http://www.opensc-project.org libraries, which specifies how to store cryptographic information on devices. 

To install "opensc":http://www.opensc-project.org:

<pre>

sudo apt-get install opensc

</pre>

Open /etc/opensc/opensc.conf.

Edit this line to use only pcsc drivers:

<pre>

reader_drivers = pcsc;

</pre>

Do not install OpenCT package, as it is incompatible with OpenSC package. OpenSC supports OpenCT protocol using shared libraries.

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

We recommend using a [[CAmanagementGUIs|certificate GUI]] 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 is 2048 bits are known to work.

Make a backup of your keys/certificates on a CD-ROM and store it in a safe place.

h3. Configuring a smartcard with pkcsc15-init

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

<pre>

    pkcs15-init --erase-card --create-pkcs15

</pre>

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

<pre>

    pkcs15-init --auth-id 1 --store-pin --pin "1234" \

                --puk "4321" --label "my PIN"

</pre>

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

<pre>

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

               [--id 45]

</pre>

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

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

<pre>

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

</pre>

h2. strongSwan management

h3. Configuring peers

To enable smart card support in strongSwan, you may need to compile from sources:

<pre>

./configure <add your options there> \

--enable-smartcard

make

sudo make install

</pre>

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

<pre>

    conn sun

         right=192.168.0.2

         rightid=@sun.strongswan.org

         left=%defaultroute

         leftcert=%smartcard

         auto=add

</pre>

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

<pre>

    leftcert=%smartcard

</pre>

which stands for the full notation

<pre>

    leftcert=%smartcard#1

</pre>

is sufficient where the first certificate/private key object enumerated by PKCS#11 module is used. If several certificate/private key objects are present then the nth object can be selected using

<pre>

    leftcert=%smartcard#<n>

</pre>

The command

<pre>

    ipsec listcards

</pre>

gives an overview over all certifcate objects made available by the PKCS#11 module. CA certificates are automatically available as trust anchors without the need to copy them into the /etc/ipsec.d/cacerts/ directory first.

As an alternative the certificate ID and/or the slot number defined by the PKCS#11 standard can be specified using the notation

<pre>

    leftcert=%smartcard<slot nr>:<key id in hex format>

</pre>

Thus

<pre>

    leftcert=%smartcard:50

</pre>

will look in all available slots for ID 0x50 starting with the first slot (usually slot 0) 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.

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

<pre>

    : PIN %smartcard "12345678"

</pre>

or with the general notation

<pre>

    : PIN %smartcard<nr> "<PIN code>"

</pre>

or alternatively

<pre>

    : PIN %smartcard<slot nr>:<key id> "<PIN code>"

</pre>

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

Thus the alternative form

<pre>

    : PIN %smartcard %prompt

</pre>

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

<pre>

    ipsec up sun

</pre>

The ipsec up 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:

<pre>

    conn rw

         right=%any

         rightrsasigkey=%cert

         left=%defaultroute

         leftcert=%smartcard1:50

         auto=add

</pre>

But if there is a corresponding entry

<pre>

    : PIN %smartcard1:50 %prompt

</pre>

in ipsec.secrets, then the standard command

<pre>

    ipsec rereadsecrets

</pre>

or the alias

<pre>

    ipsec secrets

</pre>

can be used to enter the PIN code for this connection interactively. The command

<pre>

    ipsec listcards

</pre>

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

h3. PIN-pad equipped smartcard readers

Smartcard 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 surrepticiously installed key logger. In order to tell pluto not to prompt for the PIN on the host itself, the entry

<pre>

    : PIN %smartcard:50 %pinpad

</pre>

can be used in ipsec.secrets. Because the key pad does not cache the PIN in the smartcard reader, it must be entered for every PKCS #11 session login. By default pluto does a session logout after every RSA signature. In order to avoid the repeated entry of the PIN code during the periodic IKE main mode rekeyings, the following parameter can be set in the config setup section of ipsec.conf:

<pre>

    config setup

        pkcs11keepstate=yes

</pre>

The default setting is pkcs11keepstate=no.

h2. Acknowledgements and other resources

* This article was adapted by "Smartcard HOWTO":http://michele.pupazzo.org/docs/smart-cards-openvpn.html written by Michele Baldessari. Permission granted by Michele Baldessari to reproduce the text on strongSwan wiki. strongSwan configuration is taken from strongSwan manual.

* Bold users: some Java cards may be supported, using the Muscle experimental framework.

You may read this interesting HOWTO: "How to get smartcards or crypto-tokens running on Debian Linux and Windows":http://blog.runtux.com/2009/12/05/150