gnupg-pkcs11-scd(1) | General Commands Manual | gnupg-pkcs11-scd(1) |
NAME¶
gnupg-pkcs11-scd
—
GnuPG-compatible smart-card daemon with PKCS#11
support
SYNOPSIS¶
gnupg-pkcs11-scd |
[ --server ] [--multi-server ]
[--daemon ] [--verbose ]
[--quiet ] [--sh ]
[--csh ] [--options
file ]
[--no-detach ] [--log-file
file ]
[--help ] |
DESCRIPTION¶
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:
- --server
- Run in server mode (foreground). If not redirected, input and output are over stdin/stdout.
- --multi-server
- Run in multi-server mode (foreground). In addition to communicating over stdin/stdout, the server also opens an additional listening UNIX socket.
- --daemon
- Detach and run in background.
- --verbose
- Be verbose while running.
- --quiet
- Be as quiet as possible.
- --sh
- Output sh-style environment variable definition.
- --csh
- Output csh-style environment variable definition.
- --options file
- Read options from file. Some of the configuration options can only be set in the configuration file (see the CONFIGURATION section).
- --no-detach
- Do not detach from console (useful for debugging purposes).
- --log-file file
- Output log to file.
- --help
- Print help information.
gnupg-pkcs11-scd
works only with
already personalized cards, and supports (for the
time being) only RSA keypairs. The following constraints must be satisfied:
- 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).
- The certificate and the corresponding private key must have identical CKA_ID attribute.
NOTES¶
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.
ENVIRONMENT¶
- HOME
- Used to locate the home directory.
- GNUPGHOME
- Used instead of ~/.gnupg.
- USERPROFILE
- Used only on Win32 to locate the home directory.
FILES¶
Files affecting the operation ofgnupg-pkcs11-scd
:
- ~/.gnupg/gnupg-pkcs11-scd.conf
gnupg-pkcs11-scd
uses this as a default configuration file.- /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-agent.
CONFIGURATION¶
To tell gpg-agent to use another smart-card daemon, the following needs to be put in ~/.gnupg/gpg-agent.conf:scdaemon-program /usr/bin/gnupg-pkcs11-scd pinentry-program /usr/bin/pinentry-qt
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 # are comments):
# Log file. #log-file log1 # Default is not verbose. #verbose # Default is no debugging. #debug-all # Pin cache period in seconds; default is infinite. #pin-cache 20 # Comma-separated list of available provider names. Then set # attributes for each provider using the provider-[name]-attribute # syntax. providers p1 # Provider attributes (see below for detailed description) provider-p1-library /usr/lib/pkcs11/p1.so #provider-p1-allow-protected-auth #provider-p1-cert-private #provider-p1-private-mask 0 #emulate-openpgpg #openpgp-sign 5C661B8C07CFD957F7D98D5B9A0F31D236BFAC2A #openpgp-encr D2DC0BD1EDD185969748B6025B452816F97CBA57 #openpgp-auth A7B8C1A3A8F71FCEC018886F8767927B9C8D871F
- library
- Full path to the PKCS#11 shared library (= provider).
- allow-protected-auth
- Allow protected authentication for provider. This needs to be supported by the provider and you should have appropriate reader hardware.
- cert-private
- Authentication is required before certificates can be accessed. Most configurations store certificates as public, so there is no need to use this option.
- private-mask
- 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
- 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:
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.
gpg-agent --server gpg-connect-agent
- openpgp-sign
- Hex string (Upper letter, no space) SHA1 of signing public key.
- openpgp-encr
- Hex string (Upper letter, no space) SHA1 of encryption public key.
- openpgp-auth
- Hex string (Upper letter, no space) SHA1 of authentication public key.
GNUPG INTEGRATION¶
Typical steps to set up a card for gpgsm usage:- Import the CA certificate of your issuer:
You should also manually import all self-signed certificates.
gpgsm --import < ca-certificate
- Instruct GnuPG to discover all useful certificates on the card:
gpgsm --learn-card
- Aquire key ids:
Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first field is the hash, the second is the subject name.
gpg-agent --server gpg-connect-agent
- Configure gnupg-pkcs11-scd for opengpg emulation, specify the public key hashes to be used for signature, encryption and authentication.
- Instruct GnuPG to discover all useful information of card:
You should see valid card status.
gpg --card-status
- Now, you should virtual generate keys, the keys are not actually
generated, but returned to gpg to be registered.
gpg --card-edit
admin
generate (DO NOT BACKUP KEYS)
- Disable the opengpg emulation.
SECURITY CONSIDERATIONS¶
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 PIN).SEE ALSO¶
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 <zvrba@globalnet.hr> Copyright (c) 2006-2011 Alon Bar-Lev <alon.barlev@gmail.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.October 15, 2006 | POSIX-compatible |