home | help 
UNTITLED()			      LOCAL			      UNTITLED()

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 Inter-
     face (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 fa-
     cilitates 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 im-
	  portant (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 pri-
	 vate 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 pub-
	 lic 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 gen-
	  erated, 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, authen-
	  ticate 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 (us-
     ing 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-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  DEAL-
     INGS IN THE SOFTWARE.

POSIX-compatible		October 15, 2017	     gnupg-pkcs11-scd(1)
home | help