diff options
Diffstat (limited to 'doc/scdaemon.texi')
| -rw-r--r-- | doc/scdaemon.texi | 777 |
1 files changed, 777 insertions, 0 deletions
diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi new file mode 100644 index 0000000..98fa70c --- /dev/null +++ b/doc/scdaemon.texi @@ -0,0 +1,777 @@ +@c Copyright (C) 2002 Free Software Foundation, Inc. +@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 +@cindex command options +@cindex options, SCDAEMON command + +@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 + +@mansect commands + +@node Scdaemon Commands +@section Commands + +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. Note that you cannot +abbreviate this command. + +@item --help, -h +@opindex help +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. Note that you cannot +abbreviate this command. + +@item --server +@opindex server +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 +@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 accidentally running in the background. + +@end table + + +@mansect options + +@node Scdaemon Options +@section Option Summary + +@table @gnupgtabopt + +@item --options @var{file} +@opindex options +Reads configuration from @var{file} instead of from the default +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 v +@opindex verbose +Outputs additional information while running. +You can increase the verbosity by giving several +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 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 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. +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 +@opindex debug-all +Same as @code{--debug=0xffffffff} + +@item --debug-wait @var{n} +@opindex debug-wait +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-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 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 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. Use @file{socket://} to log to +socket. + +@item --pcsc-shared +@opindex pcsc-shared +Use shared mode to access the card via PC/SC. This is a somewhat +dangerous option because Scdaemon assumes exclusivbe access to teh +card and for example caches certain information from the card. Use +this option only if you know what you are doing. + +@item --pcsc-driver @var{library} +@opindex pcsc-driver +Use @var{library} to access the smartcard reader. The current default +on Unix is @file{libpcsclite.so} and on Windows @file{winscard.dll}. +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}). +A Unicode file name may not be used on Windows. + +@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 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. + +@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: +@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 +@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 +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 +* 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}. Version 1 and version 2 of +the card is supported. + +@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'' + +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. + +@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 *************** **************** +@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 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{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 Examples +@c +@mansect examples +@node Scdaemon Examples +@section Examples + +@c man begin EXAMPLES + +@example +$ scdaemon --server -v +@end example + +@c man end + +@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 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{@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 +synchronizing access to a token between sessions. + +@menu +* Scdaemon SERIALNO:: Return the serial number. +* Scdaemon LEARN:: Read all useful information from the card. +* Scdaemon READCERT:: Return a certificate. +* 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 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 +@subsection Return the serial number + +This command should be used to check for the presence of a card. It is +special in that it can be used to reset the card. Most other commands +will return an error when a card change has been detected and the use of +this function is therefore required. + +Background: We want to keep the client clear of handling card changes +between operations; i.e. the client can assume that all operations are +done on the same card unless he call this function. + +@example + SERIALNO +@end example + +Return the serial number of the card using a status response like: + +@example + S SERIALNO D27600000000000000000000 +@end example + +The serial number is the hex encoded value identified by +the @code{0x5A} tag in the GDO file (FIX=0x2F02). + + + +@node Scdaemon LEARN +@subsection Read all useful information from the card + +@example + LEARN [--force] +@end example + +Learn all useful information of the currently inserted card. When +used without the @option{--force} option, the command might do an INQUIRE +like this: + +@example + INQUIRE KNOWNCARDP <hexstring_with_serialNumber> +@end example + +The client should just send an @code{END} if the processing should go on +or a @code{CANCEL} to force the function to terminate with a cancel +error message. The response of this command is a list of status lines +formatted as this: + +@example + S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id} +@end example + +If there is no certificate yet stored on the card a single "X" is +returned in @var{hexstring_with_keygrip}. + +@node Scdaemon READCERT +@subsection Return a certificate + +@example + READCERT @var{hexified_certid}|@var{keyid} +@end example + +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 read the certificate of version 2 cards. + + +@node Scdaemon READKEY +@subsection Return a public key + +@example +READKEY @var{hexified_certid} +@end example + +Return the public key for the given cert or key ID as an standard +S-Expression. + + + +@node Scdaemon PKSIGN +@subsection Signing data with a Smartcard + +To sign some data the caller should use the command + +@example + SETDATA @var{hexstring} +@end example + +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 + PKSIGN @var{keyid} +@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}. 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 +@subsection Decrypting data with a Smartcard + +To decrypt some data the caller should use the command + +@example + SETDATA @var{hexstring} +@end example + +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} +@end example + +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 + +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 generated 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 + |