     [file version.texi not included]

This file documents the Scute module.

This is Edition EDITION, last updated UPDATED, of The Scute Manual, for Version VERSION.

Copyright © 2002, 2003, 2004, 2005, 2006, 2007 g10 Code GmbH.

The Scute Manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The Scute Manual is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Main Menu
*********

This is Edition EDITION, last updated UPDATED, of The Scute Manual, for Version VERSION of the Scute module.

Introduction
************

This is a PKCS #11 implementation for the GnuPG Agent using the GnuPG Smart Card Daemon.  Currently, only the OpenPGP card is supported.

Scute enables use of the OpenPGP smart card in applications supporting PKCS #11 compliant security tokens.  The main application at this time is client authentication in Mozilla-based web browsers.  In the future, other applications will be supported.

Getting Started
===============

This manual documents the Scute module, how it can be used for common applications supported by it, and how it can be extended and improved by programmers.  It is thus a user manual as well as a developer manual.

The reader is assumed to possess basic knowledge about cryptography in general, and public key cryptography in particular.  The underlying cryptographic engines that are used by the library are not explained, but where necessary, special features or requirements are provided.

This manual can be used in several ways.  If read from the beginning to the end, it gives a good introduction into the module and how it can be used in an application.  Forward references are included where necessary.  Later on, the manual can be used as a reference manual to get just the information needed about any particular application of the module.

Features
========

Scute is currently the only implementation of PKCS #11 for the OpenPGP smart card.  Apart from that, it offers a couple of other benefits:

it's free software
     Anybody can use, modify, and redistribute it under the terms of the GNU General Public License (see Copying).

it's built to grow
     Although Scute currently only provides a single function, client authentication using OpenPGP smart cards in Mozilla-based web browsers, it was built with the intention of supporting other applications as well in the future.

it's easy
     Building and installing Scute is easy, and preparing smart cards for use with Scute is a snatch using the GnuPG 2.0 framework.  The integration of Scute into the application is seamless.

Overview
========

Scute is a security device that implements the PKCS #11 interface for security tokens.  Applications which know how to use the PKCS #11 interface to access security tokens for crytpographic operations can use Scute to access the OpenPGP smart card.  An important example of such an application is the Firefox web browser by the Mozilla project, which uses the Mozilla Network Security Services library (NSS).

Scute itself does not include a driver for the smart card itself. Instead, it uses the GnuPG 2.0 framework to access the smart cards and associated data like certificates.  Scute acts as the glue between the application and GnuPG 2.0.

Currently, only client authentication over HTTPS with Firefox using the OpenPGP card is supported.  In this configuration, Scute allows users to authenticate themselves to a remote web service without entering their log-in information.

Preparation
***********

To use Scute, you first have to install the software.  You also have to prepare each card you want to use with Scute before it can be used. Furthermore, you need to configure the application to make use of Scute for cryptographic operations.  This chapter explains each of these steps in detail.

Prerequisites
=============

There are two types of dependencies for Scute: compile-time dependencies and run-time dependencies.  The compile-time dependencies only need to be fulfilled when Scute is compiled and installed.  The run-time dependencies need to be fulfilled when Scute is used in an application.

Scute depends, in addition to the essential build utilities, on the following packages at build time:

libgpg-error
     Scute uses the GnuPG 2.0 framework for error handling, so it depends on the GPG error library.  The minimum version required is 1.14.

libassuan
     Scute uses the GnuPG 2.0 framework for communication with the GPG Agent, so it depends on the Assuan library.  The minimum version required is 2.0.0.

At run-time, in addition to the run-time versions of the above libraries, you also need the following packages installed and configured:

GnuPG
     Scute uses the GnuPG 2.0 framework to access the OpenPGP card and for certificate management.  The minimum version required is 2.0.0.

     Caution: A functional installation of GnuPG 2.0 requires a running GPG Agent process, which must be advertised to the applications via the GPG_AGENT_INFO environment variable.  Please make sure that you fulfill this requirement before using Scute in an application, running the Scute test suite, or preparing certificates as described in Certificate Preparation.  See Invoking GPG-AGENT (Using the GNU Privacy Guard), for details on how to run the GPG Agent.

