gpg: Extend the ERRSIG status line with a fingerprint.
[gnupg.git] / doc / scdaemon.texi
index 134ca40..a9e6d1e 100644 (file)
@@ -1,57 +1,87 @@
-g@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c Copyright (C) 2002 Free Software Foundation, Inc.
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
+@include defs.inc
+
 @node Invoking SCDAEMON
 @chapter Invoking the SCDAEMON
 @cindex SCDAEMON command options
 @cindex command options
 @cindex options, SCDAEMON command
 
-@c man begin DESCRIPTION
-
+@manpage scdaemon.1
+@ifset manverb
+.B scdaemon
+\- Smartcard daemon for the GnuPG system
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  scdaemon
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]
+.B  \-\-server
+.br
+.B  scdaemon
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]
+.B  \-\-daemon
+.RI [ command_line ]
+@end ifset
+
+
+@mansect description
 The @command{scdaemon} is a daemon to manage smartcards.  It is usually
-invoked by gpg-agent and in general not used directly.
+invoked by @command{gpg-agent} and in general not used directly.
 
-@c man end
-
-@xref{Option Index}, for an index to GPG-AGENTS's commands and options.
+@manpause
+@xref{Option Index}, for an index to @command{scdaemon}'s commands and
+options.
+@mancont
 
 @menu
 * Scdaemon Commands::      List of all commands.
 * Scdaemon Options::       List of all options.
 * Card applications::      Description of card applications.
+* Scdaemon Configuration:: Configuration files.
 * Scdaemon Examples::      Some usage examples.
 * Scdaemon Protocol::      The protocol the daemon uses.
 @end menu
 
-@c man begin COMMANDS
+@mansect commands
 
 @node Scdaemon Commands
 @section Commands
 
-Commands are not distinguished from options execpt for the fact that
-only one one command is allowed.
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
 
 @table @gnupgtabopt
 @item --version
 @opindex version
-Print the program version and licensing information.  Not that you can
+Print the program version and licensing information.  Note that you cannot
 abbreviate this command.
 
 @item --help, -h
 @opindex help
-Print a usage message summarizing the most usefule command-line options.
-Not that you can abbreviate this command.
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot abbreviate this command.
 
 @item --dump-options
 @opindex dump-options
-Print a list of all available options and commands.  Not that you can
+Print a list of all available options and commands.  Note that you cannot
 abbreviate this command.
 
 @item --server
 @opindex server
-Run in server mode and wait for commands on the @code{stdin}.  This is
+Run in server mode and wait for commands on the @code{stdin}.  The
 default mode is to create a socket and listen for commands there.
 
 @item --multi-server
@@ -63,17 +93,12 @@ may be used to get the name of that extra socket.
 @item --daemon
 @opindex daemon
 Run the program in the background.  This option is required to prevent
-it from being accidently running in the background.
-
-@item --print-atr
-@opindex print-atr
-This is mainly a debugging command, used to print the ATR
-(Answer-To-Reset) of a card and exit immediately. 
+it from being accidentally running in the background.
 
 @end table
 
 
-@c man begin OPTIONS
+@mansect options
 
 @node Scdaemon Options
 @section Option Summary
@@ -87,14 +112,8 @@ per-user configuration file.  The default configuration file is named
 @file{scdaemon.conf} and expected in the @file{.gnupg} directory directly
 below the home directory of the user.
 
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@include opt-homedir.texi
+
 
 @item -v
 @item --verbose
@@ -106,24 +125,30 @@ verbose commands to @command{gpgsm}, such as @samp{-vv}.
 
 @item --debug-level @var{level}
 @opindex debug-level
