     [file defs.inc not included]

Invoking the SCDAEMON
*********************

scdaemon.1

synopsis

description
The scdaemon is a daemon to manage smartcards.  It is usually invoked by gpg-agent and in general not used directly.

See Option Index, for an index to scdaemon's commands and options.

commands

Commands
========

Commands are not distinguished from options except for the fact that only one command is allowed.

--version
     Print the program version and licensing information.  Note that you cannot abbreviate this command.

--help, -h
     Print a usage message summarizing the most useful command-line options. Note that you cannot abbreviate this command.

--dump-options
     Print a list of all available options and commands.  Note that you cannot abbreviate this command.

--server
     Run in server mode and wait for commands on the stdin.  The default mode is to create a socket and listen for commands there.

--multi-server
     Run in server mode and wait for commands on the stdin as well as on an additional Unix Domain socket.  The server command GETINFO may be used to get the name of that extra socket.

--daemon
     Run the program in the background.  This option is required to prevent it from being accidentally running in the background.

options

Option Summary
==============

--options FILE
     Reads configuration from FILE instead of from the default per-user configuration file.  The default configuration file is named scdaemon.conf and expected in the .gnupg directory directly below the home directory of the user.

          [file opt-homedir.texi not included]

-v

--verbose
     Outputs additional information while running. You can increase the verbosity by giving several verbose commands to gpgsm, such as -vv.

--debug-level LEVEL
     Select the debug level for investigating problems.  LEVEL may be a numeric value or a keyword:

     none
          No debugging at all.  A value of less than 1 may be used instead of the keyword.

     basic
          Some basic debug messages.  A value between 1 and 2 may be used instead of the keyword.

     advanced
          More verbose debug messages.  A value between 3 and 5 may be used instead of the keyword.

     expert
          Even more detailed messages.  A value between 6 and 8 may be used instead of the keyword.

     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.

     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.

          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.

--debug FLAGS
     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:

     0  (1)
          command I/O

     1  (2)
          values of big number integers

     2  (4)
          low level crypto operations

     5  (32)
          memory allocation

     6  (64)
          caching

     7  (128)
          show memory statistics

     9  (512)
          write hashed data to files named dbgmd-000*

     10 (1024)
          trace Assuan protocol. See also option --debug-assuan-log-cats.

     11 (2048)
          trace APDU I/O to the card.  This may reveal sensitive data.

     12 (4096)
          trace some card reader related function calls.

--debug-all
     Same as --debug=0xffffffff

--debug-wait N
     When running in server mode, wait N seconds before entering the actual processing loop and print the pid.  This gives time to attach a debugger.

--debug-ccid-driver
     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.

--debug-disable-ticker
     This option disables all ticker functions like checking for card insertions.

--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 /tmp when running in --server mode.

--debug-log-tid
     This option appends a thread ID to the PID in the log output.

--debug-assuan-log-cats CATS
     Changes the active Libassuan logging categories to CATS.  The value for 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 ASSUAN_DEBUG.  Note that this option has only an effect if the Assuan debug flag has also been with the option --debug.  For a list of categories see the Libassuan manual.

--no-detach
     Don't detach the process from the console.  This is mainly useful for debugging.

--log-file FILE
     Append all logging output to FILE.  This is very helpful in seeing what the agent actually does.  Use socket:// to log to socket.

--pcsc-driver LIBRARY
     Use LIBRARY to access the smartcard reader.  The current default is libpcsclite.so.  Instead of using this option you might also want to install a symbolic link to the default file name (e.g. from libpcsclite.so.1).

--ctapi-driver LIBRARY
     Use LIBRARY to access the smartcard reader.  The current default is libtowitoko.so.  Note that the use of this interface is deprecated; it may be removed in future releases.

--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.

--reader-port NUMBER_OR_STRING
     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:

            echo scd getinfo reader_list \
              | gpg-connect-agent --decode | awk '/^D/ {print $2}'

--card-timeout N
     If N is not 0 and no client is actively using the card, the card will be powered down after 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 N other than 0.

--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.

--disable-pinpad
     Even if a card reader features a pinpad, do not try to use it.

--deny-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 --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.

--disable-application NAME
     This option disables the use of the card application named NAME.  This is mainly useful for debugging or if a application with lower priority should be used by default.

All the long options may also be given in the configuration file after stripping off the two leading dashes.

card applications

Description of card applications
================================

scdaemon supports the card applications as described below.

The OpenPGP card application ``openpgp''
----------------------------------------

This application is currently only used by gpg but may in future also be useful with gpgsm.  Version 1 and version 2 of the card is supported.

The specifications for these cards are available at

http://g10code.com/docs/openpgp-card-1.0.pdf and

http://g10code.com/docs/openpgp-card-2.0.pdf.

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 gpgsm.

The DINSIG card application ``dinsig''
--------------------------------------

