mirror of git://git.gnupg.org/gnupg.git
312 lines
8.0 KiB
Plaintext
312 lines
8.0 KiB
Plaintext
@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.
|
|
@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.
|
|
|