Project

General

Profile

strongSwan smart card configuration HOWTO » History » Version 156

Jean-Michel Pouré, 08.03.2010 17:20

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