Revamped the W32 gettext implementation.
[gnupg.git] / doc / scdaemon.texi
index 5265ed2..df9d01a 100644 (file)
@@ -8,30 +8,58 @@
 @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.
-
-@c man end
+invoked by @command{gpg-agent} and in general not used directly.
 
-@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
@@ -54,20 +82,21 @@ abbreviate this command.
 Run in server mode and wait for commands on the @code{stdin}.  This is
 default mode is to create a socket and listen for commands there.
 
+@item --multi-server
+@opindex multi-server
+Run in server mode and wait for commands on the @code{stdin} as well as
+on an additional Unix Domain socket.  The server command @code{GETINFO}
+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. 
-
 @end table
 
 
-@c man begin OPTIONS
+@mansect options
 
 @node Scdaemon Options
 @section Option Summary
@@ -81,14 +110,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 @var{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
@@ -103,49 +126,56 @@ verbose commands to @command{gpgsm}, such as @samp{-vv}.
 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
+@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
 
 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
+All debugging options are subject to change and thus should not be used
+by any application program.  As the name says, they are only used as
+helpers to debug problems.
+@end quotation
+
+
 @item --debug @var{flags}
 @opindex debug
 This option is only useful for debugging and the behaviour 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)
-   X.509 or OpenPGP protocol related data
-   @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 12 (4096)
-   bypass all certificate validation
-   @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
+@item 11 (2048)
+trace APDU I/O to the card.  This may reveal sensitive data.
+@end table
 
 @item --debug-all
 @opindex debug-all
@@ -157,13 +187,28 @@ When running in server mode, wait @var{n} seconds before entering the
 actual processing loop and print the pid.  This gives time to attach a
 debugger.
 
-@item --debug-sc @var{n}
-@opindex debug-sc
-Set the debug level of the OpenSC library to @var{n}.
+@item --debug-ccid-driver
+@opindex debug-wait
+Enable debug output from the included CCID driver for smartcards.
+Using this option twice will also enable some tracing of the T=1
+protocol.  Note that this option may reveal sensitive data.
+
+@item --debug-disable-ticker
+@opindex debug-disable-ticker
+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 options enables it and also changes the working directory to
+@file{/tmp} when running in @option{--server} mode.
+
 
 @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 --log-file @var{file}
@@ -171,17 +216,47 @@ debugging.
 Append all logging output to @var{file}.  This is very helpful in
 seeing what the agent actually does.
 
-@item --reader-port @var{number}
-When the program has been build without OpenSC support, this option must
-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 to fall 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 --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:
+@smallexample
+echo scd getinfo reader_list | gpg-connect-agent --decode | awk '/^D/ @{print $2@}'
+@end smallexample
+
+
+
+@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
@@ -191,7 +266,7 @@ 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.
+the card through wrong PIN numbers.
 
 @item --disable-application @var{name}
 @opindex disable-application
@@ -205,8 +280,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
 
@@ -239,21 +313,56 @@ 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; support is only
-available if compiled with support for the OpenSC library.  It is used
-by @command{gpgsm}.
+This is common fraqmework for smart card applications.  It is used by
+@command{gpgsm}.
+
+
+@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 veyer card
+reader's status changed. 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
+about reader status changes.  Its use is now deprecated in favor of
+@file{scd-event}.
+
+@end table
 
 
 @c 
 @c  Examples
 @c
+@mansect examples
 @node Scdaemon Examples
 @section Examples
 
@@ -268,6 +377,7 @@ $ scdaemon --server -v
 @c 
 @c  Assuan Protocol
 @c
+@manpause
 @node Scdaemon Protocol
 @section Scdaemon's Assuan Protocol
 
@@ -292,10 +402,13 @@ syncronizing access to a token between sessions.
 * Scdaemon PKDECRYPT::    Decrypting data with a Smartcard.
 * Scdaemon GETATTR::      Read an attribute's value.
 * 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 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 
@@ -357,11 +470,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 rad the certticate of version 2 cards.
 
 
 @node Scdaemon READKEY
@@ -393,7 +507,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
@@ -426,6 +547,25 @@ TO BE WRITTEN.
 
 TO BE WRITTEN.
 
+@node Scdaemon WRITEKEY
+@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 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
+@option{--force} set an existing key under this @var{keyid} will get
+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
+actual card application.
+
+
 @node Scdaemon GENKEY
 @subsection Generate a new key on-card.
 
@@ -440,12 +580,92 @@ TO BE WRITTEN.
 @node Scdaemon PASSWD
 @subsection Change PINs.
 
-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).
 
 
 @node Scdaemon CHECKPIN
 @subsection Perform a VERIFY operation.
 
-TO BE WRITTEN.
+@example
+  CHECKPIN @var{idstr}
+@end example
+
+Perform a VERIFY operation without doing anything else.  This may be
+used to initialize a the PIN cache earlier to long lasting
+operations.  Its use is highly application dependent:
+
+@table @strong
+@item OpenPGP
+
+Perform a simple verify operation for CHV1 and CHV2, so that further
+operations won't ask for CHV2 and it is possible to do a cheap check on
+the PIN: If there is something wrong with the PIN entry system, only the
+regular CHV will get blocked and not the dangerous CHV3.  @var{idstr} is
+the usual card's serial number in hex notation; an optional fingerprint
+part will get ignored.
+
+There is however a special mode if @var{idstr} is suffixed with the
+literal string @code{[CHV3]}: In this case the Admin PIN is checked if
+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] [@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 reponses to one block.
+
+
 
+@mansect see also
+@ifset isman
+@command{gpg-agent}(1),
+@command{gpgsm}(1), 
+@command{gpg2}(1)
+@end ifset
+@include see-also-note.texi