mirror of
git://git.gnupg.org/gnupg.git
synced 2024-12-22 10:19:57 +01:00
3d58329f67
that the scdaemon is still running. * gpg-agent.c (handle_signal): Do not use SIGUSR{1,2} anymore for changing the verbosity.
786 lines
21 KiB
Plaintext
786 lines
21 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 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 --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}.
|
|
|
|
|
|
|