Project

General

Profile

strongSwan smart card configuration HOWTO » History » Version 158

Tobias Brunner, 14.11.2011 11:56
note about IKEv2 added, some editorial changes

1 158 Tobias Brunner
h1. strongSwan smart card configuration HOWTO
2 1 Jean-Michel Pouré
3 68 Jean-Michel Pouré
{{>toc}}
4 68 Jean-Michel Pouré
5 56 Jean-Michel Pouré
!strongswan-smartcard.png!
6 67 Jean-Michel Pouré
7 158 Tobias Brunner
Smart cards are a mature technology which avoid your PKIs from being stolen by a theft. 
8 158 Tobias Brunner
strongSwan relies on "OpenSC":http://www.opensc-project.org to query the smart card according to the PKCS#11 RSA standard.  Actually, any shared library implementing the PKCS#11 API can be used.
9 158 Tobias Brunner
In this HOWTO, we give minimal information how to use a reader, initialize cards and configure strongSwan.
10 1 Jean-Michel Pouré
11 158 Tobias Brunner
---
12 158 Tobias Brunner
13 158 Tobias Brunner
*Note:* The configuration for IKEv2 is slightly different than for IKEv1 which is described here. Refer to [[SmartCardsIKEv2|Using Smartcards with IKEv2]] for details.
14 158 Tobias Brunner
15 158 Tobias Brunner
---
16 158 Tobias Brunner
17 86 Jean-Michel Pouré
h2. Compatible hardware
18 1 Jean-Michel Pouré
19 158 Tobias Brunner
You need a USB smart card reader and a blank smart card, preferably with support of 2048-bit RSA keys.
20 1 Jean-Michel Pouré
Since 768-bit RSA keys have been broken, the NSA recommends using 2048-bit RSA key.
21 1 Jean-Michel Pouré
22 1 Jean-Michel Pouré
h3. Compatible card readers
23 1 Jean-Michel Pouré
24 158 Tobias Brunner
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.
25 1 Jean-Michel Pouré
26 158 Tobias Brunner
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.
27 1 Jean-Michel Pouré
28 158 Tobias Brunner
These Omnikey readers are quite popular:
29 158 Tobias Brunner
* 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.
30 158 Tobias Brunner
* 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 surrepticiously installed key logger. The Omnikey 3821 secure smart card reader with LCD display and keypad for secure PIN entry may be a good choice.
31 1 Jean-Michel Pouré
32 158 Tobias Brunner
h3. Compatible smart cards
33 1 Jean-Michel Pouré
34 158 Tobias Brunner
You may use blank cards with support for 1024/2048 bit RSA to store credentials:
35 158 Tobias Brunner
* 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.
36 125 Jean-Michel Pouré
* 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.
37 158 Tobias Brunner
* 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.
38 91 Jean-Michel Pouré
* ACOS5 PKI cards are cheap, but unsupported. With a little work, OpenSC could support them.
39 1 Jean-Michel Pouré
40 158 Tobias Brunner
The OpenSC project maintains a "list of compatible cards":http://www.opensc-project.org/opensc/wiki/SupportedHardware.
41 91 Jean-Michel Pouré
42 157 Jean-Michel Pouré
You may also use read-only, pre-personalized read-only cards:
43 158 Tobias Brunner
* eID cards. Many European countries offer them and you don't need to buy extra cards for VPN use.
44 120 Jean-Michel Pouré
* [fix-me] Please provide us with names of providers.
45 1 Jean-Michel Pouré
46 151 Jean-Michel Pouré
Where to buy: in Europe, you may try:
47 158 Tobias Brunner
* "Gooze":http://www.gooze.eu sells FEITIAN PKI cards and refurbished smartcard readers. The original author of this HOWTO started the Gooze store to lower the price of security solutions. You can find a smart card reader and a card for as little as 25€. "Gooze":http://www.gooze.eu and "FEITIAN":http://www.ftsafe.com also donate free FEITIAN PKI cards to interested free software developers. You may apply for "free cards here":http://www.gooze.eu/products/feitian-pki-free-software-developer-card.
48 158 Tobias Brunner
* "Cryptoshop":http://www.cryptoshop.com sells cards and readers from multiple manufacturers (Gemalto, STARCOS SPK, Siemens Card OS).
49 158 Tobias Brunner
* "Smartcard Focus":http://www.smartcardfocus.com also sells cards and readers from several different manufacturers.
50 138 Jean-Michel Pouré
51 158 Tobias Brunner
These shops are not related to the strongSwan community in any way.
52 135 Jean-Michel Pouré
53 32 Jean-Michel Pouré
h2. Preparation
54 1 Jean-Michel Pouré
55 158 Tobias Brunner
h3. Smart card reader
56 132 Jean-Michel Pouré
57 158 Tobias Brunner
To install pcsc-tools with ccid support, under Debian based distributions use:
58 1 Jean-Michel Pouré
<pre>
59 158 Tobias Brunner
sudo apt-get install pcsc-tools libccid
60 134 Jean-Michel Pouré
</pre>
61 134 Jean-Michel Pouré
62 158 Tobias Brunner
strongSwan supports the PKCS#11 RSA standard using the "OpenSC":http://www.opensc-project.org library, which specifies how to access cryptographic information on devices. 
63 134 Jean-Michel Pouré
64 158 Tobias Brunner
To install "OpenSC":http://www.opensc-project.org use:
65 32 Jean-Michel Pouré
<pre>
66 7 Jean-Michel Pouré
sudo apt-get install opensc
67 1 Jean-Michel Pouré
</pre>
68 36 Jean-Michel Pouré
69 2 Jean-Michel Pouré
Open /etc/opensc/opensc.conf.
70 1 Jean-Michel Pouré
71 134 Jean-Michel Pouré
Edit this line to use only pcsc drivers:
72 4 Jean-Michel Pouré
<pre>
73 1 Jean-Michel Pouré
reader_drivers = pcsc;
74 22 Jean-Michel Pouré
</pre>
75 22 Jean-Michel Pouré
76 158 Tobias Brunner
Do not install the OpenCT package, as it is incompatible with the pcsc-lite package.
77 22 Jean-Michel Pouré
78 22 Jean-Michel Pouré
Check that the card reader is correctly recognized by OpenSC:
79 22 Jean-Michel Pouré
<pre>
80 22 Jean-Michel Pouré
$ opensc-tool -l
81 23 Jean-Michel Pouré
Readers known about:
82 23 Jean-Michel Pouré
Nr.    Driver     Name
83 23 Jean-Michel Pouré
0      pcsc       OmniKey CardMan 3121 00 00
84 1 Jean-Michel Pouré
</pre>
85 1 Jean-Michel Pouré
86 158 Tobias Brunner
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):
87 137 Jean-Michel Pouré
88 23 Jean-Michel Pouré
Let's double check that the card is recongized by printing its ATR:
89 1 Jean-Michel Pouré
90 1 Jean-Michel Pouré
<pre>
91 1 Jean-Michel Pouré
$ opensc-tool -r0 -a
92 1 Jean-Michel Pouré
3b:9f:95:81:31:fe:9f:00:65:46:53:05:30:06:71:df:00:00:00:81:61:10:c6
93 1 Jean-Michel Pouré
</pre>
94 1 Jean-Michel Pouré
95 136 Jean-Michel Pouré
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):
96 23 Jean-Michel Pouré
97 23 Jean-Michel Pouré
<pre>
98 136 Jean-Michel Pouré
$ opensc-tool -n
99 136 Jean-Michel Pouré
Using reader with a card: OmniKey CardMan 3121 00 00
100 1 Jean-Michel Pouré
entersafe
101 136 Jean-Michel Pouré
</pre>
102 136 Jean-Michel Pouré
103 158 Tobias Brunner
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).
104 136 Jean-Michel Pouré
105 136 Jean-Michel Pouré
h3. Certification Authority
106 71 Jean-Michel Pouré
107 158 Tobias Brunner
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.
108 1 Jean-Michel Pouré
109 71 Jean-Michel Pouré
Make a backup of your keys/certificates on a CD-ROM and store it in a safe place.
110 71 Jean-Michel Pouré
111 148 Jean-Michel Pouré
h3. Configuring a smartcard with pkcsc15-init
112 1 Jean-Michel Pouré
113 1 Jean-Michel Pouré
strongSwan's smartcard solution is based on the PKCS#15 "Cryptographic Token Information Format Standard" fully supported by OpenSC library functions. Using the command
114 71 Jean-Michel Pouré
115 1 Jean-Michel Pouré
<pre>
116 1 Jean-Michel Pouré
    pkcs15-init --erase-card