-Select the debug level for investigating problems. @var{level} may be
-one of:
-
-   @table @code
-   @item none
-   no debugging at all.
-   @item basic  
-   some basic debug messages
-   @item advanced
-   more verbose debug messages
-   @item expert
-   even more detailed messages
-   @item guru
-   all of the debug messages you can get
-   @end table
+Select the debug level for investigating problems.  @var{level} may be
+a numeric value or a keyword:
+
+@table @code
+@item none
+No debugging at all.  A value of less than 1 may be used instead of
+the keyword.
+@item basic
+Some basic debug messages.  A value between 1 and 2 may be used
+instead of the keyword.
+@item advanced
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
+@item expert
+Even more detailed messages.  A value between 6 and 8 may be used
+instead of the keyword.
+@item guru
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword.  The creation of hash tracing files is
+only enabled if the keyword is used.
+@end table
 
 How these messages are mapped to the actual debugging flags is not
-specified and may change with newer releaes of this program. They are
+specified and may change with newer releases of this program. They are
 however carefully selected to best aid in debugging.
 
 @quotation Note
@@ -135,30 +160,33 @@ helpers to debug problems.
 
 @item --debug @var{flags}
 @opindex debug
-This option is only useful for debugging and the behaviour may change at
+This option is only useful for debugging and the behavior may change at
 any time without notice.  FLAGS are bit encoded and may be given in
 usual C-Syntax. The currently defined bits are:
 
-   @table @code
-   @item 0  (1)
-   command I/O
-   @item 1  (2)  
-   values of big number integers 
-   @item 2  (4)
-   low level crypto operations
-   @item 5  (32)
-   memory allocation
-   @item 6  (64)
-   caching
-   @item 7  (128)
-   show memory statistics.
-   @item 9  (512)
-   write hashed data to files named @code{dbgmd-000*}
-   @item 10 (1024)
-   trace Assuan protocol
-   @item 11 (2048)
-   trace APDU I/O to the card.  This may reveal sensitive data.
-   @end table
+@table @code
+@item 0  (1)
+command I/O
+@item 1  (2)
+values of big number integers
+@item 2  (4)
+low level crypto operations
+@item 5  (32)
+memory allocation
+@item 6  (64)
+caching
+@item 7  (128)
+show memory statistics
+@item 9  (512)
+write hashed data to files named @code{dbgmd-000*}
+@item 10 (1024)
+trace Assuan protocol.
+See also option @option{--debug-assuan-log-cats}.
+@item 11 (2048)
+trace APDU I/O to the card.  This may reveal sensitive data.
+@item 12 (4096)
+trace some card reader related function calls.
+@end table
 
 @item --debug-all
 @opindex debug-all
@@ -181,36 +209,122 @@ protocol.  Note that this option may reveal sensitive data.
 This option disables all ticker functions like checking for card
 insertions.
 
+@item --debug-allow-core-dump
+@opindex debug-allow-core-dump
+For security reasons we won't create a core dump when the process
+aborts.  For debugging purposes it is sometimes better to allow core
+dump.  This option enables it and also changes the working directory to
+@file{/tmp} when running in @option{--server} mode.
+
+@item --debug-log-tid
+@opindex debug-log-tid
+This option appends a thread ID to the PID in the log output.
+
+@item --debug-assuan-log-cats @var{cats}
+@opindex debug-assuan-log-cats
+@efindex ASSUAN_DEBUG
+Changes the active Libassuan logging categories to @var{cats}.  The
+value for @var{cats} is an unsigned integer given in usual C-Syntax.
+A value of 0 switches to a default category.  If this option is not
+used the categories are taken from the environment variable
+@code{ASSUAN_DEBUG}.  Note that this option has only an effect if the
+Assuan debug flag has also been with the option @option{--debug}.  For
+a list of categories see the Libassuan manual.
+
 @item --no-detach
 @opindex no-detach
-Don't detach the process from the console.  This is manly usefule for
+Don't detach the process from the console.  This is mainly useful for
 debugging.
 
+@item --listen-backlog @var{n}
+@opindex listen-backlog
+Set the size of the queue for pending connections.  The default is 64.
+This option has an effect only if @option{--multi-server} is also
+used.
+
 @item --log-file @var{file}
 @opindex log-file
 Append all logging output to @var{file}.  This is very helpful in
