- Use the Source, Luke
Home | Register | News | Forums | Guide | MyLinks | Bookmark

Sponsored Links

Latest News
  General News
  Press Releases
  Off Topic

Back to files

1. Intro

This is a patch that makes possible using PKCS#11 compliant smart-cards with GNUPG 1.4.x. Due to its design, even read-only tokens with pre-generated keypairs are usable.

2. Installation

  1. You need to have PKCS#11 headers installed in your standard compiler search path. They can be obtained from the RSA's site.
  2. Available PKCS#11 drivers for your smart-card. On Linux, the drivers from the MUSCLE project can be used for some cards (Cryptoflex and Cyberflex with the MUSCLE applet).
  3. Apply the patch to the unpacked GPG distribution: cd gnupg-1.4 (directory name depends on the version you have) patch -p1 < gpg-p11.patch
  4. Execute the configure script as usual.
  5. Edit the generated config.h file and uncomment the line reading /* #define HAVE_PKCS11 */

    to read #define HAVE_PKCS11

  6. Compile and install the source as usual.

NOTE: I don't like autoconf, I think it's braindamaged, I've seen it break on far too many non-linux platforms in several packages and therefore I don't want to learn it or use it as developer. However, to make easier for users to patch their GPG, I'm seeking help to patch the to automatically detect if PKCS#11 headers are available (so that users don't have to perform step 5 manually.)

3. The design philosophy

The PKCS#11 token is used as a secure device for private key operations. The meta-data that OpenPGP card application provides is stored in the PKCS#11 configuration file. The configuration file has a very simple format:


There is exactly one PARAM per line, and it must begin at the beginning of the line (no white space is allowed). Everything after the first '=' is considered as VALUE, except trailing whitespace which is disregarded. No comments or blank lines are allowed.

3.1. OpenPGP configuration options

The OpenPGP card provides for the following attributes that are normally stored on the card:


Of these, you should provide only a selected subset (for correct GPG startup); others can be edited from within GPG itself with the --card-edit command. See example at the end of this section.

3.2. Mandatory options for PKCS#11 operation

For correct PKCS#11 startup you MUST provide values for the following parameters:

This should be a full path to the PKCS#11 library which handles your card.

Some PKCS#11 tokens give an impression of several slots (e.g. if there are multiple PINs, then each PIN is presented as a token in different slot). In most cases, you should be safe if you set this to 0.

Fingerprints of pregenerated key pairs. See the section on key handling.

If you have a writable token, then the OpenPGP meta-data will be stored on the card itself instead of in the configuration file. The program will create a PKCS#11 data object with the specified label on the token and use it to store OpenPGP meta-data.

The object is created as a PUBLIC object, so beware if storing LOGIN data on the token!

If this parameter is specified, then the OpenPGP meta-data from the rest of the configuration file is disregarded. If the object with the given label is not found on the token (or has invalid format), an error will be reported.


3.3. Key handling

GPG is designed in such a way that the only opportunity to get a keypair is generation of the new keypair. However, this may not be possible on writeprotected tokens which users receive with a set of existing keypairs and no new keypairs can be added or generated.

So instead of generating a new key pair on the card, there is a separate utility that will list all RSA public keys on the card (hex value of modulus for each key) with corresponding key fingerprints.

Once there is PKCS11_KEYGENFPR line in the configuration, you can proceed to 'generate' card key from GPG. Instead of new keypair generation, the existing keypairs will be used.

GPG will NEVER genrate keys on the PKCS#11 token by itself. The same utility should be used to generate keypairs on the token! (The keys can also be generated from some other program).

NOTE: According to RFC2440, the key fingerprint is calculated from several values, including the timestamp of creation. Since this can't be known for pre-generated key, it is ALWAYS set to 0! This needs to be done in order to get consistent results: when keys are enumerated on the token, their fingerprint is always recalculated.

3.4. PIN handling

Normally, PKCS#11 token has a single PIN for everything. If there are multiple PINs, they are presented as multiple slots with tokens. It is assumed that PIN verification always verifies CHV1, and after that everything is allowed that is possible.

3.5. An example configuration file

4. TODOs

  • Implement storing meta-data on the card itself as a PKCS#11 object.
  • Initialize PKCS#11 threads

5. Contact

You can reach me at the following email address:

Sponsored Links

Discussion Groups
  Networking / Security

About | FAQ | Privacy | Awards | Contact
Comments to the webmaster are welcome.
Copyright 2006 All rights reserved.