117 1 Jean-Michel Pouré
</pre>
118 1 Jean-Michel Pouré
This may result in a error if the card is already blank.
119 148 Jean-Michel Pouré
120 158 Tobias Brunner
A fresh PKCS#15 file structure is created on a smart card or crypto token. With the next command
121 148 Jean-Michel Pouré
122 148 Jean-Michel Pouré
<pre>
123 71 Jean-Michel Pouré
pkcs15-init  --create-pkcs15 --profile pkcs15+onepin \
124 1 Jean-Michel Pouré
             --use-default-transport-key \
125 71 Jean-Michel Pouré
             --pin 0000 --puk 111111 \
126 148 Jean-Michel Pouré
             --label "Test"
127 71 Jean-Michel Pouré
</pre>
128 71 Jean-Michel Pouré
129 158 Tobias Brunner
a secret PIN code 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 smart card will be locked and the PUK code can be used to unlock the card again.
130 71 Jean-Michel Pouré
131 158 Tobias Brunner
Next the RSA private key is transferred to the smart card
132 71 Jean-Michel Pouré
133 71 Jean-Michel Pouré
<pre>
134 1 Jean-Michel Pouré
    pkcs15-init --auth-id 1 --store-private-key myKey.pem
135 71 Jean-Michel Pouré
               [--id 45]
