gnupg/doc/scdaemon.texi

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

@node Invoking SCDAEMON
@chapter Invoking the SCDAEMON
@cindex SCDAEMON command options
@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.

@menu
* Scdaemon Commands::      List of all commands.
* Scdaemon Options::       List of all options.
* Scdaemon Examples::      Some usage examples.
* Scdaemon Protocol::      The protocol the daemon uses.
@end menu

@c man begin COMMANDS

@node Scdaemon Commands
@section Commands

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

@table @gnupgtabopt
@item --version
@opindex version
Print the program version and licensing information.  Not that you can
abbreviate this command.

@item --help, -h
@opindex help
Print a usage message summarizing the most usefule command-line options.
Not that you can abbreviate this command.

@item --dump-options
@opindex dump-options
Print a list of all available options and commands.  Not that you can
abbreviate this command.

@item --server
@opindex server
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 --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

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

@item -v
@item --verbose
@opindex v
@opindex verbose
Outputs additional information while running.
You can increase the verbosity by giving several
verbose commands to @sc{gpgsm}, such as @samp{-vv}.

@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

@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-sc @var{n}
@opindex debug-sc
Set the debug level of the OpenSC library to @var{n}.

@item --no-detach
@opindex no-detach
Don't detach the process from the console.  This is manly usefule for
debugging.

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

@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 --ctapi-driver @var{library}
Use @var{library} to access the smartcard reader.  The current default
is @code{libtowitoko.so}.

@end table

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


@c 
@c  Examples
@c
@node Scdaemon Examples
@section Examples

@c man begin EXAMPLES

@example
$ scdaemon --server -v
@end example

@c man end

@c 
@c  Assuan Protocol
@c
@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
regular user accounts are hosted on the machine.

A client connects to the SC-Daemon by connecting to the socket named
@file{/var/run/scdaemon/socket}, configuration information is read from
@var{/etc/scdaemon.conf}

Each connection acts as one session, SC-Daemon takes care of
syncronizing 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 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.
@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 reponse like:

@example
  S SERIALNO D27600000000000000000000 0
@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 
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 force options, the command might do an INQUIRE
like this:

@example
      INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
@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}
@end example

This function is used to read a certificate identified by
@var{hexified_certid} from the card.


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


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


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

TO BE WRITTEN.


@node Scdaemon CHECKPIN
@subsection Perform a VERIFY operation.

TO BE WRITTEN.