Project

General

Profile

strongSwan smart card configuration HOWTO » History » Version 159

Tobias Brunner, 26.06.2014 12:03
Some updates for 5.x

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 159 Tobias Brunner
!{float:left;margin-right:10px}strongswan-smartcard.png!
6 158 Tobias Brunner
7 159 Tobias Brunner
Smart cards are a mature technology which prevent your PKI(Public Key Infrastructure) from getting easily compromised by theft.
8 1 Jean-Michel Pouré
9 159 Tobias Brunner
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.
10 158 Tobias Brunner
11 159 Tobias Brunner
In this HOWTO, we give minimal information how to use a reader, initialize cards and configure strongSwan.
12 158 Tobias Brunner
13 86 Jean-Michel Pouré
h2. Compatible hardware
14 1 Jean-Michel Pouré
15 159 Tobias Brunner
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.
16 1 Jean-Michel Pouré
17 1 Jean-Michel Pouré
h3. Compatible card readers
18 1 Jean-Michel Pouré
19 159 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.
20 1 Jean-Michel Pouré
21 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.
22 1 Jean-Michel Pouré
23 1 Jean-Michel Pouré
These Omnikey readers are quite popular:
24 1 Jean-Michel Pouré
* 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.
25 159 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 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.
26 158 Tobias Brunner
27 159 Tobias Brunner
h3. Compatible smart cards and tokens
28 1 Jean-Michel Pouré
29 158 Tobias Brunner
You may use blank cards with support for 1024/2048 bit RSA to store credentials:
30 1 Jean-Michel Pouré
* 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.
31 158 Tobias Brunner
* 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.
32 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.
33 158 Tobias Brunner
* ACOS5 PKI cards are cheap, but unsupported. With a little work, OpenSC could support them.
34 91 Jean-Michel Pouré
35 159 Tobias Brunner
Tested USB tokens include the Feitian ePass2003.
36 158 Tobias Brunner
37 159 Tobias Brunner
The OpenSC project maintains a "list of compatible cards and USB tokens":http://www.opensc-project.org/opensc/wiki/SupportedHardware.
38 159 Tobias Brunner
39 158 Tobias Brunner
You may also use read-only, pre-personalized read-only cards:
40 120 Jean-Michel Pouré
* eID cards. Many European countries offer them and you don't need to buy extra cards for VPN use.
41 1 Jean-Michel Pouré
* [fix-me] Please provide us with names of providers.
42 151 Jean-Michel Pouré
43 1 Jean-Michel Pouré
Where to buy: in Europe, you may try:
44 158 Tobias Brunner
* "Cryptoshop":http://www.cryptoshop.com sells cards and readers from multiple manufacturers (Gemalto, STARCOS SPK, Siemens Card OS).
45 1 Jean-Michel Pouré
* "Smartcard Focus":http://www.smartcardfocus.com also sells cards and readers from several different manufacturers.
46 158 Tobias Brunner
47 138 Jean-Michel Pouré
These shops are not related to the strongSwan community in any way.
48 135 Jean-Michel Pouré
49 32 Jean-Michel Pouré
h2. Preparation
50 1 Jean-Michel Pouré
51 158 Tobias Brunner
h3. Smart card reader
52 158 Tobias Brunner
53 1 Jean-Michel Pouré
To install pcsc-tools with ccid support, under Debian based distributions use:
54 134 Jean-Michel Pouré
<pre>
55 158 Tobias Brunner
sudo apt-get install pcsc-tools libccid
56 32 Jean-Michel Pouré
</pre>
57 7 Jean-Michel Pouré
58 159 Tobias Brunner
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.
59 36 Jean-Michel Pouré
60 159 Tobias Brunner
To install OpenSC use:
61 1 Jean-Michel Pouré
<pre>
62 4 Jean-Michel Pouré
sudo apt-get install opensc
63 22 Jean-Michel Pouré
</pre>
64 22 Jean-Michel Pouré
65 158 Tobias Brunner
Do not install the OpenCT package, as it is incompatible with the pcsc-lite package.
66 22 Jean-Michel Pouré
67 22 Jean-Michel Pouré
Check that the card reader is correctly recognized by OpenSC:
68 22 Jean-Michel Pouré
<pre>
69 22 Jean-Michel Pouré
$ opensc-tool -l
70 1 Jean-Michel Pouré
Readers known about:
71 23 Jean-Michel Pouré
Nr.    Driver     Name
72 1 Jean-Michel Pouré
0      pcsc       OmniKey CardMan 3121 00 00
73 23 Jean-Michel Pouré
</pre>
74 1 Jean-Michel Pouré
75 159 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).
76 1 Jean-Michel Pouré
77 159 Tobias Brunner
Let's double check that the card is recognized by printing its ATR:
78 1 Jean-Michel Pouré
79 1 Jean-Michel Pouré
<pre>
80 1 Jean-Michel Pouré
$ opensc-tool -r0 -a
81 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
82 137 Jean-Michel Pouré
</pre>
83 23 Jean-Michel Pouré
84 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):
85 1 Jean-Michel Pouré
86 1 Jean-Michel Pouré
<pre>
87 1 Jean-Michel Pouré
$ opensc-tool -n
88 1 Jean-Michel Pouré
Using reader with a card: OmniKey CardMan 3121 00 00
89 1 Jean-Michel Pouré
entersafe
90 23 Jean-Michel Pouré
</pre>
91 23 Jean-Michel Pouré
92 1 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).
93 136 Jean-Michel Pouré
94 1 Jean-Michel Pouré
h3. Certification Authority
95 136 Jean-Michel Pouré
96 159 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.
97 136 Jean-Michel Pouré
98 159 Tobias Brunner
Make a backup of your keys/certificates and store it in a safe place.
99 136 Jean-Michel Pouré
100 159 Tobias Brunner
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.
101 1 Jean-Michel Pouré
102 159 Tobias Brunner
h3. Configuring a smart card with pkcsc15-init
103 1 Jean-Michel Pouré
104 159 Tobias Brunner
Credentials on smart cards are usually stored according to the PKCS#15 Cryptographic Token Information Format Standard fully supported by OpenSC.
105 159 Tobias Brunner
106 159 Tobias Brunner
The following command erases the card and removes the existing PKCS#15 structure and all stored cryptographic objects:
107 159 Tobias Brunner
108 71 Jean-Michel Pouré
<pre>
109 1 Jean-Michel Pouré
    pkcs15-init --erase-card