136 71 Jean-Michel Pouré
</pre>
137 71 Jean-Michel Pouré
138 158 Tobias Brunner
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.
139 71 Jean-Michel Pouré
140 71 Jean-Michel Pouré
At last we load the matching X.509 certificate onto the smartcard
141 71 Jean-Michel Pouré
142 71 Jean-Michel Pouré
<pre>
143 71 Jean-Michel Pouré
    pkcs15-init --auth-id 1 --store-certificate myCert.pem
144 71 Jean-Michel Pouré
               [--id 45]
145 1 Jean-Michel Pouré
</pre>
146 71 Jean-Michel Pouré
147 158 Tobias Brunner
The pkcs15-tool can now be used to verify the contents of the smart card.
148 1 Jean-Michel Pouré
149 1 Jean-Michel Pouré
<pre>
150 66 Jean-Michel Pouré
    pkcs15-tool --list-pins --list-keys --list-certificates
151 1 Jean-Michel Pouré
</pre>
152 79 Jean-Michel Pouré
153 158 Tobias Brunner
h2. strongSwan configuration
154 65 Jean-Michel Pouré
155 158 Tobias Brunner
*Note:* The configuration for IKEv2 is slightly different than for IKEv1 which is described here. Refer to [[SmartCardsIKEv2|Using Smartcards with IKEv2]] for details.
156 158 Tobias Brunner
157 158 Tobias Brunner
158 158 Tobias Brunner
159 1 Jean-Michel Pouré
h3. Configuring peers
160 66 Jean-Michel Pouré
161 158 Tobias Brunner
To enable smart card support in the IKEv1 daemon pluto, you may need to compile strongSwan from sources:
162 66 Jean-Michel Pouré
<pre>
163 158 Tobias Brunner
./configure <add your options there> --enable-smartcard
164 66 Jean-Michel Pouré
make
165 66 Jean-Michel Pouré
sudo make install
166 66 Jean-Michel Pouré
</pre>
167 66 Jean-Michel Pouré
168 158 Tobias Brunner
Defining a smart card based connection in ipsec.conf is easy:
169 66 Jean-Michel Pouré
170 66 Jean-Michel Pouré
<pre>
171 66 Jean-Michel Pouré
    conn sun
172 66 Jean-Michel Pouré
         right=192.168.0.2
173 66 Jean-Michel Pouré
         rightid=@sun.strongswan.org
174 66 Jean-Michel Pouré
         left=%defaultroute
175 66 Jean-Michel Pouré
         leftcert=%smartcard
176 66 Jean-Michel Pouré
         auto=add
