Ubuntu Manpage: gnupg-pkcs11-scd — GnuPG-compatible smart-card daemon with PKCS#11 support

Provided by: gnupg-pkcs11-scd_0.10.0-5build1_amd64

NAME

     gnupg-pkcs11-scd — GnuPG-compatible smart-card daemon with PKCS#11 support

SYNOPSIS

     gnupg-pkcs11-scd [--server] [--multi-server] [--daemon] [--homedir dir] [--uid-acl uid]
                      [--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 interface with GnuPG is restricted to feching existing keys from the card. Neither new
     key generation nor key transfer is possible through this interface. Instead, when the smart-
     card is asked to generate a key in a particular slot, the existing public key in that slot
     is returned. This facilitates the transfer of keys on the smart-card to usage as a subkey on
     an existing GnuPG master key.  See the GNUPG INTEGRATION section for example usage.

     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.

     --homedir dir
         Use this home directory instead of guessing.

     --uid-acl uid
         Create unix socket as world read/write and apply access control that accepts only remote
         processes of this uid. Usable for proxy scenario.

     --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.

     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 key pairs.  The following constraints must be satisfied:

     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.

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.
     GNUPG_PKCS11_SOCKETDIR
                  Create sockets in this directory, default to TMPDIR.

     Additionally, the \\Software\\GNU\\GnuPG\\HomeDir registry key is used on Win32 to locate
     the default GNUPGHOME.

FILES

     Files affecting the operation of gnupg-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

     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 # 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

           # Use the gnupg PIN cache (>=gnupg-2.3.0)
           #use-gnupg-pin-cache

           # 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

           # The following are for >=gnupg-2.0 and <gnupg-2.1.19
           #openpgp-sign 5C661B8C07CFD957F7D98D5B9A0F31D236BFAC2A
           #openpgp-encr D2DC0BD1EDD185969748B6025B452816F97CBA57
           #openpgp-auth A7B8C1A3A8F71FCEC018886F8767927B9C8D871F

     The following attributes can be set for each provider:

     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.

     openpgp-sign
         [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of signing public key see GNUPG
         INTEGRATION how to obtain.

     openpgp-encr
         [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of encryption public key see GNUPG
         INTEGRATION how to obtain.

     openpgp-auth
         [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of authentication public key see
         GNUPG INTEGRATION how to obtain.

GNUPG INTEGRATION

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:
gpgsm --learn-card

Signing, verification, etc. work as usual with gpgsm.

Typical steps to set up a card for >=gpg-2.0 and <gpg-2.1.19 usage:

1. Acquire key ids:
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.

2. Instruct GnuPG to discover all useful information of card:
gpg --card-status
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.
gpg --card-edit
admin
generate (DO NOT BACKUP KEYS)
Kill gpg-agent and modify configuration to have sign, encrypt, authenticate key hex
ids.

4. Alternatively, you can add the existing keys as subkeys on an existing GPG master key:
gpg --edit-key MASTER_KEY_ID
addcardkey

5. In order to reattach a key to smartcard, remove secret key using:
gpg --delete-secret-keys KEY_ID
Then regenerate but without replace keys using:
gpg --card-edit
admin
generate (DO NOT GENERATE KEYS)

Signing, verification, etc. work as usual with gpg.

Typical steps to set up a card for >=gpg-2.1.19 and <gpg-2.3 usage:

1. Refresh local key store:
gpg --card-status

2. Acquire key ids:
gpg-agent --server gpg-connect-agent
Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first field is the
keygrip, the second is the subject name.

3. Create master key based on existing key using:
gpg --expert --full-generate-key
Select:
(13) Existing key
Enter keygrip to be used as primary key.

4. Continue as usual to setup your primary key, you should probably use signature for
master key.

5. Add subkey using:
gpg --expert --edit-key ${MASTER_KEY_ID}
Enter:
gpg> addkey
Select:
(13) Existing key
Enter keygrip to be used as subkey.

6. Continue as usual to setup your subkey.

Signing, verification, etc. work as usual with gpg.

Typical steps to set up a card for >=gpg-2.3 usage:

1. Create master key based on existing key using:
gpg --expert --full-generate-key
Select:
(14) Existing key from card
Select the key from the list.

2. Continue as usual to setup your primary key, you should probably use signature for
master key.

3. Add subkey using:
gpg --expert --edit-key ${MASTER_KEY_ID}
Enter:
gpg> addkey
Select:
(14) Existing key from card
Select the key from the list.

4. Continue as usual to setup your subkey.

Signing, verification, etc. work as usual with gpg.

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).

AUTHORS AND COPYRIGHT

     Copyright (c) 2006-2007 Zeljko Vrba <zvrba@globalnet.hr>

     Copyright (c) 2006-2017 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.

NAME

SYNOPSIS

DESCRIPTION

NOTES

ENVIRONMENT

FILES

CONFIGURATION

GNUPG INTEGRATION

SECURITY CONSIDERATIONS

SEE ALSO

AUTHORS AND COPYRIGHT