This is an application as described in the German draft standard DIN V 66291-1.  It is intended to be used by cards supporting the German signature law and its bylaws (SigG and SigV).

The PKCS#15 card application ``p15''
------------------------------------

This is common framework for smart card applications.  It is used by gpgsm.

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.

The SmartCard-HSM card application ``sc-hsm''
---------------------------------------------

This application adds read-only support for keys and certificates stored on a SmartCard-HSM (http://www.smartcard-hsm.com).

To generate keys and store certifiates you may use OpenSC (https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM) or the tools from OpenSCDP (http://www.openscdp.org).

The SmartCard-HSM cards requires a card reader that supports Extended Length APDUs.

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.

files

Configuration files
===================

There are a few configuration files to control certain aspects of scdaemons's operation. Unless noted, they are expected in the current home directory (see option --homedir).

scdaemon.conf
     This is the standard configuration file read by 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 (see option --options).

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.

reader_N.status
     This file is created by scdaemon to let other applications know about reader status changes.  Its use is now deprecated in favor of scd-event.

examples

Examples
========

     $ scdaemon --server -v

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 LOCALRUNDIR/scdaemon/socket, configuration information is read from SYSCONFDIR/SCDAEMON.CONF

Each connection acts as one session, SC-Daemon takes care of synchronizing access to a token between sessions.

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.

       SERIALNO

Return the serial number of the card using a status response like:

       S SERIALNO D27600000000000000000000

The serial number is the hex encoded value identified by the 0x5A tag in the GDO file (FIX=0x2F02).

Read all useful information from the card
-----------------------------------------

       LEARN [--force]

Learn all useful information of the currently inserted card.  When used without the --force option, the command might do an INQUIRE like this:

           INQUIRE KNOWNCARDP <hexstring_with_serialNumber>

The client should just send an END if the processing should go on or a 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:

          S KEYPAIRINFO HEXSTRING_WITH_KEYGRIP HEXSTRING_WITH_ID

If there is no certificate yet stored on the card a single "X" is returned in HEXSTRING_WITH_KEYGRIP.

Return a certificate
--------------------

      READCERT HEXIFIED_CERTID|KEYID

This function is used to read a certificate identified by HEXIFIED_CERTID from the card.  With OpenPGP cards the keyid OpenPGP.3 may be used to read the certificate of version 2 cards.

Return a public key
-------------------

     READKEY HEXIFIED_CERTID

Return the public key for the given cert or key ID as an standard S-Expression.

Signing data with a Smartcard
-----------------------------

To sign some data the caller should use the command

      SETDATA HEXSTRING

to tell scdaemon about the data to be signed.  The data must be given in hex notation.  The actual signing is done using the command

       PKSIGN KEYID

where KEYID is the hexified ID of the key to be used.  The key id may have been retrieved using the command LEARN.  If another hash algorithm than SHA-1 is used, that algorithm may be given like:

       PKSIGN --hash=ALGONAME KEYID

With ALGONAME are one of sha1, rmd160 or md5.

Decrypting data with a Smartcard
--------------------------------

To decrypt some data the caller should use the command

      SETDATA HEXSTRING

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

       PKDECRYPT KEYID

where KEYID is the hexified ID of the key to be used.

If the card is aware of the padding format a status line with padding information is send before the plaintext data.  The key for this status line is PADDING with the only defined value being 0 and meaning padding has been removed.

Read an attribute's value
-------------------------

TO BE WRITTEN.

Update an attribute's value
---------------------------

TO BE WRITTEN.

Write a key to a card
---------------------

       WRITEKEY [--force] KEYID

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 KEYDATA and need to be provided without any protection.  With --force set an existing key under this 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.

Generate a new key on-card
--------------------------

TO BE WRITTEN.

Return random bytes generated on-card
-------------------------------------

TO BE WRITTEN.

Change PINs
-----------

        PASSWD [--reset] [--nullpin] CHVNO

Change the PIN or reset the retry counter of the card holder verification vector number CHVNO.  The option --nullpin is used to initialize the PIN of TCOS cards (6 byte NullPIN only).

Perform a VERIFY operation
--------------------------

       CHECKPIN IDSTR

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:

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.  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 IDSTR is suffixed with the literal string [CHV3]: In this case the Admin PIN is checked if and only if the retry counter is still at 3.

Perform a RESTART operation
---------------------------

       RESTART

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.

Send a verbatim APDU to the card
--------------------------------

       APDU [--atr] [--more] [--exlen[=N]] [HEXSTRING]

Send an APDU to the current reader.  This command bypasses the high level functions and sends the data directly to the card. HEXSTRING is expected to be a proper APDU.  If 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 --atr returns the ATR of the card as a status message before any data like this:

          S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1

Using the option --more handles the card status word MORE_DATA (61xx) and concatenate all responses to one block.

Using the option --exlen the returned APDU may use extended length up to N bytes.  If N is not given a default value is used (currently 4096).

see also
     [file see-also-note.texi not included]