Scute ===== This is a PKCS #11 implementation for the GnuPG Agent using the GnuPG Smart Card Daemon. Currently, only the OpenPGP card is 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 smart card for client authentication with SSL in Mozilla. See below for more details on how to get this working. In the future, Scute will enable you to use your OpenPGP smart card for email decryption and signing with Thunderbird, using the X.509 protocol. Prerequisites ============= For the compilation: * libgpg-error 1.4 * libassuan 2.0.0 At runtime: * Mozilla (or any other supported application using PKCS #11). * GnuPG 2.0, in particular: gpg-agent, scdaemon * Pinentry Installation ============ To install the PKCS #11 Module, follow the generic installation instructions in the file INSTALL that accompanies this software. You also need to install the Mozilla Personal Security Manager (PSM), which may come with your GNU/Linux distribution in a package named mozilla-psm or similar. After installation, you can configure Mozilla 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/libscute.so". Note that for the module load to complete successfully, the GPG Agent must be running and available. On Unix systems this means that Mozilla needs to have the GPG_AGENT_INFO variable set correctly in its environment. 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: http://www.gnupg.org/(en)/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/libscute.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 sign into 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 http://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 " 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_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). 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: 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: Implementing PKCS #11 for the Netscape Security Library (Caution: The content may be out of date) http://docs.sun.com/source/816-6150-10/index.htm http://docs.sun.com/source/816-6150-10/pkcs.htm Common PKCS #11 Implementation Problems http://www.mozilla.org/projects/security/pki/pkcs11/netscape/problems.html PKCS #11 Conformance Testing http://www.mozilla.org/projects/security/pki/pkcs11/ And of course the Mozilla NSS web page: http://www.mozilla.org/projects/security/pki/nss/ Mozilla Bugs ============ Mozilla has a bug that causes the security devices list to become corrupt when a security device is unloaded: The wrong entry is removed from the list. This is corrected by waiting for a refresh or closing and reopening the security device manager. Copyright and License ===================== Scute is copyrighted by g10 Code GmbH and licensed under the GNU General Pubic License version 2 or later with this exception: In addition, as a special exception, g10 Code GmbH gives permission to link this library: with the Mozilla Foundation's code for Mozilla (or with modified versions of it that use the same license as the "Mozilla" code), and distribute the linked executables. You must obey the GNU General Public License in all respects for all of the code used other than "Mozilla". If you modify the software, you may extend this exception to your version of the software, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version and from all source files. g10 Code GmbH marcus@g10code.com 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.