README

Scute
=====

This is a PKCS #11 implementation for the GnuPG Agent using smart
cards managed by GnuPG's scdaemon.  Currently, OpenPGP and PIV cards
are supported.


TOC
===

* Purpose
* Prerequisites
* Installation
* Client Authentication
* Troubleshooting
* Features and Limitations
* Development
* Mozilla Bugs
* Copyright and License


Purpose
=======

Scute enables you to use your OpenPGP or PIV smart card for client
authentication with SSL in Mozilla.  See below for more details on how
to get this working.

Scute also allows you to sign emails with Thunderbird, using the
S/MIME protocol, and to sign OpenDocument and PDF files with
LibreOffice.


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

For the compilation:
* libgpg-error 1.24
* libassuan 2.5.0

Building the documentation also requires:
* yat2m (libgpg-error)

At runtime:
* Firefox, Thunderbird or any other supported application using PKCS #11.
* GnuPG 2.2
* Pinentry

(GnuPG 2.2 is also required at build time if the tests are to be run.)


Installation
============

To install the PKCS #11 Module, follow the generic installation
instructions in the file INSTALL that accompanies this software.

After installation, you can configure Firefox or Thunderbird to use Scute by
visiting the preferences dialog in the "advanced" category, under
"Security Devices".  There you can "load" the module from its
installed path, e.g. "/usr/lib/scute.so".


Client Authentication
=====================

For client authentication to work, several steps need to be completed.
Depending on your situation, some of these steps may be performed by
third parties, like service providers.  However, they can also all be
performed locally, if use of client authentication with a local
service is desired.

For this introduction, we assume an Apache web server with SSL at the
server side, and a connecting client running Firefox.  As a
certification authority (CA) we use OpenSSL.  Scute provides a PKCS #11
compatible security device to Firefox for client authentication.  This
security device gives Firefox access to the client's OpenPGP smart
card.

The Client Perspective
----------------------

To get things started, we have to prepare an initialised OpenPGP smart
card by uploading an off-card key or generating a key on the card.
The card you got may already have been initialised.  Otherwise, you
can find more information on this step in the smartcard HowTo, which
also documents other basic card operations:
https://gnupg.org/howtos/card-howto/en/smartcard-howto.html

