doc: Typo fixes
[gnupg.git] / doc / scdaemon.texi
index 6eb2f16..81af281 100644 (file)
@@ -2,6 +2,8 @@
 @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
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
-.B  \-\-server 
+.RI [ options ]
+.B  \-\-server
 .br
 .B  scdaemon
 .RB [ \-\-homedir
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
-.B  \-\-daemon 
+.RI [ options ]
+.B  \-\-daemon
 .RI [ command_line ]
 @end ifset
 
@@ -58,28 +60,28 @@ options.
 @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
@@ -91,12 +93,7 @@ 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
 
@@ -128,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:
+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.
-@item basic  
-some basic debug messages
+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
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
 @item expert
-even more detailed messages
+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
+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
@@ -157,15 +160,15 @@ 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 1  (2)
+values of big number integers
 @item 2  (4)
 low level crypto operations
 @item 5  (32)
@@ -173,13 +176,16 @@ memory allocation
 @item 6  (64)
 caching
 @item 7  (128)
-show memory statistics.
+show memory statistics
 @item 9  (512)
 write hashed data to files named @code{dbgmd-000*}
 @item 10 (1024)
-trace Assuan protocol
+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
@@ -207,19 +213,40 @@ insertions.
 @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 options enables it and also changes the working directory to
+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 --pcsc-driver @var{library}
@@ -235,10 +262,10 @@ Use @var{library} to access the smartcard reader.  The current default
 is @file{libtowitoko.so}.  Note that the use of this interface is
 deprecated; it may be removed in future releases.
 
-@item --disable-ccid 
+@item --disable-ccid
 @opindex disable-ccid
 Disable the integrated support for CCID compliant readers.  This
-allows to fall back to one of the other drivers even if the internal
+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.
 
@@ -251,20 +278,53 @@ 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.
 
-@item --disable-keypad
-@opindex disable-keypad
-Even if a card reader features a keypad, do not try to use it.
-
-
-@item --allow-admin
-@itemx --deny-admin
-@opindex allow-admin
+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
@@ -289,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''
@@ -317,9 +383,37 @@ 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 certificates 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 ***************            ****************
@@ -345,19 +439,19 @@ 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 veyer card
-reader's status changed. An example of this script is provided with the
+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{sdaemon} to let other applications now
+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
@@ -372,7 +466,7 @@ $ scdaemon --server -v
 
 @c man end
 
-@c 
+@c
 @c  Assuan Protocol
 @c
 @manpause
@@ -381,15 +475,15 @@ $ scdaemon --server -v
 
 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.
@@ -402,14 +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
@@ -425,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).
 
 
@@ -445,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
@@ -468,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
@@ -483,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.
 
 
 
@@ -533,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
@@ -559,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}
@@ -615,7 +714,7 @@ and only if the retry counter is still at 3.
 
 
 @node Scdaemon RESTART
-@subsection Perform a RESTART operation.
+@subsection Perform a RESTART operation
 
 @example
   RESTART
@@ -623,20 +722,20 @@ and only if the retry counter is still at 3.
 
 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. 
+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. 
+command; i.e. to select another application.
 
 
 
 
 @node Scdaemon APDU
-@subsection Send a verbatim APDU to the card.
+@subsection Send a verbatim APDU to the card
 
 @example
-  APDU [--atr] [--more] [@var{hexstring}]
+  APDU [--atr] [--more] [--exlen[=@var{n}]] [@var{hexstring}]
 @end example
 
 
@@ -644,7 +743,7 @@ 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
-implictly check whether the card is ready for use.
+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:
@@ -653,14 +752,18 @@ message before any data like this:
 @end example
 
 Using the option @code{--more} handles the card status word MORE_DATA
-(61xx) and concatenate all reponses to one block.
+(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{gpgsm}(1),
 @command{gpg2}(1)
 @end ifset
 @include see-also-note.texi