177 66 Jean-Michel Pouré
</pre>
178 66 Jean-Michel Pouré
179 158 Tobias Brunner
In most cases there is a single smart card reader or crypto token and only one RSA private key safely stored on the crypto device. Thus usually the entry
180 1 Jean-Michel Pouré
181 1 Jean-Michel Pouré
<pre>
182 66 Jean-Michel Pouré
    leftcert=%smartcard
183 66 Jean-Michel Pouré
</pre>
184 66 Jean-Michel Pouré
185 66 Jean-Michel Pouré
which stands for the full notation
186 66 Jean-Michel Pouré
187 66 Jean-Michel Pouré
<pre>
188 66 Jean-Michel Pouré
    leftcert=%smartcard#1
189 66 Jean-Michel Pouré
</pre>
190 66 Jean-Michel Pouré
191 158 Tobias Brunner
is sufficient where the first certificate/private key object enumerated by the PKCS#11 module is used. If several certificate/private key objects are present then the nth object can be selected using
192 66 Jean-Michel Pouré
193 66 Jean-Michel Pouré
<pre>
194 66 Jean-Michel Pouré
    leftcert=%smartcard#<n>
195 66 Jean-Michel Pouré
</pre>
196 66 Jean-Michel Pouré
197 66 Jean-Michel Pouré
The command
198 66 Jean-Michel Pouré
199 66 Jean-Michel Pouré
<pre>
200 66 Jean-Michel Pouré
    ipsec listcards
201 66 Jean-Michel Pouré
</pre>
202 66 Jean-Michel Pouré
203 66 Jean-Michel Pouré
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.
204 66 Jean-Michel Pouré
205 66 Jean-Michel Pouré
As an alternative the certificate ID and/or the slot number defined by the PKCS#11 standard can be specified using the notation
206 66 Jean-Michel Pouré
207 66 Jean-Michel Pouré
<pre>
208 66 Jean-Michel Pouré
    leftcert=%smartcard<slot nr>:<key id in hex format>
209 66 Jean-Michel Pouré
</pre>
210 66 Jean-Michel Pouré
211 66 Jean-Michel Pouré
Thus
212 1 Jean-Michel Pouré
213 66 Jean-Michel Pouré
<pre>
214 66 Jean-Michel Pouré
    leftcert=%smartcard:50
215 66 Jean-Michel Pouré
</pre>
216 66 Jean-Michel Pouré
217 66 Jean-Michel Pouré
will look in all available slots for ID 0x50 starting with the first slot (usually slot 0) whereas
218 66 Jean-Michel Pouré
219 66 Jean-Michel Pouré
<pre>
220 66 Jean-Michel Pouré
    leftcert=%smartcard4:50
221 66 Jean-Michel Pouré
</pre>
222 66 Jean-Michel Pouré
223 66 Jean-Michel Pouré
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.
224 66 Jean-Michel Pouré
225 66 Jean-Michel Pouré
h3. Entering the PIN code
226 66 Jean-Michel Pouré
227 158 Tobias Brunner
Since the smart card signing operation needed to sign the hash with the RSA private key during IKEv1 Main Mode is protected by a PIN code, the secret PIN must be made available to pluto.
228 66 Jean-Michel Pouré
229 158 Tobias Brunner
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]]
230 66 Jean-Michel Pouré
231 66 Jean-Michel Pouré
<pre>
232 66 Jean-Michel Pouré
    : PIN %smartcard "12345678"
233 66 Jean-Michel Pouré
</pre>
234 66 Jean-Michel Pouré
235 66 Jean-Michel Pouré
or with the general notation
236 66 Jean-Michel Pouré
237 66 Jean-Michel Pouré
<pre>
238 66 Jean-Michel Pouré
    : PIN %smartcard<nr> "<PIN code>"
239 66 Jean-Michel Pouré
</pre>
240 66 Jean-Michel Pouré
241 66 Jean-Michel Pouré
or alternatively
242 66 Jean-Michel Pouré
243 66 Jean-Michel Pouré
<pre>
244 66 Jean-Michel Pouré
    : PIN %smartcard<slot nr>:<key id> "<PIN code>"
245 66 Jean-Michel Pouré
</pre>
246 66 Jean-Michel Pouré
247 66 Jean-Michel Pouré
On a personal notebook computer that could get stolen, you wouldn't want to store your PIN in ipsec.secrets.
248 66 Jean-Michel Pouré
249 66 Jean-Michel Pouré
Thus the alternative form
250 1 Jean-Michel Pouré
251 66 Jean-Michel Pouré
<pre>
252 66 Jean-Michel Pouré
    : PIN %smartcard %prompt