-seeing what the agent actually does.
+seeing what the agent actually does.  Use @file{socket://} to log to
+socket.
 
-@item --reader-port @var{number}
-This option may be used to specify the port of the card terminal.  A
-value of 0 refers to the first serial device; add 32768 to access USB
-devices.  The default is 32768 (first USB device).
+
+@item --pcsc-driver @var{library}
+@opindex pcsc-driver
+Use @var{library} to access the smartcard reader.  The current default
+is @file{libpcsclite.so}.  Instead of using this option you might also
+want to install a symbolic link to the default file name
+(e.g. from @file{libpcsclite.so.1}).
 
 @item --ctapi-driver @var{library}
+@opindex ctapi-driver
 Use @var{library} to access the smartcard reader.  The current default
-is @code{libtowitoko.so}.  Note that the use of this interface is
+is @file{libtowitoko.so}.  Note that the use of this interface is
 deprecated; it may be removed in future releases.
 
+@item --disable-ccid
+@opindex disable-ccid
+Disable the integrated support for CCID compliant readers.  This
+allows falling back to one of the other drivers even if the internal
+CCID driver can handle the reader.  Note, that CCID support is only
+available if libusb was available at build time.
 
-@item --allow-admin
-@itemx --deny-admin
-@opindex allow-admin
+@item --reader-port @var{number_or_string}
+@opindex reader-port
+This option may be used to specify the port of the card terminal.  A
+value of 0 refers to the first serial device; add 32768 to access USB
+devices.  The default is 32768 (first USB device).  PC/SC or CCID
+readers might need a string here; run the program in verbose mode to get
+a list of available readers.  The default is then the first reader
+found.
+
+To get a list of available CCID readers you may use this command:
+@cartouche
+@smallexample
+  echo scd getinfo reader_list \
+    | gpg-connect-agent --decode | awk '/^D/ @{print $2@}'
+@end smallexample
+@end cartouche
+
+@item --card-timeout @var{n}
+@opindex card-timeout
+If @var{n} is not 0 and no client is actively using the card, the card
+will be powered down after @var{n} seconds.  Powering down the card
+avoids a potential risk of damaging a card when used with certain
+cheap readers.  This also allows applications that are not aware of
+Scdaemon to access the card.  The disadvantage of using a card timeout
+is that accessing the card takes longer and that the user needs to
+enter the PIN again after the next power up.
+
+Note that with the current version of Scdaemon the card is powered
+down immediately at the next timer tick for any value of @var{n} other
+than 0.
+
+@item --enable-pinpad-varlen
+@opindex enable-pinpad-varlen
+Please specify this option when the card reader supports variable
+length input for pinpad (default is no).  For known readers (listed in
+ccid-driver.c and apdu.c), this option is not needed.  Note that if
+your card reader doesn't supports variable length input but you want
+to use it, you need to specify your pinpad request on your card.
+
+
+@item --disable-pinpad
+@opindex disable-pinpad
+Even if a card reader features a pinpad, do not try to use it.
+
+
+@item --deny-admin
 @opindex deny-admin
-This enables the use of Admin class commands for card applications
-where this is supported.  Currently we support it for the OpenPGP
-card.  Deny is the default.  This commands is useful to inhibit
-accidental access to admin class command which could ultimately lock
-the card through worng PIN numbers.
+@opindex allow-admin
+This option disables the use of admin class commands for card
+applications where this is supported.  Currently we support it for the
+OpenPGP card. This option is useful to inhibit accidental access to
+admin class command which could ultimately lock the card through wrong
+PIN numbers.  Note that GnuPG versions older than 2.0.11 featured an
+@option{--allow-admin} option which was required to use such admin
+commands.  This option has no more effect today because the default is
+now to allow admin commands.
 
 @item --disable-application @var{name}
 @opindex disable-application
@@ -224,8 +338,7 @@ All the long options may also be given in the configuration file after
 stripping off the two leading dashes.
 
 
-@c man begin CARD APPLICATIONS
-
+@mansect card applications
 @node Card applications
 @section Description of card applications
 
@@ -236,16 +349,22 @@ stripping off the two leading dashes.
 * NKS Card::              The Telesec NetKey card application
 * DINSIG Card::           The DINSIG card application
 * PKCS#15 Card::          The PKCS#15 card application
+* Geldkarte Card::        The Geldkarte application
+* SmartCard-HSM::         The SmartCard-HSM application
+* Undefined Card::        The Undefined stub application
 @end menu
 
 @node OpenPGP Card
 @subsection The OpenPGP card application ``openpgp''
 
 This application is currently only used by @command{gpg} but may in
-future also be useful with @command{gpgsm}. 
+future also be useful with @command{gpgsm}.  Version 1 and version 2 of
+the card is supported.
 
-The specification for such a card is available at
-@uref{http://g10code.com/docs/openpgp-card-1.0.pdf}.
+@noindent
+The specifications for these cards are available at@*
+@uref{http://g10code.com/docs/openpgp-card-1.0.pdf} and@*
+@uref{http://g10code.com/docs/openpgp-card-2.0.pdf}.
 
 @node NKS Card
 @subsection The Telesec NetKey card ``nks''
@@ -258,20 +377,84 @@ used by @command{gpgsm}.
 @subsection The DINSIG card application ``dinsig''
 
 This is an application as described in the German draft standard
-@emph{DIN V 66291-1}.  It is intended to be used by cards supporteing
+@emph{DIN V 66291-1}.  It is intended to be used by cards supporting
 the German signature law and its bylaws (SigG and SigV).
 
 @node PKCS#15 Card
 @subsection The PKCS#15 card application ``p15''
 
-This is common fraqmework for smart card applications.  It is used by
+This is common framework for smart card applications.  It is used by
 @command{gpgsm}.
 
+@node Geldkarte Card
+@subsection The Geldkarte card application ``geldkarte''
+
+This is a simple application to display information of a German
+Geldkarte.  The Geldkarte is a small amount debit card application which
+comes with almost all German banking cards.
+
+@node SmartCard-HSM
+@subsection The SmartCard-HSM card application ``sc-hsm''
+
+This application adds read-only support for keys and certificates
+stored on a @uref{http://www.smartcard-hsm.com, SmartCard-HSM}.
+
+To generate keys and store certifiates you may use
+@uref{https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM, OpenSC} or
+the tools from @uref{http://www.openscdp.org, OpenSCDP}.
+
+The SmartCard-HSM cards requires a card reader that supports Extended
+Length APDUs.
+
+@node Undefined Card
+@subsection The Undefined card application ``undefined''
+
+This is a stub application to allow the use of the APDU command even
+if no supported application is found on the card.  This application is
+not used automatically but must be explicitly requested using the
+SERIALNO command.
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************   FILES    ****************
+@c ***************            ****************
+@c *******************************************
+@mansect files
+@node Scdaemon Configuration
+@section Configuration files
+
+There are a few configuration files to control certain aspects of
+@command{scdaemons}'s operation. Unless noted, they are expected in the
+current home directory (@pxref{option --homedir}).
+
+@table @file
+
+@item scdaemon.conf
+@cindex scdaemon.conf
+This is the standard configuration file read by @command{scdaemon} on
+startup.  It may contain any valid long option; the leading two dashes
+may not be entered and the option may not be abbreviated.  This default
+name may be changed on the command line (@pxref{option --options}).
+
+@item scd-event
+@cindex scd-event
+If this file is present and executable, it will be called on every card
+reader's status change.  An example of this script is provided with the
+distribution
+
+@item reader_@var{n}.status
+This file is created by @command{scdaemon} to let other applications now
+about reader status changes.  Its use is now deprecated in favor of
+@file{scd-event}.
+
+@end table
 
 
-@c 
+@c
 @c  Examples
 @c
+@mansect examples
 @node Scdaemon Examples
 @section Examples
 
@@ -283,23 +466,24 @@ $ scdaemon --server -v
 
 @c man end
 
-@c 
+@c
 @c  Assuan Protocol
 @c
+@manpause
 @node Scdaemon Protocol
 @section Scdaemon's Assuan Protocol
 
 The SC-Daemon should be started by the system to provide access to
 external tokens.  Using Smartcards on a multi-user system does not
-make much sense expcet for system services, but in this case no
+make much sense except for system services, but in this case no
 regular user accounts are hosted on the machine.
 
 A client connects to the SC-Daemon by connecting to the socket named
-@file{/var/run/scdaemon/socket}, configuration information is read from
-@var{/etc/scdaemon.conf}
+@file{@value{LOCALRUNDIR}/scdaemon/socket}, configuration information
+is read from @var{@value{SYSCONFDIR}/scdaemon.conf}
 
 Each connection acts as one session, SC-Daemon takes care of
-syncronizing access to a token between sessions.
+synchronizing access to a token between sessions.
 
 @menu
 * Scdaemon SERIALNO::     Return the serial number.
@@ -312,12 +496,14 @@ syncronizing access to a token between sessions.
 * Scdaemon SETATTR::      Update an attribute's value.
 * Scdaemon WRITEKEY::     Write a key to a card.
 * Scdaemon GENKEY::       Generate a new key on-card.
-* Scdaemon RANDOM::       Return random bytes generate on-card.
+* Scdaemon RANDOM::       Return random bytes generated on-card.
 * Scdaemon PASSWD::       Change PINs.
 * Scdaemon CHECKPIN::     Perform a VERIFY operation.
+* Scdaemon RESTART::      Restart connection
+* Scdaemon APDU::         Send a verbatim APDU to the card
 @end menu
 
-@node Scdaemon SERIALNO 
+@node Scdaemon SERIALNO
 @subsection Return the serial number
 
 This command should be used to check for the presence of a card.  It is
@@ -333,14 +519,13 @@ done on the same card unless he call this function.
   SERIALNO
 @end example
 
-Return the serial number of the card using a status reponse like:
+Return the serial number of the card using a status response like:
 
 @example
-  S SERIALNO D27600000000000000000000 0
+  S SERIALNO D27600000000000000000000
 @end example
 
-The trailing 0 should be ignored for now, it is reserved for a future
-extension.  The serial number is the hex encoded value identified by 
+The serial number is the hex encoded value identified by
 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
 
 
@@ -353,11 +538,11 @@ the @code{0x5A} tag in the GDO file (FIX=0x2F02).
 @end example
 
 Learn all useful information of the currently inserted card.  When
-used without the force options, the command might do an INQUIRE
+used without the @option{--force} option, the command might do an INQUIRE
 like this:
 
 @example
-      INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
+      INQUIRE KNOWNCARDP <hexstring_with_serialNumber>
 @end example
 
 The client should just send an @code{END} if the processing should go on
@@ -376,11 +561,12 @@ returned in @var{hexstring_with_keygrip}.
 @subsection Return a certificate
 
 @example
- READCERT @var{hexified_certid}
+ READCERT @var{hexified_certid}|@var{keyid}
 @end example
 
 This function is used to read a certificate identified by
-@var{hexified_certid} from the card.
+@var{hexified_certid} from the card.  With OpenPGP cards the keyid
+@code{OpenPGP.3} may be used to read the certificate of version 2 cards.
 
 
 @node Scdaemon READKEY
@@ -391,7 +577,7 @@ READKEY @var{hexified_certid}
 @end example
 
 Return the public key for the given cert or key ID as an standard
-S-Expression. 
+S-Expression.
 
 
 
@@ -412,7 +598,14 @@ hex notation.  The actual signing is done using the command
 @end example
 
 where @var{keyid} is the hexified ID of the key to be used.  The key id
-may have been retrieved using the command @code{LEARN}.
+may have been retrieved using the command @code{LEARN}.  If another
+hash algorithm than SHA-1 is used, that algorithm may be given like:
+
+@example
+  PKSIGN --hash=@var{algoname} @var{keyid}
+@end example
+
+With @var{algoname} are one of @code{sha1}, @code{rmd160} or @code{md5}.
 
 
 @node Scdaemon PKDECRYPT
@@ -434,25 +627,29 @@ using the command
 
 where @var{keyid} is the hexified ID of the key to be used.
 
+If the card is aware of the apdding format a status line with padding
+information is send before the plaintext data.  The key for this
+status line is @code{PADDING} with the only defined value being 0 and
+meaning padding has been removed.
 
 @node Scdaemon GETATTR
-@subsection Read an attribute's value.
+@subsection Read an attribute's value
 
 TO BE WRITTEN.
 
 @node Scdaemon SETATTR
-@subsection Update an attribute's value.
+@subsection Update an attribute's value
 
 TO BE WRITTEN.
 
 @node Scdaemon WRITEKEY
-@subsection Write a key to a card.
+@subsection Write a key to a card
 
 @example
   WRITEKEY [--force] @var{keyid}
 @end example
 
-This command is used to store a secret key on a smartcard.  The
+This command is used to store a secret key on a smartcard.  The
 allowed keyids depend on the currently selected smartcard
 application. The actual keydata is requested using the inquiry
 @code{KEYDATA} and need to be provided without any protection.  With
@@ -460,34 +657,35 @@ application. The actual keydata is requested using the inquiry
 overwritten.  The key data is expected to be the usual canonical encoded
 S-expression.
 
-A PIN will be requested in most saes.  This however depends on the
+A PIN will be requested in most cases.  This however depends on the
 actual card application.
 
 
 @node Scdaemon GENKEY
-@subsection Generate a new key on-card.
+@subsection Generate a new key on-card
 
 TO BE WRITTEN.
 
 @node Scdaemon RANDOM
-@subsection Return random bytes generate on-card.
+@subsection Return random bytes generated on-card
 
 TO BE WRITTEN.
 
 
 @node Scdaemon PASSWD
-@subsection Change PINs.
+@subsection Change PINs
 
 @example
-   PASSWD [--reset] @var{chvno}
+   PASSWD [--reset] [--nullpin] @var{chvno}
 @end example
-  
+
 Change the PIN or reset the retry counter of the card holder
-verification vector number @var{chvno}.
+verification vector number @var{chvno}.  The option @option{--nullpin}
+is used to initialize the PIN of TCOS cards (6 byte NullPIN only).
 
 
 @node Scdaemon CHECKPIN
-@subsection Perform a VERIFY operation.
+@subsection Perform a VERIFY operation
 
 @example
   CHECKPIN @var{idstr}
@@ -514,3 +712,59 @@ and only if the retry counter is still at 3.
 @end table
 
 
+
+@node Scdaemon RESTART
+@subsection Perform a RESTART operation
+
+@example
+  RESTART
+@end example
+
+Restart the current connection; this is a kind of warm reset.  It
+deletes the context used by this connection but does not actually
+reset the card.
+
+This is used by gpg-agent to reuse a primary pipe connection and
+may be used by clients to backup from a conflict in the serial
+command; i.e. to select another application.
+
+
+
+
+@node Scdaemon APDU
+@subsection Send a verbatim APDU to the card
+
+@example
+  APDU [--atr] [--more] [--exlen[=@var{n}]] [@var{hexstring}]
+@end example
+
+
+Send an APDU to the current reader.  This command bypasses the high
+level functions and sends the data directly to the card.
+@var{hexstring} is expected to be a proper APDU.  If @var{hexstring} is
+not given no commands are send to the card; However the command will
+implicitly check whether the card is ready for use.
+
+Using the option @code{--atr} returns the ATR of the card as a status
+message before any data like this:
+@example
+     S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1
+@end example
+
+Using the option @code{--more} handles the card status word MORE_DATA
+(61xx) and concatenate all responses to one block.
+
+Using the option @code{--exlen} the returned APDU may use extended
+length up to N bytes.  If N is not given a default value is used
+(currently 4096).
+
+
+
+@mansect see also
+@ifset isman
+@command{gpg-agent}(1),
+@command{gpgsm}(1),
+@command{gpg2}(1)
+@end ifset
+@include see-also-note.texi
+