mirror of
git://git.gnupg.org/gnupg.git
synced 2024-12-22 10:19:57 +01:00
818e9bad58
stable version 0.1.x. * scdaemon.texi (Card applications): New section. * scdaemon.c (main): New option --disable-application. * app.c (is_app_allowed): New. (select_application): Use it to check for disabled applications. * ccid-driver.h (CCID_DRIVER_ERR_ABORTED): New. * ccid-driver.c (ccid_open_reader): Support the stable 0.1 version of libusb. (ccid_get_atr): Handle short messages. * apdu.c (my_rapdu_get_status): Implemented.
441 lines
12 KiB
Plaintext
441 lines
12 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{scdaemon} 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.
|
|
* Card applications:: Description of card applications.
|
|
* 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. The default configuration file is named
|
|
@file{scdaemon.conf} and expected in the @file{.gnupg} directory directly
|
|
below the home directory of the user.
|
|
|
|
@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-level @var{level}
|
|
@opindex debug-level
|
|
Select the debug level for investigating problems. @var{level} may be
|
|
one of:
|
|
|
|
@table @code
|
|
@item none
|
|
no debugging at all.
|
|
@item basic
|
|
some basic debug messages
|
|
@item advanced
|
|
more verbose debug messages
|
|
@item expert
|
|
even more detailed messages
|
|
@item guru
|
|
all of the debug messages you can get
|
|
@end table
|
|
|
|
How these messages are mapped to the actual debugging flags is not
|
|
specified and may change with newer releaes of this program. They are
|
|
however carefully selected to best aid in debugging.
|
|
|
|
@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}.
|
|
|
|
|
|
@item --allow-admin
|
|
@itemx --deny-admin
|
|
@opindex allow-admin
|
|
@opindex deny-admin
|
|
This enables the use of Admin class commands for card applications
|
|
where this is supported. Currently we support it for the OpenPGP
|
|
card. Deny is the default. This commands is useful to inhibit
|
|
accidental access to admin class command which could ultimately lock
|
|
the card through worng PIN numbers.
|
|
|
|
@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.
|
|
|
|
|
|
@c man begin CARD APPLICATIONS
|
|
|
|
@node Card applications
|
|
@section Description of card applications
|
|
|
|
@sc{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
|
|
@end menu
|
|
|
|
@node OpenPGP Card
|
|
@subsection The OpenPGP card application ``openpgp''
|
|
|
|
This application is currently only used by @sc{gpg} but may in
|
|
future also be useful with @sc{gpgsm}.
|
|
|
|
The specification for such a card is available at
|
|
@uref{http://g10code.com/docs/openpgp-card-1.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 @sc{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 supporteing
|
|
the German signature law and its bylaws (SigG and SigV).
|
|
|
|
@node PKCS#15 Card
|
|
@subsection The PKCS#15 card application ``p15''
|
|
|
|
This is common fraqmework for smart card applications; support is only
|
|
available if compiled with support for the OpenSC library. It is used
|
|
by @sc{gpgsm}.
|
|
|
|
|
|
|
|
@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.
|
|
|
|
|