[svn] GnuPG - r5352 - trunk/doc
svn author wk
cvs at cvs.gnupg.org
Thu Jun 10 12:39:45 CEST 2010
Author: wk
Date: 2010-06-10 12:39:44 +0200 (Thu, 10 Jun 2010)
New Revision: 5352
Added:
trunk/doc/dirmngr.texi
Modified:
trunk/doc/ChangeLog
trunk/doc/Makefile.am
trunk/doc/contrib.texi
trunk/doc/gnupg.texi
trunk/doc/gnupg7.texi
trunk/doc/gpg-agent.texi
trunk/doc/instguide.texi
trunk/doc/tools.texi
Log:
Include dirmngr manual
Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/ChangeLog 2010-06-10 10:39:44 UTC (rev 5352)
@@ -1,3 +1,16 @@
+2010-06-10 Werner Koch <wk at g10code.com>
+
+ * Makefile.am (gnupg_TEXINFOS): Add dirmngr.texi.
+ (myman_sources): Ditto.
+ (myman_pages): Add dirmngr and dirmngr-client pages.
+ (noinst_MANS): Move gnupg.7 to man_MANS.
+
+ * gnupg.texi: Include dirmngr.texi and add a menu entry.
+ * dirmngr.texi: New. Taken from the current SVN of the dirmngr
+ package and adjusted to fit into the GnuPG manual. Moved
+ dirmngr-cleint stuff to ...
+ * tools.texi (dirmngr-client): ... new.
+
2009-11-18 Werner Koch <wk at g10code.com>
* gpg.texi (GPG Key related Options): Describe
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/Makefile.am 2010-06-10 10:39:44 UTC (rev 5352)
@@ -52,7 +52,7 @@
gnupg_TEXINFOS = \
gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi instguide.texi \
tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \
- sysnotes.texi gnupg-card-architecture.fig \
+ sysnotes.texi gnupg-card-architecture.fig dirmngr.texi \
howtos.texi howto-create-a-server-cert.texi
DVIPS = TEXINPUTS="$(srcdir)$(PATH_SEPARATOR)$$TEXINPUTS" dvips
@@ -63,14 +63,14 @@
--release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard"
myman_sources = gnupg7.texi gpg.texi gpgsm.texi gpg-agent.texi \
- scdaemon.texi tools.texi
-myman_pages = gpg2.1 gpgsm.1 gpg-agent.1 scdaemon.1 gpgv2.1 \
+ dirmngr.texi scdaemon.texi tools.texi
+myman_pages = gpg2.1 gpgsm.1 gpg-agent.1 dirmngr.8 scdaemon.1 gpgv2.1 \
watchgnupg.1 gpgconf.1 addgnupghome.8 gpg-preset-passphrase.1 \
gpg-connect-agent.1 gpgparsemail.1 symcryptrun.1 \
- gpgsm-gencert.sh.1 applygnupgdefaults.8 gpg-zip.1
+ gpgsm-gencert.sh.1 applygnupgdefaults.8 gpg-zip.1 \
+ dirmngr-client.1
-man_MANS = $(myman_pages)
-noinst_MANS = gnupg.7
+man_MANS = $(myman_pages) gnupg.7
watchgnupg_SOURCE = gnupg.texi
Modified: trunk/doc/contrib.texi
===================================================================
--- trunk/doc/contrib.texi 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/contrib.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -97,7 +97,7 @@
This software has been made possible by the previous work of Chris
Wedgwood, Jean-loup Gailly, Jon Callas, Mark Adler, Martin Hellmann
Paul Kendall, Philip R. Zimmermann, Peter Gutmann, Philip A. Nelson,
-Taher ElGamal, Torbjorn Granlund, Whitfield Diffie, some unknown NSA
+Taher Elgamal, Torbjorn Granlund, Whitfield Diffie, some unknown NSA
mathematicians and all the folks who have worked hard to create
complete and free operating systems.
Added: trunk/doc/dirmngr.texi
===================================================================
--- trunk/doc/dirmngr.texi (rev 0)
+++ trunk/doc/dirmngr.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -0,0 +1,788 @@
+ at c Copyright (C) 2002 Klar"alvdalens Datakonsult AB
+ at c Copyright (C) 2004, 2005, 2006, 2007 g10 Code GmbH
+ at c This is part of the GnuPG manual.
+ at c For copying conditions, see the file gnupg.texi.
+
+ at node Invoking DIRMNGR
+ at chapter Invoking DIRMNGR
+ at cindex DIRMNGR command options
+ at cindex command options
+ at cindex options, DIRMNGR command
+
+ at manpage dirmngr.8
+ at ifset manverb
+.B dirmngr
+\- CRL and OCSP daemon
+ at end ifset
+
+ at mansect synopsis
+ at ifset manverb
+.B dirmngr
+.RI [ options ]
+.I command
+.RI [ args ]
+ at end ifset
+
+ at mansect description
+Dirmngr is a server for managing and downloading certificate revocation
+lists (CRLs) for X.509 certificates and for downloading the certificates
+themselves. Dirmngr also handles OCSP requests as an alternative to
+CRLs. Dirmngr is either invoked internally by gpgsm or when running as a
+system daemon through the @command{dirmngr-client} tool.
+
+If @command{dirmngr} is started in system daemon mode, it uses a
+directory layout as common for system daemons and does not make use of
+the default @file{~/.gnupg} directory.
+
+
+ at manpause
+ at noindent
+ at xref{Option Index},for an index to @command{DIRMNGR}'s commands and
+options.
+ at mancont
+
+ at 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.
+ at end menu
+
+
+ at node Dirmngr Commands
+ at section Commands
+ at mansect commands
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+ at table @gnupgtabopt
+ at item --version
+ at opindex version
+Print the program version and licensing information. Note that you cannot
+abbreviate this command.
+
+ at item --help, -h
+ at opindex help
+Print a usage message summarizing the most useful command-line options.
+Not that you cannot abbreviate this command.
+
+ at item --dump-options
+ at opindex dump-options
+Print a list of all available options and commands. Note that you cannot
+abbreviate this command.
+
+ at item --server
+ at 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.
+
+ at item --daemon
+ at 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.
+
+ at item --list-crls
+ at opindex list-crls
+List the contents of the CRL cache on @code{stdout}. This is probably
+only useful for debugging purposes.
+
+ at item --load-crl @var{file}
+ at 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.
+
+ at item --fetch-crl @var{url}
+ at opindex fetch-crl
+This command requires an URL as additional argument, and it will make
+dirmngr try to retrieve an import the CRL from that @var{url} into
+it's cache. This is mainly useful for debugging purposes. The
+ at command{dirmngr-client} provides the same feature for a running dirmngr.
+
+ at item --shutdown
+ at opindex shutdown
+This commands shuts down an running instance of Dirmngr. This command
+has currently no effect.
+
+ at item --flush
+ at opindex flush
+This command removes all CRLs from Dirmngr's cache. Client requests
+will thus trigger reading of fresh CRLs.
+
+ at end table
+
+
+ at mansect options
+ at node Dirmngr Options
+ at section Option Summary
+
+ at table @gnupgtabopt
+
+ at item --options @var{file}
+ at opindex options
+Reads configuration from @var{file} instead of from the default
+per-user configuration file. The default configuration file is named
+ at file{dirmngr.conf} and expected in the home directory.
+
+ at item --homedir @var{dir}
+ at 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:
+
+ at table @asis
+
+ at item With @code{--daemon} given on the commandline
+the directory named @file{/etc/gnupg} for configuration files,
+ at file{/var/lib/gnupg/} for extra data and @file{/var/cache/gnupg}
+for cached CRLs.
+
+ at 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.
+ at end table
+
+
+ at item -v
+ at item --verbose
+ at opindex v
+ at opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @sc{dirmngr}, such as @option{-vv}.
+
+
+ at item --log-file @var{file}
+ at opindex log-file
+Append all logging output to @var{file}. This is very helpful in
+seeing what the agent actually does.
+
+ at item --debug-level @var{level}
+ at opindex debug-level
+Select the debug level for investigating problems. @var{level} may be a
+numeric value or by a keyword:
+
+ at table @code
+ at item none
+No debugging at all. A value of less than 1 may be used instead of
+the keyword.
+ at item basic
+Some basic debug messages. A value between 1 and 2 may be used
+instead of the keyword.
+ at item advanced
+More verbose debug messages. A value between 3 and 5 may be used
+instead of the keyword.
+ at item expert
+Even more detailed messages. A value between 6 and 8 may be used
+instead of the keyword.
+ at 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.
+ at 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.
+
+ at item --debug @var{flags}
+ at opindex debug
+This option is only useful for debugging and the behaviour may change at
+any time without notice. FLAGS are bit encoded and may be given in
+usual C-Syntax.
+
+ at item --debug-all
+ at opindex debug-all
+Same as @code{--debug=0xffffffff}
+
+ at item --debug-wait @var{n}
+ at 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.
+
+ at item -s
+ at itemx --sh
+ at itemx -c
+ at itemx --csh
+ at opindex s
+ at opindex sh
+ at opindex c
+ at 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.
+
+ at item --force
+ at opindex force
+Enabling this option forces loading of expired CRLs; this is only
+useful for debugging.
+
+ at item --disable-ldap
+ at opindex disable-ldap
+Entirely disables the use of LDAP.
+
+ at item --disable-http
+ at opindex disable-http
+Entirely disables the use of HTTP.
+
+ at item --ignore-http-dp
+ at 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.
+
+ at item --ignore-ldap-dp
+ at 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.
+
+ at item --ignore-ocsp-service-url
+ at opindex ignore-ocsp-service-url
+Ignore all OCSP URLs contained in the certificate. The effect is to
+force the use of the default responder.
+
+ at item --honor-http-proxy
+ at opindex honor-http-proxy
+If the environment variable @env{http_proxy} has been set, use its
+value to access HTTP servers.
+
+ at item --http-proxy @var{host}[:@var{port}]
+ at opindex http-proxy
+Use @var{host} and @var{port} to access HTTP servers. The use of this
+options overrides the environment variable @env{http_proxy} regardless
+whether @option{--honor-http-proxy} has been set.
+
+
+ at item --ldap-proxy @var{host}[:@var{port}]
+ at opindex ldap-proxy
+Use @var{host} and @var{port} to connect to LDAP servers. If @var{port}
+is ommitted, 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 ommitted from the URL.
+
+ at item --only-ldap-proxy
+ at opindex only-ldap-proxy
+Never use anything else but the LDAP "proxy" as configured with
+ at option{--ldap-proxy}. Usually @command{dirmngr} tries to use other
+configured LDAP server if the connection using the "proxy" failed.
+
+
+ at item --ldapserverlist-file @var{file}
+ at 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
+ at file{ldapservers.conf} when running in @option{--daemon} mode.
+
+This server list file contains one LDAP server per line in the format
+
+ at 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 orginally 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). at footnote{The @command{gpgconf} tool might be
+helpful for frontends as it allows to edit this configuration file using
+percent escaped strings.}
+
+
+ at item --ldaptimeout @var{secs}
+ at 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.
+
+
+ at item --add-servers
+ at opindex add-servers
+This options 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 options 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.
+
+
+ at item --allow-ocsp
+ at 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.
+
+
+ at item --ocsp-responder @var{url}
+ at opindex ocsp-responder
+Use @var{url} as the default OCSP Responder if the certificate does
+not contain information about an assigned responder. Note, that
+ at code{--ocsp-signer} must also be set to a valid certificate.
+
+ at item --ocsp-signer @var{fpr}|@var{file}
+ at opindex ocsp-signer
+Use the certificate with the fingerprint @var{fpr} to check the
+responses of the default OCSP Responder. Alternativly a filename can be
+given in which case the respinse 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
+ at 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.
+
+
+ at item --ocsp-max-clock-skew @var{n}
+ at 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).
+
+ at item --ocsp-max-period @var{n}
+ at 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).
+
+ at item --ocsp-current-period @var{n}
+ at 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).
+
+
+ at item --max-replies @var{n}
+ at opindex max-replies
+Do not return more that @var{n} items in one query. The default is
+10.
+
+ at item --ignore-cert-extension @var{oid}
+ at opindex ignore-cert-extension
+Add @var{oid} to the list of ignored certificate extensions. The
+ at var{oid} is expected to be in dotted decimal form, like
+ at 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.
+
+ at end table
+
+
+ at c
+ at c Dirmngr Configuration
+ at c
+ at mansect files
+ at node Dirmngr Configuration
+ at section Configuration
+
+Dirmngr makes use of several directories when running in daemon mode:
+
+ at table @file
+
+ at item /etc/gnupg
+This is where all the configuration files are expected by default.
+
+ at 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 Reponses. 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.
+
+Note that for OCSP responses the certificate specified using the option
+ at option{--ocsp-signer} is always considered valid to sign OCSP requests.
+
+
+ at item /var/lib/gnupg/extra-certs
+This directory may contain extra certificates which are preloaded into
+the interal cache on startup. This is convenient in cases you have a
+couple intermediate CA certificates or certificates ususally used to
+sign OCSP reponses. These certificates are first tried before going out
+to the net to look for them. These certificates must also be
+ at acronym{DER} encoded and suffixed with @file{.crt} or @file{.der}.
+
+ at item /var/run/gnupg
+This directory keeps the socket file for accsing @command{dirmngr} services.
+The name of the socket file will be @file{S.dirmngr}. Make sure that this
+directory has the proper permissions to let @command{dirmngr} create the
+socket file and that eligible users may read and write to that socket.
+
+ at item /var/cache/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.
+
+ at end table
+ at manpause
+
+To be able to see what's going on you should create the configure file
+ at file{/etc/dirmngr/dirmngr.conf} with at least one line:
+
+ at example
+log-file /var/log/gnupg/dirmngr.log
+ at end example
+
+To be able to perform OCSP requests you probably want to add the line:
+
+ at example
+allow-ocsp
+ at end example
+
+Now you may start dirmngr as a system daemon using:
+
+ at example
+dirmngr --daemon
+ at end example
+
+Please ignore the output; it is not needed anymore. Check the log file
+to see whether all trusted root certificates have benn loaded correctly.
+
+
+ at c
+ at c Dirmngr Signals
+ at c
+ at mansect signals
+ at node Dirmngr Signals
+ at 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:
+
+ at table @gnupgtabopt
+
+ at item SIGHUP
+ at cpindex SIGHUP
+This signals 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.
+
+ at item SIGTERM
+ at 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.
+
+ at item SIGINT
+ at cpindex SIGINT
+Shuts down the process immediately.
+
+
+ at item SIGUSR1
+ at cpindex SIGUSR1
+This prints some caching statistics to the log file.
+
+ at end table
+
+
+
+ at c
+ at c Examples
+ at c
+ at mansect examples
+ at node Dirmngr Examples
+ at section Examples
+
+
+The way to start the dirmngr in the foreground (as done by tools if no
+dirmngr is running in the background) is to use:
+
+ at example
+ dirmngr --server -v
+ at end example
+
+If a dirmngr is supposed to be used as a system wide daemon, it should
+be started like:
+
+ at example
+ dirmngr --daemon
+ at end example
+
+This will force it to go into the backround, read the default
+certificates (including the trusted root certificates) and listen on a
+socket for client requests. It does also print information about the
+socket used but they are only for compatibilty reasons with old GnuPG
+versions and may be ignored.
+
+
+ at c
+ at c Assuan Protocol
+ at c
+ at manpause
+ at node Dirmngr Protocol
+ at section Dirmngr's Assuan Protocol
+
+Assuan is the IPC protocol used to access dirmngr. This is a
+description of the commands implemented by dirmngr.
+
+ at 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.
+ at end menu
+
+ at node Dirmngr LOOKUP
+ at 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:
+
+ at example
+ S: D <DER encoded certificate>
+ S: END
+ S: D <second DER encoded certificate>
+ S: END
+ S: OK
+ at 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
+
+ at example
+ S: S TRUNCATED <n>
+ at 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:
+
+ at example
+ C: LOOKUP --url CN%3DWerner%20Koch,o%3DIntevation%20GmbH,c%3DDE?userCertificate
+ at 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.
+
+
+
+ at node Dirmngr ISVALID
+ at subsection Validate a certificate using a CRL or OCSP
+
+ at example
+ ISVALID [--only-ocsp] [--force-default-responder] @var{certid}|@var{certfpr}
+ at 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.
+
+ at noindent
+Common return values are:
+
+ at table @code
+ at 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.
+
+ at 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.
+
+ at item GPG_ERR_NO_CRL_KNOWN
+No CRL is known for this certificate or the CRL is not valid or out of
+date.
+
+ at item GPG_ERR_NO_DATA
+The OCSP responder returned an ``unknown'' status. This means that it
+is not aware of the certificate's status.
+
+ at item GPG_ERR_NOT_SUPPORTED
+This is commonly seen if OCSP support has not been enabled in the
+configuration.
+ at 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:
+
+ at example
+ S: INQUIRE SENDCERT <CertID>
+ C: D <DER encoded certificate>
+ C: END
+ at 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:
+
+ at example
+ S: INQUIRE ISTRUSTED <CertHexfpr>
+ C: D 1
+ C: END
+ at end example
+
+Only this answer will let Dirmngr consider the CRL as valid.
+
+
+ at node Dirmngr CHECKCRL
+ at 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 know, the function inquires the
+certificate using:
+
+ at example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+ at 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.
+
+ at 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.
+
+ at node Dirmngr CHECKOCSP
+ at subsection Validate a certificate using OCSP
+
+ at example
+ CHECKOCSP [--force-default-responder] [@var{fingerprint}]
+ at 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 appropiate
+OCSP responder. If the fingerprint has not been given or the
+certificate is not known by Dirmngr, the function inquires the
+certificate using:
+
+ at example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+ at 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}.
+
+
+ at 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.
+
+ at node Dirmngr CACHECERT
+ at 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
+wnats 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
+
+ at example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+ at end example
+
+Thus the caller is expected to return the certificate for the request
+as a binary blob.
+
+ at noindent
+The return code is 0 for success; i.e. the certificate has not been
+succesfully cached or one of the usual error codes from libgpg-error.
+
+ at node Dirmngr VALIDATE
+ at 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
+
+ at example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+ at end example
+
+Thus the caller is expected to return the certificate for the request
+as a binary blob.
+
+
+ at mansect see also
+ at ifset isman
+ at command{gpgsm}(1),
+ at command{dirmngr-client}(1)
+ at end ifset
+ at include see-also-note.texi
+
Modified: trunk/doc/gnupg.texi
===================================================================
--- trunk/doc/gnupg.texi 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/gnupg.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -50,6 +50,9 @@
@direntry
* gpg2: (gnupg). OpenPGP encryption and signing tool.
* gpgsm: (gnupg). S/MIME encryption and signing tool.
+* gpg-agent: (gnupg). The secret key daemon.
+* dirmngr: (gnupg). X.509 CRL and OCSP server.
+* dirmngr-client: (gnupg). X.509 CRL and OCSP client.
@end direntry
@@ -121,6 +124,7 @@
* Installation:: A short installation guide.
* Invoking GPG-AGENT:: How to launch the secret key daemon.
+* Invoking DIRMNGR:: How to launch the CRL and OCSP daemon.
* Invoking GPG:: Using the OpenPGP protocol.
* Invoking GPGSM:: Using the S/MIME protocol.
* Invoking SCDAEMON:: How to handle Smartcards.
@@ -152,6 +156,7 @@
@include instguide.texi
@include gpg-agent.texi
+ at include dirmngr.texi
@include gpg.texi
@include gpgsm.texi
@include scdaemon.texi
@@ -194,6 +199,18 @@
@c Epilogue
@c ---------------------------------------------------------------------
+ at c @node History
+ at c @unnumbered History
+ at c
+ at c Here are the notices from the old dirmngr manual:
+ at c
+ at c @itemize
+ at c @item Using DirMngr, 2002, Steffen Hansen, Klar"alvdalens Datakonsult AB.
+ at c @item Using DirMngr, 2004, 2005, 2006, 2008 Werner Koch, g10 Code GmbH.
+ at c @end itemize
+ at c
+
+
@bye
Modified: trunk/doc/gnupg7.texi
===================================================================
--- trunk/doc/gnupg7.texi 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/gnupg7.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -23,6 +23,7 @@
@command{gpgv}(1),
@command{gpgsm}(1),
@command{gpg-agent}(1),
+ at command{dirmngr}(8),
@command{scdaemon}(1)
@include see-also-note.texi
@end ifset
Modified: trunk/doc/gpg-agent.texi
===================================================================
--- trunk/doc/gpg-agent.texi 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/gpg-agent.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -136,18 +136,18 @@
@table @gnupgtabopt
@item --version
@opindex version
-Print the program version and licensing information. Not that you can
+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.
-Not that you can abbreviate this command.
+Note that you cannot abbreviate this command.
@item --dump-options
@opindex dump-options
-Print a list of all available options and commands. Not that you can
+Print a list of all available options and commands. Note that you cannot
abbreviate this command.
@item --server
Modified: trunk/doc/instguide.texi
===================================================================
--- trunk/doc/instguide.texi 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/instguide.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -6,7 +6,6 @@
@node Installation
@chapter A short installation guide.
-
Unfortunately the installation guide has not been finished in time.
Instead of delaying the release of GnuPG 2.0 even further, I decided to
release without that guide. The chapter on gpg-agent and gpgsm do
@@ -16,6 +15,31 @@
gnupg-users mailing listsfor advise on how to solve problems or how to
get that whole thing up and running.
+** Building the software
+
+Building the software is decribed in the file @file{INSTALL}. Given
+that you are already reading this documentation we can only give some
+extra hints
+
+To comply with the rules on GNU systems you should have build time
+configured @command{dirmngr} using:
+
+ at example
+./configure --sysconfdir=/etc --localstatedir=/var
+ at end example
+
+This is to make sure that system wide configuration files are searched
+in the directory @file{/etc/gnupg} and variable data below @file{/var};
+the default would be to also install them below @file{/usr/local} where
+the binaries get installed. If you selected to use the
+ at option{--prefix=/} you obviously don't need those option as they are
+the default then.
+
+
+
+** Explain how to setup a root CA key as trusted
+
+
Such questions may also help to write a proper installation guide.
[to be written]
Modified: trunk/doc/tools.texi
===================================================================
--- trunk/doc/tools.texi 2010-06-09 16:53:51 UTC (rev 5351)
+++ trunk/doc/tools.texi 2010-06-10 10:39:44 UTC (rev 5352)
@@ -16,6 +16,7 @@
* gpgsm-gencert.sh:: Generate an X.509 certificate request.
* 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.
@@ -1381,7 +1382,168 @@
@include see-also-note.texi
@end ifset
+ at c
+ at c DIRMNGR-CLIENT
+ at c
+ at node dirmngr-client
+ at section The Dirmngr Client Tool
+ at manpage dirmngr-client.1
+ at ifset manverb
+.B dirmngr-client
+\- Tool to access the Dirmngr services
+ at end ifset
+
+ at mansect synopsis
+ at ifset manverb
+.B dirmngr-client
+.RI [ options ]
+.RI [ certfile | pattern ]
+ at end ifset
+
+ at 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.
+
+ at noindent
+The usual way to run this tool is either:
+
+ at example
+dirmngr-client @var{acert}
+ at end example
+
+ at noindent
+or
+
+ at example
+dirmngr-client <@var{acert}
+ at end example
+
+Where @var{acert} is one DER encoded (binary) X.509 certificates to be
+tested.
+ at ifclear isman
+The return value of this command is
+ at end ifclear
+
+ at mansect return value
+ at ifset isman
+ at command{dirmngr-client} returns these values:
+ at end ifset
+ at table @code
+
+ at item 0
+The certificate under question is valid; i.e. there is a valid CRL
+available and it is not listed tehre or teh OCSP request returned that
+that certificate is valid.
+
+ at item 1
+The certificate has been revoked
+
+ at 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.
+
+ at end table
+
+ at mansect options
+ at noindent
+ at command{dirmngr-client} may be called with the following options:
+
+
+ at table @gnupgtabopt
+ at item --version
+ at opindex version
+Print the program version and licensing information. Note that you cannot
+abbreviate this command.
+
+ at item --help, -h
+ at opindex help
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot abbreviate this command.
+
+ at item --quiet, -q
+ at opindex quiet
+Make the output extra brief by suppressing any informational messages.
+
+ at item -v
+ at item --verbose
+ at opindex v
+ at opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @sc{dirmngr}, such as @samp{-vv}.
+
+ at item --pem
+ at opindex pem
+Assume that the given certificate is in PEM (armored) format.
+
+ at item --ocsp
+ at opindex ocsp
+Do the check using the OCSP protocol and ignore any CRLs.
+
+ at item --force-default-responder
+ at opindex force-default-responder
+When checking using the OCSP protocl, force the use of the default OCSP
+responder. That is not to use the Reponder as given by the certificate.
+
+ at item --ping
+ at opindex ping
+Check whether the dirmngr daemon is up and running.
+
+ at item --cache-cert
+ at opindex cache-cert
+Put the given certificate into the cache of a running dirmngr. This is
+mainly useful for debugging.
+
+ at item --validate
+ at opindex validate
+Validate the given certificate using dirmngr's internal validation code.
+This is mainly useful for debugging.
+
+ at item --load-crl
+ at 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.
+
+ at item --lookup
+ at 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.
+
+ at item --url
+ at itemx -u
+ at opindex url
+Modify the @command{lookup} and @command{load-crl} commands to take an URL.
+
+ at item --local
+ at itemx -l
+ at opindex url
+Let the @command{lookup} command only search the local cache.
+
+ at item --squid-mode
+ at opindex squid-mode
+Run @sc{dirmngr-client} in a mode suitable as a helper program for
+Squid's @option{external_acl_type} option.
+
+
+ at end table
+
+ at ifset isman
+ at mansect see also
+ at command{dirmngr}(8),
+ at command{gpgsm}(1)
+ at include see-also-note.texi
+ at end ifset
+
+
@c
@c GPGPARSEMAIL
@c
More information about the Gnupg-commits
mailing list