Once the card is initialised, we have to generate a certificate
signing request (CSR) to get the authentication key of the card
(OPENPGP.3, the third key on the card) certified by the CA.  This can
be done using "gpgsm --gen-key".  For the CSR, a distinguished name
(DN) is required.  Your CA will have more information about what this
DN should contain.  Below we use an example for a test-employee
"Floppy Head" of the test-CA that ships with OpenSSL ("Snake Oil,
Ltd.").

Generating the CSR is then just a matter of answering a few questions:

$ gpgsm --gen-key > client.csr
Please select what kind of key you want:
   (1) RSA
   (2) Existing key
   (3) Existing key from card
Your selection? 3
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
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
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: certificate request created
Ready.  You should now send this request to your CA.

It is required to enter the signing PIN of the card to complete this
step.  The certificate can then be found in the file "/tmp/floppy.csr".
This file should then be sent to the CA for certification (see below).

The CA will return to the client a certificate "/tmp/floppy.crt", who
can then import the issuer certificate of the CA (in this example, we
access directly the local server certificate) and its own certificate
with gpgsm:

$ gpgsm --import /etc/apache/ssl.crt/snakeoil-ca-rsa.crt
gpgsm: total number processed: 1
gpgsm:               imported: 1
marcus@ulysses:~/g10/projects/pkcs11-for-scdaemon/ca/usercert/card3$ gpgsm --import /tmp/floppy.crt
gpgsm: total number processed: 1
gpgsm:              unchanged: 1

$ gpgsm --list-keys Floppy
Serial number: 08
       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-10-11 13:17:08 through 2007-10-11 13:17:08
     key type: 1024 bit RSA
  fingerprint: C9:08:0E:86:92:6C:7B:4B:8C:23:1C:9D:D7:15:BF:D4:A4:00:54:11

Now the client can configure his web browser.  If desired, the client
can install the web servers certificate (alternatively, Firefox will
ask when establishing the initial connection).

To actually perform the client authentication, the client needs to set
up the web browser for use with Scute.  The Scute PKCS #11 module,
installed under /usr/lib/scute.so by default, needs to be loaded as
a security device in Firefox under
Preferences->Advanced->Security->Certificates->Security Devices->Load
When the security device is loaded, card insertion should cause the
security device list be updated with the inserted token (the card), and the certificate that has been imported into gpgsm should be visible under
Preferences->Advanced->Security->Certificates->View Certificates
automatically.

Firefox will by default select the certificate to be used for client
authentication automatically from the list of available certificates.
This setting can be changed if desired in
Preferences->Advanced->Security->Certificates ("Select one
automatically" vs. "Ask me every time")

When the client then attempts to open the URL "https://localhost/" in
this example, the web server will require SSL authentication, which
causes Firefox to look (or ask) for a client certificate.  If the
certificate on the card is suitable (or selected), the user will have
to enter the PIN number on the card to #to the web site.


The CA Perspective
------------------

The CA will have to process the CSR submitted by the client.  After
verifying the identity of the submitter by some external means, the CA
may use for example this OpenSSL command to create a certificate (we
use the example CA shipping with the Apache SSL module on Ubuntu):

# cd /etc/apache/ssl.crt/
# 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
Using configuration from /usr/lib/ssl/openssl.cnf
Check that the request matches the signature
Signature ok
Certificate Details:
        Serial Number: 8 (0x8)
        Validity
            Not Before: Oct 11 13:17:08 2006 GMT
            Not After : Oct 11 13:17:08 2007 GMT
        Subject:
            countryName               = XY
            stateOrProvinceName       = Snake Desert
            organizationName          = Snake Oil, Ltd
            organizationalUnitName    = Webserver Team
            commonName                = Floppy Head
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            Netscape Comment:
                OpenSSL Generated Certificate
            X509v3 Subject Key Identifier:
                72:AF:B8:13:3D:3D:9D:02:93:E4:D4:56:0C:06:90:4C:26:85:85:5D
            X509v3 Authority Key Identifier:
                DirName:/C=XY/ST=Snake Desert/L=Snake Town/O=Snake Oil, Ltd/OU=Certificate Authority/CN=Snake Oil CA/emailAddress=ca@snakeoil.dom
                serial:00

Certificate is to be certified until Oct 11 13:17:08 2007 GMT (365 days)
Sign the certificate? [y/n]:y


1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

The resulting file, "/tmp/floppy.crt" is sent back from the CA to the
client along with the issuer certificate.

For more information how to set up and work with a CA using OpenSSL,
please see the OpenSSL documentation.

The Server Perspective
----------------------

The service provider will set up an Apache web server with SSL
support, and configure it to accept certificates from the CA.  This
step is quite involved.  Garex has a concise HowTo online at
https://www.garex.net/apache/ about how to do this.  Beside the
creation of a certificate that has its own fully qualified domain name
(FQDN) as common name (CN part of the DN), this involves installing
the Apache SSL module and configuration for it, for example in
httpd.conf:

SSLEngine on
SSLCertificateFile /etc/apache/ssl.crt/server.crt
SSLCertificateKeyFile /etc/apache/ssl.key/server.key

SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile /etc/apache/ssl.crt/snakeoil-ca-rsa.crt

The file server.key is not protected by a passphrase (if it is, this
passphrase needs to be provided when starting up Apache), and
server.crt has "CN=localhost" as part of its DN for this example.


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 gpg-agent is
running and can be found via the environment variable GPG_AGENT_INFO.


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.


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.


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

Scute implements version 2.20 of the PKCS #11 specification.

The OpenPGP smart card 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_DecryptInit, C_Decrypt: Not yet supported, but will be in the
  future.

* C_#date, 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: Not supported.

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


Development
===========

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:
https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/nss_tech_notes/nss_tech_note2

More informations about implementing a PKCS #11 module for Mozilla can
be found on the Mozilla NSS web page:
https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS#PKCS_11_information

The following links point to archived pages from the Mozilla
documentation on that topic (the content may be outdated):

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

PKCS #11 Conformance Testing
https://www-archive.mozilla.org/projects/security/pki/pkcs11/


Copyright and License
=====================

Scute is copyrighted by g10 Code GmbH and licensed under the GNU
Lesser General Public License version 2.1 or later.  See the file
COPYING.LESSER for details.


 Copyright 2006, 2009 g10 Code GmbH

 This file is free software; as a special exception the author gives
 unlimited permission to copy and/or distribute it, with or without
 modifications, as long as this notice is preserved.

 This file is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.