Add a manual section for card-stored certificates.
[scute.git] / doc / manual / scute.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename scute.info
3 @settitle The Scute Manual
4
5 @dircategory GNU Utilities
6 @direntry
7 * Scute: (scute).          PKCS #11 module for the OpenPGP Card
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the Scute module.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The Scute Manual}, for Version @value{VERSION}.
21
22 @c NOTE: Don't forget to update the year for the TeX version, too.
23 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.
24
25 The Scute Manual is free software; you can redistribute it and/or modify
26 it under the terms of the GNU General Public License as published by the
27 Free Software Foundation; either version 2 of the License, or (at your
28 option) any later version.
29
30 The Scute Manual is distributed in the hope that it will be useful, but
31 WITHOUT ANY WARRANTY; without even the implied warranty of
32 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
33 General Public License for more details.
34
35 You should have received a copy of the GNU Lesser General Public License
36 along with this program; if not, write to the Free Software Foundation,
37 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
38
39 @end ifinfo
40
41 @iftex
42 @shorttitlepage The Scute Manual
43 @end iftex
44 @titlepage
45 @center @titlefont{The Scute Manual}
46 @sp 6
47 @center Edition @value{EDITION}
48 @sp 1
49 @center last updated @value{UPDATED}
50 @sp 1
51 @center for version @value{VERSION}
52 @page
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.
55
56
57 The Scute Manual is free software; you can redistribute it and/or modify
58 it under the terms of the GNU General Public License as published by the
59 Free Software Foundation; either version 2 of the License, or (at your
60 option) any later version.
61
62 The Scute Manual is distributed in the hope that it will be useful, but
63 WITHOUT ANY WARRANTY; without even the implied warranty of
64 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
65 General Public License for more details.
66
67 You should have received a copy of the GNU Lesser General Public License
68 along with this program; if not, write to the Free Software Foundation,
69 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
70 @end titlepage
71 @page
72
73 @ifnottex
74 @node Top
75 @top Main Menu
76 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
77 @cite{The Scute Manual}, for Version @value{VERSION} of the Scute
78 module.
79 @end ifnottex
80
81 @menu
82 * Introduction::                  How to use this manual.
83 * Preparation::                   What you should do before using Scute.
84 * Client Authentication::         How to use Scute for client authentication.
85 * Email Signing::                 How to use Scute for S/MIME email signing.
86 * Document Signing::              How to use Scute with LibreOffice.
87 * Troubleshooting::               What to do when things go wrong.
88 * Internals::                     Technical details about Scute.
89
90 Appendices
91
92 * Copying::                       The GNU General Public License says
93                                   how you can copy and share Scute.
94
95 Indices
96
97 * Concept Index::                 Index of concepts and programs.
98
99
100 @detailmenu
101  --- The Detailed Node Listing ---
102
103 Introduction
104
105 * Getting Started::               Purpose of the manual, and how to use it.
106 * Features::                      Reasons to install and use Scute.
107 * Overview::                      Basic architecture of the Scute module.
108
109 Preparation
110
111 * Prerequisites::                 Dependencies of Scute.
112 * Building the Source::           How to build Scute.
113 * Certificate Preparation::       Preparing certificates for use with Scute.
114
115 Client Authentication
116
117 * Application Configuration::     Preparing the application for use with Scute.
118 * Authentication With Service::   Using Scute for client authentication.
119
120 Email Signing
121
122 Document Signing
123
124 Troubleshooting
125
126 Internals
127
128 * Features and Limitations::      Details about the interfaces implemented.
129 * Developing Scute::              How to understand or improve Scute.
130 * Mozilla Compatibility::         Interoperability notes for Mozilla NSS.
131
132
133 @end detailmenu
134 @end menu
135
136 @node Introduction
137 @chapter Introduction
138
139 This is a PKCS #11 implementation for the GnuPG Agent using the GnuPG
140 Smart Card Daemon.  Currently, only the OpenPGP card is supported.
141
142 Scute enables use of the OpenPGP smart card in applications supporting
143 PKCS #11 compliant security tokens.  The main application at this time
144 is client authentication in Mozilla-based web browsers.  In the future,
145 other applications will be supported.
146
147
148 @menu
149 * Getting Started::               Purpose of the manual, and how to use it.
150 * Features::                      Reasons to install and use Scute.
151 * Overview::                      Basic architecture of the Scute module.
152 @end menu
153
154
155 @node Getting Started
156 @section Getting Started
157
158 This manual documents the Scute module, how it can be used for common
159 applications supported by it, and how it can be extended and improved by
160 programmers.  It is thus a user manual as well as a developer manual.
161
162 The reader is assumed to possess basic knowledge about cryptography in
163 general, and public key cryptography in particular.  The underlying
164 cryptographic engines that are used by the library are not explained,
165 but where necessary, special features or requirements are provided.
166
167 This manual can be used in several ways.  If read from the beginning to
168 the end, it gives a good introduction into the module and how it can be
169 used in an application.  Forward references are included where
170 necessary.  Later on, the manual can be used as a reference manual to
171 get just the information needed about any particular application of the
172 module.
173
174
175 @node Features
176 @section Features
177
178 Scute is currently the only implementation of PKCS #11 for the OpenPGP
179 smart card.  Apart from that, it offers a couple of other benefits:
180
181 @table @asis
182 @item it's free software
183 Anybody can use, modify, and redistribute it under the terms of the GNU
184 General Public License (@pxref{Copying}).
185
186 @item it's built to grow
187 Although Scute initially provided a single function, client
188 authentication using OpenPGP smart cards in Mozilla-based web browsers,
189 it was built with the intention of supporting other applications as well
190 in the future.
191
192 @item it's easy
193 Building and installing Scute is easy, and preparing smart cards for use
194 with Scute is a snatch using the GnuPG 2 framework.  The integration
195 of Scute into the application is seamless.
196 @end table
197
198
199 @node Overview
200 @section Overview
201
202 Scute is a security device that implements the PKCS #11 interface for
203 security tokens.  Applications which know how to use the PKCS #11
204 interface to access security tokens for cryptographic operations can use
205 Scute to access the OpenPGP smart card.  An important example of such an
206 application is the Firefox web browser by the Mozilla project, which
207 uses the Mozilla Network Security Services library (NSS).
208
209 Scute itself does not include a driver for the smart card itself.
210 Instead, it uses the GnuPG 2 framework to access the smart cards and
211 associated data like certificates.  Scute acts as the glue between the
212 application and GnuPG 2.
213
214 Currently supported usages are client authentication over HTTPS with
215 Firefox (allowing users to authenticate themselves to a remote web
216 service without entering their log-in information), email signing
217 with Thunderbird, and document signing with LibreOffice.
218
219
220 @node Preparation
221 @chapter Preparation
222
223 To use Scute, you first have to install the software.  You also have to
224 prepare each card you want to use with Scute before it can be used.
225 Furthermore, you need to configure the application to make use of Scute
226 for cryptographic operations.  This chapter explains each of these steps
227 in detail.
228
229 @menu
230 * Prerequisites::                 Dependencies of Scute.
231 * Building the Source::           How to build Scute.
232 * Certificate Preparation::       Preparing certificates for use with Scute.
233 @end menu
234
235
236 @node Prerequisites
237 @section Prerequisites
238
239 There are two types of dependencies for Scute: compile-time dependencies
240 and run-time dependencies.  The compile-time dependencies only need to
241 be fulfilled when Scute is compiled and installed.  The run-time
242 dependencies need to be fulfilled when Scute is used in an application.
243
244 Scute depends, in addition to the essential build utilities, on the
245 following packages at build time:
246
247 @table @code
248 @item libgpg-error
249 Scute uses the GnuPG 2 framework for error handling, so it depends on
250 the GPG error library.  The minimum version required is 1.14.
251
252 @item libassuan
253 Scute uses the GnuPG 2 framework for communication with the GPG Agent,
254 so it depends on the Assuan library.  The minimum version required is
255 2.0.0.
256 @end table
257
258 At run-time, in addition to the run-time versions of the above
259 libraries, you also need the following packages installed and
260 configured:
261
262 @table @asis
263 @item GnuPG
264 Scute uses the GnuPG 2 framework to access the OpenPGP card and for
265 certificate management.  The minimum version required is 2.0.0 for
266 client authentication with TLS 1.0 and 1.1.  Client authentication
267 with TLS 1.2, email and document signing require GnuPG 2.1.0.
268
269 @item Pinentry
270 Pinentry is a dependency of GnuPG 2, so it also needs to be installed
271 with it.
272
273 @item Firefox et al.
274 Firefox is the first application supported by Scute.  In the future,
275 other applications may be supported.  The applications are not
276 dependencies of Scute, but Scute can not be used stand-alone, so you can
277 not experience it without an application.
278 @end table
279
280
281 @node Building the Source
282 @section Building the Source
283
284 Scute does comply to the GNU coding standards and thus can be compiled
285 and installed according to the generic installation instructions found
286 in the source package in the file @code{INSTALL}.  There are no Scute
287 specific options to the configure script.
288
289 After installation, the @code{scute.so} module file can be found in
290 the library directory of the installation path.
291
292
293 @node Certificate Preparation
294 @section Certificate Preparation
295
296 To use an OpenPGP card with Scute, it first has to be initialized by
297 generating or loading a key on the card, see
298 @uref{http://www.gnupg.org/(en)/howtos/card-howto/en/smartcard-howto.html,
299 the OpenPGP Card How-To}.  Then a certificate has to be created and
300 imported into GPGSM.  This task involves three steps: First, a
301 certificate signing request (@acronym{CSR}) has to be created that
302 matches the key on the card.  This certificate signing request then has
303 to be submitted to a certificate authority (@acronym{CA}), which will
304 create the certificate and send it back to you.  At last, the
305 certificate has to be imported into GPGSM.  This section will explain
306 all of these steps in detail.
307
308 @menu
309 * Creating a CSR::                How to create a card-based CSR.
310 * Signing the CSR::               Obtain a certificate from the CSR.
311 * Importing the Certificate::     How to import the certificate into GPGSM.
312 * On-card Certificate::           How to store the certificate on the card.
313 @end menu
314
315 @node Creating a CSR
316 @subsection Creating a CSR
317
318 Before you start, make sure that the GPG Agent is running, see
319 @ref{Prerequisites} and that your card is in the reader.  There is no
320 need to configure GPGSM, so you can create a CSR with the command:
321
322 @example
323 $ gpgsm --gen-key > floppy-head.csr
324 Please select what kind of key you want:
325    (1) RSA
326    (2) Existing key
327    (3) Existing key from card
328 Your selection? 3
329 @end example
330
331 As we create a certificate for the OpenPGP Card, the option ``@code{[3]
332 Direct from card}'' should be selected.
333
334 @example
335 Serial number of the card: 355F9746499F0D4B4ECEE4928B007D16
336 Available keys:
337    (1) D53137B94C38D9BF6A199706EA6D5253 OPENPGP.1
338    (2) B0CD1A9DFC3539A1D6A8B851A11C8665 OPENPGP.2
339    (3) 53DB41052CC590A40B403F3E6350E5DC OPENPGP.3
340 Your selection? 3
341 Possible actions for a RSA key:
342    (1) sign, encrypt
343    (2) sign
344    (3) encrypt
345 Your selection? 2
346 @end example
347
348 The only operation currently supported is client authentication.  For
349 this, the authentication key has to be selected.  This is the third key
350 on the card, so the options ``@code{[3] OPENPGP.3}'' and ``@code{[2]
351 sign}'' should be chosen.  Note that the key usage is only advisory, and
352 the CA may assign different capabilities.
353
354 @example
355 Enter the X.509 subject name: CN=Floppy Head,OU="Webserver Team",O="Snake Oil, Ltd",L="Snake Town",ST="Snake Desert",C=XY
356 Enter email addresses (end with an empty line):
357 > floppy.head@@example.org
358 >
359 Enter DNS names (optional; end with an empty line):
360 >
361 Enter URIs (optional; end with an empty line):
362 >
363 Create self-signed certificate? (y/N) n
364 @end example
365
366 As a last step, the common name and e-mail address of the key owner need
367 to be specified by you.  The above are only an example for a fictious
368 person working at a fictious company.  DNS names are only meaningful for
369 server certificates and thus should be left empty.
370
371 We have now entered all required information and gpgsm will display what
372 it has gathered and ask whether to create the certificate request:
373
374 @example
375 These parameters are used:
376     Key-Type: card:OPENPGP.3
377     Key-Length: 1024
378     Key-Usage: sign
379     Name-DN: CN=Floppy Head,OU="Webserver Team",O="Snake Oil, Ltd",L="Snake Town",ST="Snake Desert",C=XY
380     Name-Email: floppy.head@@example.org
381
382 Proceed with creation? (y/N) y
383 Now creating certificate request.  This may take a while ...
384 gpgsm: about to sign the CSR for key: &53DB41052CC590A40B403F3E6350E5DC
385 @end example
386
387 GPGSM will now start working on creating the request.  During this time
388 you will be asked once for a passphrase to unprotect the authentication
389 key on the card.  A pop up window will appear to ask for it.
390
391 When it is ready, you should see the final notice:
392
393 @example
394 gpgsm: certificate request created
395 Ready.  You should now send this request to your CA.
396 @end example
397
398 Now, you may look at the created request:
399
400 @example
401 $ cat floppy-head.csr
402 -----BEGIN CERTIFICATE REQUEST-----
403 MIICCDCCAXECAQAwgYExCzAJBgNVBAYTAlhZMRUwEwYDVQQIEwxTbmFrZSBEZXNl
404 cnQxEzARBgNVBAcTClNuYWtlIFRvd24xFzAVBgNVBAoTDlNuYWtlIE9pbCwgTHRk
405 MRcwFQYDVQQLEw5XZWJzZXJ2ZXIgVGVhbTEUMBIGA1UEAxMLRmxvcHB5IEhlYWQw
406 gaAwDQYJKoZIhvcNAQEBBQADgY4AMIGKAoGBANWaM9YS89AOx3GX1Rua+4DUHwbL
407 wt0rBYdBddlabMMteVjUcOOhbFMirLpLAi1S8fUXNiy84ysOmFStmvSIXDsAgXq5
408 1ESOU4SNg2zEkPDF1WYJ5BFIXdYq9i2k5W7+ctV8PkKv3e5IeYXTa5qppIPD31de
409 gM8Qj7tK0hL/eNCfAgQAAQABoEUwQwYJKoZIhvcNAQkOMTYwNDAiBgNVHREEGzAZ
410 gRdmbG9wcHkuaGVhZEBleGFtcGxlLmNvbTAOBgNVHQ8BAf8EBAMCBsAwDQYJKoZI
411 hvcNAQEFBQADgYEAFC9q6+ib9YGCLB/2AlZR+/dvb+pEeXR1EbpV/dw/gjP1yPY6
412 29n8ZIDLUvQvNCtfCcXFxFimVSSB/KmFXXsJbM+NXQyT6Ocn34iHmkf9IVRMWQWg
413 ZBYfQVeXAd7XlxI6d1wXDLwD/26lTU/rH2JU6H1+zSfZxqwVC4Iu+kiN4Y8=
414 -----END CERTIFICATE REQUEST-----
415 $
416 @end example
417
418 @node Signing the CSR
419 @subsection Signing the CSR
420
421 The next step is to submit this certificate request to the CA, which can
422 then create a certificate and send it back to you.
423
424 If, for example, you use the CA @uref{http://www.cacert.org, CAcert},
425 then you can log into your account at the CAcert website, choose
426 ``Client Certificates -> New'', check ``Show advanced options'', paste
427 the above request block into the text field and click on ``Submit''.
428 If everything works correctly, a certificate will be shown, which you
429 can cut and paste into a new file @file{floppy-head.crt}.
430
431 Alternatively if, for example, you set up your own CA with OpenSSL, then
432 you can create your own certificate by issueing a command similar
433 @code{openssl ca -in floppy-head.csr -cert snakeoil-ca-rsa.crt -keyfile
434 snakeoil-ca-rsa.key -out floppy-head.crt}.  Please see the OpenSSL
435 documentation for more details on how to set up and administrate a
436 certificate authority infrastructure.
437
438 @node Importing the Certificate
439 @subsection Importing the Certificate into GPGSM
440
441 Once the CSR has been signed, you should end up with a certificate file
442 @file{floppy-head.crt}, which you then have to import into GPGSM.  It is
443 also recommended that you import the root certificate of the CA first in
444 the same fashion.
445
446 @example
447 $ gpgsm --import floppy-head.crt
448 gpgsm: certificate imported
449   
450 gpgsm: total number processed: 1
451 gpgsm:               imported: 1
452 @end example
453
454 gpgsm tells you that it has imported the certificate.  It is now
455 associated with the key you used when creating the request.  To see the
456 content of your certificate, you may now enter:
457
458 @example
459 $ gpgsm -K Floppy
460 /home/foo/.gnupg/pubring.kbx
461 ---------------------------
462 Serial number: 10
463        Issuer: /CN=Snake Oil CA/OU=Certificate Authority/O=Snake Oil, Ltd/L=Snake Town/ST=Snake Desert/C=XY/EMail=ca@@snakeoil.dom
464       Subject: /CN=Floppy Head/OU=Webserver Team/O=Snake Oil, Ltd/ST=Snake Desert/C=XY
465      validity: 2006-11-11 14:09:12 through 2007-11-11 14:09:12
466      key type: 1024 bit RSA
467   fingerprint: EC:93:A2:55:C6:58:7F:C9:9E:96:DB:12:6E:64:99:54:BB:E1:94:68
468 @end example
469
470 The option ``@code{-K}'' is used above because this will only list
471 certificates for which a private key is available.  To see more details,
472 you may use ``@code{--dump-secret-keys}'' instead of ``@code{-K}''.
473
474 @node On-card Certificate
475 @subsection Loading the Certificate onto the Card
476
477 This step is optional. You may choose to store the certificate directly
478 into your OpenPGP card. The benefit of doing so is that Scute will then
479 be able to fetch the certificate from the card without having to look
480 into the GPGSM store.
481
482 You need your certificate in the DER format. Export it from the GPGSM
483 store with the following command:
484
485 @example
486 $ gpgsm -o floppy-head.crt --export Floppy
487 @end example
488
489 Then, fire up the GnuPG card editor to transfer the certificate to the
490 card (note that the @code{writecert} command is not listed in the
491 editor's online help):
492
493 @example
494 $ gpg2 --card-edit
495
496 Application ID ...: D27600012301020000005000012340000
497 [...]
498
499 gpg/card> admin
500 Admin commands are allowed
501
502 gpg/card> writecert 3 < floppy-head.crt
503
504 gpg/card> quit
505 @end example
506
507
508 @node Client Authentication
509 @chapter Client Authentication
510
511 @menu
512 * Application Configuration::     Preparing the application for use with Scute.
513 * Authentication With Service::   Using Scute for client authentication.
514 @end menu
515
516 Scute allows you to authenticate yourself to a website securely without
517 entering a username or password by simply using your OpenPGP card.
518 Currently, only Mozilla-based browsers like Firefox are supported,
519 although other applications using Mozilla NSS or supporting PKCS #11
520 modules may work.
521
522
523 @node Application Configuration
524 @section Application Configuration
525
526 To prepare your application for use with Scute, you have to load the
527 Scute module as a PKCS #11 module into the application.  With Firefox,
528 this can be done by choosing @code{Edit->Preferences} in the menu.  In
529 the preferences configuration dialog, you should select the
530 @code{Advanced} configuration section, then the @code{Security} tab, and
531 then select @code{Security Devices} in the category @code{Certificates}.
532
533 @center @image{firefox-pref,13cm}
534
535 In the devices manager dialog, you can select @code{Load} to load a new
536 PKCS #11 device.
537
538 @center @image{firefox-dm-load-before,13cm}
539
540 In the pop-up dialog that follows, you can give a module name
541 (e.g. ``@code{Scute}'') and a module filename.  The latter should
542 correspond to the full file name of the installed Scute module file
543 @file{scute.so}.  The default installation path is
544 @file{/usr/local/lib}, which would mean that you have to provide the
545 file name @file{/usr/local/lib/scute.so}.  If you or your system
546 administrator installed Scute in a different location, you have to
547 adjust the file name correspondingly.
548
549 @center @image{firefox-dm-load,8cm}
550
551 After confirming installation of the security device, a pop-up window
552 should confirm that the module was successfully loaded, and an entry for
553 the security device should appear in the device manager list of
554 @code{Security Modules and Devices}.
555
556 @center @image{firefox-dm-load-after,15cm}
557
558 When you insert the OpenPGP card for which you generated and imported a
559 certificate earlier (see @ref{Certificate Preparation}), the device
560 manager should detect this security token and display some information
561 about it in the @code{Details} list when you select it from the module
562 list.
563
564 @center @image{firefox-dm-token-present,15cm}
565
566 The client certificate will show up in the @code{Certificate Manager}
567 under @code{Your Certificates}:
568
569 @center @image{firefox-cm,13cm}
570
571 @node Authentication With Service
572 @section Authentication With Service
573
574 Before you access a web service which requires client authentication,
575 for instance a fictious web service
576 @ifnottex
577 @indicateurl{https://example.com},
578 @end ifnottex
579 @iftex
580 @code{https://example.com},
581 @end iftex
582 the OpenPGP card should be present.  In this case, a pop-up window will
583 appear that requests you to enter the PIN number protecting the
584 authentication key on the OpenPGP card.  After entering the PIN number,
585 your browser will be authenticated to the server.  If the server accepts
586 your request and certificate, this is all which is required.  You should
587 leave the card in the reader as long as the connection persists.
588 Depending on how aggressively GPG Agent caches your PIN number, you may
589 have to enter the PIN number again later to keep up the connection to
590 the server.
591
592 If the card is not present, or you enter the wrong PIN, or the server
593 does not admit your certificate, you will get an error message.  This
594 error message is generated by the application and Scute can not
595 influence it.  Unfortunately, in Firefox (at least up to version
596 38.5.0), this error message is not very user friendly.  For example,
597 entering a bad PIN results in the following generic error message, and
598 the @code{Try Again} button does not work as expected:
599
600 @center @image{firefox-bad-pin,11cm}
601
602 @comment FIXME: Document possible error codes.
603
604
605 @node Email Signing
606 @chapter Email Signing
607
608 Scute also allows you to use your card-based X.509 certificate to sign
609 your emails with the S/MIME signature format.  This has been tested
610 with Mozilla Thunderbird only, but should work with any mail client
611 with support for PKCS #11 (notably GNOME Evolution).
612
613 You must first load the Scute module into your mail client.  With
614 Mozilla Thunderbird, the procedure is the same as the one described
615 above for Mozilla Firefox.
616
617 Then, open your accent configuration dialog (@code{Edit->Account
618 Settings}), and in the @code{Security} tab, under the section
619 @code{Digital Signing}, use the @code{Select...} button to associate
620 your card-based certificate with your account.
621
622 @center @image{thunderbird-account-settings,13cm}
623
624 When writing a new message, you may then use the @code{S/MIME} button
625 and select @code{Digitally sign this message} in the popup menu.  You
626 will be prompted for your User PIN before the message is sent.
627
628 @center @image{thunderbird-smime-button,13cm}
629
630
631 @node Document Signing
632 @chapter Document Signing
633
634 Scute can also be used with LibreOffice to sign OpenDocument files.
635
636 First, you must load the Scute module into Mozilla Firefox according to
637 the above procedure.  Then, configure LibreOffice to use Firefox's
638 certificate store by defining the @code{MOZILLA_CERTIFICATE_FOLDER}
639 environment variable to your Firefox profile directory.
640
641 Then, to sign the document you are editing, select the
642 @code{File->Digital Signatures...} menu option to open the
643 @code{Digital Signatures} dialog.
644
645 @center @image{libreoffice-digital-signatures,13cm}
646
647 Click the @code{Sign Document} button to open the certificate selection
648 dialog.  Select your card-based certificate, then validate.  Enter your
649 User PIN when prompted by GPG Agent.
650
651 @center @image{libreoffice-certificate-selection,13cm}
652
653 You may also sign a PDF export of your document.  Select the
654 @code{File->Export as PDF...} menu option to open the @code{PDF Options}
655 dialog.  In the @code{Digital Signatures} tab, use the @code{Select}
656 button to open the certificate selection dialog as above.  You will be
657 prompted for your User PIN when you will click the @code{Export} button.
658
659 @center @image{libreoffice-pdf-signature,13cm}
660
661
662 @node Troubleshooting
663 @chapter Troubleshooting
664
665 @strong{Symptom:} Loading the Scute security device in the security
666 device manager of Firefox fails with "Unable to load module".
667
668 @strong{Solution:} Make sure that Scute is correctly installed, and that
669 all libraries and executables are available.  If you are using GnuPG
670 2.0 (instead of 2.1), you may need to make sure that the GPG Agent is
671 running and can be found via the environment variable
672 @code{GPG_AGENT_INFO}.  @xref{Invoking GPG-AGENT, , , gnupg, Using the
673 GNU Privacy Guard}, for details on how to run the GPG Agent.
674
675
676 @strong{Symptom:} Client authentication fails with "<example.com> has
677 received an incorrect or unexpected message.  Error code: -12227".
678
679 @strong{Solution:} Make sure that the correct OpenPGP card is inserted
680 and the certificate available in GPGSM.  Check that the OpenPGP card is
681 detected correctly in the security device manager and the corresponding
682 certificate is displayed in the certificate manager of Firefox.
683 @xref{Authentication With Service}.
684
685
686 @strong{Symptom:} The OpenPGP card is detected and displayed in the
687 security device manager in Firefox, but no corresponding certificate is
688 displayed in the certificate manager of Firefox.
689
690 @strong{Solution:} Make sure that the corresponding certificate is
691 imported in GPGSM.
692
693 @comment FIXME: Can this really happen???
694
695
696 @node Internals
697 @chapter Internals
698
699 The following notes are intended for people interested in more technical
700 details about Scute and its implementation.  They give an overview about
701 its scope and potential compatibility issues with applications.
702
703 @menu
704 * Features and Limitations::      Details about the interfaces implemented.
705 * Developing Scute::              How to understand or improve Scute.
706 * Mozilla Compatibility::         Interoperability notes for Mozilla NSS.
707 @end menu
708
709
710 @node Features and Limitations
711 @section Features and Limitations
712
713 Scute implements version 2.20 of the
714 @uref{https://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-11-cryptographic-token-interface-standard.htm, PKCS #11}
715 specification.
716
717 The @uref{http://www.g10code.com/p-card.html,OpenPGP smart card}
718 application is supported in read-only mode.
719
720 The following functions are not supported:
721
722 @table @code
723 @item C_Initialize
724 No support for native thread package.  Locking callbacks must be
725 provided if multi-threaded operation is desired.
726
727 @item C_WaitForSlotEvent
728 Not implemented.  The interface as specified by PKCS #11 is broken
729 anyway, as the function can not safely be canceled.  Thus, we require
730 polling.
731
732 @item C_GetOperationState
733 @itemx C_SetOperationState
734 Not supported.
735
736 @item C_InitToken
737
738 @itemx C_InitPIN
739 @itemx C_SetPIN
740 Not supported.  No write operations are allowed.  To configure the
741 token, please use the tools accompanying the GnuPG software suite.
742
743 @item C_Login
744 @itemx C_Logout
745 Not supported.  No login into the token by the software is required.
746 Passphrase queries are implemented by the use of GPG Agent and Pinentry.
747
748 @item C_EncryptInit
749 @itemx C_Encrypt
750 @itemx C_EncryptUpdate
751 @itemx C_EncryptFinal
752 @itemx C_DigestInit
753 @itemx C_Digest
754 @itemx C_DigestUpdate
755 @itemx C_DigestKey
756 @itemx C_DigestFinal
757 @itemx C_VerifyInit
758 @itemx C_Verify
759 @itemx C_VerifyUpdate
760 @itemx C_VerifyFinal
761 @itemx C_VerifyRecoverInit
762 @itemx C_VerifyRec
763 Not supported.  Only secret key operations are supported.
764
765 @item C_DecryptInit
766 @itemx C_Decrypt
767 Not yet supported, but will be in the future.
768
769 @item C_SignUpdate
770 @itemx C_SignFinal
771 @itemx C_DecryptUpdate
772 @itemx C_DecryptFinal
773 No progressive crypto-operations are supported.
774
775 @item C_SignRecoverInit
776 @itemx C_SignRecover
777 Not supported.
778
779 @item C_DigestEncryptUpdate
780 @itemx C_DecryptDigestUpdate
781 @itemx C_SignEncryptUpdate
782 @itemx C_DecryptVerifyUpdate
783 Dual-purpose cryptographic functions are not supported.
784
785 @item C_GenerateKey
786 @itemx C_GenerateKeyPair
787 @itemx C_WrapKey
788 @itemx C_UnwrapKey
789 @itemx C_DeriveKey
790 Key management functions are not supported.  Please use the tools
791 accompanying the GnuPG software suite to generate and import keys for
792 use with the token.
793
794 @item C_SeedRandom
795 Not supported.
796
797 @item C_CreateObject
798 @itemx C_CopyObject
799 @itemx C_DestroyObject
800 @itemx C_SetAttributeValue:
801 Only read-only operations are supported on objects.
802
803 @item C_GetObjectSize
804 Not supported.
805
806 @item CKO_CERTIFICATE
807 The label specifies the key on the card used (e.g. @code{OPENPGP.3}).
808 The ID is the fingerprint.
809
810 @item CKO_PRIVATE_KEY:
811 The @code{CKA_LOCAL} attribute can not be supported by the OpenPGP card.
812 It is always set to false (as the key on the card may be copied to the
813 card from an external source).
814 @end table
815
816 @node Developing Scute
817 @section Developing Scute
818
819 Scute is single-threaded.  There is a global lock that is taken in all
820 entry points of Scute, except for @code{C_Initialize},
821 @code{C_Finalize}, @code{C_GetFunctionList}, and stubs.
822
823 Here are a couple of hints on how to develop PKCS #11 modules for
824 Mozilla:
825
826 @code{libopensc2} ships with a @code{pkcs11-spy} library that can be
827 loaded as a wrapper around the PKCS #11 library you want to use to log
828 all functions invoked by Mozilla.  Here is how to use it:
829
830 Set the @code{PKCS11SPY_OUTPUT} environment variable to a filename.
831 @code{pkcs11-spy} appends its log messages at the end of this file.  Set
832 the @code{PKCS11SPY} environment variable to the filename of the PKCS
833 #11 module you actually want to use.  Start Mozilla within this
834 environment.
835
836 There is a different, probably more powerful way to debug Mozilla PKCS
837 #11 libraries.  However, to be able to use it, you need to configure and
838 compile the Mozilla NSS sources with @code{--enable-debug}.
839 Instructions can be found at:
840 @uref{https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/nss_tech_notes}
841
842 Here are a couple of links to more information about implementing a
843 PKCS #11 module for Mozilla:
844
845 @table @uref
846 @item https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/PKCS11_Implement
847 Guidelines for implementors of PKCS #11 modules targeting Mozilla
848
849 @item http://www-archive.mozilla.org/projects/security/pki/pkcs11/
850 PKCS #11 Conformance Testing
851
852 @item https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS
853 The Mozilla NSS web page
854 @end table
855
856
857 @node Mozilla Compatibility
858 @section Mozilla Compatibility
859
860 Mozilla has a bug that causes the wrong security device to be unloaded
861 when unloading a security device.  Also, the displayed list becomes
862 corrupt. When closing and reopening the security device manager, the
863 list displayed is correct, but in anyway the wrong security module is
864 unloaded.
865
866
867 @include gpl.texi
868
869
870 @node Concept Index
871 @unnumbered Concept Index
872
873 @printindex cp
874
875
876 @summarycontents
877 @contents
878 @bye