253 66 Jean-Michel Pouré
</pre>
254 66 Jean-Michel Pouré
255 1 Jean-Michel Pouré
will prompt you for the PIN when you start up the first IPsec connection using the command
256 66 Jean-Michel Pouré
257 66 Jean-Michel Pouré
<pre>
258 66 Jean-Michel Pouré
    ipsec up sun
259 66 Jean-Michel Pouré
</pre>
260 66 Jean-Michel Pouré
261 158 Tobias Brunner
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:
262 66 Jean-Michel Pouré
263 66 Jean-Michel Pouré
<pre>
264 66 Jean-Michel Pouré
    conn rw
265 1 Jean-Michel Pouré
         right=%any
266 66 Jean-Michel Pouré
         rightrsasigkey=%cert
267 66 Jean-Michel Pouré
         left=%defaultroute
268 66 Jean-Michel Pouré
         leftcert=%smartcard1:50
269 66 Jean-Michel Pouré
         auto=add
270 66 Jean-Michel Pouré
</pre>
271 66 Jean-Michel Pouré
272 66 Jean-Michel Pouré
But if there is a corresponding entry
273 66 Jean-Michel Pouré
274 66 Jean-Michel Pouré
<pre>
275 66 Jean-Michel Pouré
    : PIN %smartcard1:50 %prompt
276 66 Jean-Michel Pouré
</pre>
277 66 Jean-Michel Pouré
278 66 Jean-Michel Pouré
in ipsec.secrets, then the standard command
279 66 Jean-Michel Pouré
280 66 Jean-Michel Pouré
<pre>
281 66 Jean-Michel Pouré
    ipsec rereadsecrets
282 66 Jean-Michel Pouré
</pre>
283 66 Jean-Michel Pouré
284 66 Jean-Michel Pouré
or the alias
285 66 Jean-Michel Pouré
286 66 Jean-Michel Pouré
<pre>
287 66 Jean-Michel Pouré
    ipsec secrets
288 66 Jean-Michel Pouré
</pre>
289 66 Jean-Michel Pouré
290 66 Jean-Michel Pouré
can be used to enter the PIN code for this connection interactively. The command
291 66 Jean-Michel Pouré
292 66 Jean-Michel Pouré
<pre>
293 66 Jean-Michel Pouré
    ipsec listcards
294 66 Jean-Michel Pouré
</pre>
295 66 Jean-Michel Pouré
296 66 Jean-Michel Pouré
can be executed at any time to check the current status of the PIN code[s].
297 66 Jean-Michel Pouré
 
298 66 Jean-Michel Pouré
h3. PIN-pad equipped smartcard readers
299 66 Jean-Michel Pouré
300 158 Tobias Brunner
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 surrepticiously installed key logger. In order to tell pluto not to prompt for the PIN on the host itself, the entry
301 66 Jean-Michel Pouré
302 66 Jean-Michel Pouré
<pre>
303 66 Jean-Michel Pouré
    : PIN %smartcard:50 %pinpad
304 66 Jean-Michel Pouré
</pre>
305 66 Jean-Michel Pouré
306 158 Tobias Brunner
can be used in ipsec.secrets. Because the key pad does not cache the PIN in the smart card 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:
307 65 Jean-Michel Pouré
308 1 Jean-Michel Pouré
<pre>
309 128 Jean-Michel Pouré
    config setup
310 1 Jean-Michel Pouré
        pkcs11keepstate=yes
311 127 Jean-Michel Pouré
</pre>
312 127 Jean-Michel Pouré
313 127 Jean-Michel Pouré
The default setting is pkcs11keepstate=no.
314 1 Jean-Michel Pouré
315 1 Jean-Michel Pouré
h2. Acknowledgements and other resources
316 1 Jean-Michel Pouré
317 158 Tobias Brunner
* This article was 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. strongSwan configuration is taken from the strongSwan manual.
318 1 Jean-Michel Pouré
* Bold users: some Java cards may be supported, using the Muscle experimental framework.
319 1 Jean-Michel Pouré
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