diff options
Diffstat (limited to 'doc/scdaemon.texi')
| -rw-r--r-- | doc/scdaemon.texi | 387 |
1 files changed, 0 insertions, 387 deletions
diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi deleted file mode 100644 index 51ec4b34c..000000000 --- a/doc/scdaemon.texi +++ /dev/null @@ -1,387 +0,0 @@ -@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. 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 application -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. - -@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. - - |