doc: Clarify dirmngr's --keyserver option.
[gnupg.git] / doc / scdaemon.texi
index c254868..7f1058b 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
 
@@ -69,7 +71,7 @@ abbreviate this command.
 
 @item --help, -h
 @opindex help
-Print a usage message summarizing the most usefule command-line options.
+Print a usage message summarizing the most useful command-line options.
 Not that you can abbreviate this command.
 
 @item --dump-options
@@ -91,7 +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.
+it from being accidentally running in the background.
 
 @end table
 
@@ -123,20 +125,26 @@ 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
@@ -159,8 +167,8 @@ 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)
@@ -172,9 +180,12 @@ 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
@@ -209,6 +220,15 @@ dump.  This options enables it and also changes the working directory to
 @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
+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 of 0 switches to a default category.  If this option is not
+used the categories are taken from the environment variable
+@samp{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
@@ -234,7 +254,7 @@ 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
@@ -251,10 +271,12 @@ 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@}'
+  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
@@ -267,13 +289,21 @@ 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 immediatley at the next timer tick for any value of @var{n} other
+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-keypad
-@opindex disable-keypad
-Even if a card reader features a keypad, do not try to use it.
+@item --disable-pinpad
+@opindex disable-pinpad
+Even if a card reader features a pinpad, do not try to use it.
 
 
 @item --deny-admin
@@ -312,6 +342,8 @@ stripping off the two leading dashes.
 * 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
@@ -319,10 +351,11 @@ stripping off the two leading dashes.
 
 This application is currently only used by @command{gpg} but may in
 future also be useful with @command{gpgsm}.  Version 1 and version 2 of
-the card is supported. 
+the card is supported.
 
-The specifications for these cards are available at
-@uref{http://g10code.com/docs/openpgp-card-1.0.pdf} and
+@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
@@ -342,7 +375,7 @@ 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
@@ -352,6 +385,27 @@ 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 ***************            ****************
@@ -389,7 +443,7 @@ about reader status changes.  Its use is now deprecated in favor of
 @end table
 
 
-@c 
+@c
 @c  Examples
 @c
 @mansect examples
@@ -404,7 +458,7 @@ $ scdaemon --server -v
 
 @c man end
 
-@c 
+@c
 @c  Assuan Protocol
 @c
 @manpause
@@ -413,15 +467,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 expect 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.
@@ -441,7 +495,7 @@ syncronizing access to a token between sessions.
 * 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
@@ -457,14 +511,14 @@ 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
 @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 
+extension.  The serial number is the hex encoded value identified by
 the @code{0x5A} tag in the GDO file (FIX=0x2F02).
 
 
@@ -505,7 +559,7 @@ returned in @var{hexstring_with_keygrip}.
 
 This function is used to read a certificate identified by
 @var{hexified_certid} from the card.  With OpenPGP cards the keyid
-@code{OpenPGP.3} may be used to rad the certticate of version 2 cards.
+@code{OpenPGP.3} may be used to rad the certificate of version 2 cards.
 
 
 @node Scdaemon READKEY
@@ -516,7 +570,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.
 
 
 
@@ -566,6 +620,10 @@ using the command
 
 where @var{keyid} is the hexified ID of the key to be used.
 
+If the card is ware 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.
@@ -584,7 +642,7 @@ TO BE WRITTEN.
   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
@@ -592,7 +650,7 @@ 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.
 
 
@@ -613,7 +671,7 @@ TO BE WRITTEN.
 @example
    PASSWD [--reset] [--nullpin] @var{chvno}
 @end example
-  
+
 Change the PIN or reset the retry counter of the card holder
 verification vector number @var{chvno}.  The option @option{--nullpin}
 is used to initialize the PIN of TCOS cards (6 byte NullPIN only).
@@ -657,11 +715,11 @@ 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.
 
 
 
@@ -687,7 +745,7 @@ 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
@@ -698,7 +756,7 @@ length up to N bytes.  If N is not given a default value is used
 @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