Let gpgsm do the actual key selection work.
[scute.git] / README
1 Scute
2 =====
3
4 This is a PKCS #11 implementation for the GnuPG Agent using the GnuPG
5 Smart Card Daemon.  Currently, only the OpenPGP card is supported.
6
7 TOC
8 ===
9
10 * Purpose
11 * Prerequisites
12 * Installation
13 * Client Authentication
14 * Troubleshooting
15 * Features and Limitations
16 * Development
17 * Mozilla Bugs
18 * Copyright and License
19
20
21 Purpose
22 =======
23
24 Scute enables you to use your OpenPGP smart card for client
25 authentication with SSL in Mozilla.  See below for more details on how
26 to get this working.
27
28 Scute also allows you to sign emails with Thunderbird, using the
29 S/MIME protocol, and to sign OpenDocument and PDF files with
30 LibreOffice.
31
32
33 Prerequisites
34 =============
35
36 For the compilation:
37 * libgpg-error 1.14
38 * libassuan 2.0.0
39
40 At runtime:
41 * Mozilla (or any other supported application using PKCS #11).
42 * GnuPG 2.0, in particular: gpg-agent, scdaemon
43 * Pinentry
44
45 Note that client authentication with TLS 1.2 and S/MIME signing
46 require GnuPG 2.1.
47
48
49 Installation
50 ============
51
52 To install the PKCS #11 Module, follow the generic installation
53 instructions in the file INSTALL that accompanies this software.
54
55 After installation, you can configure Mozilla to use Scute by
56 visiting the preferences dialog in the "advanced" category, under
57 "Security Devices".  There you can "load" the module from its
58 installed path, e.g. "/usr/lib/scute.so".
59
60
61 Client Authentication
62 =====================
63
64 For client authentication to work, several steps need to be completed.
65 Depending on your situation, some of these steps may be performed by
66 third parties, like service providers.  However, they can also all be
67 performed locally, if use of client authentication with a local
68 service is desired.
69
70 For this introduction, we assume an Apache web server with SSL at the
71 server side, and a connecting client running Firefox.  As a
72 certification authority (CA) we use OpenSSL.  Scute provides a PKCS #11
73 compatible security device to Firefox for client authentication.  This
74 security device gives Firefox access to the client's OpenPGP smart
75 card.
76
77 The Client Perspective
78 ----------------------
79
80 To get things started, we have to prepare an initialised OpenPGP smart
81 card by uploading an off-card key or generating a key on the card.
82 The card you got may already have been initialised.  Otherwise, you
83 can find more information on this step in the smartcard HowTo, which
84 also documents other basic card operations:
85 http://www.gnupg.org/(en)/howtos/card-howto/en/smartcard-howto.html
86
87 Once the card is initialised, we have to generate a certificate
88 signing request (CSR) to get the authentication key of the card
89 (OPENPGP.3, the third key on the card) certified by the CA.  This can
90 be done using "gpgsm --gen-key".  For the CSR, a distinguished name
91 (DN) is required.  Your CA will have more information about what this
92 DN should contain.  Below we use an example for a test-employee
93 "Floppy Head" of the test-CA that ships with OpenSSL ("Snake Oil,
94 Ltd.").
95
96 Generating the CSR is then just a matter of answering a few questions:
97
98 $ gpgsm --gen-key > client.csr
99 Please select what kind of key you want:
100    (1) RSA
101    (2) Existing key
102    (3) Existing key from card
103 Your selection? 3
104 Serial number of the card: 355F9746499F0D4B4ECEE4928B007D16
105 Available keys:
106    (1) D53137B94C38D9BF6A199706EA6D5253 OPENPGP.1
107    (2) B0CD1A9DFC3539A1D6A8B851A11C8665 OPENPGP.2
108    (3) 53DB41052CC590A40B403F3E6350E5DC OPENPGP.3
109 Your selection? 3
110 Possible actions for a RSA key:
111    (1) sign, encrypt
112    (2) sign
113    (3) encrypt
114 Your selection? 2
115 Enter the X.509 subject name: CN=Floppy Head,OU="Webserver Team",O="Snake Oil, Ltd",L="Snake Town",ST="Snake Desert",C=XY
116 Enter email addresses (end with an empty line):
117 > floppy.head@example.org
118 >
119 Enter DNS names (optional; end with an empty line):
120 >
121 Enter URIs (optional; end with an empty line):
122 >
123 Create self-signed certificate? (y/N) n
124 These parameters are used:
125     Key-Type: card:OPENPGP.3
126     Key-Length: 1024
127     Key-Usage: sign
128     Name-DN: CN=Floppy Head,OU="Webserver Team",O="Snake Oil, Ltd",L="Snake Town",ST="Snake Desert",C=XY
129     Name-Email: floppy.head@example.org
130
131 Proceed with creation? (y/N) y
132 Now creating certificate request.  This may take a while ...
133 gpgsm: about to sign the CSR for key: &53DB41052CC590A40B403F3E6350E5DC
134 gpgsm: certificate request created
135 Ready.  You should now send this request to your CA.
136
137 It is required to enter the signing PIN of the card to complete this
138 step.  The certificate can then be found in the file "/tmp/floppy.csr".
139 This file should then be sent to the CA for certification (see below).
140
141 The CA will return to the client a certificate "/tmp/floppy.crt", who
142 can then import the issuer certificate of the CA (in this example, we
143 access directly the local server certificate) and its own certificate
144 with gpgsm:
145
146 $ gpgsm --import /etc/apache/ssl.crt/snakeoil-ca-rsa.crt
147 gpgsm: total number processed: 1
148 gpgsm:               imported: 1
149 marcus@ulysses:~/g10/projects/pkcs11-for-scdaemon/ca/usercert/card3$ gpgsm --import /tmp/floppy.crt
150 gpgsm: total number processed: 1
151 gpgsm:              unchanged: 1
152
153 $ gpgsm --list-keys Floppy
154 Serial number: 08
155        Issuer: /CN=Snake Oil CA/OU=Certificate Authority/O=Snake Oil, Ltd/L=Snake Town/ST=Snake Desert/C=XY/EMail=ca@snakeoil.dom
156       Subject: /CN=Floppy Head/OU=Webserver Team/O=Snake Oil, Ltd/ST=Snake Desert/C=XY
157      validity: 2006-10-11 13:17:08 through 2007-10-11 13:17:08
158      key type: 1024 bit RSA
159   fingerprint: C9:08:0E:86:92:6C:7B:4B:8C:23:1C:9D:D7:15:BF:D4:A4:00:54:11
160
161 Now the client can configure his web browser.  If desired, the client
162 can install the web servers certificate (alternatively, Firefox will
163 ask when establishing the initial connection).
164
165 To actually perform the client authentication, the client needs to set
166 up the web browser for use with Scute.  The Scute PKCS #11 module,
167 installed under /usr/lib/scute.so by default, needs to be loaded as
168 a security device in Firefox under
169 Preferences->Advanced->Security->Certificates->Security Devices->Load
170 When the security device is loaded, card insertion should cause the
171 security device list be updated with the inserted token (the card), and the certificate that has been imported into gpgsm should be visible under 
172 Preferences->Advanced->Security->Certificates->View Certificates
173 automatically.
174
175 Firefox will by default select the certificate to be used for client
176 authentication automatically from the list of available certificates.
177 This setting can be changed if desired in
178 Preferences->Advanced->Security->Certificates ("Select one
179 automatically" vs. "Ask me every time")
180
181 When the client then attempts to open the URL "https://localhost/" in
182 this example, the web server will require SSL authentication, which
183 causes Firefox to look (or ask) for a client certificate.  If the
184 certificate on the card is suitable (or selected), the user will have
185 to enter the PIN number on the card to sign into the web site.
186
187
188 The CA Perspective
189 ------------------
190
191 The CA will have to process the CSR submitted by the client.  After
192 verifying the identity of the submitter by some external means, the CA
193 may use for example this OpenSSL command to create a certificate (we
194 use the example CA shipping with the Apache SSL module on Ubuntu):
195
196 # cd /etc/apache/ssl.crt/
197 # openssl ca -in /tmp/floppy.csr -cert /etc/apache/ssl.crt/snakeoil-ca-rsa.crt -keyfile /etc/apache/ssl.key/snakeoil-ca-rsa.key -out /tmp/floppy.crt
198 Using configuration from /usr/lib/ssl/openssl.cnf
199 Check that the request matches the signature
200 Signature ok
201 Certificate Details:
202         Serial Number: 8 (0x8)
203         Validity
204             Not Before: Oct 11 13:17:08 2006 GMT
205             Not After : Oct 11 13:17:08 2007 GMT
206         Subject:
207             countryName               = XY
208             stateOrProvinceName       = Snake Desert
209             organizationName          = Snake Oil, Ltd
210             organizationalUnitName    = Webserver Team
211             commonName                = Floppy Head
212         X509v3 extensions:
213             X509v3 Basic Constraints:
214                 CA:FALSE
215             Netscape Comment:
216                 OpenSSL Generated Certificate
217             X509v3 Subject Key Identifier:
218                 72:AF:B8:13:3D:3D:9D:02:93:E4:D4:56:0C:06:90:4C:26:85:85:5D
219             X509v3 Authority Key Identifier:
220                 DirName:/C=XY/ST=Snake Desert/L=Snake Town/O=Snake Oil, Ltd/OU=Certificate Authority/CN=Snake Oil CA/emailAddress=ca@snakeoil.dom
221                 serial:00
222
223 Certificate is to be certified until Oct 11 13:17:08 2007 GMT (365 days)
224 Sign the certificate? [y/n]:y
225
226
227 1 out of 1 certificate requests certified, commit? [y/n]y
228 Write out database with 1 new entries
229 Data Base Updated
230
231 The resulting file, "/tmp/floppy.crt" is sent back from the CA to the
232 client along with the issuer certificate.
233
234 For more information how to set up and work with a CA using OpenSSL,
235 please see the OpenSSL documentation.
236
237 The Server Perspective
238 ----------------------
239
240 The service provider will set up an Apache web server with SSL
241 support, and configure it to accept certificates from the CA.  This
242 step is quite involved.  Garex has a concise HowTo online at
243 http://www.garex.net/apache/ about how to do this.  Beside the
244 creation of a certificate that has its own fully qualified domain name
245 (FQDN) as common name (CN part of the DN), this involves installing
246 the Apache SSL module and configuration for it, for example in
247 httpd.conf:
248
249 SSLEngine on
250 SSLCertificateFile /etc/apache/ssl.crt/server.crt
251 SSLCertificateKeyFile /etc/apache/ssl.key/server.key
252
253 SSLVerifyClient require
254 SSLVerifyDepth 1
255 SSLCACertificateFile /etc/apache/ssl.crt/snakeoil-ca-rsa.crt
256
257 The file server.key is not protected by a passphrase (if it is, this
258 passphrase needs to be provided when starting up Apache), and
259 server.crt has "CN=localhost" as part of its DN for this example.
260
261
262 Troubleshooting
263 ===============
264
265 Symptom: Loading the Scute security device in the security device
266 manager of Firefox fails with "Unable to load module".
267
268 Solution: Make sure that Scute is correctly installed, and that all
269 libraries and executables are available.  Make sure that gpg-agent is
270 running and can be found via the environment variable GPG_AGENT_INFO.
271
272
273 Symptom: Client authentication fails with "<example.com> has received
274 an incorrect or unexpected message.  Error code: -12227".
275
276 Solution: Make sure that the correct OpenPGP card is inserted and the
277 certificate available in GPGSM.  Check that the OpenPGP card is
278 detected correctly in the security device manager and the
279 corresponding certificate is displayed in the certificate manager of
280 Firefox.
281
282
283 Symptom: The OpenPGP card is detected and displayed in the security
284 device manager in Firefox, but no corresponding certificate is
285 displayed in the certificate manager of Firefox.
286
287 Solution: Make sure that the corresponding certificate is imported in
288 GPGSM.
289
290
291 Features and Limitations
292 ========================
293
294 Scute implements version 2.20 of the PKCS #11 specification.
295
296 The OpenPGP smart card application is supported in read-only mode.
297
298 The following functions are not supported:
299
300 * C_Initialize: No support for native thread package.  Locking
301   callbacks must be provided if multi-threaded operation is desired.
302
303 * C_WaitForSlotEvent: Not implemented.  The interface as specified by
304   PKCS #11 is broken anyway, as the function can not safely be
305   canceled.  Thus, we require polling.
306
307 * C_GetOperationState, C_SetOperationState: Not supported.
308
309 * C_InitToken, C_InitPIN, C_SetPIN: Not supported.  No write
310   operations are allowed.  To configure the token, please use the
311   tools accompanying the GnuPG software suite.
312
313 * C_Login, C_Logout: Not supported.  No login into the token by the
314   software is required.  Passphrase queries are implemented by the use
315   of GPG Agent and Pinentry.
316
317 * C_EncryptInit, C_Encrypt, C_EncryptUpdate, C_EncryptFinal,
318   C_DigestInit, C_Digest, C_DigestUpdate, C_DigestKey, C_DigestFinal,
319   C_VerifyInit, C_Verify, C_VerifyUpdate, C_VerifyFinal,
320   C_VerifyRecoverInit, C_VerifyRec: Not supported.  Only secret key
321   operations are supported.
322
323 * C_DecryptInit, C_Decrypt: Not yet supported, but will be in the
324   future.
325
326 * C_SignUpdate, C_SignFinal, C_DecryptUpdate, C_DecryptFinal: No
327   progressive crypto-operations are supported.
328
329 * C_SignRecoverInit, C_SignRecover: Not supported.
330
331 * C_DigestEncryptUpdate, C_DecryptDigestUpdate, C_SignEncryptUpdate,
332   C_DecryptVerifyUpdate: Dual-purpose cryptographic functions are not
333   supported.
334
335 * C_GenerateKey, C_GenerateKeyPair, C_WrapKey, C_UnwrapKey,
336   C_DeriveKey: Key management functions are not supported.  Please use
337   the tools accompanying the GnuPG software suite to generate and
338   import keys for use with the token.
339
340 * C_SeedRandom: Not supported.
341
342 * C_CreateObject, C_CopyObject, C_DestroyObject, C_SetAttributeValue:
343   Only read-only operations are supported on objects.
344
345 * C_GetObjectSize: Not supported.
346
347 * CKO_CERTIFICATE:
348   The label specifies the key on the card used (e.g. OPENPGP.3).  The
349   ID is the fingerprint.
350
351 * CKO_PRIVATE_KEY:
352   The CKA_LOCAL attribute can not be supported by the OpenPGP card.
353   It is always set to false (as the key on the card may be copied to
354   the card from an external source).
355
356
357 Development
358 ===========
359
360 Scute is single-threaded.  There is a global lock that is taken in all
361 entry points of Scute, except for C_Initialize, C_Finalize,
362 C_GetFunctionList, and stubs.
363
364
365 Here are a couple of hints on how to develop PKCS #11 modules for
366 Mozilla:
367
368 libopensc2 ships with a pkcs11-spy library that can be loaded as a
369 wrapper around the PKCS #11 library you want to use to log all
370 functions invoked by Mozilla.  Here is how to use it:
371
372  Set the PKCS11SPY_OUTPUT environment variable to a filename.
373  pkcs11-spy appends its log messages at the end of this file.  Set the
374  PKCS11SPY environment variable to the filename of the PKCS #11 module
375  you actually want to use.  Start Mozilla within this environment.
376
377 There is a different, probably more powerful way to debug Mozilla PKCS
378 #11 libraries.  However, to be able to use it, you need to configure
379 and compile the Mozilla NSS sources with --enable-debug.  Instructions
380 can be found at:
381 http://www.mozilla.org/projects/security/pki/nss/tech-notes/tn2.html
382
383 Here are a couple of links to more information about implementing a
384 PKCS #11 module for Mozilla:
385
386 Implementing PKCS #11 for the Netscape Security Library
387 (Caution: The content may be out of date)
388 http://docs.sun.com/source/816-6150-10/index.htm
389 http://docs.sun.com/source/816-6150-10/pkcs.htm
390
391 Common PKCS #11 Implementation Problems
392 http://www.mozilla.org/projects/security/pki/pkcs11/netscape/problems.html
393
394 PKCS #11 Conformance Testing
395 http://www.mozilla.org/projects/security/pki/pkcs11/
396
397 And of course the Mozilla NSS web page:
398 http://www.mozilla.org/projects/security/pki/nss/
399
400
401 Mozilla Bugs
402 ============
403
404 Mozilla has a bug that causes the security devices list to become
405 corrupt when a security device is unloaded: The wrong entry is removed
406 from the list.  This is corrected by waiting for a refresh or closing
407 and reopening the security device manager.
408
409
410 Copyright and License
411 =====================
412
413 Scute is copyrighted by g10 Code GmbH and licensed under the GNU
414 General Pubic License version 2 or later with this exception:
415
416   In addition, as a special exception, g10 Code GmbH gives permission
417   to link this library: with the Mozilla Foundation's code for
418   Mozilla (or with modified versions of it that use the same license
419   as the "Mozilla" code), and distribute the linked executables.  You
420   must obey the GNU General Public License in all respects for all of
421   the code used other than "Mozilla".  If you modify the software, you
422   may extend this exception to your version of the software, but you
423   are not obligated to do so.  If you do not wish to do so, delete this
424   exception statement from your version and from all source files.
425
426
427 g10 Code GmbH
428 marcus@g10code.com
429
430
431  Copyright 2006, 2009 g10 Code GmbH
432
433  This file is free software; as a special exception the author gives
434  unlimited permission to copy and/or distribute it, with or without
435  modifications, as long as this notice is preserved.
436
437  This file is distributed in the hope that it will be useful, but
438  WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
439  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.