Pinentry
     Pinentry is a dependency of GnuPG 2.0, so it also needs to be installed with it.

Firefox et al.
     Firefox is the first application supported by Scute.  In the future, other applications may be supported.  The applications are not dependencies of Scute, but Scute can not be used stand-alone, so you can not experience it without an application.

Building the Source
===================

Scute does comply to the GNU coding standards and thus can be compiled and installed according to the generic installation instructions found in the source package in the file INSTALL.  There are no Scute specific options to the configure script.

After installation, the scute.so module file can be found in the library directory of the installation path.

Certificate Preparation
=======================

To use an OpenPGP card with Scute, it first has to be initialized by generating or loading a key on the card, see the OpenPGP Card How-To (http://www.gnupg.org/(en)/howtos/card-howto/en/smartcard-howto.html).  Then a certificate has to be created and imported into GPGSM.  This task involves three steps: First, a certificate signing request (CSR) has to be created that matches the key on the card.  This certificate signing request then has to be submitted to a certificate authority (CA), which will create the certificate and send it back to you.  At last, the certificate has to be imported into GPGSM.  This section will explain all of these steps in detail.

Before you start, make sure that the GPG Agent is running, see Prerequisites.  There is no need to configure GPGSM, so you can create a CSR with the command:

     $ gpgsm --gen-key > floppy-head.csr
     Please select what kind of key you want:
        (1) RSA
        (2) Existing key
        (3) Existing key from card
     Your selection? 3

As we create a certificate for the OpenPGP Card, the option ``[3] Direct from card'' should be selected.

     Serial number of the card: 355F9746499F0D4B4ECEE4928B007D16
     Available keys:
        (1) D53137B94C38D9BF6A199706EA6D5253 OPENPGP.1
        (2) B0CD1A9DFC3539A1D6A8B851A11C8665 OPENPGP.2
        (3) 53DB41052CC590A40B403F3E6350E5DC OPENPGP.3
     Your selection? 3
     Possible actions for a RSA key:
        (1) sign, encrypt
        (2) sign
        (3) encrypt
     Your selection? 2

The only operation currently supported is client authentication.  For this, the authentication key has to be selected.  This is the third key on the card, so the options ``[3] OPENPGP.3'' and ``[2] sign'' should be chosen.  Note that the key usage is only advisory, and the CA may assign different capabilities.

     Enter the X.509 subject name: CN=Floppy Head,OU="Webserver Team",O="Snake Oil, Ltd",L="Snake Town",ST="Snake Desert",C=XY
     Enter email addresses (end with an empty line):
     > floppy.head@example.org
     >
     Enter DNS names (optional; end with an empty line):
     >
     Enter URIs (optional; end with an empty line):
     >
     Create self-signed certificate? (y/N) n

As a last step, the common name and e-mail address of the key owner need to be specified by you.  The above are only an example for a fictious person working at a fictious company.  DNS names are only meaningful for server certificates and thus should be left empty.

We have now entered all required information and gpgsm will display what it has gathered and ask whether to create the certificate request:

     These parameters are used:
         Key-Type: card:OPENPGP.3
         Key-Length: 1024
         Key-Usage: sign
         Name-DN: CN=Floppy Head,OU="Webserver Team",O="Snake Oil, Ltd",L="Snake Town",ST="Snake Desert",C=XY
         Name-Email: floppy.head@example.org

     Proceed with creation? (y/N) y
     Now creating certificate request.  This may take a while ...
     gpgsm: about to sign the CSR for key: &53DB41052CC590A40B403F3E6350E5DC

GPGSM will now start working on creating the request.  During this time you will be asked once for a passphrase to unprotect the authentication key on the card.  A pop up window will appear to ask for it.

When it is ready, you should see the final notice:

     gpgsm: certificate request created
     Ready.  You should now send this request to your CA.

Now, you may look at the created request:

     $ cat floppy-head.csr
     -----BEGIN CERTIFICATE REQUEST-----
     MIICCDCCAXECAQAwgYExCzAJBgNVBAYTAlhZMRUwEwYDVQQIEwxTbmFrZSBEZXNl
     cnQxEzARBgNVBAcTClNuYWtlIFRvd24xFzAVBgNVBAoTDlNuYWtlIE9pbCwgTHRk
     MRcwFQYDVQQLEw5XZWJzZXJ2ZXIgVGVhbTEUMBIGA1UEAxMLRmxvcHB5IEhlYWQw
     gaAwDQYJKoZIhvcNAQEBBQADgY4AMIGKAoGBANWaM9YS89AOx3GX1Rua+4DUHwbL
     wt0rBYdBddlabMMteVjUcOOhbFMirLpLAi1S8fUXNiy84ysOmFStmvSIXDsAgXq5
     1ESOU4SNg2zEkPDF1WYJ5BFIXdYq9i2k5W7+ctV8PkKv3e5IeYXTa5qppIPD31de
     gM8Qj7tK0hL/eNCfAgQAAQABoEUwQwYJKoZIhvcNAQkOMTYwNDAiBgNVHREEGzAZ
     gRdmbG9wcHkuaGVhZEBleGFtcGxlLmNvbTAOBgNVHQ8BAf8EBAMCBsAwDQYJKoZI
     hvcNAQEFBQADgYEAFC9q6+ib9YGCLB/2AlZR+/dvb+pEeXR1EbpV/dw/gjP1yPY6
     29n8ZIDLUvQvNCtfCcXFxFimVSSB/KmFXXsJbM+NXQyT6Ocn34iHmkf9IVRMWQWg
     ZBYfQVeXAd7XlxI6d1wXDLwD/26lTU/rH2JU6H1+zSfZxqwVC4Iu+kiN4Y8=
     -----END CERTIFICATE REQUEST-----
     $

The next step is to submit this certificate request to the CA, which can then create a certificate and send it back to you.

If, for example, you use the CA CAcert (http://www.cacert.org), then you can log into your account at the CAcert website, choose ``Client Certificates -> New'', check ``Show advanced options'', paste the above request block into the text field and click on ``Submit''. If everything works correctly, a certificate will be shown, which you can cut and paste into a new file floppy-head.crt.

Alternatively if, for example, you set up your own CA with OpenSSL, then you can create your own certificate by issueing a command similar openssl ca -in floppy-head.csr -cert snakeoil-ca-rsa.crt -keyfile snakeoil-ca-rsa.key -out floppy-head.crt.  Please see the OpenSSL documentation for more details on how to set up and administrate a certificate authority infrastructure.

In any way you should end up with a certificate file floppy-head.crt, which you then have to import into GPGSM.  It is also recommended that you import the root certificate of the CA first in the same fashion.

     $ gpgsm --import floppy-head.crt
     gpgsm: certificate imported

     gpgsm: total number processed: 1
     gpgsm:               imported: 1

gpgsm tells you that it has imported the certificate.  It is now associated with the key you used when creating the request.  To see the content of your certificate, you may now enter:

     $ gpgsm -K Floppy
     /home/foo/.gnupg/pubring.kbx
     ---------------------------
     Serial number: 10
            Issuer: /CN=Snake Oil CA/OU=Certificate Authority/O=Snake Oil, Ltd/L=Snake Town/ST=Snake Desert/C=XY/EMail=ca@snakeoil.dom
           Subject: /CN=Floppy Head/OU=Webserver Team/O=Snake Oil, Ltd/ST=Snake Desert/C=XY
          validity: 2006-11-11 14:09:12 through 2007-11-11 14:09:12
          key type: 1024 bit RSA
       fingerprint: EC:93:A2:55:C6:58:7F:C9:9E:96:DB:12:6E:64:99:54:BB:E1:94:68

The option ``-K'' is used above because this will only list certificates for which a private key is available.  To see more details, you may use ``--dump-secret-keys'' instead of ``-K''.

Client Authentication
*********************

Scute allows you to authenticate yourself to a website securely without entering a username or password by simply using your OpenPGP card. Currently, only Mozilla-based browsers like Firefox are supported, although other applications using Mozilla NSS or supporting PKCS #11 modules may work.

Application Configuration
=========================

To prepare your application for use with Scute, you have to load the Scute module as a PKCS #11 module into the application.  With Firefox, this can be done by choosing Edit->Preferences in the menu.  In the preferences configuration dialog, you should select the Advanced configuration section, then the Security tab, and then select Security Devices in the category Certificates.

In the devices manager dialog, you can select Load to load a new PKCS #11 device.

In the pop-up dialog that follows, you can give a module name (e.g. ``Scute'') and a module filename.  The latter should correspond to the full file name of the installed Scute module file scute.so.  The default installation path is /usr/local/lib, which would mean that you have to provide the file name /usr/local/lib/scute.so.  If you or your system administrator installed Scute in a different location, you have to adjust the file name correspondingly.

After confirming installation of the security device, a pop-up window should confirm that the module was successfully loaded, and an entry for the security device should appear in the device manager list of Security Modules and Devices.

When you insert the OpenPGP card for which you generated and imported a certificate earlier (see Certificate Preparation), the device manager should detect this security token and display some information about it in the Details list when you select it from the module list.

The client certificate will show up in the Certificate Manager under Your Certificates:

Authentication With Service
===========================

Before you access a web service which requires client authentication, for instance a fictious web service https://example.com, the OpenPGP card should be present.  In this case, a pop-up window will appear that requests you to enter the PIN number protecting the authentication key on the OpenPGP card.  After entering the PIN number, your browser will be authenticated to the server.  If the server accepts your request and certificate, this is all which is required.  You should leave the card in the reader as long as the connection persists. Depending on how aggressively GPG Agent caches your PIN number, you may have to enter the PIN number again later to keep up the connection to the server.

If the card is not present, or you enter the wrong PIN, or the server does not admit your certificate, you will get an error message.  This error message is generated by the application and Scute can not influence it.  Unfortunately, in Firefox (at least up to version 38.5.0), this error message is not very user friendly.  For example, entering a bad PIN results in the following generic error message, and the Try Again button does not work as expected:

Troubleshooting
***************

Symptom: Loading the Scute security device in the security device manager of Firefox fails with "Unable to load module".

Solution: Make sure that Scute is correctly installed, and that all libraries and executables are available.  Make sure that the GPG Agent is running and can be found via the environment variable GPG_AGENT_INFO.  See Invoking GPG-AGENT (Using the GNU Privacy Guard), for details on how to run the GPG Agent.

Symptom: Client authentication fails with "<example.com> has received an incorrect or unexpected message.  Error code: -12227".

Solution: Make sure that the correct OpenPGP card is inserted and the certificate available in GPGSM.  Check that the OpenPGP card is detected correctly in the security device manager and the corresponding certificate is displayed in the certificate manager of Firefox. See Authentication With Service.

Symptom: The OpenPGP card is detected and displayed in the security device manager in Firefox, but no corresponding certificate is displayed in the certificate manager of Firefox.

Solution: Make sure that the corresponding certificate is imported in GPGSM.

Internals
*********

The following notes are intended for people interested in more technical details about Scute and its implementation.  They give an overview about its scope and potential compatibility issues with applications.

Features and Limitations
========================

Scute implements version 2.20 of the PKCS #11 (http://www.rsasecurity.com/rsalabs/node.asp?id=2133) specification.

The OpenPGP smart card (http://www.g10code.com/p-card.html) application is supported in read-only mode.

The following functions are not supported:

C_Initialize
     No support for native thread package.  Locking callbacks must be provided if multi-threaded operation is desired.

C_WaitForSlotEvent
     Not implemented.  The interface as specified by PKCS #11 is broken anyway, as the function can not safely be canceled.  Thus, we require polling.

C_GetOperationState
C_SetOperationState
     Not supported.

C_InitToken

C_InitPIN
C_SetPIN
     Not supported.  No write operations are allowed.  To configure the token, please use the tools accompanying the GnuPG software suite.

C_Login
C_Logout
     Not supported.  No login into the token by the software is required. Passphrase queries are implemented by the use of GPG Agent and Pinentry.

C_EncryptInit
C_Encrypt
C_EncryptUpdate
C_EncryptFinal
C_DigestInit
C_Digest
C_DigestUpdate
C_DigestKey
C_DigestFinal
C_VerifyInit
C_Verify
C_VerifyUpdate
C_VerifyFinal
C_VerifyRecoverInit
C_VerifyRec
     Not supported.  Only secret key operations are supported.

C_SignInit
C_Sign
     Currently, only signing 36 bytes (MD5+SHA1) hashes is supported (used for client authentication).

C_DecryptInit
C_Decrypt
     Not yet supported, but will be in the future.

C_SignUpdate
C_SignFinal
C_DecryptUpdate
C_DecryptFinal
     No progressive crypto-operations are supported.

C_SignRecoverInit
C_SignRecover
     Not supported.

C_DigestEncryptUpdate
C_DecryptDigestUpdate
C_SignEncryptUpdate
C_DecryptVerifyUpdate
     Dual-purpose cryptographic functions are not supported.

C_GenerateKey
C_GenerateKeyPair
C_WrapKey
C_UnwrapKey
C_DeriveKey
     Key management functions are not supported.  Please use the tools accompanying the GnuPG software suite to generate and import keys for use with the token.

C_SeedRandom
C_GenerateRandom
     Not supported at this point.  C_GenerateRandom may be supported in the future, though.

C_CreateObject
C_CopyObject
C_DestroyObject
C_SetAttributeValue:
     Only read-only operations are supported on objects.

C_GetObjectSize
     Not supported.

CKO_CERTIFICATE
     The label specifies the key on the card used (e.g. OPENPGP.3). The ID is the fingerprint.

CKO_PRIVATE_KEY:
     The CKA_LOCAL attribute can not be supported by the OpenPGP card. It is always set to false (as the key on the card may be copied to the card from an external source).

Developing Scute
================

Scute is single-threaded.  There is a global lock that is taken in all entry points of Scute, except for C_Initialize, C_Finalize, C_GetFunctionList, and stubs.

Here are a couple of hints on how to develop PKCS #11 modules for Mozilla:

libopensc2 ships with a pkcs11-spy library that can be loaded as a wrapper around the PKCS #11 library you want to use to log all functions invoked by Mozilla.  Here is how to use it:

Set the PKCS11SPY_OUTPUT environment variable to a filename. pkcs11-spy appends its log messages at the end of this file.  Set the PKCS11SPY environment variable to the filename of the PKCS #11 module you actually want to use.  Start Mozilla within this environment.

There is a different, probably more powerful way to debug Mozilla PKCS #11 libraries.  However, to be able to use it, you need to configure and compile the Mozilla NSS sources with --enable-debug. Instructions can be found at: http://www.mozilla.org/projects/security/pki/nss/tech-notes/tn2.html

Here are a couple of links to more information about implementing a PKCS #11 module for Mozilla:

http://docs.sun.com/source/816-6150-10/index.htm
http://docs.sun.com/source/816-6150-10/pkcs.htm
     Implementing PKCS #11 for the Netscape Security Library (Caution: The content may be out of date)

http://www.mozilla.org/projects/security/pki/pkcs11/netscape/problems.html
     Common PKCS #11 Implementation Problems

http://www.mozilla.org/projects/security/pki/pkcs11/
     PKCS #11 Conformance Testing

http://www.mozilla.org/projects/security/pki/nss/
     The Mozilla NSS web page

Mozilla Compatibility
=====================

Mozilla has a bug that causes the wrong security device to be unloaded when unloading a security device.  Also, the displayed list becomes corrupt. When closing and reopening the security device manager, the list displayed is correct, but in anyway the wrong security module is unloaded.

     [file gpl.texi not included]