110 1 Jean-Michel Pouré
</pre>
111 159 Tobias Brunner
112 1 Jean-Michel Pouré
This may result in a error if the card is already blank.
113 148 Jean-Michel Pouré
114 159 Tobias Brunner
With the next command a fresh PKCS#15 file structure is created on a smart card or crypto token:
115 1 Jean-Michel Pouré
116 148 Jean-Michel Pouré
<pre>
117 1 Jean-Michel Pouré
pkcs15-init  --create-pkcs15 --profile pkcs15+onepin \
118 148 Jean-Michel Pouré
             --use-default-transport-key \
119 1 Jean-Michel Pouré
             --pin 0000 --puk 111111 \
120 71 Jean-Michel Pouré
             --label "Test"
121 1 Jean-Michel Pouré
</pre>
122 71 Jean-Michel Pouré
123 159 Tobias Brunner
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.
124 158 Tobias Brunner
125 159 Tobias Brunner
Next the private key is transferred to the smart card
126 158 Tobias Brunner
127 1 Jean-Michel Pouré
<pre>
128 1 Jean-Michel Pouré
    pkcs15-init --auth-id 1 --store-private-key myKey.pem
129 1 Jean-Michel Pouré
               [--id 45]
130 71 Jean-Michel Pouré
</pre>
131 158 Tobias Brunner
132 71 Jean-Michel Pouré
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.
133 71 Jean-Michel Pouré
134 159 Tobias Brunner
At last we load the matching X.509 certificate onto the smart card
135 1 Jean-Michel Pouré
136 66 Jean-Michel Pouré
<pre>
137 66 Jean-Michel Pouré
    pkcs15-init --auth-id 1 --store-certificate myCert.pem
138 1 Jean-Michel Pouré
               [--id 45]
139 66 Jean-Michel Pouré
</pre>
140 1 Jean-Michel Pouré
141 66 Jean-Michel Pouré
The pkcs15-tool can now be used to verify the contents of the smart card.
142 66 Jean-Michel Pouré
143 1 Jean-Michel Pouré
<pre>
144 66 Jean-Michel Pouré
    pkcs15-tool --list-pins --list-keys --list-certificates
