diff options
Diffstat (limited to 'doc/gpg-agent.texi')
| -rw-r--r-- | doc/gpg-agent.texi | 791 |
1 files changed, 0 insertions, 791 deletions
diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi deleted file mode 100644 index aad0fbb68..000000000 --- a/doc/gpg-agent.texi +++ /dev/null @@ -1,791 +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 GPG-AGENT -@chapter Invoking GPG-AGENT -@cindex GPG-AGENT command options -@cindex command options -@cindex options, GPG-AGENT command - -@c man begin DESCRIPTION - -@sc{gpg-agent} is a daemon to manage secret (private) keys independelty -from any protocol. It is used as a backend for @sc{gpg} and @sc{gpgsm} -as well as for a couple of other utilities. - -@noindent -The usual way to run the agent is from the @code{~/.xsession} file: - -@example -eval `gpg-agent --daemon` -@end example - -@noindent -If you don't use an X server, you can also put this into your regular -startup file @code{~/.profile} or @code{.bash_profile}. It is best not -to run multiple instance of the gpg-agent, so you should make sure that -only is running: @sc{gpg-agent} uses an environment variable to inform -clients about the communication parameters. You can write the -content of this environment variable to a file so that you can test for -a running agent. This short script may do the job: - -@smallexample -if test -f $HOME/.gpg-agent-info && \ - kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then - GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info` - export GPG_AGENT_INFO -else - eval `gpg-agent --daemon` - echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info -fi -@end smallexample - -@noindent -If you want to use a curses based pinentry (which is usually also the -fallback mode for a GUI based pinentry), you should add these lines to -your @code{.bashrc} or whatever initialization file is used for all shell -invocations: - -@smallexample -GPG_TTY=`tty` -export GPG_TTY -@end smallexample - -It is important that this environment variable always reflects the -output of the @code{tty} command. - -@c man end - -@noindent -@xref{Option Index}, for an index to GPG-AGENTS's commands and options. - -@menu -* Agent Commands:: List of all commands. -* Agent Options:: List of all options. -* Agent Signals:: Use of some signals. -* Agent Examples:: Some usage examples. -* Agent Protocol:: The protocol the agent uses. -@end menu - -@c man begin COMMANDS - -@node Agent 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}. The -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. A common way to do -this is: -@example -@end example -$ eval `gpg-agent --daemon` -@end table - - -@c man begin OPTIONS - -@node Agent 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{gpg-agent.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 -q -@item --quiet -@opindex q -@opindex quiet -Try to be as quiet as possible. - -@item --batch -@opindex batch -Don't invoke a pinentry or do any other thing requiring human interaction. - -@item --faked-system-time @var{epoch} -@opindex faked-system-time -This option is only useful for testing; it sets the system time back or -forth to @var{epoch} which is the number of seconds elapsed since the year -1970. - -@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 --no-detach -@opindex no-detach -Don't detach the process from the console. This is manly usefule for -debugging. - -@item -s -@itemx --sh -@itemx -c -@itemx --csh -@opindex s -@opindex sh -@opindex c -@opindex csh -Format the info output in daemon mode for use with the standard Bourne -shell respective the C-shell . The default ist to guess it based on the -environment variable @code{SHELL} which is in almost all cases -sufficient. - -@item --no-grab -@opindex no-grab -Tell the pinentryo not to grab the keyboard and mouse. This option -should in general not be used to avaoid X-sniffing attacks. - -@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 --disable-pth -@opindex disable-pth -Don't allow multiple connections. This option is in general not very -useful. - -@item --allow-mark-trusted -@opindex allow-mark-trusted -Allow clients to mark keys as trusted, i.e. put them into the -@code{trustlist.txt} file. This is by default not allowed to make it -harder for users to inadvertly accept Root-CA keys. - -@item --ignore-cache-for-signing -@opindex ignore-cache-for-signing -This option will let gpg-agent bypass the passphrase cache for all -signing operation. Note that there is also a per-session option to -control this behaviour but this command line option takes precedence. - -@item --default-cache-ttl @var{n} -@opindex default-cache-ttl -Set the time a cache entry is valid to @var{n} seconds. The default are -600 seconds. - -@item --pinentry-program @var{filename} -@opindex pinentry-program -Use program @var{filename} as the PIN entry. The default is installation -dependend and can be shown with the @code{--version} command. - -@item --scdaemon-program @var{filename} -@opindex scdaemon-program -Use program @var{filename} as the Smartcard daemon. The default is -installation dependend and can be shown with the @code{--version} -command. - - -@item --display @var{string} -@itemx --ttyname @var{string} -@itemx --ttytype @var{string} -@itemx --lc-type @var{string} -@itemx --lc-messages @var{string} -@opindex display -@opindex ttyname -@opindex ttytype -@opindex lc-type -@opindex lc-messa -These options are used with the server mode to pass localization -information. - -@item --keep-tty -@itemx --keep-display -@opindex keep-tty -@opindex keep-display -Ignore requests to change change the current @sc{tty} respective the X -window system's @code{DISPLAY} variable. This is useful to lock the -pinentry to pop up at the @sc{tty} or display you started the agent. - - -@end table - -All the long options may also be given in the configuration file after -stripping off the two leading dashes. - -@c -@c Agent Signals -@c -@node Agent Signals -@section Use of some signals. -A running @command{gpg-agent} may be controlled by signals, i.e. using -the @command{kill} command to send a signal to the process. - -Here is a list of supported signals: - -@table @gnupgtabopt - -@item SIGHUP -@cpindex SIGHUP -This signals flushes all chached passphrases and when the program was -started with a configuration file, the configuration file is read again. -Only certain options are honored: @code{quiet}, @code{verbose}, -@code{debug}, @code{debug-all}, @code{no-grab}, @code{pinentry-program}, -@code{default-cache-ttl} and @code{ignore-cache-for-signing}. -@code{scdaemon-program} is also supported but due to the current -implementation, which calls the scdaemon only once, it is not of much -use. - - -@item SIGTERM -@cpindex SIGTERM -Shuts down the process but waits until all current requests are -fulfilled. If the process has received 3 of these signals and requests -are still pending, a shutdown is forced. - -@item SIGINT -@cpindex SIGINT -Shuts down the process immediately. - - -@item SIGUSR1 -@itemx SIGUSR2 -@cpindex SIGUSR1 -@cpindex SIGUSR2 -These signals are used for internal purposes. - -@end table - -@c -@c Examples -@c -@node Agent Examples -@section Examples - -@c man begin EXAMPLES - -@example -$ eval `gpg-agent --daemon` -@end example - -@c man end - - -@c -@c Assuan Protocol -@c -@node Agent Protocol -@section Agent's Assuan Protocol - -The gpg-agent should be started by the login shell and set an -environment variable to tell clients about the socket to be used. -Clients should deny to access an agent with a socket name which does -not match its own configuration. An application may choose to start -an instance of the gpgagent if it does not figure that any has been -started; it should not do this if a gpgagent is running but not -usable. Because gpg-agent can only be used in background mode, no -special command line option is required to activate the use of the -protocol. - -To identify a key we use a thing called keygrip which is the SHA-1 hash -of an canoncical encoded S-Expression of the the public key as used in -Libgcrypt. For the purpose of this interface the keygrip is given as a -hex string. The advantage of using this and not the hash of a -certificate is that it will be possible to use the same keypair for -different protocols, thereby saving space on the token used to keep the -secret keys. - -@menu -* Agent PKDECRYPT:: Decrypting a session key -* Agent PKSIGN:: Signing a Hash -* Agent GENKEY:: Generating a Key -* Agent IMPORT:: Importing a Secret Key -* Agent EXPORT:: Exporting a Secret Key -* Agent ISTRUSTED:: Importing a Root Certificate -* Agent GET_PASSPHRASE:: Ask for a passphrase -* Agent GET_CONFIRMATION:: Ask for confirmation -* Agent HAVEKEY:: Check whether a key is available -* Agent LEARN:: Register a smartcard -* Agent PASSWD:: Change a Passphrase -@end menu - -@node Agent PKDECRYPT -@subsection Decrypting a session key - -The client asks the server to decrypt a session key. The encrypted -session key should have all information needed to select the -appropriate secret key or to delegate it to a smartcard. - -@example - SETKEY <keyGrip> -@end example - -Tell the server about the key to be used for decryption. If this is -not used, gpg-agent may try to figure out the key by trying to -decrypt the message with each key available. - -@example - PKDECRYPT -@end example - -The agent checks whether this command is allowed and then does an -INQUIRY to get the ciphertext the client should then send the cipher -text. - -@example - S: INQUIRE CIPHERTEXT - C: D (xxxxxx - C: D xxxx) - C: END -@end example - -Please note that the server may send status info lines while reading the -data lines from the client. The data send is a SPKI like S-Exp with -this structure: - -@example - (enc-val - (<algo> - (<param_name1> <mpi>) - ... - (<param_namen> <mpi>))) -@end example - -Where algo is a string with the name of the algorithm; see the libgcrypt -documentation for a list of valid algorithms. The number and names of -the parameters depend on the algorithm. The agent does return an error -if there is an inconsistency. - -If the decryption was successful the decrypted data is returned by -means of "D" lines. - -Here is an example session: - -@example - C: PKDECRYPT - S: INQUIRE CIPHERTEXT - C: D (enc-val elg (a 349324324) - C: D (b 3F444677CA))) - C: END - S: # session key follows - S: D 1234567890ABCDEF0 - S: OK descryption successful -@end example - - -@node Agent PKSIGN -@subsection Signing a Hash - -The client ask the agent to sign a given hash value. A default key -will be chosen if no key has been set. To set a key a client first -uses: - -@example - SIGKEY <keyGrip> -@end example - -This can be used multiple times to create multiple signature, the list -of keys is reset with the next PKSIGN command or a RESET. The server -test whether the key is a valid key to sign something and responds with -okay. - -@example - SETHASH <hexstring> -@end example - -The client can use this command to tell the server about the data -(which usually is a hash) to be signed. - -The actual signing is done using - -@example - PKSIGN <options> -@end example - -Options are not yet defined, but my later be used to choosen among -different algorithms (e.g. pkcs 1.5) - -The agent does then some checks, asks for the passphrase and -if SETHASH has not been used asks the client for the data to sign: - -@example - S: INQUIRE HASHVAL - C: D ABCDEF012345678901234 - C: END -@end example - -As a result the server returns the signature as an SPKI like S-Exp -in "D" lines: - -@example - (sig-val - (<algo> - (<param_name1> <mpi>) - ... - (<param_namen> <mpi>))) -@end example - - -The operation is affected by the option - -@example - OPTION use-cache-for-signing=0|1 -@end example - -The default of @code{1} uses the cache. Setting this option to @code{0} -will lead gpg-agent to ignore the passphrase cache. Note, that there is -also a global command line option for gpg-agent to globally disable the -caching. - - -Here is an example session: - -@example - C: SIGKEY <keyGrip> - S: OK key available - C: SIGKEY <keyGrip> - S: OK key available - C: PKSIGN - S: # I did ask the user whether he really wants to sign - S: # I did ask the user for the passphrase - S: INQUIRE HASHVAL - C: D ABCDEF012345678901234 - C: END - S: # signature follows - S: D (sig-val rsa (s 45435453654612121212)) - S: OK -@end example - - -@node Agent GENKEY -@subsection Generating a Key - -This is used to create a new keypair and store the secret key inside the -active PSE -w which is in most cases a Soft-PSE. An not yet defined -option allows to choose the storage location. To get the secret key out -of the PSE, a special export tool has to be used. - -@example - GENKEY -@end example - -Invokes the key generation process and the server will then inquire -on the generation parameters, like: - -@example - S: INQUIRE KEYPARM - C: D (genkey (rsa (nbits 1024))) - C: END -@end example - -The format of the key parameters which depends on the algorithm is of -the form: - -@example - (genkey - (algo - (parameter_name_1 ....) - .... - (parameter_name_n ....))) -@end example - -If everything succeeds, the server returns the *public key* in a SPKI -like S-Expression like this: - -@example - (public-key - (rsa - (n <mpi>) - (e <mpi>))) -@end example - -Here is an example session: - -@example - C: GENKEY - S: INQUIRE KEYPARM - C: D (genkey (rsa (nbits 1024))) - C: END - S: D (public-key - S: D (rsa (n 326487324683264) (e 10001))) - S OK key created -@end example - -@node Agent IMPORT -@subsection Importing a Secret Key - -This operation is not yet supportted by GpgAgent. Specialized tools -are to be used for this. - -There is no actual need because we can expect that secret keys -created by a 3rd party are stored on a smartcard. If we have -generated the key ourself, we do not need to import it. - -@node Agent EXPORT -@subsection Export a Secret Key - -Not implemented. - -Should be done by an extra tool. - -@node Agent ISTRUSTED -@subsection Importing a Root Certificate - -Actually we do not import a Root Cert but provide a way to validate -any piece of data by storing its Hash along with a description and -an identifier in the PSE. Here is the interface desription: - -@example - ISTRUSTED <fingerprint> -@end example - -Check whether the OpenPGP primary key or the X.509 certificate with the -given fingerprint is an ultimately trusted key or a trusted Root CA -certificate. The fingerprint should be given as a hexstring (without -any blanks or colons or whatever in between) and may be left padded with -00 in case of an MD5 fingerprint. GPGAgent will answer with: - -@example - OK -@end example - -The key is in the table of trusted keys. - -@example - ERR 304 (Not Trusted) -@end example - -The key is not in this table. - -Gpg needs the entire list of trusted keys to maintain the web of -trust; the following command is therefore quite helpful: - -@example - LISTTRUSTED -@end example - -GpgAgent returns a list of trusted keys line by line: - -@example - S: D 000000001234454556565656677878AF2F1ECCFF P - S: D 340387563485634856435645634856438576457A P - S: D FEDC6532453745367FD83474357495743757435D S - S: OK -@end example - -The first item on a line is the hexified fingerprint where MD5 -ingerprints are @code{00} padded to the left and the second item is a -flag to indicate the type of key (so that gpg is able to only take care -of PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest -of the line, so that we can extend the format in the future. - -Finally a client should be able to mark a key as trusted: - -@example - MARKTRUSTED @var{fingerprint} "P"|"S" -@end example - -The server will then pop up a window to ask the user whether she -really trusts this key. For this it will probably ask for a text to -be displayed like this: - -@example - S: INQUIRE TRUSTDESC - C: D Do you trust the key with the fingerprint @@FPR@@ - C: D bla fasel blurb. - C: END - S: OK -@end example - -Known sequences with the pattern @@foo@@ are replaced according to this -table: - -@table @code -@item @@FPR16@@ -Format the fingerprint according to gpg rules for a v3 keys. -@item @@FPR20@@ -Format the fingerprint according to gpg rules for a v4 keys. -@item @@FPR@@ -Choose an appropriate format to format the fingerprint. -@item @@@@ -Replaced by a single @code{@@} -@end table - -@node Agent GET_PASSPHRASE -@subsection Ask for a passphrase - -This function is usually used to ask for a passphrase to be used for -conventional encryption, but may also be used by programs which need -special handling of passphrases. This command uses a syntax which helps -clients to use the agent with minimum effort. - -@example - GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}] -@end example - -@var{cache_id} is expected to be a hex string used for caching a -passphrase. Use a @code{X} to bypass the cache. With no other -arguments the agent returns a cached passphrase or an error. - -@var{error_message} is either a single @code{X} for no error message or -a string to be shown as an error message like (e.g. "invalid -passphrase"). Blanks must be percent escaped or replaced by @code{+}'. - -@var{prompt} is either a single @code{X} for a default prompt or the -text to be shown as the prompt. Blanks must be percent escaped or -replaced by @code{+}. - -@var{description} is a text shown above the entry field. Blanks must be -percent escaped or replaced by @code{+}. - -The agent either returns with an error or with a OK followed by the -hex encoded passphrase. Note that the length of the strings is -implicitly limited by the maximum length of a command. - -@example - CLEAR_PASSPHRASE @var{cache_id} -@end example - -may be used to invalidate the cache entry for a passphrase. The -function returns with OK even when there is no cached passphrase. - - -@node Agent GET_CONFIRMATION -@subsection Ask for confirmation - -This command may be used to ask for a simple confirmation by -presenting a text and 2 bottonts: Okay and Cancel. - -@example - GET_CONFIRMATION @var{description} -@end example - -@var{description}is displayed along with a Okay and Cancel -button. Blanks must be percent escaped or replaced by @code{+}. A -@code{X} may be used to display confirmation dialog with a default -text. - -The agent either returns with an error or with a OK. Note, that the -length of @var{description} is implicitly limited by the maximum -length of a command. - - - -@node Agent HAVEKEY -@subsection Check whether a key is available - -This can be used to see whether a secret key is available. It does -not return any information on whether the key is somehow protected. - -@example - HAVEKEY @var{keygrip} -@end example - -The Agent answers either with OK or @code{No_Secret_Key} (208). The -caller may want to check for other error codes as well. - - -@node Agent LEARN -@subsection Register a smartcard - -@example - LEARN [--send] -@end example - -This command is used to register a smartcard. With the --send -option given the certificates are send back. - - -@node Agent PASSWD -@subsection Change a Passphrase - -@example - PASSWD @var{keygrip} -@end example - -This command is used to interactively change the passphrase of the key -indentified by the hex string @var{keygrip}. - - - |