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