145 1 Jean-Michel Pouré
</pre>
146 66 Jean-Michel Pouré
147 1 Jean-Michel Pouré
h2. strongSwan configuration
148 1 Jean-Michel Pouré
149 159 Tobias Brunner
h3. pkcs11 plugin
150 66 Jean-Michel Pouré
151 159 Tobias Brunner
To use smart cards with strongSwan the [[PKCS11plugin|pkcs11 plugin]] has to be enabled and configured.
152 66 Jean-Michel Pouré
153 159 Tobias Brunner
If you [[InstallationDocumentation|installed strongSwan]] with your Linux distribution and the pkcs11 plugin is not provided, you'll need to compile strongSwan from sources:
154 1 Jean-Michel Pouré
155 66 Jean-Michel Pouré
<pre>
156 159 Tobias Brunner
./configure <add your options there> --enable-pkcs11
157 66 Jean-Michel Pouré
make
158 158 Tobias Brunner
sudo make install
159 66 Jean-Michel Pouré
</pre>
160 66 Jean-Michel Pouré
161 159 Tobias Brunner
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]].
162 66 Jean-Michel Pouré
163 159 Tobias Brunner
Since version:5.1.2 the plugin is configured in [[strongswandirectory|/etc/strongswan.d]]@/charon/pkcs11.conf@:
164 66 Jean-Michel Pouré
165 66 Jean-Michel Pouré
<pre>
166 159 Tobias Brunner
pkcs11 {
167 159 Tobias Brunner
	modules {
168 159 Tobias Brunner
		opensc {
169 159 Tobias Brunner
			path = /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
170 159 Tobias Brunner
		}
171 159 Tobias Brunner
	}
172 159 Tobias Brunner
}
173 66 Jean-Michel Pouré
</pre>
174 158 Tobias Brunner
175 66 Jean-Michel Pouré
h3. Entering the PIN code
176 66 Jean-Michel Pouré
177 159 Tobias Brunner
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.
178 66 Jean-Michel Pouré
179 159 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]]:
180 66 Jean-Michel Pouré
181 66 Jean-Michel Pouré
<pre>
182 159 Tobias Brunner
: PIN %smartcard:45 "12345678"
183 66 Jean-Michel Pouré
</pre>
184 66 Jean-Michel Pouré
185 66 Jean-Michel Pouré
or with the general notation
186 66 Jean-Michel Pouré
187 66 Jean-Michel Pouré
<pre>
188 159 Tobias Brunner
: PIN %smartcard<slotnr>:<keyid> "<PIN code>"
189 1 Jean-Michel Pouré
</pre>
190 66 Jean-Michel Pouré
191 159 Tobias Brunner
or if multiple PKCS#11 modules are loaded
192 66 Jean-Michel Pouré
193 66 Jean-Michel Pouré
<pre>
194 159 Tobias Brunner
: PIN %smartcard<slotnr>@<module>:<keyid> "<PIN code>"
195 158 Tobias Brunner
</pre>
196 66 Jean-Michel Pouré
197 159 Tobias Brunner
On a personal notebook computer that could get stolen, you wouldn't want to store your PIN in [[PinSecret|ipsec.secrets]].
198 66 Jean-Michel Pouré
199 1 Jean-Michel Pouré
Thus the alternative form
200 66 Jean-Michel Pouré
201 66 Jean-Michel Pouré
<pre>
202 159 Tobias Brunner
: PIN %smartcard:45 %prompt
203 66 Jean-Michel Pouré
</pre>
204 66 Jean-Michel Pouré
205 159 Tobias Brunner
will prompt you for the PIN when triggered with the command
206 66 Jean-Michel Pouré
207 66 Jean-Michel Pouré
<pre>
208 159 Tobias Brunner
ipsec rereadsecrets
209 66 Jean-Michel Pouré
</pre>
210 66 Jean-Michel Pouré
211 159 Tobias Brunner
or the alias
212 66 Jean-Michel Pouré
213 66 Jean-Michel Pouré
<pre>
214 159 Tobias Brunner
ipsec secrets
215 66 Jean-Michel Pouré
</pre>
216 66 Jean-Michel Pouré
217 159 Tobias Brunner
h3. Configuring certificates/connections
218 66 Jean-Michel Pouré
219 159 Tobias Brunner
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.
220 66 Jean-Michel Pouré
221 159 Tobias Brunner
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.
222 66 Jean-Michel Pouré
223 159 Tobias Brunner
For instance, if @alice@strongswan.org@ is contained in the certificate as _subjectAltName_ extension simply configure:
224 66 Jean-Michel Pouré
225 66 Jean-Michel Pouré
<pre>
226 159 Tobias Brunner
leftid=alice@strongswan.org
227 66 Jean-Michel Pouré
</pre>
228 66 Jean-Michel Pouré
229 159 Tobias Brunner
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.
230 66 Jean-Michel Pouré
231 159 Tobias Brunner
The syntax is the same like that for [[PINSecret|PIN secrets]] in ipsec.secrets:
232 159 Tobias Brunner
233 66 Jean-Michel Pouré
<pre>
234 159 Tobias Brunner
leftcert=%smartcard[<slotnr>[@<module>]]:<keyid>
235 66 Jean-Michel Pouré
</pre>
236 66 Jean-Michel Pouré
237 159 Tobias Brunner
Thus
238 66 Jean-Michel Pouré
239 66 Jean-Michel Pouré
<pre>
240 159 Tobias Brunner
leftcert=%smartcard:50
241 65 Jean-Michel Pouré
</pre>
242 1 Jean-Michel Pouré
243 159 Tobias Brunner
will look in all available modules and slots for ID 0x50 starting with the first slot whereas
244 1 Jean-Michel Pouré
245 127 Jean-Michel Pouré
<pre>
246 159 Tobias Brunner
leftcert=%smartcard4:50
247 127 Jean-Michel Pouré
</pre>
248 1 Jean-Michel Pouré
249 159 Tobias Brunner
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.
250 1 Jean-Michel Pouré
251 158 Tobias Brunner
h2. Acknowledgements and other resources
252 1 Jean-Michel Pouré
253 159 Tobias Brunner
* 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.