Post beta release update.
[gnupg.git] / doc / scdaemon.texi
index 86ce9c0..79a5fcc 100644 (file)
 .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
 
@@ -123,20 +123,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 +165,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 +178,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 +218,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 +252,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 +269,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
@@ -270,10 +290,18 @@ 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-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 +340,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 +349,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
@@ -352,6 +383,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 +441,7 @@ about reader status changes.  Its use is now deprecated in favor of
 @end table
 
 
-@c 
+@c
 @c  Examples
 @c
 @mansect examples
@@ -404,7 +456,7 @@ $ scdaemon --server -v
 
 @c man end
 
-@c 
+@c
 @c  Assuan Protocol
 @c
 @manpause
@@ -441,7 +493,7 @@ synchronizing 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
@@ -464,7 +516,7 @@ Return the serial number of the card using a status response like:
 @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).
 
 
@@ -516,7 +568,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 +618,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.
@@ -613,7 +669,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 +713,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.
 
 
 
@@ -698,7 +754,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