diff --git a/NEWS b/NEWS index ef5f50d..98f12b8 100644 --- a/NEWS +++ b/NEWS @@ -1,69 +1,78 @@ Noteworthy changes in version 1.6.0 (unreleased) ------------------------------------------------ + * Support for PIV cards. + + * Speedup by letting GPGSM select missing keys. + + * License change to LGPL-2.1-or-later. + (See commit 60a071e3b7b2885ce994667a9186173772f3a647). + + * Requires the current stable version of GnuPG (2.2.0) + Noteworthy changes in version 1.5.0 (2017-07-14) ------------------------------------------------ * Support for TLS 1.2 client authentication and S/MIME signing. * Support for 4096 bit keys. * Support for GnuPG 2.1. * C_GenerateRandom is implemented. Noteworthy changes in version 1.4.0 (2010-04-21) ------------------------------------------------ * Update to libassuan 2.0.0 interface. Noteworthy changes in version 1.3.0 (2009-06-19) ------------------------------------------------ * Scute can read certificates directly from the OpenPGP 2.0 cards. * Support for 2048 bit keys. Noteworthy changes in version 1.2.0 (2008-09-02) ------------------------------------------------ * Ported to Windows 32. * GPG Agent can now be launched on demand. Noteworthy changes in version 1.1.0 (2007-05-03) ------------------------------------------------ * Scute now comes with a manual. * Code licensed from RSA Security Inc. has been removed due to licensing issues ("advertisment clause"). * A memory leak has been fixed. Note that you need libassuan 1.0.1 to fix another memory leak. * Scute now supports certificates larger than the kernel pipe buffer with GPGSM versions later than 2.0.0 (exclusive). * Scute now sets the CKA_TRUSTED attribute to something useful. Noteworthy changes in version 1.0.0 (2006-11-11) ------------------------------------------------ * Initial release. Copyright 2006, 2009, 2010 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. diff --git a/README b/README index 4d93733..13a10cc 100644 --- a/README +++ b/README @@ -1,426 +1,416 @@ Scute ===== -This is a PKCS #11 implementation for the GnuPG Agent using the GnuPG -Smart Card Daemon. Currently, only the OpenPGP card is supported. +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 smart card for client +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.14 * libassuan 2.0.0 At runtime: -* Mozilla (or any other supported application using PKCS #11). -* GnuPG 2.0, in particular: gpg-agent, scdaemon +* Firefix, Thunderbird or any other supported application using PKCS #11. +* GnuPG 2.2 * Pinentry -Note that client authentication with TLS 1.2 and S/MIME signing -require GnuPG 2.1. - 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 Mozilla to use Scute by +After installation, you can configure Firefox or Thunderbord 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: -http://www.gnupg.org/(en)/howtos/card-howto/en/smartcard-howto.html +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 +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 +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 " 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_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: 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: -http://www.mozilla.org/projects/security/pki/nss/tech-notes/tn2.html +https://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 +https://docs.sun.com/source/816-6150-10/index.htm +https://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 +https://www.mozilla.org/projects/security/pki/pkcs11/netscape/problems.html PKCS #11 Conformance Testing -http://www.mozilla.org/projects/security/pki/pkcs11/ +https://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. +https://www.mozilla.org/projects/security/pki/nss/ 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. diff --git a/TODO b/TODO index 6f49130..6639023 100644 --- a/TODO +++ b/TODO @@ -1,79 +1,77 @@ # Emacs, please get me into -*- org -*- mode. +#+STARTUP: showall * Manual: ** Some FIXME's which need attention. ** The pictures in info output do not exist. * Bugs or misfeatures: ** Mozilla presents the other certificates in "Websites". Only the first one is presented in the certicate manager under "Personal". ** Mozilla does not unload the right security token!!! ** Duplicate certificates should be removed from the object list (this can occur when including all certificate chains). ** Windows: Find thread-safe replacement for localtime_r and timegm. * Missing features: ** Add canonical gnupg logging module. + This is meanwhile part of libgpg-error which is already in use. ** Mozilla ignores the CKA_TRUSTED attribute to certificates, so exporting the information from GPGSM (ISTRUSTED) will not be useful. It's unclear if this can be improved in a meaningful way. -* Could be done better: -** Search for grip/fingerprint directly instead iterating over all - keys with GPGSM? - * Standard ambiguities, or non-conformance in the applications: ** If the token is removed, the current sessions are closed. If then a new token is inserted, and the application calls C_OpenSession, a previously used session handle may be reused. It is not clear what behaviour the standard specifies in this case. ** Mozilla NSS has this comment (and relies on the assumption): "check to see if the module has added new slots. PKCS 11 v2.20 allows for modules to add new slots, but never remove them. Slots cannot be added between a call to C_GetSlotLlist(Flag, NULL, &count) and the subsequent C_GetSlotList(flag, &data, &count) so that the array doesn't accidently grow on the caller. It is permissible for the slots to increase between successive calls with NULL to get the size." My reading of the spec is quite different. I do not think it does say that the slot list can not shrink, at least it does not say explicitely. Maybe it is a tacit assumption, because the interface is obviously broken if the list shrinks. However, the spec says: "All slots which C_GetSlotList reports must be able to be queried as valid slots by C_GetSlotInfo. Furthermore, the set of slots accessible through a Cryptoki library is checked at the time that C_GetSlotList, for list length prediction (NULL pSlotList argument) is called. If an application calls C_GetSlotList with a non-NULL pSlotList, and then the user adds or removes a hardware device, the changed slot list will only be visible and effective if C_GetSlotList is called again with NULL. Even if C_GetSlotList is successfully called this way, it may or may not be the case that the changed slot list will be successfully recognized depending on the library implementation. On some platforms, or earlier PKCS11 compliant libraries, it may be necessary to successfully call C_Initialize or to restart the entire system." Note the phrase "user adds or removes a hardware device" and "the changed slot list". This implies that removal of a hardware device could lead to a shrinking slot list. If this is true, then the note in the NSS code is incorrect, and the NSS code will break if a driver shrinks the slot list. However, as long as the assumption is made, we have to comply. * Website: ** Border picture width constant hard-coded in CSS. * Copyright notice Copyright 2006 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.