gnupg-pkcs11-scd - GnuPG-compatible smart-card daemon with PKCS#11
gnupg-pkcs11-scd [--server] [--multi-server] [--daemon] [--verbose]
[--quiet] [--sh] [--csh] [--options file] [--no-detach]
[--log-file file] [--help]
gnupg-pkcs11-scd is a drop-in replacement for the smart-card daemon (scd)
shipped with the next-generation GnuPG (gnupg-2). The daemon interfaces
to smart-cards by using RSA Security Inc. PKCS#11 Cryptographic Token
Interface (Cryptoki). The following options are available:
Run in server mode (foreground). If not redirected, input and output
are over stdin/stdout.
Run in multi-server mode (foreground). In addition to communicating
over stdin/stdout, the server also opens an additional listening UNIX
Detach and run in background.
Be verbose while running.
Be as quiet as possible.
Output sh-style environment variable definition.
Output csh-style environment variable definition.
Read options from file. Some of the configuration options can only
be set in the configuration file (see the CONFIGURATION section).
Do not detach from console (useful for debugging purposes).
Output log to file.
Print help information.
When the daemon receives any of the SIGHUP, SIGTERM and SIGINT signals,
it cleans up and exits.
gnupg-pkcs11-scd works only with already personalized cards, and supports
(for the time being) only RSA keypairs. The following constraints must
1. For each private key object, a certificate object must exist on the
card. The existence of the corresponding public key object is not
important (since the certificate includes public key).
2. The certificate and the corresponding private key must have
identical CKA_ID attribute.
The PKCS#11 implementation is not obliged to enforce any of the above
rules. However, practice has shown that popular PKCS#11 implementations
found "in the wild" seem to respect them.
Unlike gpg-agent, gnupg-pkcs11-scd supports more than one token available
at the same time. In order to make gpg-agent happy, gnupg-pkcs11-scd
always returns the same card serial number to gpg-agent. When
unavailable token is requested, gnupg-pkcs11-scd will use NEEDPIN
callback in order to ask for the requested token. When and if gpg-agent
will support more than one serial number or NEEDTOKEN callback, this
behavior will be modified.
HOME Used to locate the home directory.
GNUPGHOME Used instead of ~/.gnupg.
USERPROFILE Used only on Win32 to locate the home directory.
Additionally, the \\Software\\GNU\\GnuPG\\HomeDir registry key is used on
Win32 to locate the default GNUPGHOME.
Files affecting the operation of gnupg-pkcs11-scd:
~/.gnupg/gnupg-pkcs11-scd.conf gnupg-pkcs11-scd uses this as a default
/etc/gnupg-pkcs11-scd.conf gnupg-pkcs11-scd uses this as a default
system wide configuration file.
~/.gnupg/gpg-agent.conf Default configuration file for gpg-
To tell gpg-agent to use another smart-card daemon, the following needs
to be put in ~/.gnupg/gpg-agent.conf:
The first line is mandatory in order to use gnupg-pkcs11-scd. With the
second line you can set your preferred pinentry program (it has to be one
compatible with GnuPG). Of course, you need to adjust the paths according
to your system setup.
An example ~/.gnupg/gnupg-pkcs11-scd.conf file (lines beginning with #
# Log file.
# Default is not verbose.
# Default is no debugging.
# Pin cache period in seconds; default is infinite.
# Comma-separated list of available provider names. Then set
# attributes for each provider using the provider-[name]-attribute
# Provider attributes (see below for detailed description)
The following attributes can be set for each provider:
Full path to the PKCS#11 shared library (= provider).
Allow protected authentication for provider. This needs to be
supported by the provider and you should have appropriate reader
Authentication is required before certificates can be accessed. Most
configurations store certificates as public, so there is no need to
use this option.
Private key mask mode. Use this only when you have problem using
private key operations. The value is hex encoded mask number.
0 Determine automatically.
1 Force sign.
2 Force sign with recovery.
4 Force decrypt.
8 Force decrypt with unwrap.
Emulate OpenPGP card. Unfortunately, gnupg cannot handle the OpenPGP
card with certificates. So you need to turn this on in order to
learn card keys.
In OpenPGP card emulation we cannot guess which key should match a
type, so you have to specify the SHA1 of the key explicitly.
In order to determine which key is which, use the following command:
gpg-agent --server gpg-connect-agent
Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first
field is the hash, the second is the subject name.
You still have to store a certificate (may be self-signed) that
corresponds to the keypair.
Hex string (Upper letter, no space) SHA1 of signing public key.
Hex string (Upper letter, no space) SHA1 of encryption public key.
Hex string (Upper letter, no space) SHA1 of authentication public
Typical steps to set up a card for gpgsm usage:
1. Import the CA certificate of your issuer:
gpgsm --import < ca-certificate
You should also manually import all self-signed certificates.
2. Instruct GnuPG to discover all useful certificates on the card:
Signing, verification, etc. work as usual with gpgsm.
Typical steps to set up a card for gpg usage:
1. Configure gnupg-pkcs11-scd for opengpg emulation, specify the public
key hashes to be used for signature, encryption and authentication.
2. Instruct GnuPG to discover all useful information of card:
You should see valid card status.
3. Now, you should virtual generate keys, the keys are not actually
generated, but returned to gpg to be registered.
generate (DO NOT BACKUP KEYS)
4. Disable the opengpg emulation.
Now you can use the same card with your gpg and gpgsm keys. We don’t know
if this is a bug or feature in gnupg, but we glad that it works.
Signing, verification, etc. work as usual with gpg.
All communication between components is currently unprotected and in
plain text (that’s how the Assuan protocol operates). It is trivial to
trace (using e.g. the strace(1) program) individual components (e.g.
pinentry) and steal sensitive data (such as the smart-card PIN) or even
change it (e.g. the hash to be signed).
When using the software in production scenario, be sure to turn off
debugging/verbose options in configuration of all components. Otherwise,
some sensitive data might be displayed on the screen (most notably, the
strace(1) truss(1) gnupg(7)
GnuPG Home Page, http://www.gnupg.org.
gnupg-pkcs11 Home Page, http://gnupg-pkcs11.sourceforge.net.
AUTHORS AND COPYRIGHT
Copyright (c) 2006-2007 Zeljko Vrba <firstname.lastname@example.org>
Copyright (c) 2006-2007 Alon Bar-Lev <email@example.com>
All rights reserved.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
THE USE OR OTHER DEALINGS IN THE SOFTWARE.