No OneTemporary
Actions

Size

172 KB

Subscribers

None

View Options

	diff --git a/doc/dirmngr.texi b/doc/dirmngr.texi
	index 7b5c7e77b..0f37cc4e3 100644
	--- a/doc/dirmngr.texi
	+++ b/doc/dirmngr.texi
	@@ -1,1106 +1,1106 @@
	@c Copyright (C) 2002 Klar"alvdalens Datakonsult AB
	@c Copyright (C) 2004, 2005, 2006, 2007 g10 Code GmbH
	@c This is part of the GnuPG manual.
	@c For copying conditions, see the file gnupg.texi.

	@include defs.inc

	@node Invoking DIRMNGR
	@chapter Invoking DIRMNGR
	@cindex DIRMNGR command options
	@cindex command options
	@cindex options, DIRMNGR command

	@manpage dirmngr.8
	@ifset manverb
	.B dirmngr
	\- CRL and OCSP daemon
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B dirmngr
	.RI [ options ]
	.I command
	.RI [ args ]
	@end ifset

	@mansect description
	Since version 2.1 of GnuPG, @command{dirmngr} takes care of accessing
	the OpenPGP keyservers. As with previous versions it is also used as
	a server for managing and downloading certificate revocation lists
	(CRLs) for X.509 certificates, downloading X.509 certificates, and
	providing access to OCSP providers. Dirmngr is invoked internally by
	@command{gpg}, @command{gpgsm}, or via the @command{gpg-connect-agent}
	tool.

	@manpause
	@noindent
	@xref{Option Index},for an index to @command{DIRMNGR}'s commands and
	options.
	@mancont

	@menu
	* Dirmngr Commands:: List of all commands.
	* Dirmngr Options:: List of all options.
	* Dirmngr Configuration:: Configuration files.
	* Dirmngr Signals:: Use of signals.
	* Dirmngr Examples:: Some usage examples.
	* Dirmngr Protocol:: The protocol dirmngr uses.
	@end menu


	@node Dirmngr Commands
	@section Commands
	@mansect commands

	Commands are not distinguished from options except for the fact that
	only one command is allowed.

	@table @gnupgtabopt
	@item --version
	@opindex version
	Print the program version and licensing information. Note that you cannot
	abbreviate this command.

	@item --help, -h
	@opindex help
	Print a usage message summarizing the most useful command-line options.
	Note that you can abbreviate this command.

	@item --dump-options
	@opindex dump-options
	Print a list of all available options and commands. Note that you cannot
	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.
	This is only used for testing.

	@item --daemon
	@opindex daemon
	Run in background daemon mode and listen for commands on a socket.
	Note that this also changes the default home directory and enables the
	internal certificate validation code. This mode is deprecated.

	@item --list-crls
	@opindex list-crls
	List the contents of the CRL cache on @code{stdout}. This is probably
	only useful for debugging purposes.

	@item --load-crl @var{file}
	@opindex load-crl
	This command requires a filename as additional argument, and it will
	make Dirmngr try to import the CRL in @var{file} into it's cache.
	Note, that this is only possible if Dirmngr is able to retrieve the
	CA's certificate directly by its own means. In general it is better
	to use @code{gpgsm}'s @code{--call-dirmngr loadcrl filename} command
	so that @code{gpgsm} can help dirmngr.

	@item --fetch-crl @var{url}
	@opindex fetch-crl
	This command requires an URL as additional argument, and it will make
	dirmngr try to retrieve and import the CRL from that @var{url} into
	it's cache. This is mainly useful for debugging purposes. The
	@command{dirmngr-client} provides the same feature for a running dirmngr.

	@item --shutdown
	@opindex shutdown
	This commands shuts down an running instance of Dirmngr. This command
	has currently no effect.

	@item --flush
	@opindex flush
	This command removes all CRLs from Dirmngr's cache. Client requests
	will thus trigger reading of fresh CRLs.

	@end table


	@mansect options
	@node Dirmngr 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{dirmngr.conf} and expected in the home directory.

	@item --homedir @var{dir}
	@opindex options
	Set the name of the home directory to @var{dir}. This option is only
	effective when used on the command line. The default depends on the
	running mode:

	@table @asis

	@item With @code{--daemon} given on the commandline
	the directory named @file{@value{SYSCONFDIR}} is used for configuration files
	and @file{@value{LOCALCACHEDIR}} for cached CRLs.

	@item Without @code{--daemon} given on the commandline
	the directory named @file{.gnupg} directly below the home directory
	of the user unless the environment variable @code{GNUPGHOME} has been set
	in which case its value will be used. All kind of data is stored below
	this directory.
	@end table


	@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{dirmngr}, such as @option{-vv}.


	@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. Use @file{socket://} to log to
	socket.

	@item --debug-level @var{level}
	@opindex debug-level
	Select the debug level for investigating problems. @var{level} may be a
	numeric value or by a keyword:

	@table @code
	@item none
	No debugging at all. A value of less than 1 may be used instead of
	the keyword.
	@item basic
	Some basic debug messages. A value between 1 and 2 may be used
	instead of the keyword.
	@item advanced
	More verbose debug messages. A value between 3 and 5 may be used
	instead of the keyword.
	@item expert
	Even more detailed messages. A value between 6 and 8 may be used
	instead of the keyword.
	@item guru
	All of the debug messages you can get. A value greater than 8 may be
	used instead of the keyword. The creation of hash tracing files is
	only enabled if the keyword is used.
	@end table

	How these messages are mapped to the actual debugging flags is not
	specified and may change with newer releases 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
	+This option is only useful for debugging and the behavior may change at
	any time without notice. FLAGS are bit encoded and may be given in
	usual C-Syntax.

	@item --debug-all
	@opindex debug-all
	Same as @code{--debug=0xffffffff}

	@item --gnutls-debug @var{level}
	@opindex gnutls-debug
	Enable debugging of GNUTLS at @var{level}.

	@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 --disable-check-own-socket
	@opindex disable-check-own-socket
	On some platforms @command{dirmngr} is able to detect the removal of
	its socket file and shutdown itself. This option disable this
	self-test for debugging purposes.

	@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 --force
	@opindex force
	Enabling this option forces loading of expired CRLs; this is only
	useful for debugging.

	@item --use-tor
	@opindex use-tor
	This option switches Dirmngr and thus GnuPG into ``Tor mode'' to route
	all network access via Tor (an anonymity network). WARNING: As of now
	this still leaks the DNS queries; e.g. to lookup the hosts in a
	keyserver pool. Certain other features are disabled if this mode is
	active.

	@item --keyserver @var{name}
	@opindex keyserver
	Use @var{name} as your keyserver. This is the server that @command{gpg}
	communicates with to receive keys, send keys, and search for
	keys. The format of the @var{name} is a URI:
	`scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
	"hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
	keyservers, or "mailto" for the Graff email keyserver. Note that your
	particular installation of GnuPG may have other keyserver types
	available as well. Keyserver schemes are case-insensitive. After the
	keyserver name, optional keyserver configuration options may be
	provided. These are the same as the @option{--keyserver-options} of
	@command{gpg}, but apply only to this particular keyserver.

	Most keyservers synchronize with each other, so there is generally no
	need to send keys to more than one server. The keyserver
	@code{hkp://keys.gnupg.net} uses round robin DNS to give a different
	keyserver each time you use it.

	If exactly two keyservers are configured and only one is a Tor hidden
	service (.onion), Dirmngr selects the keyserver to use depending on
	whether Tor is locally running or not. The check for a running Tor is
	done for each new connection.


	@item --nameserver @var{ipaddr}
	@opindex nameserver
	In ``Tor mode'' Dirmngr uses a public resolver via Tor to resolve DNS
	names. If the default public resolver, which is @code{8.8.8.8}, shall
	not be used a different one can be given using this option. Note that
	a numerical IP address must be given (IPv6 or IPv4) and that no error
	checking is done for @var{ipaddr}. DNS queries in Tor mode do only
	work if GnuPG as been build with ADNS support.

	@item --disable-ldap
	@opindex disable-ldap
	Entirely disables the use of LDAP.

	@item --disable-http
	@opindex disable-http
	Entirely disables the use of HTTP.

	@item --ignore-http-dp
	@opindex ignore-http-dp
	When looking for the location of a CRL, the to be tested certificate
	usually contains so called @dfn{CRL Distribution Point} (DP) entries
	which are URLs describing the way to access the CRL. The first found DP
	entry is used. With this option all entries using the @acronym{HTTP}
	scheme are ignored when looking for a suitable DP.

	@item --ignore-ldap-dp
	@opindex ignore-ldap-dp
	This is similar to @option{--ignore-http-dp} but ignores entries using
	the @acronym{LDAP} scheme. Both options may be combined resulting in
	ignoring DPs entirely.

	@item --ignore-ocsp-service-url
	@opindex ignore-ocsp-service-url
	Ignore all OCSP URLs contained in the certificate. The effect is to
	force the use of the default responder.

	@item --honor-http-proxy
	@opindex honor-http-proxy
	If the environment variable @env{http_proxy} has been set, use its
	value to access HTTP servers.

	@item --http-proxy @var{host}[:@var{port}]
	@opindex http-proxy
	@efindex http_proxy
	Use @var{host} and @var{port} to access HTTP servers. The use of this
	option overrides the environment variable @env{http_proxy} regardless
	whether @option{--honor-http-proxy} has been set.


	@item --ldap-proxy @var{host}[:@var{port}]
	@opindex ldap-proxy
	Use @var{host} and @var{port} to connect to LDAP servers. If @var{port}
	is omitted, port 389 (standard LDAP port) is used. This overrides any
	specified host and port part in a LDAP URL and will also be used if host
	and port have been omitted from the URL.

	@item --only-ldap-proxy
	@opindex only-ldap-proxy
	Never use anything else but the LDAP "proxy" as configured with
	@option{--ldap-proxy}. Usually @command{dirmngr} tries to use other
	configured LDAP server if the connection using the "proxy" failed.


	@item --ldapserverlist-file @var{file}
	@opindex ldapserverlist-file
	Read the list of LDAP servers to consult for CRLs and certificates from
	file instead of the default per-user ldap server list file. The default
	value for @var{file} is @file{dirmngr_ldapservers.conf} or
	@file{ldapservers.conf} when running in @option{--daemon} mode.

	This server list file contains one LDAP server per line in the format

	@sc{hostname:port:username:password:base_dn}

	Lines starting with a @samp{#} are comments.

	Note that as usual all strings entered are expected to be UTF-8 encoded.
	Obviously this will lead to problems if the password has originally been
	encoded as Latin-1. There is no other solution here than to put such a
	password in the binary encoding into the file (i.e. non-ascii characters
	won't show up readable).@footnote{The @command{gpgconf} tool might be
	helpful for frontends as it enables editing this configuration file using
	percent-escaped strings.}


	@item --ldaptimeout @var{secs}
	@opindex ldaptimeout
	Specify the number of seconds to wait for an LDAP query before timing
	out. The default is currently 100 seconds. 0 will never timeout.


	@item --add-servers
	@opindex add-servers
	This option makes dirmngr add any servers it discovers when validating
	certificates against CRLs to the internal list of servers to consult for
	certificates and CRLs.

	This option is useful when trying to validate a certificate that has
	a CRL distribution point that points to a server that is not already
	listed in the ldapserverlist. Dirmngr will always go to this server and
	try to download the CRL, but chances are high that the certificate used
	to sign the CRL is located on the same server. So if dirmngr doesn't add
	that new server to list, it will often not be able to verify the
	signature of the CRL unless the @code{--add-servers} option is used.

	Note: The current version of dirmngr has this option disabled by default.


	@item --allow-ocsp
	@opindex allow-ocsp
	This option enables OCSP support if requested by the client.

	OCSP requests are rejected by default because they may violate the
	privacy of the user; for example it is possible to track the time when
	a user is reading a mail.


	@item --ocsp-responder @var{url}
	@opindex ocsp-responder
	Use @var{url} as the default OCSP Responder if the certificate does
	not contain information about an assigned responder. Note, that
	@code{--ocsp-signer} must also be set to a valid certificate.

	@item --ocsp-signer @var{fpr}\|@var{file}
	@opindex ocsp-signer
	Use the certificate with the fingerprint @var{fpr} to check the
	responses of the default OCSP Responder. Alternatively a filename can be
	given in which case the response is expected to be signed by one of the
	certificates described in that file. Any argument which contains a
	slash, dot or tilde is considered a filename. Usual filename expansion
	takes place: A tilde at the start followed by a slash is replaced by the
	content of @env{HOME}, no slash at start describes a relative filename
	which will be searched at the home directory. To make sure that the
	@var{file} is searched in the home directory, either prepend the name
	with "./" or use a name which contains a dot.

	If a response has been signed by a certificate described by these
	fingerprints no further check upon the validity of this certificate is
	done.

	The format of the @var{FILE} is a list of SHA-1 fingerprint, one per
	line with optional colons between the bytes. Empty lines and lines
	prefix with a hash mark are ignored.


	@item --ocsp-max-clock-skew @var{n}
	@opindex ocsp-max-clock-skew
	The number of seconds a skew between the OCSP responder and them local
	clock is accepted. Default is 600 (20 minutes).

	@item --ocsp-max-period @var{n}
	@opindex ocsp-max-period
	Seconds a response is at maximum considered valid after the time given
	in the thisUpdate field. Default is 7776000 (90 days).

	@item --ocsp-current-period @var{n}
	@opindex ocsp-current-period
	The number of seconds an OCSP response is considered valid after the
	time given in the NEXT_UPDATE datum. Default is 10800 (3 hours).


	@item --max-replies @var{n}
	@opindex max-replies
	Do not return more that @var{n} items in one query. The default is
	10.

	@item --ignore-cert-extension @var{oid}
	@opindex ignore-cert-extension
	Add @var{oid} to the list of ignored certificate extensions. The
	@var{oid} is expected to be in dotted decimal form, like
	@code{2.5.29.3}. This option may be used more than once. Critical
	flagged certificate extensions matching one of the OIDs in the list
	are treated as if they are actually handled and thus the certificate
	won't be rejected due to an unknown critical extension. Use this
	option with care because extensions are usually flagged as critical
	for a reason.

	@item --hkp-cacert @var{file}
	Use the root certificates in @var{file} for verification of the TLS
	certificates used with @code{hkps} (keyserver access over TLS). If
	the file is in PEM format a suffix of @code{.pem} is expected for
	@var{file}. This option may be given multiple times to add more
	root certificates. Tilde expansion is supported.

	@end table


	@c
	@c Dirmngr Configuration
	@c
	@mansect files
	@node Dirmngr Configuration
	@section Configuration

	Dirmngr makes use of several directories when running in daemon mode:

	@table @file

	@item ~/.gnupg
	This is the standard home directory for all configuration files.

	@item /etc/gnupg/trusted-certs
	This directory should be filled with certificates of Root CAs you
	are trusting in checking the CRLs and signing OCSP Responses.

	Usually these are the same certificates you use with the applications
	making use of dirmngr. It is expected that each of these certificate
	files contain exactly one @acronym{DER} encoded certificate in a file
	with the suffix @file{.crt} or @file{.der}. @command{dirmngr} reads
	those certificates on startup and when given a SIGHUP. Certificates
	which are not readable or do not make up a proper X.509 certificate
	are ignored; see the log file for details.

	Applications using dirmngr (e.g. gpgsm) can request these
	certificates to complete a trust chain in the same way as with the
	extra-certs directory (see below).

	Note that for OCSP responses the certificate specified using the option
	@option{--ocsp-signer} is always considered valid to sign OCSP requests.

	@item /etc/gnupg/extra-certs
	This directory may contain extra certificates which are preloaded
	into the interal cache on startup. Applications using dirmngr (e.g. gpgsm)
	can request cached certificates to complete a trust chain.
	This is convenient in cases you have a couple intermediate CA certificates
	or certificates usually used to sign OCSP responses.
	These certificates are first tried before going
	out to the net to look for them. These certificates must also be
	@acronym{DER} encoded and suffixed with @file{.crt} or @file{.der}.

	@item ~/.gnupg/crls.d
	This directory is used to store cached CRLs. The @file{crls.d}
	part will be created by dirmngr if it does not exists but you need to
	make sure that the upper directory exists.

	@end table
	@manpause

	To be able to see what's going on you should create the configure file
	@file{~/gnupg/dirmngr.conf} with at least one line:

	@example
	log-file ~/dirmngr.log
	@end example

	To be able to perform OCSP requests you probably want to add the line:

	@example
	allow-ocsp
	@end example

	To make sure that new options are read and that after the installation
	of a new GnuPG versions the installed dirmngr is running, you may want
	to kill an existing dirmngr first:

	@example
	gpgconf --kill dirmngr
	@end example

	You may check the log file to see whether all desired root
	certificates have been loaded correctly.


	@c
	@c Dirmngr Signals
	@c
	@mansect signals
	@node Dirmngr Signals
	@section Use of signals.

	A running @command{dirmngr} 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 signal flushes all internally cached CRLs as well as any cached
	certificates. Then the certificate cache is reinitialized as on
	startup. Options are re-read from the configuration file. Instead of
	sending this signal it is better to use
	@example
	gpgconf --reload dirmngr
	@end example

	@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. You may also use
	@example
	gpgconf --kill dirmngr
	@end example
	instead of this signal

	@item SIGINT
	@cpindex SIGINT
	Shuts down the process immediately.


	@item SIGUSR1
	@cpindex SIGUSR1
	This prints some caching statistics to the log file.

	@end table



	@c
	@c Examples
	@c
	@mansect examples
	@node Dirmngr Examples
	@section Examples

	Here is an example on how to show dirmngr's internal table of OpenPGP
	keyserver addresses. The output is intended for debugging purposes
	and not part of a defined API.

	@example
	gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
	@end example

	To inhibit the use of a particular host you have noticed in one of the
	keyserver pools, you may use

	@example
	gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
	@end example

	The description of the @code{keyserver} command can be printed using

	@example
	gpg-connect-agent --dirmngr 'help keyserver' /bye
	@end example



	@c
	@c Assuan Protocol
	@c
	@manpause
	@node Dirmngr Protocol
	@section Dirmngr's Assuan Protocol

	Assuan is the IPC protocol used to access dirmngr. This is a
	description of the commands implemented by dirmngr.

	@menu
	* Dirmngr LOOKUP:: Look up a certificate via LDAP
	* Dirmngr ISVALID:: Validate a certificate using a CRL or OCSP.
	* Dirmngr CHECKCRL:: Validate a certificate using a CRL.
	* Dirmngr CHECKOCSP:: Validate a certificate using OCSP.
	* Dirmngr CACHECERT:: Put a certificate into the internal cache.
	* Dirmngr VALIDATE:: Validate a certificate for debugging.
	@end menu

	@node Dirmngr LOOKUP
	@subsection Return the certificate(s) found

	Lookup certificate. To allow multiple patterns (which are ORed)
	quoting is required: Spaces are to be translated into "+" or into
	"%20"; obviously this requires that the usual escape quoting rules
	are applied. The server responds with:

	@example
	S: D <DER encoded certificate>
	S: END
	S: D <second DER encoded certificate>
	S: END
	S: OK
	@end example

	In this example 2 certificates are returned. The server may return
	any number of certificates; OK will also be returned when no
	certificates were found. The dirmngr might return a status line

	@example
	S: S TRUNCATED <n>
	@end example


	To indicate that the output was truncated to N items due to a
	limitation of the server or by an arbitrary set limit.

	The option @option{--url} may be used if instead of a search pattern a
	complete URL to the certificate is known:

	@example
	C: LOOKUP --url CN%3DWerner%20Koch,o%3DIntevation%20GmbH,c%3DDE?userCertificate
	@end example

	If the option @option{--cache-only} is given, no external lookup is done
	so that only certificates from the cache are returned.

	With the option @option{--single}, the first and only the first match
	will be returned. Unless option @option{--cache-only} is also used, no
	local lookup will be done in this case.



	@node Dirmngr ISVALID
	@subsection Validate a certificate using a CRL or OCSP

	@example
	ISVALID [--only-ocsp] [--force-default-responder] @var{certid}\|@var{certfpr}
	@end example

	Check whether the certificate described by the @var{certid} has been
	revoked. Due to caching, the Dirmngr is able to answer immediately in
	most cases.

	The @var{certid} is a hex encoded string consisting of two parts,
	delimited by a single dot. The first part is the SHA-1 hash of the
	issuer name and the second part the serial number.

	Alternatively the certificate's SHA-1 fingerprint @var{certfpr} may be
	given in which case an OCSP request is done before consulting the CRL.
	If the option @option{--only-ocsp} is given, no fallback to a CRL check
	will be used. If the option @option{--force-default-responder} is
	given, only the default OCSP responder will be used and any other
	methods of obtaining an OCSP responder URL won't be used.

	@noindent
	Common return values are:

	@table @code
	@item GPG_ERR_NO_ERROR (0)
	This is the positive answer: The certificate is not revoked and we have
	an up-to-date revocation list for that certificate. If OCSP was used
	the responder confirmed that the certificate has not been revoked.

	@item GPG_ERR_CERT_REVOKED
	This is the negative answer: The certificate has been revoked. Either
	it is in a CRL and that list is up to date or an OCSP responder informed
	us that it has been revoked.

	@item GPG_ERR_NO_CRL_KNOWN
	No CRL is known for this certificate or the CRL is not valid or out of
	date.

	@item GPG_ERR_NO_DATA
	The OCSP responder returned an ``unknown'' status. This means that it
	is not aware of the certificate's status.

	@item GPG_ERR_NOT_SUPPORTED
	This is commonly seen if OCSP support has not been enabled in the
	configuration.
	@end table

	If DirMngr has not enough information about the given certificate (which
	is the case for not yet cached certificates), it will will inquire the
	missing data:

	@example
	S: INQUIRE SENDCERT <CertID>
	C: D <DER encoded certificate>
	C: END
	@end example

	A client should be aware that DirMngr may ask for more than one
	certificate.

	If Dirmngr has a certificate but the signature of the certificate
	could not been validated because the root certificate is not known to
	dirmngr as trusted, it may ask back to see whether the client trusts
	this the root certificate:

	@example
	S: INQUIRE ISTRUSTED <CertHexfpr>
	C: D 1
	C: END
	@end example

	Only this answer will let Dirmngr consider the CRL as valid.


	@node Dirmngr CHECKCRL
	@subsection Validate a certificate using a CRL

	Check whether the certificate with FINGERPRINT (SHA-1 hash of the
	entire X.509 certificate blob) is valid or not by consulting the CRL
	responsible for this certificate. If the fingerprint has not been
	given or the certificate is not known, the function inquires the
	certificate using:

	@example
	S: INQUIRE TARGETCERT
	C: D <DER encoded certificate>
	C: END
	@end example

	Thus the caller is expected to return the certificate for the request
	(which should match FINGERPRINT) as a binary blob. Processing then
	takes place without further interaction; in particular dirmngr tries
	to locate other required certificate by its own mechanism which
	includes a local certificate store as well as a list of trusted root
	certificates.

	@noindent
	The return code is 0 for success; i.e. the certificate has not been
	revoked or one of the usual error codes from libgpg-error.

	@node Dirmngr CHECKOCSP
	@subsection Validate a certificate using OCSP

	@example
	CHECKOCSP [--force-default-responder] [@var{fingerprint}]
	@end example

	Check whether the certificate with @var{fingerprint} (the SHA-1 hash of
	the entire X.509 certificate blob) is valid by consulting the appropriate
	OCSP responder. If the fingerprint has not been given or the
	certificate is not known by Dirmngr, the function inquires the
	certificate using:

	@example
	S: INQUIRE TARGETCERT
	C: D <DER encoded certificate>
	C: END
	@end example

	Thus the caller is expected to return the certificate for the request
	(which should match @var{fingerprint}) as a binary blob. Processing
	then takes place without further interaction; in particular dirmngr
	tries to locate other required certificates by its own mechanism which
	includes a local certificate store as well as a list of trusted root
	certificates.

	If the option @option{--force-default-responder} is given, only the
	default OCSP responder is used. This option is the per-command variant
	of the global option @option{--ignore-ocsp-service-url}.


	@noindent
	The return code is 0 for success; i.e. the certificate has not been
	revoked or one of the usual error codes from libgpg-error.

	@node Dirmngr CACHECERT
	@subsection Put a certificate into the internal cache

	Put a certificate into the internal cache. This command might be
	useful if a client knows in advance certificates required for a test and
	wants to make sure they get added to the internal cache. It is also
	helpful for debugging. To get the actual certificate, this command
	immediately inquires it using

	@example
	S: INQUIRE TARGETCERT
	C: D <DER encoded certificate>
	C: END
	@end example

	Thus the caller is expected to return the certificate for the request
	as a binary blob.

	@noindent
	The return code is 0 for success; i.e. the certificate has not been
	successfully cached or one of the usual error codes from libgpg-error.

	@node Dirmngr VALIDATE
	@subsection Validate a certificate for debugging

	Validate a certificate using the certificate validation function used
	internally by dirmngr. This command is only useful for debugging. To
	get the actual certificate, this command immediately inquires it using

	@example
	S: INQUIRE TARGETCERT
	C: D <DER encoded certificate>
	C: END
	@end example

	Thus the caller is expected to return the certificate for the request
	as a binary blob.


	@mansect see also
	@ifset isman
	@command{gpgsm}(1),
	@command{dirmngr-client}(1)
	@end ifset
	@include see-also-note.texi

	@c
	@c !!! UNDER CONSTRUCTION !!!
	@c
	@c
	@c @section Verifying a Certificate
	@c
	@c There are several ways to request services from Dirmngr. Almost all of
	@c them are done using the Assuan protocol. What we describe here is the
	@c Assuan command CHECKCRL as used for example by the dirmnr-client tool if
	@c invoked as
	@c
	@c @example
	@c dirmngr-client foo.crt
	@c @end example
	@c
	@c This command will send an Assuan request to an already running Dirmngr
	@c instance. foo.crt is expected to be a standard X.509 certificate and
	@c dirmngr will receive the Assuan command
	@c
	@c @example
	@c CHECKCRL @var [{fingerprint}]
	@c @end example
	@c
	@c @var{fingerprint} is optional and expected to be the SHA-1 has of the
	@c DER encoding of the certificate under question. It is to be HEX
	@c encoded. The rationale for sending the fingerprint is that it allows
	@c dirmngr to reply immediately if it has already cached such a request. If
	@c this is not the case and no certificate has been found in dirmngr's
	@c internal certificate storage, dirmngr will request the certificate using
	@c the Assuan inquiry
	@c
	@c @example
	@c INQUIRE TARGETCERT
	@c @end example
	@c
	@c The caller (in our example dirmngr-client) is then expected to return
	@c the certificate for the request (which should match @var{fingerprint})
	@c as a binary blob.
	@c
	@c Dirmngr now passes control to @code{crl_cache_cert_isvalid}. This
	@c function checks whether a CRL item exists for target certificate. These
	@c CRL items are kept in a database of already loaded and verified CRLs.
	@c This mechanism is called the CRL cache. Obviously timestamps are kept
	@c there with each item to cope with the expiration date of the CRL. The
	@c possible return values are: @code{0} to indicate that a valid CRL is
	@c available for the certificate and the certificate itself is not listed
	@c in this CRL, @code{GPG_ERR_CERT_REVOKED} to indicate that the certificate is
	@c listed in the CRL or @code{GPG_ERR_NO_CRL_KNOWN} in cases where no CRL or no
	@c information is available. The first two codes are immediately returned to
	@c the caller and the processing of this request has been done.
	@c
	@c Only the @code{GPG_ERR_NO_CRL_KNOWN} needs more attention: Dirmngr now
	@c calls @code{clr_cache_reload_crl} and if this succeeds calls
	@c @code{crl_cache_cert_isvald) once more. All further errors are
	@c immediately returned to the caller.
	@c
	@c @code{crl_cache_reload_crl} is the actual heart of the CRL management.
	@c It locates the corresponding CRL for the target certificate, reads and
	@c verifies this CRL and stores it in the CRL cache. It works like this:
	@c
	@c * Loop over all crlDPs in the target certificate.
	@c * If the crlDP is invalid immediately terminate the loop.
	@c * Loop over all names in the current crlDP.
	@c * If the URL scheme is unknown or not enabled
	@c (--ignore-http-dp, --ignore-ldap-dp) continues with
	@c the next name.
	@c * @code{crl_fetch} is called to actually retrieve the CRL.
	@c In case of problems this name is ignore and we continue with
	@c the next name. Note that @code{crl_fetch} does only return
	@c a descriptor for the CRL for further reading so does the CRL
	@c does not yet end up in memory.
	@c * @code{crl_cache_insert} is called with that descriptor to
	@c actually read the CRL into the cache. See below for a
	@c description of this function. If there is any error (e.g. read
	@c problem, CRL not correctly signed or verification of signature
	@c not possible), this descriptor is rejected and we continue
	@c with the next name. If the CRL has been successfully loaded,
	@c the loop is terminated.
	@c * If no crlDP has been found in the previous loop use a default CRL.
	@c Note, that if any crlDP has been found but loading of the CRL failed,
	@c this condition is not true.
	@c * Try to load a CRL from all configured servers (ldapservers.conf)
	@c in turn. The first server returning a CRL is used.
	@c * @code(crl_cache_insert) is then used to actually insert the CRL
	@c into the cache. If this failed we give up immediately without
	@c checking the rest of the servers from the first step.
	@c * Ready.
	@c
	@c
	@c The @code{crl_cache_insert} function takes care of reading the bulk of
	@c the CRL, parsing it and checking the signature. It works like this: A
	@c new database file is created using a temporary file name. The CRL
	@c parsing machinery is started and all items of the CRL are put into
	@c this database file. At the end the issuer certificate of the CRL
	@c needs to be retrieved. Three cases are to be distinguished:
	@c
	@c a) An authorityKeyIdentifier with an issuer and serialno exits: The
	@c certificate is retrieved using @code{find_cert_bysn}. If
	@c the certificate is in the certificate cache, it is directly
	@c returned. Then the requester (i.e. the client who requested the
	@c CRL check) is asked via the Assuan inquiry ``SENDCERT'' whether
	@c he can provide this certificate. If this succeed the returned
	@c certificate gets cached and returned. Note, that dirmngr does not
	@c verify in any way whether the expected certificate is returned.
	@c It is in the interest of the client to return a useful certificate
	@c as otherwise the service request will fail due to a bad signature.
	@c The last way to get the certificate is by looking it up at
	@c external resources. This is done using the @code{ca_cert_fetch}
	@c and @code{fetch_next_ksba_cert} and comparing the returned
	@c certificate to match the requested issuer and seriano (This is
	@c needed because the LDAP layer may return several certificates as
	@c LDAP as no standard way to retrieve by serial number).
	@c
	@c b) An authorityKeyIdentifier with a key ID exists: The certificate is
	@c retrieved using @code{find_cert_bysubject}. If the certificate is
	@c in the certificate cache, it is directly returned. Then the
	@c requester is asked via the Assuan inquiry ``SENDCERT_SKI'' whether
	@c he can provide this certificate. If this succeed the returned
	@c certificate gets cached and returned. Note, that dirmngr does not
	@c verify in any way whether the expected certificate is returned.
	@c It is in the interest of the client to return a useful certificate
	@c as otherwise the service request will fail due to a bad signature.
	@c The last way to get the certificate is by looking it up at
	@c external resources. This is done using the @code{ca_cert_fetch}
	@c and @code{fetch_next_ksba_cert} and comparing the returned
	@c certificate to match the requested subject and key ID.
	@c
	@c c) No authorityKeyIdentifier exits: The certificate is retrieved
	@c using @code{find_cert_bysubject} without the key ID argument. If
	@c the certificate is in the certificate cache the first one with a
	@c matching subject is is directly returned. Then the requester is
	@c asked via the Assuan inquiry ``SENDCERT'' and an exact
	@c specification of the subject whether he can
	@c provide this certificate. If this succeed the returned
	@c certificate gets cached and returned. Note, that dirmngr does not
	@c verify in any way whether the expected certificate is returned.
	@c It is in the interest of the client to return a useful certificate
	@c as otherwise the service request will fail due to a bad signature.
	@c The last way to get the certificate is by looking it up at
	@c external resources. This is done using the @code{ca_cert_fetch}
	@c and @code{fetch_next_ksba_cert} and comparing the returned
	@c certificate to match the requested subject; the first certificate
	@c with a matching subject is then returned.
	@c
	@c If no certificate was found, the function returns with the error
	@c GPG_ERR_MISSING_CERT. Now the signature is verified. If this fails,
	@c the erro is returned. On success the @code{validate_cert_chain} is
	@c used to verify that the certificate is actually valid.
	@c
	@c Here we may encounter a recursive situation:
	@c @code{validate_cert_chain} needs to look at other certificates and
	@c also at CRLs to check whether these other certificates and well, the
	@c CRL issuer certificate itself are not revoked. FIXME: We need to make
	@c sure that @code{validate_cert_chain} does not try to lookup the CRL we
	@c are currently processing. This would be a catch-22 and may indicate a
	@c broken PKI. However, due to overlapping expiring times and imprecise
	@c clocks this may actually happen.
	@c
	@c For historical reasons the Assuan command ISVALID is a bit different
	@c to CHECKCRL but this is mainly due to different calling conventions.
	@c In the end the same fucntionality is used, albeit hidden by a couple
	@c of indirection and argument and result code mangling. It furthere
	@c ingetrages OCSP checking depending on options are the way it is
	@c called. GPGSM still uses this command but might eventuall switch over
	@c to CHECKCRL and CHECKOCSP so that ISVALID can be retired.
	@c
	@c
	@c @section Validating a certificate
	@c
	@c We describe here how the internal function @code{validate_cert_chain}
	@c works. Note that mainly testing purposes this functionality may be
	@c called directly using @cmd{dirmngr-client --validate @file{foo.crt}}.
	@c
	@c The function takes the target certificate and a mode argument as
	@c parameters and returns an error code and optionally the closes
	@c expiration time of all certificates in the chain.
	@c
	@c We first check that the certificate may be used for the requested
	@c purpose (i.e. OCSP or CRL signing). If this is not the case
	@c GPG_ERR_WRONG_KEY_USAGE is returned.
	@c
	@c The next step is to find the trust anchor (root certificate) and to
	@c assemble the chain in memory: Starting with the target certificate,
	@c the expiration time is checked against the current date, unknown
	@c critical extensions are detected and certificate policies are matched
	@c (We only allow 2.289.9.9 but I have no clue about that OID and from
	@c where I got it - it does not even seem to be assigned - debug cruft?).
	@c
	@c Now if this certificate is a self-signed one, we have reached the
	@c trust anchor. In this case we check that the signature is good, the
	@c certificate is allowed to act as a CA, that it is a trusted one (by
	@c checking whether it is has been put into the trusted-certs
	@c configuration directory) and finally prepend into to our list
	@c representing the certificate chain. This steps ends then.
	@c
	@c If it is not a self-signed certificate, we check that the chain won't
	@c get too long (current limit is 100), if this is the case we terminate
	@c with the error GPG_ERR_BAD_CERT_CHAIN.
	@c
	@c Now the issuer's certificate is looked up: If an
	@c authorityKeyIdentifier is available, this one is used to locate the
	@c certificate either using issuer and serialnumber or subject DN
	@c (i.e. the issuer's DN) and the keyID. The functions
	@c @code{find_cert_bysn) and @code{find_cert_bysubject} are used
	@c respectively. The have already been described above under the
	@c description of @code{crl_cache_insert}. If no certificate was found
	@c or with no authorityKeyIdentifier, only the cache is consulted using
	@c @code{get_cert_bysubject}. The latter is is done under the assumption
	@c that a matching certificate has explicitly been put into the
	@c certificate cache. If the issuer's certificate could not be found,
	@c the validation terminates with the error code @code{GPG_ERR_MISSING_CERT}.
	@c
	@c If the issuer's certificate has been found, the signature of the
	@c actual certificate is checked and in case this fails the error
	@c #code{GPG_ERR_BAD_CERT_CHAIN} is returned. If the signature checks out, the
	@c maximum chain length of the issuing certificate is checked as well as
	@c the capability of the certificate (i.e. whether he may be used for
	@c certificate signing). Then the certificate is prepended to our list
	@c representing the certificate chain. Finally the loop is continued now
	@c with the issuer's certificate as the current certificate.
	@c
	@c After the end of the loop and if no error as been encountered
	@c (i.e. the certificate chain has been assempled correctly), a check is
	@c done whether any certificate expired or a critical policy has not been
	@c met. In any of these cases the validation terminates with an
	@c appropriate error.
	@c
	@c Finally the function @code{check_revocations} is called to verify no
	@c certificate in the assempled chain has been revoked: This is an
	@c recursive process because a CRL has to be checked for each certificate
	@c in the chain except for the root certificate, of which we already know
	@c that it is trusted and we avoid checking a CRL here due to common
	@c setup problems and the assumption that a revoked root certifcate has
	@c been removed from the list of trusted certificates.
	@c
	@c
	@c
	@c
	@c @section Looking up certificates through LDAP.
	@c
	@c This describes the LDAP layer to retrieve certificates.
	@c the functions @code{ca_cert_fetch} and @code{fetch_next_ksba_cert} are
	@c used for this. The first one starts a search and the second one is
	@c used to retrieve certificate after certificate.
	@c


	diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi
	index b99dc5f5f..8176b3766 100644
	--- a/doc/gpg-agent.texi
	+++ b/doc/gpg-agent.texi
	@@ -1,1505 +1,1505 @@
	@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.

	@include defs.inc

	@node Invoking GPG-AGENT
	@chapter Invoking GPG-AGENT
	@cindex GPG-AGENT command options
	@cindex command options
	@cindex options, GPG-AGENT command

	@manpage gpg-agent.1
	@ifset manverb
	.B gpg-agent
	\- Secret key management for GnuPG
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B gpg-agent
	.RB [ \-\-homedir
	.IR dir ]
	.RB [ \-\-options
	.IR file ]
	.RI [ options ]
	.br
	.B gpg-agent
	.RB [ \-\-homedir
	.IR dir ]
	.RB [ \-\-options
	.IR file ]
	.RI [ options ]
	.B \-\-server
	.br
	.B gpg-agent
	.RB [ \-\-homedir
	.IR dir ]
	.RB [ \-\-options
	.IR file ]
	.RI [ options ]
	.B \-\-daemon
	.RI [ command_line ]
	@end ifset

	@mansect description
	@command{gpg-agent} is a daemon to manage secret (private) keys
	independently from any protocol. It is used as a backend for
	@command{gpg} and @command{gpgsm} as well as for a couple of other
	utilities.

	The agent is automatically started on demand by @command{gpg},
	@command{gpgsm}, @command{gpgconf}, or @command{gpg-connect-agent}.
	Thus there is no reason to start it manually. In case you want to use
	the included Secure Shell Agent you may start the agent using:

	@c From dkg on gnupg-devel on 2016-04-21:
	@c
	@c Here's an attempt at writing a short description of the goals of an
	@c isolated cryptographic agent:
	@c
	@c A cryptographic agent should control access to secret key material.
	@c The agent permits use of the secret key material by a supplicant
	@c without providing a copy of the secret key material to the supplicant.
	@c
	@c An isolated cryptographic agent separates the request for use of
	@c secret key material from permission for use of secret key material.
	@c That is, the system or process requesting use of the key (the
	@c "supplicant") can be denied use of the key by the owner/operator of
	@c the agent (the "owner"), which the supplicant has no control over.
	@c
	@c One way of enforcing this split is a per-key or per-session
	@c passphrase, known only by the owner, which must be supplied to the
	@c agent to permit the use of the secret key material. Another way is
	@c with an out-of-band permission mechanism (e.g. a button or GUI
	@c interface that the owner has access to, but the supplicant does not).
	@c
	@c The rationale for this separation is that it allows access to the
	@c secret key to be tightly controlled and audited, and it doesn't permit
	@c the the supplicant to either copy the key or to override the owner's
	@c intentions.

	@example
	gpg-connect-agent /bye
	@end example

	@noindent
	@efindex GPG_TTY
	You should always add the following lines to your @code{.bashrc} or
	whatever initialization file is used for all shell invocations:

	@smallexample
	GPG_TTY=$(tty)
	export GPG_TTY
	@end smallexample

	@noindent
	It is important that this environment variable always reflects the
	output of the @code{tty} command. For W32 systems this option is not
	required.

	Please make sure that a proper pinentry program has been installed
	under the default filename (which is system dependent) or use the
	option @option{pinentry-program} to specify the full name of that program.
	It is often useful to install a symbolic link from the actual used
	pinentry (e.g. @file{@value{BINDIR}/pinentry-gtk}) to the expected
	one (e.g. @file{@value{BINDIR}/pinentry}).

	@manpause
	@noindent
	@xref{Option Index},for an index to @command{GPG-AGENT}'s commands and options.
	@mancont

	@menu
	* Agent Commands:: List of all commands.
	* Agent Options:: List of all options.
	* Agent Configuration:: Configuration files.
	* Agent Signals:: Use of some signals.
	* Agent Examples:: Some usage examples.
	* Agent Protocol:: The protocol the agent uses.
	@end menu

	@mansect commands
	@node Agent Commands
	@section Commands

	Commands are not distinguished from options except for the fact that
	only one command is allowed.

	@table @gnupgtabopt
	@item --version
	@opindex version
	Print the program version and licensing information. Note that you cannot
	abbreviate this command.

	@item --help
	@itemx -h
	@opindex help
	Print a usage message summarizing the most useful command-line options.
	Note that you can abbreviate this command.

	@item --dump-options
	@opindex dump-options
	Print a list of all available options and commands. Note that you cannot
	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 [@var{command line}]
	@opindex daemon
	Start the gpg-agent as a daemon; that is, detach it from the console
	and run it in the background.

	As an alternative you may create a new process as a child of
	gpg-agent: @code{gpg-agent --daemon /bin/sh}. This way you get a new
	shell with the environment setup properly; after you exit from this
	shell, gpg-agent terminates within a few seconds.
	@end table

	@mansect options
	@node Agent Options
	@section Option Summary

	@table @gnupgtabopt

	@anchor{option --options}
	@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.

	@anchor{option --homedir}
	@include opt-homedir.texi


	@item -v
	@item --verbose
	@opindex verbose
	Outputs additional information while running.
	You can increase the verbosity by giving several
	verbose commands to @command{gpgsm}, such as @samp{-vv}.

	@item -q
	@item --quiet
	@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
	a numeric value or a keyword:

	@table @code
	@item none
	No debugging at all. A value of less than 1 may be used instead of
	the keyword.
	@item basic
	Some basic debug messages. A value between 1 and 2 may be used
	instead of the keyword.
	@item advanced
	More verbose debug messages. A value between 3 and 5 may be used
	instead of the keyword.
	@item expert
	Even more detailed messages. A value between 6 and 8 may be used
	instead of the keyword.
	@item guru
	All of the debug messages you can get. A value greater than 8 may be
	used instead of the keyword. The creation of hash tracing files is
	only enabled if the keyword is used.
	@end table

	How these messages are mapped to the actual debugging flags is not
	specified and may change with newer releases 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
	+This option is only useful for debugging and the behavior 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-quick-random
	@opindex debug-quick-random
	This option inhibits the use of the very secure random quality level
	(Libgcrypt’s @code{GCRY_VERY_STRONG_RANDOM}) and degrades all request
	down to standard random quality. It is only used for testing and
	should not be used for any production quality keys. This option is
	only effective when given on the command line.

	On GNU/Linux, another way to quickly generate insecure keys is to use
	@command{rngd} to fill the kernel's entropy pool with lower quality
	random data. @command{rngd} is typically provided by the
	@command{rng-tools} package. It can be run as follows: @samp{sudo
	rngd -f -r /dev/urandom}.

	@item --debug-pinentry
	@opindex debug-pinentry
	This option enables extra debug information pertaining to the
	Pinentry. As of now it is only useful when used along with
	@code{--debug 1024}.

	@item --no-detach
	@opindex no-detach
	Don't detach the process from the console. This is mainly useful for
	debugging.

	@item -s
	@itemx --sh
	@itemx -c
	@itemx --csh
	@opindex sh
	@opindex csh
	@efindex SHELL
	Format the info output in daemon mode for use with the standard Bourne
	shell or the C-shell respectively. The default is to guess it based on
	the environment variable @code{SHELL} which is correct in almost all
	cases.


	@item --no-grab
	@opindex no-grab
	Tell the pinentry not to grab the keyboard and mouse. This option
	should in general not be used to avoid X-sniffing attacks.

	@anchor{option --log-file}
	@item --log-file @var{file}
	@opindex log-file
	@efindex HKCU\Software\GNU\GnuPG:DefaultLogFile
	Append all logging output to @var{file}. This is very helpful in
	seeing what the agent actually does. Use @file{socket://} to log to
	socket. If neither a log file nor a log file descriptor has been set
	on a Windows platform, the Registry entry
	@code{HKCU\Software\GNU\GnuPG:DefaultLogFile}, if set, is used to
	specify the logging output.


	@anchor{option --no-allow-mark-trusted}
	@item --no-allow-mark-trusted
	@opindex no-allow-mark-trusted
	Do not allow clients to mark keys as trusted, i.e. put them into the
	@file{trustlist.txt} file. This makes it harder for users to inadvertently
	accept Root-CA keys.

	@anchor{option --allow-preset-passphrase}
	@item --allow-preset-passphrase
	@opindex allow-preset-passphrase
	This option allows the use of @command{gpg-preset-passphrase} to seed the
	internal cache of @command{gpg-agent} with passphrases.

	@anchor{option --no-allow-loopback-pinentry}
	@item --no-allow-loopback-pinentry
	@item --allow-loopback-pinentry
	@opindex no-allow-loopback-pinentry
	@opindex allow-loopback-pinentry
	Disallow or allow clients to use the loopback pinentry features; see
	the option @option{pinentry-mode} for details. Allow is the default.

	The @option{--force} option of the Assuan command @command{DELETE_KEY}
	is also controlled by this option: The option is ignored if a loopback
	pinentry is disallowed.

	@item --no-allow-external-cache
	@opindex no-allow-external-cache
	Tell Pinentry not to enable features which use an external cache for
	passphrases.

	Some desktop environments prefer to unlock all
	credentials with one master password and may have installed a Pinentry
	which employs an additional external cache to implement such a policy.
	By using this option the Pinentry is advised not to make use of such a
	cache and instead always ask the user for the requested passphrase.

	@item --allow-emacs-pinentry
	@opindex allow-emacs-pinentry
	Tell Pinentry to allow features to divert the passphrase entry to a
	running Emacs instance. How this is exactly handled depends on the
	version of the used Pinentry.

	@item --ignore-cache-for-signing
	@opindex ignore-cache-for-signing
	This option will let @command{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.
	+control this behavior 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
	is 600 seconds. Each time a cache entry is accessed, the entry's
	timer is reset. To set an entry's maximum lifetime, use
	@command{max-cache-ttl}.

	@item --default-cache-ttl-ssh @var{n}
	@opindex default-cache-ttl
	Set the time a cache entry used for SSH keys is valid to @var{n}
	seconds. The default is 1800 seconds. Each time a cache entry is
	accessed, the entry's timer is reset. To set an entry's maximum
	lifetime, use @command{max-cache-ttl-ssh}.

	@item --max-cache-ttl @var{n}
	@opindex max-cache-ttl
	Set the maximum time a cache entry is valid to @var{n} seconds. After
	this time a cache entry will be expired even if it has been accessed
	recently or has been set using @command{gpg-preset-passphrase}. The
	default is 2 hours (7200 seconds).

	@item --max-cache-ttl-ssh @var{n}
	@opindex max-cache-ttl-ssh
	Set the maximum time a cache entry used for SSH keys is valid to
	@var{n} seconds. After this time a cache entry will be expired even
	if it has been accessed recently or has been set using
	@command{gpg-preset-passphrase}. The default is 2 hours (7200
	seconds).

	@item --enforce-passphrase-constraints
	@opindex enforce-passphrase-constraints
	Enforce the passphrase constraints by not allowing the user to bypass
	them using the ``Take it anyway'' button.

	@item --min-passphrase-len @var{n}
	@opindex min-passphrase-len
	Set the minimal length of a passphrase. When entering a new passphrase
	shorter than this value a warning will be displayed. Defaults to 8.

	@item --min-passphrase-nonalpha @var{n}
	@opindex min-passphrase-nonalpha
	Set the minimal number of digits or special characters required in a
	passphrase. When entering a new passphrase with less than this number
	of digits or special characters a warning will be displayed. Defaults
	to 1.

	@item --check-passphrase-pattern @var{file}
	@opindex check-passphrase-pattern
	Check the passphrase against the pattern given in @var{file}. When
	entering a new passphrase matching one of these pattern a warning will
	be displayed. @var{file} should be an absolute filename. The default is
	not to use any pattern file.

	Security note: It is known that checking a passphrase against a list of
	pattern or even against a complete dictionary is not very effective to
	enforce good passphrases. Users will soon figure up ways to bypass such
	a policy. A better policy is to educate users on good security
	behavior and optionally to run a passphrase cracker regularly on all
	users passphrases to catch the very simple ones.

	@item --max-passphrase-days @var{n}
	@opindex max-passphrase-days
	Ask the user to change the passphrase if @var{n} days have passed since
	the last change. With @option{--enforce-passphrase-constraints} set the
	user may not bypass this check.

	@item --enable-passphrase-history
	@opindex enable-passphrase-history
	This option does nothing yet.

	@item --pinentry-invisible-char @var{char}
	@opindex pinentry-invisible-char
	This option asks the Pinentry to use @var{char} for displaying hidden
	characters. @var{char} must be one character UTF-8 string. A
	Pinentry may or may not honor this request.

	@item --pinentry-timeout @var{n}
	@opindex pinentry-timeout
	This option asks the Pinentry to timeout after @var{n} seconds with no
	user input. The default value of 0 does not ask the pinentry to
	timeout, however a Pinentry may use its own default timeout value in
	this case. A Pinentry may or may not honor this request.

	@item --pinentry-program @var{filename}
	@opindex pinentry-program
	Use program @var{filename} as the PIN entry. The default is
	installation dependent. With the default configuration the name of
	the default pinentry is @file{pinentry}; if that file does not exist
	but a @file{pinentry-basic} exist the latter is used.

	On a Windows platform the default is to use the first existing program
	from this list:
	@file{bin\pinentry.exe},
	@file{..\Gpg4win\bin\pinentry.exe},
	@file{..\Gpg4win\pinentry.exe},
	@file{..\GNU\GnuPG\pinentry.exe},
	@file{..\GNU\bin\pinentry.exe},
	@file{bin\pinentry-basic.exe}
	where the file names are relative to the GnuPG installation directory.


	@item --pinentry-touch-file @var{filename}
	@opindex pinentry-touch-file
	By default the filename of the socket gpg-agent is listening for
	requests is passed to Pinentry, so that it can touch that file before
	exiting (it does this only in curses mode). This option changes the
	file passed to Pinentry to @var{filename}. The special name
	@code{/dev/null} may be used to completely disable this feature. Note
	that Pinentry will not create that file, it will only change the
	modification and access time.


	@item --scdaemon-program @var{filename}
	@opindex scdaemon-program
	Use program @var{filename} as the Smartcard daemon. The default is
	installation dependent and can be shown with the @command{gpgconf}
	command.

	@item --disable-scdaemon
	@opindex disable-scdaemon
	Do not make use of the scdaemon tool. This option has the effect of
	disabling the ability to do smartcard operations. Note, that enabling
	this option at runtime does not kill an already forked scdaemon.

	@item --disable-check-own-socket
	@opindex disable-check-own-socket
	@command{gpg-agent} employs a periodic self-test to detect a stolen
	socket. This usually means a second instance of @command{gpg-agent}
	has taken over the socket and @command{gpg-agent} will then terminate
	itself. This option may be used to disable this self-test for
	debugging purposes.

	@item --use-standard-socket
	@itemx --no-use-standard-socket
	@itemx --use-standard-socket-p
	@opindex use-standard-socket
	@opindex no-use-standard-socket
	@opindex use-standard-socket-p
	Since GnuPG 2.1 the standard socket is always used. These options
	have no more effect. The command @code{gpg-agent
	--use-standard-socket-p} will thus always return success.

	@item --display @var{string}
	@itemx --ttyname @var{string}
	@itemx --ttytype @var{string}
	@itemx --lc-ctype @var{string}
	@itemx --lc-messages @var{string}
	@itemx --xauthority @var{string}
	@opindex display
	@opindex ttyname
	@opindex ttytype
	@opindex lc-ctype
	@opindex lc-messages
	@opindex xauthority
	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 the current @code{tty} or X window system's
	@code{DISPLAY} variable respectively. This is useful to lock the
	pinentry to pop up at the @code{tty} or display you started the agent.


	@anchor{option --extra-socket}
	@item --extra-socket @var{name}
	@opindex extra-socket
	Also listen on native gpg-agent connections on the given socket. The
	intended use for this extra socket is to setup a Unix domain socket
	forwarding from a remote machine to this socket on the local machine.
	A @command{gpg} running on the remote machine may then connect to the
	local gpg-agent and use its private keys. This enables decrypting or
	signing data on a remote machine without exposing the private keys to the
	remote machine.


	@anchor{option --enable-ssh-support}
	@item --enable-ssh-support
	@itemx --enable-putty-support
	@opindex enable-ssh-support
	@opindex enable-putty-support

	Enable the OpenSSH Agent protocol.

	In this mode of operation, the agent does not only implement the
	gpg-agent protocol, but also the agent protocol used by OpenSSH
	(through a separate socket). Consequently, it should be possible to use
	the gpg-agent as a drop-in replacement for the well known ssh-agent.

	SSH Keys, which are to be used through the agent, need to be added to
	the gpg-agent initially through the ssh-add utility. When a key is
	added, ssh-add will ask for the password of the provided key file and
	send the unprotected key material to the agent; this causes the
	gpg-agent to ask for a passphrase, which is to be used for encrypting
	the newly received key and storing it in a gpg-agent specific
	directory.

	Once a key has been added to the gpg-agent this way, the gpg-agent
	will be ready to use the key.

	Note: in case the gpg-agent receives a signature request, the user might
	need to be prompted for a passphrase, which is necessary for decrypting
	the stored key. Since the ssh-agent protocol does not contain a
	mechanism for telling the agent on which display/terminal it is running,
	gpg-agent's ssh-support will use the TTY or X display where gpg-agent
	has been started. To switch this display to the current one, the
	following command may be used:

	@smallexample
	gpg-connect-agent updatestartuptty /bye
	@end smallexample

	Although all GnuPG components try to start the gpg-agent as needed, this
	is not possible for the ssh support because ssh does not know about it.
	Thus if no GnuPG tool which accesses the agent has been run, there is no
	guarantee that ssh is able to use gpg-agent for authentication. To fix
	this you may start gpg-agent if needed using this simple command:

	@smallexample
	gpg-connect-agent /bye
	@end smallexample

	Adding the @option{--verbose} shows the progress of starting the agent.

	The @option{--enable-putty-support} is only available under Windows
	and allows the use of gpg-agent with the ssh implementation
	@command{putty}. This is similar to the regular ssh-agent support but
	makes use of Windows message queue as required by @command{putty}.


	@end table

	All the long options may also be given in the configuration file after
	stripping off the two leading dashes.


	@mansect files
	@node Agent Configuration
	@section Configuration

	There are a few configuration files needed for the operation of the
	agent. By default they may all be found in the current home directory
	(@pxref{option --homedir}).

	@table @file

	@item gpg-agent.conf
	@efindex gpg-agent.conf
	This is the standard configuration file read by @command{gpg-agent} on
	startup. It may contain any valid long option; the leading
	two dashes may not be entered and the option may not be abbreviated.
	This file is also read after a @code{SIGHUP} however only a few
	options will actually have an effect. This default name may be
	changed on the command line (@pxref{option --options}).
	You should backup this file.

	@item trustlist.txt
	@efindex trustlist.txt
	This is the list of trusted keys. You should backup this file.

	Comment lines, indicated by a leading hash mark, as well as empty
	lines are ignored. To mark a key as trusted you need to enter its
	fingerprint followed by a space and a capital letter @code{S}. Colons
	may optionally be used to separate the bytes of a fingerprint; this
	enables cutting and pasting the fingerprint from a key listing output. If
	the line is prefixed with a @code{!} the key is explicitly marked as
	not trusted.

	Here is an example where two keys are marked as ultimately trusted
	and one as not trusted:

	@cartouche
	@smallexample
	# CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
	A6935DD34EF3087973C706FC311AA2CCF733765B S

	# CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
	DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S

	# CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
	!14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
	@end smallexample
	@end cartouche

	Before entering a key into this file, you need to ensure its
	authenticity. How to do this depends on your organisation; your
	administrator might have already entered those keys which are deemed
	trustworthy enough into this file. Places where to look for the
	fingerprint of a root certificate are letters received from the CA or
	the website of the CA (after making 100% sure that this is indeed the
	website of that CA). You may want to consider disallowing interactive
	updates of this file by using the @ref{option --no-allow-mark-trusted}.
	It might even be advisable to change the permissions to read-only so
	that this file can't be changed inadvertently.

	As a special feature a line @code{include-default} will include a global
	list of trusted certificates (e.g. @file{@value{SYSCONFDIR}/trustlist.txt}).
	This global list is also used if the local list is not available.

	It is possible to add further flags after the @code{S} for use by the
	caller:

	@table @code

	@item relax
	@cindex relax
	Relax checking of some root certificate requirements. As of now this
	flag allows the use of root certificates with a missing basicConstraints
	attribute (despite that it is a MUST for CA certificates) and disables
	CRL checking for the root certificate.

	@item cm
	If validation of a certificate finally issued by a CA with this flag set
	fails, try again using the chain validation model.

	@end table


	@item sshcontrol
	@efindex sshcontrol
	This file is used when support for the secure shell agent protocol has
	been enabled (@pxref{option --enable-ssh-support}). Only keys present in
	this file are used in the SSH protocol. You should backup this file.

	The @command{ssh-add} tool may be used to add new entries to this file;
	you may also add them manually. Comment lines, indicated by a leading
	hash mark, as well as empty lines are ignored. An entry starts with
	optional whitespace, followed by the keygrip of the key given as 40 hex
	digits, optionally followed by the caching TTL in seconds and another
	optional field for arbitrary flags. A non-zero TTL overrides the global
	default as set by @option{--default-cache-ttl-ssh}.

	The only flag support is @code{confirm}. If this flag is found for a
	key, each use of the key will pop up a pinentry to confirm the use of
	that key. The flag is automatically set if a new key was loaded into
	@code{gpg-agent} using the option @option{-c} of the @code{ssh-add}
	command.

	The keygrip may be prefixed with a @code{!} to disable an entry.

	The following example lists exactly one key. Note that keys available
	through a OpenPGP smartcard in the active smartcard reader are
	implicitly added to this list; i.e. there is no need to list them.

	@cartouche
	@smallexample
	# Key added on: 2011-07-20 20:38:46
	# Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
	34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm
	@end smallexample
	@end cartouche

	@item private-keys-v1.d/
	@efindex private-keys-v1.d

	This is the directory where gpg-agent stores the private keys. Each
	key is stored in a file with the name made up of the keygrip and the
	suffix @file{key}. You should backup all files in this directory
	and take great care to keep this backup closed away.


	@end table

	Note that on larger installations, it is useful to put predefined
	files into the directory @file{@value{SYSCONFSKELDIR}} so that newly created
	users start up with a working configuration. For existing users the
	a small helper script is provided to create these files (@pxref{addgnupghome}).



	@c
	@c Agent Signals
	@c
	@mansect signals
	@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 signal flushes all cached passphrases and if the program has been
	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{debug-level},
	@code{debug-pinentry},
	@code{no-grab},
	@code{pinentry-program},
	@code{pinentry-invisible-char},
	@code{default-cache-ttl},
	@code{max-cache-ttl}, @code{ignore-cache-for-signing},
	@code{no-allow-external-cache}, @code{allow-emacs-pinentry},
	@code{no-allow-mark-trusted}, @code{disable-scdaemon}, and
	@code{disable-check-own-socket}. @code{scdaemon-program} is also
	supported but due to the current implementation, which calls the
	scdaemon only once, it is not of much use unless you manually kill the
	scdaemon.


	@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
	@cpindex SIGUSR1
	Dump internal information to the log file.

	@item SIGUSR2
	@cpindex SIGUSR2
	This signal is used for internal purposes.

	@end table

	@c
	@c Examples
	@c
	@mansect examples
	@node Agent Examples
	@section Examples

	It is important to set the environment variable @code{GPG_TTY} in
	your login shell, for example in the @file{~/.bashrc} init script:

	@cartouche
	@example
	export GPG_TTY=$(tty)
	@end example
	@end cartouche

	If you enabled the Ssh Agent Support, you also need to tell ssh about
	it by adding this to your init script:

	@cartouche
	@example
	unset SSH_AGENT_PID
	if [ "$@{gnupg_SSH_AUTH_SOCK_by:-0@}" -ne $$ ]; then
	export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
	fi
	@end example
	@end cartouche


	@c
	@c Assuan Protocol
	@c
	@manpause
	@node Agent Protocol
	@section Agent's Assuan Protocol

	Note: this section does only document the protocol, which is used by
	GnuPG components; it does not deal with the ssh-agent protocol. To
	see the full specification of each command, use

	@example
	gpg-connect-agent 'help COMMAND' /bye
	@end example

	@noindent
	or just 'help' to list all available commands.

	@noindent
	The @command{gpg-agent} daemon is started on demand by the GnuPG
	components.

	To identify a key we use a thing called keygrip which is the SHA-1 hash
	of an canonical encoded S-Expression of 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.

	The @command{gpg-agent} may send status messages during a command or when
	returning from a command to inform a client about the progress or result of an
	operation. For example, the @var{INQUIRE_MAXLEN} status message may be sent
	during a server inquire to inform the client of the maximum usable length of
	the inquired data (which should not be exceeded).

	@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 CLEAR_PASSPHRASE:: Expire a cached passphrase
	* Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip
	* Agent GET_CONFIRMATION:: Ask for confirmation
	* Agent HAVEKEY:: Check whether a key is available
	* Agent LEARN:: Register a smartcard
	* Agent PASSWD:: Change a Passphrase
	* Agent UPDATESTARTUPTTY:: Change the Standard Display
	* Agent GETEVENTCOUNTER:: Get the Event Counters
	* Agent GETINFO:: Return information about the process
	* Agent OPTION:: Set options for the session
	@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, @command{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:
	@cartouche
	@smallexample
	C: PKDECRYPT
	S: INQUIRE CIPHERTEXT
	C: D (enc-val elg (a 349324324)
	C: D (b 3F444677CA)))
	C: END
	S: # session key follows
	S: S PADDING 0
	S: D (value 1234567890ABCDEF0)
	S: OK decryption successful
	@end smallexample
	@end cartouche

	The “PADDING” status line is only send if gpg-agent can tell what kind
	of padding is used. As of now only the value 0 is used to indicate
	that the padding has been removed.


	@node Agent PKSIGN
	@subsection Signing a Hash

	The client asks 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
	tests whether the key is a valid key to sign something and responds with
	okay.

	@example
	SETHASH --hash=<name>\|<algo> <hexstring>
	@end example

	The client can use this command to tell the server about the data <hexstring>
	(which usually is a hash) to be signed. <algo> is the decimal encoded hash
	algorithm number as used by Libgcrypt. Either <algo> or --hash=<name>
	must be given. Valid names for <name> are:

	@table @code
	@item sha1
	The SHA-1 hash algorithm
	@item sha256
	The SHA-256 hash algorithm
	@item rmd160
	The RIPE-MD160 hash algorithm
	@item md5
	The old and broken MD5 hash algorithm
	@item tls-md5sha1
	A combined hash algorithm as used by the TLS protocol.
	@end table

	@noindent
	The actual signing is done using

	@example
	PKSIGN <options>
	@end example

	Options are not yet defined, but may later be used to choose among
	different algorithms. The agent does then some checks, asks for the
	passphrase and as a result the server returns the signature as an SPKI
	like S-expression 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 @command{gpg-agent} to ignore the passphrase cache. Note, that there is
	also a global command line option for @command{gpg-agent} to globally disable the
	caching.


	Here is an example session:
	@cartouche
	@smallexample
	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 smallexample
	@end cartouche

	@node Agent GENKEY
	@subsection Generating a Key

	This is used to create a new keypair and store the secret key inside the
	active PSE --- which is in most cases a Soft-PSE. A not-yet-defined
	option allows choosing the storage location. To get the secret key out
	of the PSE, a special export tool has to be used.

	@example
	GENKEY [--no-protection] [--preset] [<cache_nonce>]
	@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:
	@cartouche
	@smallexample
	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 smallexample
	@end cartouche

	The @option{--no-protection} option may be used to prevent prompting for a
	passphrase to protect the secret key while leaving the secret key unprotected.
	The @option{--preset} option may be used to add the passphrase to the cache
	using the default cache parameters.

	The @option{--inq-passwd} option may be used to create the key with a
	supplied passphrase. When used the agent does an inquiry with the
	keyword @code{NEWPASSWD} to retrieve that passphrase. This option
	takes precedence over @option{--no-protection}; however if the client
	sends a empty (zero-length) passphrase, this is identical to
	@option{--no-protection}.

	@node Agent IMPORT
	@subsection Importing a Secret Key

	This operation is not yet supported 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 ourselves, 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 description:

	@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
	fingerprints 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
	symmetric 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 [--data] [--check] [--no-ask] [--repeat[=N]] \
	[--qualitybar] @var{cache_id} \
	[@var{error_message} @var{prompt} @var{description}]
	@end example

	@var{cache_id} is expected to be a string used to identify a cached
	passphrase. Use a @code{X} to bypass the cache. With no other
	arguments the agent returns a cached passphrase or an error. By
	convention either the hexified fingerprint of the key shall be used for
	@var{cache_id} or an arbitrary string prefixed with the name of the
	calling application and a colon: Like @code{gpg:somestring}.

	@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. If the option
	@option{--data} is used, the passphrase is not returned on the OK line
	but by regular data lines; this is the preferred method.

	If the option @option{--check} is used, the standard passphrase
	constraints checks are applied. A check is not done if the passphrase
	has been found in the cache.

	If the option @option{--no-ask} is used and the passphrase is not in the
	cache the user will not be asked to enter a passphrase but the error
	code @code{GPG_ERR_NO_DATA} is returned.

	If the option @option{--qualitybar} is used and a minimum passphrase
	length has been configured, a visual indication of the entered
	passphrase quality is shown.

	@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 CLEAR_PASSPHRASE
	@subsection Remove a cached passphrase

	Use this command to remove a cached passphrase.

	@example
	CLEAR_PASSPHRASE [--mode=normal] <cache_id>
	@end example

	The @option{--mode=normal} option can be used to clear a @var{cache_id} that
	was set by gpg-agent.


	@node Agent PRESET_PASSPHRASE
	@subsection Set a passphrase for a keygrip

	This command adds a passphrase to the cache for the specified @var{keygrip}.

	@example
	PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
	@end example

	The passphrase is a hexidecimal string when specified. When not specified, the
	passphrase will be retrieved from the pinentry module unless the
	@option{--inquire} option was specified in which case the passphrase will be
	retrieved from the client.

	The @var{timeout} parameter keeps the passphrase cached for the specified
	number of seconds. A value of @code{-1} means infinite while @code{0} means
	the default (currently only a timeout of -1 is allowed, which means to never
	expire it).


	@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 buttons: 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{keygrips}
	@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. More than one
	keygrip may be given. In this case the command returns success if at
	least one of the keygrips corresponds to an available secret key.


	@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 sent back.


	@node Agent PASSWD
	@subsection Change a Passphrase

	@example
	PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] @var{keygrip}
	@end example

	This command is used to interactively change the passphrase of the key
	identified by the hex string @var{keygrip}. The @option{--preset}
	option may be used to add the new passphrase to the cache using the
	default cache parameters.


	@node Agent UPDATESTARTUPTTY
	@subsection Change the standard display

	@example
	UPDATESTARTUPTTY
	@end example

	Set the startup TTY and X-DISPLAY variables to the values of this
	session. This command is useful to direct future pinentry invocations
	to another screen. It is only required because there is no way in the
	ssh-agent protocol to convey this information.


	@node Agent GETEVENTCOUNTER
	@subsection Get the Event Counters

	@example
	GETEVENTCOUNTER
	@end example

	This function return one status line with the current values of the
	event counters. The event counters are useful to avoid polling by
	delaying a poll until something has changed. The values are decimal
	numbers in the range @code{0} to @code{UINT_MAX} and wrapping around to
	0. The actual values should not be relied upon; they shall only be used
	to detect a change.

	The currently defined counters are are:
	@table @code
	@item ANY
	Incremented with any change of any of the other counters.
	@item KEY
	Incremented for added or removed private keys.
	@item CARD
	Incremented for changes of the card readers stati.
	@end table

	@node Agent GETINFO
	@subsection Return information about the process

	This is a multipurpose function to return a variety of information.

	@example
	GETINFO @var{what}
	@end example

	The value of @var{what} specifies the kind of information returned:
	@table @code
	@item version
	Return the version of the program.
	@item pid
	Return the process id of the process.
	@item socket_name
	Return the name of the socket used to connect the agent.
	@item ssh_socket_name
	Return the name of the socket used for SSH connections. If SSH support
	has not been enabled the error @code{GPG_ERR_NO_DATA} will be returned.
	@end table

	@node Agent OPTION
	@subsection Set options for the session

	Here is a list of session options which are not yet described with
	other commands. The general syntax for an Assuan option is:

	@smallexample
	OPTION @var{key}=@var{value}
	@end smallexample

	@noindent
	Supported @var{key}s are:

	@table @code
	@item agent-awareness
	This may be used to tell gpg-agent of which gpg-agent version the
	client is aware of. gpg-agent uses this information to enable
	features which might break older clients.

	@item putenv
	Change the session's environment to be used for the
	Pinentry. Valid values are:

	@table @code
	@item @var{name}
	Delete envvar @var{name}
	@item @var{name}=
	Set envvar @var{name} to the empty string
	@item @var{name}=@var{value}
	Set envvar @var{name} to the string @var{value}.
	@end table

	@item use-cache-for-signing
	See Assuan command @code{PKSIGN}.

	@item allow-pinentry-notify
	This does not need any value. It is used to enable the
	PINENTRY_LAUNCHED inquiry.

	@item pinentry-mode
	This option is used to change the operation mode of the pinentry. The
	following values are defined:

	@table @code
	@item ask
	This is the default mode which pops up a pinentry as needed.

	@item cancel
	Instead of popping up a pinentry, return the error code
	@code{GPG_ERR_CANCELED}.

	@item error
	Instead of popping up a pinentry, return the error code
	@code{GPG_ERR_NO_PIN_ENTRY}.

	@item loopback
	Use a loopback pinentry. This fakes a pinentry by using inquiries
	back to the caller to ask for a passphrase. This option may only be
	set if the agent has been configured for that.
	To disable this feature use @ref{option --no-allow-loopback-pinentry}.
	@end table

	@item cache-ttl-opt-preset
	This option sets the cache TTL for new entries created by GENKEY and
	PASSWD commands when using the @option{--preset} option. It it is not
	used a default value is used.

	@item s2k-count
	Instead of using the standard S2K count (which is computed on the
	fly), the given S2K count is used for new keys or when changing the
	passphrase of a key. Values below 65536 are considered to be 0. This
	option is valid for the entire session or until reset to 0. This
	option is useful if the key is later used on boxes which are either
	much slower or faster than the actual box.

	@end table


	@mansect see also
	@ifset isman
	@command{gpg2}(1),
	@command{gpgsm}(1),
	@command{gpg-connect-agent}(1),
	@command{scdaemon}(1)
	@end ifset
	@include see-also-note.texi
	diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi
	index 3ab44ae9b..3728d9622 100644
	--- a/doc/scdaemon.texi
	+++ b/doc/scdaemon.texi
	@@ -1,765 +1,765 @@
	@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.

	@include defs.inc

	@node Invoking SCDAEMON
	@chapter Invoking the SCDAEMON
	@cindex SCDAEMON command options
	@cindex command options
	@cindex options, SCDAEMON command

	@manpage scdaemon.1
	@ifset manverb
	.B scdaemon
	\- Smartcard daemon for the GnuPG system
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B scdaemon
	.RB [ \-\-homedir
	.IR dir ]
	.RB [ \-\-options
	.IR file ]
	.RI [ options ]
	.B \-\-server
	.br
	.B scdaemon
	.RB [ \-\-homedir
	.IR dir ]
	.RB [ \-\-options
	.IR file ]
	.RI [ options ]
	.B \-\-daemon
	.RI [ command_line ]
	@end ifset


	@mansect description
	The @command{scdaemon} is a daemon to manage smartcards. It is usually
	invoked by @command{gpg-agent} and in general not used directly.

	@manpause
	@xref{Option Index}, for an index to @command{scdaemon}'s commands and
	options.
	@mancont

	@menu
	* Scdaemon Commands:: List of all commands.
	* Scdaemon Options:: List of all options.
	* Card applications:: Description of card applications.
	* Scdaemon Configuration:: Configuration files.
	* Scdaemon Examples:: Some usage examples.
	* Scdaemon Protocol:: The protocol the daemon uses.
	@end menu

	@mansect commands

	@node Scdaemon Commands
	@section Commands

	Commands are not distinguished from options except for the fact that
	only one command is allowed.

	@table @gnupgtabopt
	@item --version
	@opindex version
	Print the program version and licensing information. Note that you cannot
	abbreviate this command.

	@item --help, -h
	@opindex help
	Print a usage message summarizing the most useful command-line options.
	Note that you can abbreviate this command.

	@item --dump-options
	@opindex dump-options
	Print a list of all available options and commands. Note that you cannot
	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 --multi-server
	@opindex multi-server
	Run in server mode and wait for commands on the @code{stdin} as well as
	on an additional Unix Domain socket. The server command @code{GETINFO}
	may be used to get the name of that extra socket.

	@item --daemon
	@opindex daemon
	Run the program in the background. This option is required to prevent
	it from being accidentally running in the background.

	@end table


	@mansect 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.

	@include opt-homedir.texi


	@item -v
	@item --verbose
	@opindex v
	@opindex verbose
	Outputs additional information while running.
	You can increase the verbosity by giving several
	verbose commands to @command{gpgsm}, such as @samp{-vv}.

	@item --debug-level @var{level}
	@opindex debug-level
	Select the debug level for investigating problems. @var{level} may be
	a numeric value or a keyword:

	@table @code
	@item none
	No debugging at all. A value of less than 1 may be used instead of
	the keyword.
	@item basic
	Some basic debug messages. A value between 1 and 2 may be used
	instead of the keyword.
	@item advanced
	More verbose debug messages. A value between 3 and 5 may be used
	instead of the keyword.
	@item expert
	Even more detailed messages. A value between 6 and 8 may be used
	instead of the keyword.
	@item guru
	All of the debug messages you can get. A value greater than 8 may be
	used instead of the keyword. The creation of hash tracing files is
	only enabled if the keyword is used.
	@end table

	How these messages are mapped to the actual debugging flags is not
	specified and may change with newer releases of this program. They are
	however carefully selected to best aid in debugging.

	@quotation Note
	All debugging options are subject to change and thus should not be used
	by any application program. As the name says, they are only used as
	helpers to debug problems.
	@end quotation


	@item --debug @var{flags}
	@opindex debug
	-This option is only useful for debugging and the behaviour may change at
	+This option is only useful for debugging and the behavior 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)
	command I/O
	@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.
	See also option @option{--debug-assuan-log-cats}.
	@item 11 (2048)
	trace APDU I/O to the card. This may reveal sensitive data.
	@item 12 (4096)
	trace some card reader related function calls.
	@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-ccid-driver
	@opindex debug-wait
	Enable debug output from the included CCID driver for smartcards.
	Using this option twice will also enable some tracing of the T=1
	protocol. Note that this option may reveal sensitive data.

	@item --debug-disable-ticker
	@opindex debug-disable-ticker
	This option disables all ticker functions like checking for card
	insertions.

	@item --debug-allow-core-dump
	@opindex debug-allow-core-dump
	For security reasons we won't create a core dump when the process
	aborts. For debugging purposes it is sometimes better to allow core
	dump. This option enables it and also changes the working directory to
	@file{/tmp} when running in @option{--server} mode.

	@item --debug-log-tid
	@opindex debug-log-tid
	This option appends a thread ID to the PID in the log output.

	@item --debug-assuan-log-cats @var{cats}
	@opindex debug-assuan-log-cats
	@efindex ASSUAN_DEBUG
	Changes the active Libassuan logging categories to @var{cats}. The
	value for @var{cats} is an unsigned integer given in usual C-Syntax.
	A value of of 0 switches to a default category. If this option is not
	used the categories are taken from the environment variable
	@code{ASSUAN_DEBUG}. Note that this option has only an effect if the
	Assuan debug flag has also been with the option @option{--debug}. For
	a list of categories see the Libassuan manual.

	@item --no-detach
	@opindex no-detach
	Don't detach the process from the console. This is mainly useful 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. Use @file{socket://} to log to
	socket.


	@item --pcsc-driver @var{library}
	@opindex pcsc-driver
	Use @var{library} to access the smartcard reader. The current default
	is @file{libpcsclite.so}. Instead of using this option you might also
	want to install a symbolic link to the default file name
	(e.g. from @file{libpcsclite.so.1}).

	@item --ctapi-driver @var{library}
	@opindex ctapi-driver
	Use @var{library} to access the smartcard reader. The current default
	is @file{libtowitoko.so}. Note that the use of this interface is
	deprecated; it may be removed in future releases.

	@item --disable-ccid
	@opindex disable-ccid
	Disable the integrated support for CCID compliant readers. This
	allows falling back to one of the other drivers even if the internal
	CCID driver can handle the reader. Note, that CCID support is only
	available if libusb was available at build time.

	@item --reader-port @var{number_or_string}
	@opindex reader-port
	This option may 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). PC/SC or CCID
	readers might need a string here; run the program in verbose mode to get
	a list of available readers. The default is then the first reader
	found.

	To get a list of available CCID readers you may use this command:
	@cartouche
	@smallexample
	echo scd getinfo reader_list \
	\| gpg-connect-agent --decode \| awk '/^D/ @{print $2@}'
	@end smallexample
	@end cartouche

	@item --card-timeout @var{n}
	@opindex card-timeout
	If @var{n} is not 0 and no client is actively using the card, the card
	will be powered down after @var{n} seconds. Powering down the card
	avoids a potential risk of damaging a card when used with certain
	cheap readers. This also allows applications that are not aware of
	Scdaemon to access the card. The disadvantage of using a card timeout
	is that accessing the card takes longer and that the user needs to
	enter the PIN again after the next power up.

	Note that with the current version of Scdaemon the card is powered
	down immediately at the next timer tick for any value of @var{n} other
	than 0.

	@item --enable-pinpad-varlen
	@opindex enable-pinpad-varlen
	Please specify this option when the card reader supports variable
	length input for pinpad (default is no). For known readers (listed in
	ccid-driver.c and apdu.c), this option is not needed. Note that if
	your card reader doesn't supports variable length input but you want
	to use it, you need to specify your pinpad request on your card.


	@item --disable-pinpad
	@opindex disable-pinpad
	Even if a card reader features a pinpad, do not try to use it.


	@item --deny-admin
	@opindex deny-admin
	@opindex allow-admin
	This option disables the use of admin class commands for card
	applications where this is supported. Currently we support it for the
	OpenPGP card. This commands is useful to inhibit accidental access to
	admin class command which could ultimately lock the card through wrong
	PIN numbers. Note that GnuPG versions older than 2.0.11 featured an
	@option{--allow-admin} command which was required to use such admin
	commands. This option has no more effect today because the default is
	now to allow admin commands.

	@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.


	@mansect card applications
	@node Card applications
	@section Description of card applications

	@command{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
	* Geldkarte Card:: The Geldkarte application
	* SmartCard-HSM:: The SmartCard-HSM application
	* Undefined Card:: The Undefined stub application
	@end menu

	@node OpenPGP Card
	@subsection The OpenPGP card application ``openpgp''

	This application is currently only used by @command{gpg} but may in
	future also be useful with @command{gpgsm}. Version 1 and version 2 of
	the card is supported.

	@noindent
	The specifications for these cards are available at@*
	@uref{http://g10code.com/docs/openpgp-card-1.0.pdf} and@*
	@uref{http://g10code.com/docs/openpgp-card-2.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 @command{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 supporting
	the German signature law and its bylaws (SigG and SigV).

	@node PKCS#15 Card
	@subsection The PKCS#15 card application ``p15''

	This is common framework for smart card applications. It is used by
	@command{gpgsm}.

	@node Geldkarte Card
	@subsection The Geldkarte card application ``geldkarte''

	This is a simple application to display information of a German
	Geldkarte. The Geldkarte is a small amount debit card application which
	comes with almost all German banking cards.

	@node SmartCard-HSM
	@subsection The SmartCard-HSM card application ``sc-hsm''

	This application adds read-only support for keys and certificates
	stored on a @uref{http://www.smartcard-hsm.com, SmartCard-HSM}.

	To generate keys and store certifiates you may use
	@uref{https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM, OpenSC} or
	the tools from @uref{http://www.openscdp.org, OpenSCDP}.

	The SmartCard-HSM cards requires a card reader that supports Extended
	Length APDUs.

	@node Undefined Card
	@subsection The Undefined card application ``undefined''

	This is a stub application to allow the use of the APDU command even
	if no supported application is found on the card. This application is
	not used automatically but must be explicitly requested using the
	SERIALNO command.


	@c *******************************************
	@c ************* **************
	@c ************* FILES **************
	@c ************* **************
	@c *******************************************
	@mansect files
	@node Scdaemon Configuration
	@section Configuration files

	There are a few configuration files to control certain aspects of
	@command{scdaemons}'s operation. Unless noted, they are expected in the
	current home directory (@pxref{option --homedir}).

	@table @file

	@item scdaemon.conf
	@cindex scdaemon.conf
	This is the standard configuration file read by @command{scdaemon} on
	startup. It may contain any valid long option; the leading two dashes
	may not be entered and the option may not be abbreviated. This default
	name may be changed on the command line (@pxref{option --options}).

	@item scd-event
	@cindex scd-event
	If this file is present and executable, it will be called on every card
	reader's status change. An example of this script is provided with the
	distribution

	@item reader_@var{n}.status
	This file is created by @command{scdaemon} to let other applications now
	about reader status changes. Its use is now deprecated in favor of
	@file{scd-event}.

	@end table


	@c
	@c Examples
	@c
	@mansect examples
	@node Scdaemon Examples
	@section Examples

	@c man begin EXAMPLES

	@example
	$ scdaemon --server -v
	@end example

	@c man end

	@c
	@c Assuan Protocol
	@c
	@manpause
	@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 except 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{@value{LOCALRUNDIR}/scdaemon/socket}, configuration information
	is read from @var{@value{SYSCONFDIR}/scdaemon.conf}

	Each connection acts as one session, SC-Daemon takes care of
	synchronizing 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 WRITEKEY:: Write a key to a card.
	* Scdaemon GENKEY:: Generate a new key on-card.
	* Scdaemon RANDOM:: Return random bytes generated on-card.
	* Scdaemon PASSWD:: Change PINs.
	* Scdaemon CHECKPIN:: Perform a VERIFY operation.
	* Scdaemon RESTART:: Restart connection
	* Scdaemon APDU:: Send a verbatim APDU to the card
	@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 response 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}\|@var{keyid}
	@end example

	This function is used to read a certificate identified by
	@var{hexified_certid} from the card. With OpenPGP cards the keyid
	@code{OpenPGP.3} may be used to read the certificate of version 2 cards.


	@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 @command{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}. If another
	hash algorithm than SHA-1 is used, that algorithm may be given like:

	@example
	PKSIGN --hash=@var{algoname} @var{keyid}
	@end example

	With @var{algoname} are one of @code{sha1}, @code{rmd160} or @code{md5}.


	@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 @command{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.

	If the card is aware of the apdding format a status line with padding
	information is send before the plaintext data. The key for this
	status line is @code{PADDING} with the only defined value being 0 and
	meaning padding has been removed.

	@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 WRITEKEY
	@subsection Write a key to a card.

	@example
	WRITEKEY [--force] @var{keyid}
	@end example

	This command is used to store a secret key on a smartcard. The
	allowed keyids depend on the currently selected smartcard
	application. The actual keydata is requested using the inquiry
	@code{KEYDATA} and need to be provided without any protection. With
	@option{--force} set an existing key under this @var{keyid} will get
	overwritten. The key data is expected to be the usual canonical encoded
	S-expression.

	A PIN will be requested in most cases. This however depends on the
	actual card application.


	@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.

	@example
	PASSWD [--reset] [--nullpin] @var{chvno}
	@end example

	Change the PIN or reset the retry counter of the card holder
	verification vector number @var{chvno}. The option @option{--nullpin}
	is used to initialize the PIN of TCOS cards (6 byte NullPIN only).


	@node Scdaemon CHECKPIN
	@subsection Perform a VERIFY operation.

	@example
	CHECKPIN @var{idstr}
	@end example

	Perform a VERIFY operation without doing anything else. This may be
	used to initialize a the PIN cache earlier to long lasting
	operations. Its use is highly application dependent:

	@table @strong
	@item OpenPGP

	Perform a simple verify operation for CHV1 and CHV2, so that further
	operations won't ask for CHV2 and it is possible to do a cheap check on
	the PIN: If there is something wrong with the PIN entry system, only the
	regular CHV will get blocked and not the dangerous CHV3. @var{idstr} is
	the usual card's serial number in hex notation; an optional fingerprint
	part will get ignored.

	There is however a special mode if @var{idstr} is suffixed with the
	literal string @code{[CHV3]}: In this case the Admin PIN is checked if
	and only if the retry counter is still at 3.

	@end table



	@node Scdaemon RESTART
	@subsection Perform a RESTART operation.

	@example
	RESTART
	@end example

	Restart the current connection; this is a kind of warm reset. It
	deletes the context used by this connection but does not actually
	reset the card.

	This is used by gpg-agent to reuse a primary pipe connection and
	may be used by clients to backup from a conflict in the serial
	command; i.e. to select another application.




	@node Scdaemon APDU
	@subsection Send a verbatim APDU to the card.

	@example
	APDU [--atr] [--more] [--exlen[=@var{n}]] [@var{hexstring}]
	@end example


	Send an APDU to the current reader. This command bypasses the high
	level functions and sends the data directly to the card.
	@var{hexstring} is expected to be a proper APDU. If @var{hexstring} is
	not given no commands are send to the card; However the command will
	implicitly check whether the card is ready for use.

	Using the option @code{--atr} returns the ATR of the card as a status
	message before any data like this:
	@example
	S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1
	@end example

	Using the option @code{--more} handles the card status word MORE_DATA
	(61xx) and concatenate all responses to one block.

	Using the option @code{--exlen} the returned APDU may use extended
	length up to N bytes. If N is not given a default value is used
	(currently 4096).



	@mansect see also
	@ifset isman
	@command{gpg-agent}(1),
	@command{gpgsm}(1),
	@command{gpg2}(1)
	@end ifset
	@include see-also-note.texi

	diff --git a/doc/tools.texi b/doc/tools.texi
	index d6e130f17..1cb992eb1 100644
	--- a/doc/tools.texi
	+++ b/doc/tools.texi
	@@ -1,1910 +1,1910 @@
	@c Copyright (C) 2004, 2008 Free Software Foundation, Inc.
	@c This is part of the GnuPG manual.
	@c For copying conditions, see the file GnuPG.texi.

	@include defs.inc

	@node Helper Tools
	@chapter Helper Tools

	GnuPG comes with a couple of smaller tools:

	@menu
	* watchgnupg:: Read logs from a socket.
	* gpgv:: Verify OpenPGP signatures.
	* addgnupghome:: Create .gnupg home directories.
	* gpgconf:: Modify .gnupg home directories.
	* applygnupgdefaults:: Run gpgconf for all users.
	* gpg-preset-passphrase:: Put a passphrase into the cache.
	* gpg-connect-agent:: Communicate with a running agent.
	* dirmngr-client:: How to use the Dirmngr client tool.
	* gpgparsemail:: Parse a mail message into an annotated format
	* symcryptrun:: Call a simple symmetric encryption tool.
	* gpg-zip:: Encrypt or sign files into an archive.
	@end menu

	@c
	@c WATCHGNUPG
	@c
	@manpage watchgnupg.1
	@node watchgnupg
	@section Read logs from a socket
	@ifset manverb
	.B watchgnupg
	\- Read and print logs from a socket
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B watchgnupg
	.RB [ \-\-force ]
	.RB [ \-\-verbose ]
	.I socketname
	@end ifset

	@mansect description
	Most of the main utilities are able to write their log files to a Unix
	Domain socket if configured that way. @command{watchgnupg} is a simple
	listener for such a socket. It ameliorates the output with a time stamp
	and makes sure that long lines are not interspersed with log output from
	other utilities. This tool is not available for Windows.


	@noindent
	@command{watchgnupg} is commonly invoked as

	@example
	watchgnupg --force ~/.gnupg/S.log
	@end example
	@manpause

	@noindent
	This starts it on the current terminal for listening on the socket
	@file{~/.gnupg/S.log}.

	@mansect options
	@noindent
	@command{watchgnupg} understands these options:

	@table @gnupgtabopt

	@item --force
	@opindex force
	Delete an already existing socket file.

	@anchor{option watchgnupg --tcp}
	@item --tcp @var{n}
	Instead of reading from a local socket, listen for connects on TCP port
	@var{n}.

	@item --verbose
	@opindex verbose
	Enable extra informational output.

	@item --version
	@opindex version
	Print version of the program and exit.

	@item --help
	@opindex help
	Display a brief help page and exit.

	@end table

	@noindent
	@mansect examples
	@chapheading Examples

	@example
	$ watchgnupg --force /home/foo/.gnupg/S.log
	@end example

	This waits for connections on the local socket
	@file{/home/foo/.gnupg/S.log} and shows all log entries. To make this
	work the option @option{log-file} needs to be used with all modules
	which logs are to be shown. The value for that option must be given
	with a special prefix (e.g. in the conf files):

	@example
	log-file socket:///home/foo/.gnupg/S.log
	@end example

	If only @code{socket://} is used a default socket file named
	@file{S.log} in the standard socket directory is used.
	For debugging purposes it is also possible to do remote logging. Take
	care if you use this feature because the information is send in the
	clear over the network. Use this syntax in the conf files:

	@example
	log-file tcp://192.168.1.1:4711
	@end example

	You may use any port and not just 4711 as shown above; only IP addresses
	are supported (v4 and v6) and no host names. You need to start
	@command{watchgnupg} with the @option{tcp} option. Note that under
	Windows the registry entry @var{HKCU\Software\GNU\GnuPG:DefaultLogFile}
	can be used to change the default log output from @code{stderr} to
	whatever is given by that entry. However the only useful entry is a TCP
	name for remote debugging.


	@mansect see also
	@ifset isman
	@command{gpg}(1),
	@command{gpgsm}(1),
	@command{gpg-agent}(1),
	@command{scdaemon}(1)
	@end ifset
	@include see-also-note.texi


	@c
	@c GPGV
	@c
	@include gpgv.texi


	@c
	@c ADDGNUPGHOME
	@c
	@manpage addgnupghome.8
	@node addgnupghome
	@section Create .gnupg home directories.
	@ifset manverb
	.B addgnupghome
	\- Create .gnupg home directories
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B addgnupghome
	.I account_1
	.IR account_2 ... account_n
	@end ifset

	@mansect description
	If GnuPG is installed on a system with existing user accounts, it is
	sometimes required to populate the GnuPG home directory with existing
	files. Especially a @file{trustlist.txt} and a keybox with some
	initial certificates are often desired. This script helps to do this
	by copying all files from @file{/etc/skel/.gnupg} to the home
	directories of the accounts given on the command line. It takes care
	not to overwrite existing GnuPG home directories.

	@noindent
	@command{addgnupghome} is invoked by root as:

	@example
	addgnupghome account1 account2 ... accountn
	@end example


	@c
	@c GPGCONF
	@c
	@manpage gpgconf.1
	@node gpgconf
	@section Modify .gnupg home directories.
	@ifset manverb
	.B gpgconf
	\- Modify .gnupg home directories
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B gpgconf
	.RI [ options ]
	.B \-\-list-components
	.br
	.B gpgconf
	.RI [ options ]
	.B \-\-list-options
	.I component
	.br
	.B gpgconf
	.RI [ options ]
	.B \-\-change-options
	.I component
	@end ifset


	@mansect description
	The @command{gpgconf} is a utility to automatically and reasonable
	safely query and modify configuration files in the @file{.gnupg} home
	directory. It is designed not to be invoked manually by the user, but
	automatically by graphical user interfaces (GUI).@footnote{Please note
	that currently no locking is done, so concurrent access should be
	avoided. There are some precautions to avoid corruption with
	concurrent usage, but results may be inconsistent and some changes may
	get lost. The stateless design makes it difficult to provide more
	guarantees.}

	@command{gpgconf} provides access to the configuration of one or more
	components of the GnuPG system. These components correspond more or
	less to the programs that exist in the GnuPG framework, like GnuPG,
	GPGSM, DirMngr, etc. But this is not a strict one-to-one
	relationship. Not all configuration options are available through
	@command{gpgconf}. @command{gpgconf} provides a generic and abstract
	method to access the most important configuration options that can
	feasibly be controlled via such a mechanism.

	@command{gpgconf} can be used to gather and change the options
	available in each component, and can also provide their default
	values. @command{gpgconf} will give detailed type information that
	can be used to restrict the user's input without making an attempt to
	commit the changes.

	@command{gpgconf} provides the backend of a configuration editor. The
	configuration editor would usually be a graphical user interface
	program that displays the current options, their default
	values, and allows the user to make changes to the options. These
	changes can then be made active with @command{gpgconf} again. Such a
	program that uses @command{gpgconf} in this way will be called GUI
	throughout this section.

	@menu
	* Invoking gpgconf:: List of all commands and options.
	* Format conventions:: Formatting conventions relevant for all commands.
	* Listing components:: List all gpgconf components.
	* Checking programs:: Check all programs known to gpgconf.
	* Listing options:: List all options of a component.
	* Changing options:: Changing options of a component.
	* Listing global options:: List all global options.
	* Files used by gpgconf:: What files are used by gpgconf.
	@end menu

	@manpause
	@node Invoking gpgconf
	@subsection Invoking gpgconf

	@mansect commands
	One of the following commands must be given:

	@table @gnupgtabopt

	@item --list-components
	List all components. This is the default command used if none is
	specified.

	@item --check-programs
	List all available backend programs and test whether they are runnable.

	@item --list-options @var{component}
	List all options of the component @var{component}.

	@item --change-options @var{component}
	Change the options of the component @var{component}.

	@item --check-options @var{component}
	Check the options for the component @var{component}.

	@item --apply-defaults
	Update all configuration files with values taken from the global
	configuration file (usually @file{/etc/gnupg/gpgconf.conf}).

	@item --list-dirs [@var{names}]
	Lists the directories used by @command{gpgconf}. One directory is
	listed per line, and each line consists of a colon-separated list where
	the first field names the directory type (for example @code{sysconfdir})
	and the second field contains the percent-escaped directory. Although
	they are not directories, the socket file names used by
	@command{gpg-agent} and @command{dirmngr} are printed as well. Note
	that the socket file names and the @code{homedir} lines are the default
	names and they may be overridden by command line switches. If
	@var{names} are given only the directories or file names specified by
	the list names are printed without any escaping.

	@item --list-config [@var{filename}]
	List the global configuration file in a colon separated format. If
	@var{filename} is given, check that file instead.

	@item --check-config [@var{filename}]
	Run a syntax check on the global configuration file. If @var{filename}
	is given, check that file instead.

	@item --reload [@var{component}]
	@opindex reload
	Reload all or the given component. This is basically the same as sending
	a SIGHUP to the component. Components which don't support reloading are
	ignored.

	@item --launch [@var{component}]
	@opindex launch
	If the @var{component} is not already running, start it.
	@command{component} must be a daemon. This is in general not required
	because the system starts these daemons as needed. However, external
	software making direct use of @command{gpg-agent} or @command{dirmngr}
	may use this command to ensure that they are started.

	@item --kill [@var{component}]
	@opindex kill
	Kill the given component. Components which support killing are
	gpg-agent and scdaemon. Components which don't support reloading are
	ignored. Note that as of now reload and kill have the same effect for
	scdaemon.

	@item --create-socketdir
	@opindex create-socketdir
	Create a directory for sockets below /run/user or /var/run/user. This
	is command is only required if a non default home directory is used
	and the /run based sockets shall be used. For the default home
	directory GnUPG creates a directory on the fly.

	@item --remove-socketdir
	@opindex remove-socketdir
	Remove a directory created with command @option{--create-socketdir}.

	@end table


	@mansect options

	The following options may be used:

	@table @gnupgtabopt

	@item -o @var{file}
	@itemx --output @var{file}
	Write output to @var{file}. Default is to write to stdout.

	@item -v
	@itemx --verbose
	Outputs additional information while running. Specifically, this
	extends numerical field values by human-readable descriptions.

	@item -q
	@itemx --quiet
	@opindex quiet
	Try to be as quiet as possible.

	@item -n
	@itemx --dry-run
	Do not actually change anything. This is currently only implemented
	for @code{--change-options} and can be used for testing purposes.

	@item -r
	@itemx --runtime
	Only used together with @code{--change-options}. If one of the
	modified options can be changed in a running daemon process, signal
	the running daemon to ask it to reparse its configuration file after
	changing.

	This means that the changes will take effect at run-time, as far as
	this is possible. Otherwise, they will take effect at the next start
	of the respective backend programs.
	@manpause
	@end table


	@node Format conventions
	@subsection Format conventions

	Some lines in the output of @command{gpgconf} contain a list of
	colon-separated fields. The following conventions apply:

	@itemize @bullet
	@item
	The GUI program is required to strip off trailing newline and/or
	carriage return characters from the output.

	@item
	@command{gpgconf} will never leave out fields. If a certain version
	provides a certain field, this field will always be present in all
	@command{gpgconf} versions from that time on.

	@item
	Future versions of @command{gpgconf} might append fields to the list.
	New fields will always be separated from the previously last field by
	a colon separator. The GUI should be prepared to parse the last field
	it knows about up until a colon or end of line.

	@item
	Not all fields are defined under all conditions. You are required to
	ignore the content of undefined fields.
	@end itemize

	There are several standard types for the content of a field:

	@table @asis
	@item verbatim
	Some fields contain strings that are not escaped in any way. Such
	fields are described to be used @emph{verbatim}. These fields will
	never contain a colon character (for obvious reasons). No de-escaping
	or other formatting is required to use the field content. This is for
	easy parsing of the output, when it is known that the content can
	never contain any special characters.

	@item percent-escaped
	Some fields contain strings that are described to be
	@emph{percent-escaped}. Such strings need to be de-escaped before
	their content can be presented to the user. A percent-escaped string
	is de-escaped by replacing all occurrences of @code{%XY} by the byte
	that has the hexadecimal value @code{XY}. @code{X} and @code{Y} are
	from the set @code{0-9a-f}.

	-@item localised
	-Some fields contain strings that are described to be @emph{localised}.
	+@item localized
	+Some fields contain strings that are described to be @emph{localized}.
	Such strings are translated to the active language and formatted in
	the active character set.

	@item @w{unsigned number}
	Some fields contain an @emph{unsigned number}. This number will
	always fit into a 32-bit unsigned integer variable. The number may be
	followed by a space, followed by a human readable description of that
	value (if the verbose option is used). You should ignore everything
	in the field that follows the number.

	@item @w{signed number}
	Some fields contain a @emph{signed number}. This number will always
	fit into a 32-bit signed integer variable. The number may be followed
	by a space, followed by a human readable description of that value (if
	the verbose option is used). You should ignore everything in the
	field that follows the number.

	@item @w{boolean value}
	Some fields contain a @emph{boolean value}. This is a number with
	either the value 0 or 1. The number may be followed by a space,
	followed by a human readable description of that value (if the verbose
	option is used). You should ignore everything in the field that follows
	the number; checking just the first character is sufficient in this
	case.

	@item option
	Some fields contain an @emph{option} argument. The format of an
	option argument depends on the type of the option and on some flags:

	@table @asis
	@item no argument
	The simplest case is that the option does not take an argument at all
	(@var{type} @code{0}). Then the option argument is an unsigned number
	that specifies how often the option occurs. If the @code{list} flag
	is not set, then the only valid number is @code{1}. Options that do
	not take an argument never have the @code{default} or @code{optional
	arg} flag set.

	@item number
	If the option takes a number argument (@var{alt-type} is @code{2} or
	@code{3}), and it can only occur once (@code{list} flag is not set),
	then the option argument is either empty (only allowed if the argument
	is optional), or it is a number. A number is a string that begins
	with an optional minus character, followed by one or more digits. The
	number must fit into an integer variable (unsigned or signed,
	depending on @var{alt-type}).

	@item number list
	If the option takes a number argument and it can occur more than once,
	then the option argument is either empty, or it is a comma-separated
	list of numbers as described above.

	@item string
	If the option takes a string argument (@var{alt-type} is 1), and it
	can only occur once (@code{list} flag is not set) then the option
	argument is either empty (only allowed if the argument is optional),
	or it starts with a double quote character (@code{"}) followed by a
	percent-escaped string that is the argument value. Note that there is
	only a leading double quote character, no trailing one. The double
	quote character is only needed to be able to differentiate between no
	value and the empty string as value.

	@item string list
	If the option takes a number argument and it can occur more than once,
	then the option argument is either empty, or it is a comma-separated
	list of string arguments as described above.
	@end table
	@end table

	The active language and character set are currently determined from
	the locale environment of the @command{gpgconf} program.

	@c FIXME: Document the active language and active character set. Allow
	@c to change it via the command line?


	@mansect usage
	@node Listing components
	@subsection Listing components

	The command @code{--list-components} will list all components that can
	be configured with @command{gpgconf}. Usually, one component will
	correspond to one GnuPG-related program and contain the options of
	that program's configuration file that can be modified using
	@command{gpgconf}. However, this is not necessarily the case. A
	component might also be a group of selected options from several
	programs, or contain entirely virtual options that have a special
	effect rather than changing exactly one option in one configuration
	file.

	A component is a set of configuration options that semantically belong
	together. Furthermore, several changes to a component can be made in
	an atomic way with a single operation. The GUI could for example
	provide a menu with one entry for each component, or a window with one
	tabulator sheet per component.

	The command argument @code{--list-components} lists all available
	components, one per line. The format of each line is:

	@code{@var{name}:@var{description}:@var{pgmname}:}

	@table @var
	@item name
	This field contains a name tag of the component. The name tag is used
	to specify the component in all communication with @command{gpgconf}.
	The name tag is to be used @emph{verbatim}. It is thus not in any
	escaped format.

	@item description
	The @emph{string} in this field contains a human-readable description
	of the component. It can be displayed to the user of the GUI for
	informational purposes. It is @emph{percent-escaped} and
	@emph{localized}.

	@item pgmname
	The @emph{string} in this field contains the absolute name of the
	program's file. It can be used to unambiguously invoke that program.
	It is @emph{percent-escaped}.
	@end table

	Example:
	@example
	$ gpgconf --list-components
	gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
	gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
	scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
	gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
	dirmngr:Directory Manager:/usr/local/bin/dirmngr:
	@end example



	@node Checking programs
	@subsection Checking programs

	The command @code{--check-programs} is similar to
	@code{--list-components} but works on backend programs and not on
	components. It runs each program to test whether it is installed and
	runnable. This also includes a syntax check of all config file options
	of the program.

	The command argument @code{--check-programs} lists all available
	programs, one per line. The format of each line is:

	@code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}

	@table @var
	@item name
	This field contains a name tag of the program which is identical to the
	name of the component. The name tag is to be used @emph{verbatim}. It
	is thus not in any escaped format. This field may be empty to indicate
	a continuation of error descriptions for the last name. The description
	and pgmname fields are then also empty.

	@item description
	The @emph{string} in this field contains a human-readable description
	of the component. It can be displayed to the user of the GUI for
	informational purposes. It is @emph{percent-escaped} and
	@emph{localized}.

	@item pgmname
	The @emph{string} in this field contains the absolute name of the
	program's file. It can be used to unambiguously invoke that program.
	It is @emph{percent-escaped}.

	@item avail
	The @emph{boolean value} in this field indicates whether the program is
	installed and runnable.

	@item okay
	The @emph{boolean value} in this field indicates whether the program's
	config file is syntactically okay.

	@item cfgfile
	If an error occurred in the configuration file (as indicated by a false
	value in the field @code{okay}), this field has the name of the failing
	configuration file. It is @emph{percent-escaped}.

	@item line
	If an error occurred in the configuration file, this field has the line
	number of the failing statement in the configuration file.
	It is an @emph{unsigned number}.

	@item error
	If an error occurred in the configuration file, this field has the error
	text of the failing statement in the configuration file. It is
	@emph{percent-escaped} and @emph{localized}.

	@end table

	@noindent
	In the following example the @command{dirmngr} is not runnable and the
	configuration file of @command{scdaemon} is not okay.

	@example
	$ gpgconf --check-programs
	gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
	gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
	scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
	gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
	dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
	@end example

	@noindent
	The command @w{@code{--check-options @var{component}}} will verify the
	configuration file in the same manner as @code{--check-programs}, but
	only for the component @var{component}.


	@node Listing options
	@subsection Listing options

	Every component contains one or more options. Options may be gathered
	into option groups to allow the GUI to give visual hints to the user
	about which options are related.

	The command argument @code{@w{--list-options @var{component}}} lists
	all options (and the groups they belong to) in the component
	@var{component}, one per line. @var{component} must be the string in
	the field @var{name} in the output of the @code{--list-components}
	command.

	There is one line for each option and each group. First come all
	options that are not in any group. Then comes a line describing a
	group. Then come all options that belong into each group. Then comes
	the next group and so on. There does not need to be any group (and in
	this case the output will stop after the last non-grouped option).

	The format of each line is:

	@code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}

	@table @var
	@item name
	This field contains a name tag for the group or option. The name tag
	is used to specify the group or option in all communication with
	@command{gpgconf}. The name tag is to be used @emph{verbatim}. It is
	thus not in any escaped format.

	@item flags
	The flags field contains an @emph{unsigned number}. Its value is the
	OR-wise combination of the following flag values:

	@table @code
	@item group (1)
	If this flag is set, this is a line describing a group and not an
	option.
	@end table

	The following flag values are only defined for options (that is, if
	the @code{group} flag is not used).

	@table @code
	@item optional arg (2)
	If this flag is set, the argument is optional. This is never set for
	@var{type} @code{0} (none) options.

	@item list (4)
	If this flag is set, the option can be given multiple times.

	@item runtime (8)
	If this flag is set, the option can be changed at runtime.

	@item default (16)
	If this flag is set, a default value is available.

	@item default desc (32)
	If this flag is set, a (runtime) default is available. This and the
	@code{default} flag are mutually exclusive.

	@item no arg desc (64)
	If this flag is set, and the @code{optional arg} flag is set, then the
	option has a special meaning if no argument is given.

	@item no change (128)
	If this flag is set, gpgconf ignores requests to change the value. GUI
	frontends should grey out this option. Note, that manual changes of the
	configuration files are still possible.
	@end table

	@item level
	This field is defined for options and for groups. It contains an
	@emph{unsigned number} that specifies the expert level under which
	this group or option should be displayed. The following expert levels
	are defined for options (they have analogous meaning for groups):

	@table @code
	@item basic (0)
	This option should always be offered to the user.

	@item advanced (1)
	This option may be offered to advanced users.

	@item expert (2)
	This option should only be offered to expert users.

	@item invisible (3)
	This option should normally never be displayed, not even to expert
	users.

	@item internal (4)
	This option is for internal use only. Ignore it.
	@end table

	The level of a group will always be the lowest level of all options it
	contains.

	@item description
	This field is defined for options and groups. The @emph{string} in
	this field contains a human-readable description of the option or
	group. It can be displayed to the user of the GUI for informational
	purposes. It is @emph{percent-escaped} and @emph{localized}.

	@item type
	This field is only defined for options. It contains an @emph{unsigned
	number} that specifies the type of the option's argument, if any. The
	following types are defined:

	Basic types:

	@table @code
	@item none (0)
	No argument allowed.

	@item string (1)
	An @emph{unformatted string}.

	@item int32 (2)
	A @emph{signed number}.

	@item uint32 (3)
	An @emph{unsigned number}.
	@end table

	Complex types:

	@table @code
	@item pathname (32)
	A @emph{string} that describes the pathname of a file. The file does
	not necessarily need to exist.

	@item ldap server (33)
	A @emph{string} that describes an LDAP server in the format:

	@code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}

	@item key fingerprint (34)
	A @emph{string} with a 40 digit fingerprint specifying a certificate.

	@item pub key (35)
	A @emph{string} that describes a certificate by user ID, key ID or
	fingerprint.

	@item sec key (36)
	A @emph{string} that describes a certificate with a key by user ID,
	key ID or fingerprint.

	@item alias list (37)
	A @emph{string} that describes an alias list, like the one used with
	gpg's group option. The list consists of a key, an equal sign and space
	separated values.
	@end table

	More types will be added in the future. Please see the @var{alt-type}
	field for information on how to cope with unknown types.

	@item alt-type
	This field is identical to @var{type}, except that only the types
	@code{0} to @code{31} are allowed. The GUI is expected to present the
	user the option in the format specified by @var{type}. But if the
	argument type @var{type} is not supported by the GUI, it can still
	display the option in the more generic basic type @var{alt-type}. The
	GUI must support all the defined basic types to be able to display all
	options. More basic types may be added in future versions. If the
	GUI encounters a basic type it doesn't support, it should report an
	error and abort the operation.

	@item argname
	This field is only defined for options with an argument type
	@var{type} that is not @code{0}. In this case it may contain a
	-@emph{percent-escaped} and @emph{localised string} that gives a short
	+@emph{percent-escaped} and @emph{localized string} that gives a short
	name for the argument. The field may also be empty, though, in which
	case a short name is not known.

	@item default
	This field is defined only for options for which the @code{default} or
	@code{default desc} flag is set. If the @code{default} flag is set,
	its format is that of an @emph{option argument} (@pxref{Format
	conventions}, for details). If the default value is empty, then no
	default is known. Otherwise, the value specifies the default value
	for this option. If the @code{default desc} flag is set, the field is
	either empty or contains a description of the effect if the option is
	not given.

	@item argdef
	This field is defined only for options for which the @code{optional
	arg} flag is set. If the @code{no arg desc} flag is not set, its
	format is that of an @emph{option argument} (@pxref{Format
	conventions}, for details). If the default value is empty, then no
	default is known. Otherwise, the value specifies the default argument
	for this option. If the @code{no arg desc} flag is set, the field is
	either empty or contains a description of the effect of this option if
	no argument is given.

	@item value
	This field is defined only for options. Its format is that of an
	@emph{option argument}. If it is empty, then the option is not
	explicitly set in the current configuration, and the default applies
	(if any). Otherwise, it contains the current value of the option.
	Note that this field is also meaningful if the option itself does not
	take a real argument (in this case, it contains the number of times
	the option appears).
	@end table


	@node Changing options
	@subsection Changing options

	The command @w{@code{--change-options @var{component}}} will attempt
	to change the options of the component @var{component} to the
	specified values. @var{component} must be the string in the field
	@var{name} in the output of the @code{--list-components} command. You
	have to provide the options that shall be changed in the following
	format on standard input:

	@code{@var{name}:@var{flags}:@var{new-value}}

	@table @var
	@item name
	This is the name of the option to change. @var{name} must be the
	string in the field @var{name} in the output of the
	@code{--list-options} command.

	@item flags
	The flags field contains an @emph{unsigned number}. Its value is the
	OR-wise combination of the following flag values:

	@table @code
	@item default (16)
	If this flag is set, the option is deleted and the default value is
	used instead (if applicable).
	@end table

	@item new-value
	The new value for the option. This field is only defined if the
	@code{default} flag is not set. The format is that of an @emph{option
	argument}. If it is empty (or the field is omitted), the default
	argument is used (only allowed if the argument is optional for this
	option). Otherwise, the option will be set to the specified value.
	@end table

	@noindent
	The output of the command is the same as that of
	@code{--check-options} for the modified configuration file.

	Examples:

	To set the force option, which is of basic type @code{none (0)}:

	@example
	$ echo 'force:0:1' \| gpgconf --change-options dirmngr
	@end example

	To delete the force option:

	@example
	$ echo 'force:16:' \| gpgconf --change-options dirmngr
	@end example

	The @code{--runtime} option can influence when the changes take
	effect.


	@node Listing global options
	@subsection Listing global options

	Sometimes it is useful for applications to look at the global options
	file @file{gpgconf.conf}.
	The colon separated listing format is record oriented and uses the first
	field to identify the record type:

	@table @code
	@item k
	This describes a key record to start the definition of a new ruleset for
	a user/group. The format of a key record is:

	@code{k:@var{user}:@var{group}:}

	@table @var
	@item user
	This is the user field of the key. It is percent escaped. See the
	definition of the gpgconf.conf format for details.

	@item group
	This is the group field of the key. It is percent escaped.
	@end table

	@item r
	This describes a rule record. All rule records up to the next key record
	make up a rule set for that key. The format of a rule record is:

	@code{r:::@var{component}:@var{option}:@var{flags}:@var{value}:}

	@table @var
	@item component
	This is the component part of a rule. It is a plain string.

	@item option
	This is the option part of a rule. It is a plain string.

	@item flag
	This is the flags part of a rule. There may be only one flag per rule
	but by using the same component and option, several flags may be
	assigned to an option. It is a plain string.

	@item value
	This is the optional value for the option. It is a percent escaped
	string with a single quotation mark to indicate a string. The quotation
	mark is only required to distinguish between no value specified and an
	empty string.
	@end table

	@end table

	@noindent
	Unknown record types should be ignored. Note that there is intentionally
	no feature to change the global option file through @command{gpgconf}.



	@mansect files
	@node Files used by gpgconf
	@subsection Files used by gpgconf

	@table @file

	@item /etc/gnupg/gpgconf.conf
	@cindex gpgconf.conf
	If this file exists, it is processed as a global configuration file.
	A commented example can be found in the @file{examples} directory of
	the distribution.
	@end table


	@mansect see also
	@ifset isman
	@command{gpg}(1),
	@command{gpgsm}(1),
	@command{gpg-agent}(1),
	@command{scdaemon}(1),
	@command{dirmngr}(1)
	@end ifset
	@include see-also-note.texi



	@c
	@c APPLYGNUPGDEFAULTS
	@c
	@manpage applygnupgdefaults.8
	@node applygnupgdefaults
	@section Run gpgconf for all users.
	@ifset manverb
	.B applygnupgdefaults
	\- Run gpgconf --apply-defaults for all users.
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B applygnupgdefaults
	@end ifset

	@mansect description
	This script is a wrapper around @command{gpgconf} to run it with the
	command @code{--apply-defaults} for all real users with an existing
	GnuPG home directory. Admins might want to use this script to update he
	GnuPG configuration files for all users after
	@file{/etc/gnupg/gpgconf.conf} has been changed. This allows enforcing
	certain policies for all users. Note, that this is not a bulletproof way to
	force a user to use certain options. A user may always directly edit
	the configuration files and bypass gpgconf.

	@noindent
	@command{applygnupgdefaults} is invoked by root as:

	@example
	applygnupgdefaults
	@end example


	@c
	@c GPG-PRESET-PASSPHRASE
	@c
	@node gpg-preset-passphrase
	@section Put a passphrase into the cache.
	@manpage gpg-preset-passphrase.1
	@ifset manverb
	.B gpg-preset-passphrase
	\- Put a passphrase into gpg-agent's cache
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B gpg-preset-passphrase
	.RI [ options ]
	.RI [ command ]
	.I cache-id
	@end ifset

	@mansect description
	The @command{gpg-preset-passphrase} is a utility to seed the internal
	cache of a running @command{gpg-agent} with passphrases. It is mainly
	useful for unattended machines, where the usual @command{pinentry} tool
	may not be used and the passphrases for the to be used keys are given at
	machine startup.

	Passphrases set with this utility don't expire unless the
	@option{--forget} option is used to explicitly clear them from the
	cache --- or @command{gpg-agent} is either restarted or reloaded (by
	sending a SIGHUP to it). Note that the maximum cache time as set with
	@option{--max-cache-ttl} is still honored. It is necessary to allow
	this passphrase presetting by starting @command{gpg-agent} with the
	@option{--allow-preset-passphrase}.

	@menu
	* Invoking gpg-preset-passphrase:: List of all commands and options.
	@end menu

	@manpause
	@node Invoking gpg-preset-passphrase
	@subsection List of all commands and options.
	@mancont

	@noindent
	@command{gpg-preset-passphrase} is invoked this way:

	@example
	gpg-preset-passphrase [options] [command] @var{cacheid}
	@end example

	@var{cacheid} is either a 40 character keygrip of hexadecimal
	characters identifying the key for which the passphrase should be set
	or cleared. The keygrip is listed along with the key when running the
	command: @code{gpgsm --dump-secret-keys}. Alternatively an arbitrary
	string may be used to identify a passphrase; it is suggested that such
	a string is prefixed with the name of the application (e.g
	@code{foo:12346}).

	@noindent
	One of the following command options must be given:

	@table @gnupgtabopt
	@item --preset
	@opindex preset
	Preset a passphrase. This is what you usually will
	use. @command{gpg-preset-passphrase} will then read the passphrase from
	@code{stdin}.

	@item --forget
	@opindex forget
	Flush the passphrase for the given cache ID from the cache.

	@end table

	@noindent
	The following additional options may be used:

	@table @gnupgtabopt
	@item -v
	@itemx --verbose
	@opindex verbose
	Output additional information while running.

	@item -P @var{string}
	@itemx --passphrase @var{string}
	@opindex passphrase
	Instead of reading the passphrase from @code{stdin}, use the supplied
	@var{string} as passphrase. Note that this makes the passphrase visible
	for other users.
	@end table

	@mansect see also
	@ifset isman
	@command{gpg}(1),
	@command{gpgsm}(1),
	@command{gpg-agent}(1),
	@command{scdaemon}(1)
	@end ifset
	@include see-also-note.texi




	@c
	@c GPG-CONNECT-AGENT
	@c
	@node gpg-connect-agent
	@section Communicate with a running agent.
	@manpage gpg-connect-agent.1
	@ifset manverb
	.B gpg-connect-agent
	\- Communicate with a running agent
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B gpg-connect-agent
	.RI [ options ] [commands]
	@end ifset

	@mansect description
	The @command{gpg-connect-agent} is a utility to communicate with a
	running @command{gpg-agent}. It is useful to check out the commands
	gpg-agent provides using the Assuan interface. It might also be useful
	for scripting simple applications. Input is expected at stdin and out
	put gets printed to stdout.

	It is very similar to running @command{gpg-agent} in server mode; but
	here we connect to a running instance.

	@menu
	* Invoking gpg-connect-agent:: List of all options.
	* Controlling gpg-connect-agent:: Control commands.
	@end menu

	@manpause
	@node Invoking gpg-connect-agent
	@subsection List of all options.

	@noindent
	@command{gpg-connect-agent} is invoked this way:

	@example
	gpg-connect-agent [options] [commands]
	@end example
	@mancont

	@noindent
	The following options may be used:

	@table @gnupgtabopt
	@item -v
	@itemx --verbose
	@opindex verbose
	Output additional information while running.

	@item -q
	@item --quiet
	@opindex q
	@opindex quiet
	Try to be as quiet as possible.

	@include opt-homedir.texi

	@item --agent-program @var{file}
	@opindex agent-program
	Specify the agent program to be started if none is running. The
	default value is determined by running @command{gpgconf} with the
	option @option{--list-dirs}. Note that the pipe symbol (@code{\|}) is
	used for a regression test suite hack and may thus not be used in the
	file name.

	@item --dirmngr-program @var{file}
	@opindex dirmngr-program
	Specify the directory manager (keyserver client) program to be started
	if none is running. This has only an effect if used together with the
	option @option{--dirmngr}.

	@item --dirmngr
	@opindex dirmngr
	Connect to a running directory manager (keyserver client) instead of
	to the gpg-agent. If a dirmngr is not running, start it.

	@item -S
	@itemx --raw-socket @var{name}
	@opindex raw-socket
	Connect to socket @var{name} assuming this is an Assuan style server.
	Do not run any special initializations or environment checks. This may
	be used to directly connect to any Assuan style socket server.

	@item -E
	@itemx --exec
	@opindex exec
	Take the rest of the command line as a program and it's arguments and
	execute it as an Assuan server. Here is how you would run @command{gpgsm}:
	@smallexample
	gpg-connect-agent --exec gpgsm --server
	@end smallexample
	Note that you may not use options on the command line in this case.

	@item --no-ext-connect
	@opindex no-ext-connect
	When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
	connects to the Assuan server in extended mode to allow descriptor
	passing. This option makes it use the old mode.

	@item --no-autostart
	@opindex no-autostart
	Do not start the gpg-agent or the dirmngr if it has not yet been
	started.

	@item -r @var{file}
	@itemx --run @var{file}
	@opindex run
	Run the commands from @var{file} at startup and then continue with the
	regular input method. Note, that commands given on the command line are
	executed after this file.

	@item -s
	@itemx --subst
	@opindex subst
	Run the command @code{/subst} at startup.

	@item --hex
	@opindex hex
	Print data lines in a hex format and the ASCII representation of
	non-control characters.

	@item --decode
	@opindex decode
	Decode data lines. That is to remove percent escapes but make sure that
	a new line always starts with a D and a space.

	@end table

	@mansect control commands
	@node Controlling gpg-connect-agent
	@subsection Control commands.

	While reading Assuan commands, gpg-agent also allows a few special
	commands to control its operation. These control commands all start
	with a slash (@code{/}).

	@table @code

	@item /echo @var{args}
	Just print @var{args}.

	@item /let @var{name} @var{value}
	Set the variable @var{name} to @var{value}. Variables are only
	substituted on the input if the @command{/subst} has been used.
	Variables are referenced by prefixing the name with a dollar sign and
	optionally include the name in curly braces. The rules for a valid name
	are identically to those of the standard bourne shell. This is not yet
	enforced but may be in the future. When used with curly braces no
	leading or trailing white space is allowed.

	If a variable is not found, it is searched in the environment and if
	found copied to the table of variables.

	Variable functions are available: The name of the function must be
	followed by at least one space and the at least one argument. The
	following functions are available:

	@table @code
	@item get
	Return a value described by the argument. Available arguments are:

	@table @code
	@item cwd
	The current working directory.
	@item homedir
	The gnupg homedir.
	@item sysconfdir
	GnuPG's system configuration directory.
	@item bindir
	GnuPG's binary directory.
	@item libdir
	GnuPG's library directory.
	@item libexecdir
	GnuPG's library directory for executable files.
	@item datadir
	GnuPG's data directory.
	@item serverpid
	The PID of the current server. Command @command{/serverpid} must
	have been given to return a useful value.
	@end table

	@item unescape @var{args}
	Remove C-style escapes from @var{args}. Note that @code{\0} and
	@code{\x00} terminate the returned string implicitly. The string to be
	converted are the entire arguments right behind the delimiting space of
	the function name.

	@item unpercent @var{args}
	@itemx unpercent+ @var{args}
	Remove percent style escaping from @var{args}. Note that @code{%00}
	terminates the string implicitly. The string to be converted are the
	entire arguments right behind the delimiting space of the function
	name. @code{unpercent+} also maps plus signs to a spaces.

	@item percent @var{args}
	@itemx percent+ @var{args}
	Escape the @var{args} using percent style escaping. Tabs, formfeeds,
	linefeeds, carriage returns and colons are escaped. @code{percent+} also
	maps spaces to plus signs.

	@item errcode @var{arg}
	@itemx errsource @var{arg}
	@itemx errstring @var{arg}
	Assume @var{arg} is an integer and evaluate it using @code{strtol}. Return
	the gpg-error error code, error source or a formatted string with the
	error code and error source.


	@item +
	@itemx -
	@itemx *
	@itemx /
	@itemx %
	Evaluate all arguments as long integers using @code{strtol} and apply
	this operator. A division by zero yields an empty string.

	@item !
	@itemx \|
	@itemx &
	Evaluate all arguments as long integers using @code{strtol} and apply
	the logical operators NOT, OR or AND. The NOT operator works on the
	last argument only.


	@end table


	@item /definq @var{name} @var{var}
	Use content of the variable @var{var} for inquiries with @var{name}.
	@var{name} may be an asterisk (@code{*}) to match any inquiry.


	@item /definqfile @var{name} @var{file}
	Use content of @var{file} for inquiries with @var{name}.
	@var{name} may be an asterisk (@code{*}) to match any inquiry.

	@item /definqprog @var{name} @var{prog}
	Run @var{prog} for inquiries matching @var{name} and pass the
	entire line to it as command line arguments.

	@item /datafile @var{name}
	Write all data lines from the server to the file @var{name}. The file
	is opened for writing and created if it does not exists. An existing
	file is first truncated to 0. The data written to the file fully
	decoded. Using a single dash for @var{name} writes to stdout. The
	file is kept open until a new file is set using this command or this
	command is used without an argument.

	@item /showdef
	Print all definitions

	@item /cleardef
	Delete all definitions

	@item /sendfd @var{file} @var{mode}
	Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
	mode string) and send the file descriptor to the server. This is
	usually followed by a command like @code{INPUT FD} to set the
	input source for other commands.

	@item /recvfd
	Not yet implemented.

	@item /open @var{var} @var{file} [@var{mode}]
	Open @var{file} and assign the file descriptor to @var{var}. Warning:
	This command is experimental and might change in future versions.

	@item /close @var{fd}
	Close the file descriptor @var{fd}. Warning: This command is
	experimental and might change in future versions.

	@item /showopen
	Show a list of open files.

	@item /serverpid
	Send the Assuan command @command{GETINFO pid} to the server and store
	the returned PID for internal purposes.

	@item /sleep
	Sleep for a second.

	@item /hex
	@itemx /nohex
	Same as the command line option @option{--hex}.

	@item /decode
	@itemx /nodecode
	Same as the command line option @option{--decode}.

	@item /subst
	@itemx /nosubst
	Enable and disable variable substitution. It defaults to disabled
	unless the command line option @option{--subst} has been used.
	If /subst as been enabled once, leading whitespace is removed from
	input lines which makes scripts easier to read.

	@item /while @var{condition}
	@itemx /end
	These commands provide a way for executing loops. All lines between
	the @code{while} and the corresponding @code{end} are executed as long
	as the evaluation of @var{condition} yields a non-zero value or is the
	string @code{true} or @code{yes}. The evaluation is done by passing
	@var{condition} to the @code{strtol} function. Example:

	@smallexample
	/subst
	/let i 3
	/while $i
	/echo loop couter is $i
	/let i $@{- $i 1@}
	/end
	@end smallexample

	@item /if @var{condition}
	@itemx /end
	These commands provide a way for conditional execution. All lines between
	the @code{if} and the corresponding @code{end} are executed only if
	the evaluation of @var{condition} yields a non-zero value or is the
	string @code{true} or @code{yes}. The evaluation is done by passing
	@var{condition} to the @code{strtol} function.

	@item /run @var{file}
	Run commands from @var{file}.

	@item /bye
	Terminate the connection and the program

	@item /help
	Print a list of available control commands.

	@end table


	@ifset isman
	@mansect see also
	@command{gpg-agent}(1),
	@command{scdaemon}(1)
	@include see-also-note.texi
	@end ifset

	@c
	@c DIRMNGR-CLIENT
	@c
	@node dirmngr-client
	@section The Dirmngr Client Tool

	@manpage dirmngr-client.1
	@ifset manverb
	.B dirmngr-client
	\- Tool to access the Dirmngr services
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B dirmngr-client
	.RI [ options ]
	.RI [ certfile \| pattern ]
	@end ifset

	@mansect description
	The @command{dirmngr-client} is a simple tool to contact a running
	dirmngr and test whether a certificate has been revoked --- either by
	being listed in the corresponding CRL or by running the OCSP protocol.
	If no dirmngr is running, a new instances will be started but this is
	in general not a good idea due to the huge performance overhead.

	@noindent
	The usual way to run this tool is either:

	@example
	dirmngr-client @var{acert}
	@end example

	@noindent
	or

	@example
	dirmngr-client <@var{acert}
	@end example

	Where @var{acert} is one DER encoded (binary) X.509 certificates to be
	tested.
	@ifclear isman
	The return value of this command is
	@end ifclear

	@mansect return value
	@ifset isman
	@command{dirmngr-client} returns these values:
	@end ifset
	@table @code

	@item 0
	The certificate under question is valid; i.e. there is a valid CRL
	available and it is not listed there or the OCSP request returned that
	that certificate is valid.

	@item 1
	The certificate has been revoked

	@item 2 (and other values)
	There was a problem checking the revocation state of the certificate.
	A message to stderr has given more detailed information. Most likely
	this is due to a missing or expired CRL or due to a network problem.

	@end table

	@mansect options
	@noindent
	@command{dirmngr-client} may be called with the following options:


	@table @gnupgtabopt
	@item --version
	@opindex version
	Print the program version and licensing information. Note that you cannot
	abbreviate this command.

	@item --help, -h
	@opindex help
	Print a usage message summarizing the most useful command-line options.
	Note that you can abbreviate this command.

	@item --quiet, -q
	@opindex quiet
	Make the output extra brief by suppressing any informational messages.

	@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{dirmngr}, such as @samp{-vv}.

	@item --pem
	@opindex pem
	Assume that the given certificate is in PEM (armored) format.

	@item --ocsp
	@opindex ocsp
	Do the check using the OCSP protocol and ignore any CRLs.

	@item --force-default-responder
	@opindex force-default-responder
	When checking using the OCSP protocol, force the use of the default OCSP
	responder. That is not to use the Reponder as given by the certificate.

	@item --ping
	@opindex ping
	Check whether the dirmngr daemon is up and running.

	@item --cache-cert
	@opindex cache-cert
	Put the given certificate into the cache of a running dirmngr. This is
	mainly useful for debugging.

	@item --validate
	@opindex validate
	Validate the given certificate using dirmngr's internal validation code.
	This is mainly useful for debugging.

	@item --load-crl
	@opindex load-crl
	This command expects a list of filenames with DER encoded CRL files.
	With the option @option{--url} URLs are expected in place of filenames
	and they are loaded directly from the given location. All CRLs will be
	validated and then loaded into dirmngr's cache.

	@item --lookup
	@opindex lookup
	Take the remaining arguments and run a lookup command on each of them.
	The results are Base-64 encoded outputs (without header lines). This
	may be used to retrieve certificates from a server. However the output
	format is not very well suited if more than one certificate is returned.

	@item --url
	@itemx -u
	@opindex url
	Modify the @command{lookup} and @command{load-crl} commands to take an URL.

	@item --local
	@itemx -l
	@opindex url
	Let the @command{lookup} command only search the local cache.

	@item --squid-mode
	@opindex squid-mode
	Run @sc{dirmngr-client} in a mode suitable as a helper program for
	Squid's @option{external_acl_type} option.


	@end table

	@ifset isman
	@mansect see also
	@command{dirmngr}(8),
	@command{gpgsm}(1)
	@include see-also-note.texi
	@end ifset


	@c
	@c GPGPARSEMAIL
	@c
	@node gpgparsemail
	@section Parse a mail message into an annotated format

	@manpage gpgparsemail.1
	@ifset manverb
	.B gpgparsemail
	\- Parse a mail message into an annotated format
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B gpgparsemail
	.RI [ options ]
	.RI [ file ]
	@end ifset

	@mansect description
	The @command{gpgparsemail} is a utility currently only useful for
	debugging. Run it with @code{--help} for usage information.



	@c
	@c SYMCRYPTRUN
	@c
	@node symcryptrun
	@section Call a simple symmetric encryption tool.
	@manpage symcryptrun.1
	@ifset manverb
	.B symcryptrun
	\- Call a simple symmetric encryption tool
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B symcryptrun
	.B \-\-class
	.I class
	.B \-\-program
	.I program
	.B \-\-keyfile
	.I keyfile
	.RB [ --decrypt \| --encrypt ]
	.RI [ inputfile ]
	@end ifset

	@mansect description
	Sometimes simple encryption tools are already in use for a long time and
	there might be a desire to integrate them into the GnuPG framework. The
	protocols and encryption methods might be non-standard or not even
	properly documented, so that a full-fledged encryption tool with an
	interface like gpg is not doable. @command{symcryptrun} provides a
	solution: It operates by calling the external encryption/decryption
	module and provides a passphrase for a key using the standard
	@command{pinentry} based mechanism through @command{gpg-agent}.

	Note, that @command{symcryptrun} is only available if GnuPG has been
	configured with @samp{--enable-symcryptrun} at build time.

	@menu
	* Invoking symcryptrun:: List of all commands and options.
	@end menu

	@manpause
	@node Invoking symcryptrun
	@subsection List of all commands and options.

	@noindent
	@command{symcryptrun} is invoked this way:

	@example
	symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE
	[--decrypt \| --encrypt] [inputfile]
	@end example
	@mancont

	For encryption, the plain text must be provided on STDIN or as the
	argument @var{inputfile}, and the ciphertext will be output to STDOUT.
	For decryption vice versa.

	@var{CLASS} describes the calling conventions of the external tool.
	Currently it must be given as @samp{confucius}. @var{PROGRAM} is
	the full filename of that external tool.

	For the class @samp{confucius} the option @option{--keyfile} is
	required; @var{keyfile} is the name of a file containing the secret key,
	which may be protected by a passphrase. For detailed calling
	conventions, see the source code.

	@noindent
	Note, that @command{gpg-agent} must be running before starting
	@command{symcryptrun}.

	@noindent
	The following additional options may be used:

	@table @gnupgtabopt
	@item -v
	@itemx --verbose
	@opindex verbose
	Output additional information while running.

	@item -q
	@item --quiet
	@opindex q
	@opindex quiet
	Try to be as quiet as possible.

	@include opt-homedir.texi


	@item --log-file @var{file}
	@opindex log-file
	Append all logging output to @var{file}. Use @file{socket://} to log
	to socket. Default is to write logging information to STDERR.

	@end table

	@noindent
	The possible exit status codes of @command{symcryptrun} are:

	@table @code
	@item 0
	Success.
	@item 1
	Some error occurred.
	@item 2
	No valid passphrase was provided.
	@item 3
	The operation was canceled by the user.

	@end table

	@mansect see also
	@ifset isman
	@command{gpg}(1),
	@command{gpgsm}(1),
	@command{gpg-agent}(1),
	@end ifset
	@include see-also-note.texi


	@c
	@c GPG-ZIP
	@c
	@c The original manpage on which this section is based was written
	@c by Colin Tuckley <colin@tuckley.org> and Daniel Leidert
	@c <daniel.leidert@wgdd.de> for the Debian distribution (but may be used by
	@c others).
	@manpage gpg-zip.1
	@node gpg-zip
	@section Encrypt or sign files into an archive
	@ifset manverb
	.B gpg-zip \- Encrypt or sign files into an archive
	@end ifset

	@mansect synopsis
	@ifset manverb
	.B gpg-zip
	.RI [ options ]
	.I filename1
	.I [ filename2, ... ]
	.I directory1
	.I [ directory2, ... ]
	@end ifset

	@mansect description
	@command{gpg-zip} encrypts or signs files into an archive. It is an
	gpg-ized tar using the same format as used by PGP's PGP Zip.

	@manpause
	@noindent
	@command{gpg-zip} is invoked this way:

	@example
	gpg-zip [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
	@end example

	@mansect options
	@noindent
	@command{gpg-zip} understands these options:

	@table @gnupgtabopt

	@item --encrypt
	@itemx -e
	@opindex encrypt
	Encrypt data. This option may be combined with @option{--symmetric} (for output that may be decrypted via a secret key or a passphrase).

	@item --decrypt
	@itemx -d
	@opindex decrypt
	Decrypt data.

	@item --symmetric
	@itemx -c
	Encrypt with a symmetric cipher using a passphrase. The default
	symmetric cipher used is CAST5, but may be chosen with the
	@option{--cipher-algo} option to @command{gpg}.

	@item --sign
	@itemx -s
	Make a signature. See @command{gpg}.

	@item --recipient @var{user}
	@itemx -r @var{user}
	@opindex recipient
	Encrypt for user id @var{user}. See @command{gpg}.

	@item --local-user @var{user}
	@itemx -u @var{user}
	@opindex local-user
	Use @var{user} as the key to sign with. See @command{gpg}.

	@item --list-archive
	@opindex list-archive
	List the contents of the specified archive.

	@item --output @var{file}
	@itemx -o @var{file}
	@opindex output
	Write output to specified file @var{file}.

	@item --gpg @var{gpgcmd}
	@opindex gpg
	Use the specified command @var{gpgcmd} instead of @command{gpg}.

	@item --gpg-args @var{args}
	@opindex gpg-args
	Pass the specified options to @command{gpg}.

	@item --tar @var{tarcmd}
	@opindex tar
	Use the specified command @var{tarcmd} instead of @command{tar}.

	@item --tar-args @var{args}
	@opindex tar-args
	Pass the specified options to @command{tar}.

	@item --version
	@opindex version
	Print version of the program and exit.

	@item --help
	@opindex help
	Display a brief help page and exit.

	@end table

	@mansect diagnostics
	@noindent
	The program returns 0 if everything was fine, 1 otherwise.


	@mansect examples
	@ifclear isman
	@noindent
	Some examples:

	@end ifclear
	@noindent
	Encrypt the contents of directory @file{mydocs} for user Bob to file
	@file{test1}:

	@example
	gpg-zip --encrypt --output test1 --gpg-args -r Bob mydocs
	@end example

	@noindent
	List the contents of archive @file{test1}:

	@example
	gpg-zip --list-archive test1
	@end example


	@mansect see also
	@ifset isman
	@command{gpg}(1),
	@command{tar}(1),
	@end ifset
	@include see-also-note.texi

File Metadata

Mime Type: text/x-diff
Expires: Sat, May 10, 8:33 AM (1 d, 7 h)
Storage Engine: local-disk
Storage Format: Raw Data
Storage Handle: 86/c0/bf9e56d00ab3c0bcda3a1863e258

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions