From babd87f2dadfb8be042c18e1b88e5bba00fd3249 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Mon, 21 Sep 2020 09:11:33 +0200 Subject: [PATCH] doc: Some documentation updates. -- Also fixed some typos and documented soon to be used OIDs --- doc/DETAILS | 6 ++++ doc/dirmngr.texi | 79 ++++++++++++++++++++++++++++++++++++++++++------ doc/gpgsm.texi | 2 +- g10/getkey.c | 2 +- 4 files changed, 78 insertions(+), 11 deletions(-) diff --git a/doc/DETAILS b/doc/DETAILS index b8f360e35..728239e19 100644 --- a/doc/DETAILS +++ b/doc/DETAILS @@ -1543,6 +1543,12 @@ Status codes are: 1.3.6.1.4.1.11591.2.2.2 wellKnownPrivateKey 1.3.6.1.4.1.11591.2.3 CMS contentType 1.3.6.1.4.1.11591.2.3.1 OpenPGP keyblock (as octet string) + 1.3.6.1.4.1.11591.2.4 LDAP stuff + 1.3.6.1.4.1.11591.2.4.1 attributes + 1.3.6.1.4.1.11591.2.4.1.1 gpgFingerprint attribute + 1.3.6.1.4.1.11591.2.4.1.2 gpgSubFingerprint attribute + 1.3.6.1.4.1.11591.2.4.1.3 gpgMailbox attribute + 1.3.6.1.4.1.11591.2.4.1.4 gpgSubCertID attribute 1.3.6.1.4.1.11591.2.12242973 invalid encoded OID #+end_example diff --git a/doc/dirmngr.texi b/doc/dirmngr.texi index 5e86cf36a..846057bcf 100644 --- a/doc/dirmngr.texi +++ b/doc/dirmngr.texi @@ -539,7 +539,7 @@ certificate for that pool. Otherwise, it will use the system CAs. @section Configuration Dirmngr makes use of several directories when running in daemon mode: -There are a few configuration files whih control the operation of +There are a few configuration files to control the operation of dirmngr. By default they may all be found in the current home directory (@pxref{option --homedir}). @@ -589,31 +589,92 @@ 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: +Several options control the use of trusted certificates for TLS and +CRLs. Here is an Overview on the use and origin of those Root CA +certificates: +@table @asis + +@item System + +These System root certificates are used by: FIXME + +The origin of the system provided certificates depends on the +platform. On Windows all certificates from the Windows System Stores +@code{ROOT} and @code{CA} are used. + +On other platforms the certificates are read from the first file found +form this list: @file{/etc/ssl/ca-bundle.pem}, +@file{/etc/ssl/certs/ca-certificates.crt}, +@file{/etc/pki/tls/cert.pem}, +@file{/usr/local/share/certs/ca-root-nss.crt}, +@file{/etc/ssl/cert.pem}. + +@item GnuPG + +The GnuPG specific certificates stored in the directory +@file{/etc/gnupg/trusted-certs} are only used to validate CRLs. + +@c Note that dirmngr's VALIDATE command also uses them but that +@c command is anyway only intended for debugging. + +@item OpenPGP keyserver + +For accessing the OpenPGP keyservers the only certificates used are +those set with the configuration option @option{hkp-cacert}. + +@item OpenPGP keyserver pool + +This is usually only one certificate read from the file +@file{@value{DATADIR}/gnupg/sks-keyservers.netCA.pem}. If this +certificate exists it is used to access the special keyservers +@code{hkps.pool.sks-keyservers.net} (or @file{hkps://keys.gnupg.net}). + +@end table + +Please note that @command{gpgsm} accepts Root CA certificates for its +own purposes only if they are listed in its file @file{trustlist.txt}. +@command{dirmngr} does not make use of this list - except FIXME. + + +@mansect notes + +To be able to see diagnostics it is often useful to put at least the +following lines into the configuration file +@file{~/gnupg/dirmngr.conf}: @example log-file ~/dirmngr.log +verbose @end example +You may want to check the log file to see whether all desired root CA +certificates are correctly loaded. + 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: +To make sure that new options are read or that after the installation +of a new GnuPG versions the right dirmngr version is running, you +should kill an existing dirmngr so that a new instance is started as +needed by the otehr components: @example gpgconf --kill dirmngr @end example -You may check the log file to see whether all desired root -certificates have been loaded correctly. +Direct interfaction with the dirmngr is possible by using the command + +@example +gpg-connect-agent --dirmngr +@end example + +Enter @code{HELP} at the prompt to see a list of commands and enter +@code{HELP} followed by a command name to get help on that command. + @c diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index 516213841..17e30d243 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -364,7 +364,7 @@ are ignored. Note that all parts of that string are expected to be UTF-8 encoded. This may lead to problems if the @sc{password} has originally been -encoded as Latin-1; in such a case better configure tsuch an LDAP server +encoded as Latin-1; in such a case better configure such an LDAP server using the global configuration of @command{dirmngr}. Here is an example which uses the default port, no username, no diff --git a/g10/getkey.c b/g10/getkey.c index cfcf9c96a..a0b71407a 100644 --- a/g10/getkey.c +++ b/g10/getkey.c @@ -1271,7 +1271,7 @@ subkey_is_ok (const PKT_public_key *sub) return ! sub->flags.revoked && sub->flags.valid && ! sub->flags.disabled; } -/* Return true if KEYBLOCK has only expired encryption subkyes. Note +/* Return true if KEYBLOCK has only expired encryption subkeys. Note * that the function returns false if the key has no encryption * subkeys at all or the subkeys are revoked. */ static int