@cindex command options
@cindex options, SCDAEMON command
-@c man begin DESCRIPTION
-
-The @sc{scdaeon} is a daemon to manage smartcards. It is usually
-invoked by gpg-agent and in general not used directly.
-
-@c man end
-
-@xref{Option Index}, for an index to GPG-AGENTS's commands and options.
+@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 @command{gpg-agent} and in general not used directly.
+
+@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
@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
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.
+it from being accidentally running in the background.
@end table
-@c man begin OPTIONS
+@mansect options
@node Scdaemon Options
@section Option Summary
@item --options @var{file}
@opindex options
Reads configuration from @var{file} instead of from the default
-per-user configuration file.
+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.
+
+@include opt-homedir.texi
+
@item -v
@item --verbose
@opindex verbose
Outputs additional information while running.
You can increase the verbosity by giving several
-verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+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
+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 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
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 --debug-log-tid
+@opindex debug-log-tid
+This option appends a thread ID to the PID in the log output.
+
@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}
seeing what the agent actually does.
+@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 @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 --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 non Scdaemon aware applications 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 --disable-keypad
+@opindex disable-keypad
+Even if a card reader features a keypad, do not try to use it.
+
+
+@item --deny-admin
+@opindex deny-admin
+@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 commands 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} command 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
+This option disables the use of the card application named
+@var{name}. This is mainly useful for debugging or if a application
+with lower priority should be used by default.
+
@end table
All the long options may also be given in the configuration file after
stripping off the two leading dashes.
+@mansect card applications
+@node Card applications
+@section Description of card applications
+
+@command{scdaemon} supports the card applications as described below.
+
+@menu
+* OpenPGP Card:: The OpenPGP card application
+* 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
+@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}. Version 1 and version 2 of
+the card is supported.
+
+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''
+
+This is the main application of the Telesec cards as available in
+Germany. It is a superset of the German DINSIG card. The card is
+used by @command{gpgsm}.
+
+@node DINSIG Card
+@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 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 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.
+
+
+@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
@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 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
@var{/etc/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.
* Scdaemon READKEY:: Return a public key.
* Scdaemon PKSIGN:: Signing data with a Smartcard.
* 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
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
@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 certificate of version 2 cards.
@node Scdaemon READKEY
SETDATA @var{hexstring}
@end example
-to tell scdaemon about the data to be signed. The data must be given in
+to tell @command{scdaemon} about the data to be signed. The data must be given in
hex notation. The actual signing is done using the command
@example
@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
SETDATA @var{hexstring}
@end example
-to tell scdaemon about the data to be decrypted. The data must be given in
-hex notation. The actual decryption is then done using the command
+to tell @command{scdaemon} about the data to be decrypted. The data
+must be given in hex notation. The actual decryption is then done
+using the command
@example
PKDECRYPT @var{keyid}
where @var{keyid} is the hexified ID of the key to be used.
+
+@node Scdaemon GETATTR
+@subsection Read an attribute's value.
+
+TO BE WRITTEN.
+
+@node Scdaemon SETATTR
+@subsection Update an attribute's value.
+
+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 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 cases. This however depends on the
+actual card application.
+
+
+@node Scdaemon GENKEY
+@subsection Generate a new key on-card.
+
+TO BE WRITTEN.
+
+@node Scdaemon RANDOM
+@subsection Return random bytes generate on-card.
+
+TO BE WRITTEN.
+
+
+@node Scdaemon PASSWD
+@subsection Change PINs.
+
+@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.
+
+@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] [--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
+
projects / gnupg.git / blobdiff