diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/DETAILS | 13 | ||||
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/debugging.texi | 4 | ||||
| -rw-r--r-- | doc/dirmngr.texi | 34 | ||||
| -rw-r--r-- | doc/gpg-agent.texi | 26 | ||||
| -rw-r--r-- | doc/gpg-card.texi | 2 | ||||
| -rw-r--r-- | doc/gpg.texi | 148 | ||||
| -rw-r--r-- | doc/gpgsm.texi | 53 | ||||
| -rw-r--r-- | doc/gpgv.texi | 14 | ||||
| -rw-r--r-- | doc/howto-create-a-server-cert.texi | 2 | ||||
| -rw-r--r-- | doc/keyformat.txt | 520 | ||||
| -rw-r--r-- | doc/scdaemon.texi | 8 | ||||
| -rw-r--r-- | doc/specify-user-id.texi | 4 | ||||
| -rw-r--r-- | doc/tools.texi | 31 | ||||
| -rw-r--r-- | doc/wks.texi | 2 |
15 files changed, 722 insertions, 141 deletions
diff --git a/doc/DETAILS b/doc/DETAILS index 29e39708b..a278d045f 100644 --- a/doc/DETAILS +++ b/doc/DETAILS @@ -167,11 +167,13 @@ described here. The value is quoted like a C string to avoid control characters (the colon is quoted =\x3a=). For a "pub" record this field is - not used on --fixed-list-mode. A UAT record puts the attribute + not used on --fixed-list-mode. A "uat" record puts the attribute subpacket count here, a space, and then the total attribute - subpacket size. In gpgsm the issuer name comes here. The FPR and FP2 - records store the fingerprints here. The fingerprint of a - revocation key is stored here. + subpacket size. In gpgsm the issuer name comes here. The FPR and + FP2 records store the fingerprints here. The fingerprint of a + revocation key is also stored here. A "grp" records puts the + keygrip here; for combined algorithms the keygrips are delimited + by comma. *** Field 11 - Signature class @@ -243,7 +245,8 @@ described here. *** Field 17 - Curve name For pub, sub, sec, ssb, crt, and crs records this field is used - for the ECC curve name. + for the ECC curve name. For combined algorithms the first and the + second algorithm name, delimited by an underscore are put here. *** Field 18 - Compliance flags diff --git a/doc/Makefile.am b/doc/Makefile.am index 390153c76..66a934cef 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -42,7 +42,7 @@ EXTRA_DIST = samplekeys.asc mksamplekeys com-certs.pem \ FAQ gnupg7.texi mkdefsinc.c defsincdate \ opt-homedir.texi see-also-note.texi specify-user-id.texi \ gpgv.texi yat2m.c ChangeLog-2011 whats-new-in-2.1.txt \ - trust-values.texi + trust-values.texi keyformat.txt BUILT_SOURCES = gnupg-module-overview.png gnupg-module-overview.pdf \ gnupg-card-architecture.png gnupg-card-architecture.pdf \ diff --git a/doc/debugging.texi b/doc/debugging.texi index 6639e184b..a389bdf50 100644 --- a/doc/debugging.texi +++ b/doc/debugging.texi @@ -91,7 +91,7 @@ should not occur but sometimes things go wrong), run it using @item How to find the IP address of a keyserver If a round robin URL of is used for a keyserver -(e.g. subkeys.gnupg.org); it is not easy to see what server is actually +(e.g., subkeys.gnupg.org); it is not easy to see what server is actually used. Using the keyserver debug option as in @smallexample @@ -130,7 +130,7 @@ but Dirmngr's OCSP feature has not been enabled using The far most common reason for this is that the environment variable @code{GPG_TTY} has not been set correctly. Make sure that it has been set to a real tty device and not just to @samp{/dev/tty}; -i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is +i.e., @samp{GPG_TTY=tty} is plainly wrong; what you want is @samp{GPG_TTY=`tty`} --- note the back ticks. Also make sure that this environment variable gets exported, that is you should follow up the setting with an @samp{export GPG_TTY} (assuming a Bourne style diff --git a/doc/dirmngr.texi b/doc/dirmngr.texi index e50406035..420340ee3 100644 --- a/doc/dirmngr.texi +++ b/doc/dirmngr.texi @@ -213,7 +213,7 @@ however carefully selected to best aid in debugging. @item --debug @var{flags} @opindex debug Set debug flags. All flags are or-ed and @var{flags} may be given in -C syntax (e.g. 0x0042) or as a comma separated list of flag names. To +C syntax (e.g., 0x0042) or as a comma separated list of flag names. To get a list of all supported flags the single word "help" can be used. This option is only useful for debugging and the behavior may change at any time without notice. @@ -295,7 +295,7 @@ seconds. @opindex connect-quick-timeout Set the timeout for HTTP and generic TCP connection attempts to N seconds. The value set with the quick variant is used when the ---quick option has been given to certain Assuan commands. The quick +@option{--quick} option has been given to certain Assuan commands. The quick value is capped at the value of the regular connect timeout. The default values are 15 and 2 seconds. Note that the timeout values are for each connection attempt; the connection code will attempt to @@ -375,7 +375,7 @@ there for details; here is an example: as given. Replace USERNAME, PASSWORD, and the 'dc' parts according to the instructions received from your LDAP administrator. Note that only simple authentication - (i.e. cleartext passwords) is supported and thus using ldaps is + (i.e., cleartext passwords) is supported and thus using ldaps is strongly suggested (since 2.2.28 "ldaps" defaults to port 389 and uses STARTTLS). On Windows authentication via AD can be requested by adding @code{gpgNtds=1} after the fourth question @@ -468,7 +468,7 @@ 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 +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.} @@ -684,7 +684,7 @@ 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 +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). @@ -693,7 +693,7 @@ Note that for OCSP responses the certificate specified using the option @item /etc/gnupg/extra-certs This directory may contain extra certificates which are preloaded -into the internal cache on startup. Applications using dirmngr (e.g. gpgsm) +into the internal 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. @@ -752,7 +752,7 @@ certificate exists it is used to access the special keyservers 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. +@command{dirmngr} does not make use of this list --- except FIXME. @mansect notes @@ -802,7 +802,7 @@ Enter @code{HELP} at the prompt to see a list of commands and enter @node Dirmngr Signals @section Use of signals -A running @command{dirmngr} may be controlled by signals, i.e. using +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: @@ -1034,7 +1034,7 @@ 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 +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 @@ -1069,7 +1069,7 @@ of the global option @option{--ignore-ocsp-service-url}. @noindent -The return code is 0 for success; i.e. the certificate has not been +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 @@ -1091,7 +1091,7 @@ 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 +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 @@ -1191,7 +1191,7 @@ as a binary blob. @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 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, @@ -1217,7 +1217,7 @@ as a binary blob. @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 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 @@ -1296,7 +1296,7 @@ as a binary blob. @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 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 @@ -1320,7 +1320,7 @@ as a binary blob. @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 (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 @@ -1334,13 +1334,13 @@ as a binary blob. @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 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 (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. diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 74c4c10af..1d531fb57 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -72,7 +72,7 @@ the included Secure Shell Agent you may start the agent using: @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 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 @@ -111,8 +111,8 @@ 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}). +pinentry (e.g., @file{@value{BINDIR}/pinentry-gtk}) to the expected +one (e.g., @file{@value{BINDIR}/pinentry}). @manpause @noindent @@ -177,8 +177,8 @@ Windows. If in @file{common.conf} the option @option{no-autostart} is set, any start attempts will be ignored. -In --supervised mode, different file descriptors can be provided for -use as different socket types (e.g. ssh, extra) as long as they are +In @option{--supervised} mode, different file descriptors can be provided for +use as different socket types (e.g., ssh, extra) as long as they are identified in the environment variable @code{LISTEN_FDNAMES} (see sd_listen_fds(3) on some Linux distributions for more information on this convention). @@ -259,7 +259,7 @@ however carefully selected to best aid in debugging. @item --debug @var{flags} @opindex debug Set debug flags. All flags are or-ed and @var{flags} may be given -in C syntax (e.g. 0x0042) or as a comma separated list of flag names. +in C syntax (e.g., 0x0042) or as a comma separated list of flag names. To get a list of all supported flags the single word "help" can be used. This option is only useful for debugging and the behavior may change at any time without notice. @@ -345,7 +345,7 @@ 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 +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. @@ -716,7 +716,7 @@ The order in which keys are presented to ssh are: Editing the "Use-for-ssh" values can be done with an editor or using @command{gpg-connect-agent} and "KEYATTR" (Remember to append a colon -to the key; i.e. use "Use-for-ssh:"). +to the key; i.e., use "Use-for-ssh:"). @anchor{option --ssh-fingerprint-digest} @@ -724,7 +724,7 @@ to the key; i.e. use "Use-for-ssh:"). @opindex ssh-fingerprint-digest Select the digest algorithm used to compute ssh fingerprints that are -communicated to the user, e.g. in pinentry dialogs. OpenSSH has +communicated to the user, e.g., in pinentry dialogs. OpenSSH has transitioned from using MD5 to the more secure SHA256. @@ -830,7 +830,7 @@ 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}). +list of trusted certificates (e.g., @file{@value{SYSCONFDIR}/trustlist.txt}). This global list is also used if the local list is not available; the @ref{option --no-user-trustlist} enforces the use of only this global list. @@ -892,7 +892,7 @@ 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. +implicitly added to this list; i.e., there is no need to list them. @cartouche @smallexample @@ -925,7 +925,7 @@ a small helper script is provided to create these files (@pxref{addgnupghome}). @mansect signals @node Agent Signals @section Use of some signals -A running @command{gpg-agent} may be controlled by signals, i.e. using +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: @@ -1407,7 +1407,7 @@ convention either the hexified fingerprint of the key shall be used for 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 +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 diff --git a/doc/gpg-card.texi b/doc/gpg-card.texi index 3a659e80f..6458598bd 100644 --- a/doc/gpg-card.texi +++ b/doc/gpg-card.texi @@ -546,7 +546,7 @@ be printed; to create a new key anyway the option @samp{--force} can be used. Note that only the private and public keys have been created but no certificates are stored in the key slots. In fact, GnuPG uses its own non-standard method to store just the public key in place of -the the certificate. Other application will not be able to make use +the certificate. Other application will not be able to make use these keys until @command{gpgsm} or another tool has been used to create and store the respective certificates. Let us see what the list command now shows: diff --git a/doc/gpg.texi b/doc/gpg.texi index 8755b9455..446189b4b 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -330,21 +330,21 @@ The status of the verification is indicated by a flag directly following the "sig" tag (and thus before the flags described below. A "!" indicates that the signature has been successfully verified, a "-" denotes a bad signature and a "%" is used if an error occurred while -checking the signature (e.g. a non supported algorithm). Signatures +checking the signature (e.g., a non supported algorithm). Signatures where the public key is not available are not listed; to see their keyids the command @option{--list-sigs} can be used. For each signature listed, there are several flags in between the signature status flag and keyid. These flags give additional information about each key signature. From left to right, they are -the numbers 1-3 for certificate check level (see +the numbers 1--3 for certificate check level (see @option{--ask-cert-level}), "L" for a local or non-exportable signature (see @option{--lsign-key}), "R" for a nonRevocable signature (see the @option{--edit-key} command "nrsign"), "P" for a signature that contains a policy URL (see @option{--cert-policy-url}), "N" for a signature that contains a notation (see @option{--cert-notation}), "X" for an eXpired signature (see @option{--ask-cert-expire}), and the -numbers 1-9 or "T" for 10 and above to indicate trust signature levels +numbers 1--9 or "T" for 10 and above to indicate trust signature levels (see the @option{--edit-key} command "tsign"). @@ -362,9 +362,9 @@ public keys are listed. The variant @option{--locate-external-keys} does not consider a locally existing key and can thus be used to force the refresh of a key via the defined external methods. If a fingerprint is given and -and the methods defined by --auto-key-locate define LDAP servers, the -key is fetched from these resources; defined non-LDAP keyservers are -skipped. +and the methods defined by @option{--auto-key-locate} define LDAP +servers, the key is fetched from these resources; defined non-LDAP +keyservers are skipped. @item --show-keys @@ -405,7 +405,7 @@ description, please see the Card HOWTO at https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO . Please note that the command "openpgp" can be used to switch to the OpenPGP application of cards which by default are presenting another -application (e.g. PIV). +application (e.g., PIV). @item --card-status @opindex card-status @@ -589,7 +589,7 @@ corrupted trustdb. Example: Update the trustdb with the ownertrust values stored in @code{files} (or STDIN if not given); existing values will be overwritten. In case of a severely damaged trustdb and if you have a recent backup of the -ownertrust values (e.g. in the file @file{otrust.txt}), you may re-create +ownertrust values (e.g., in the file @file{otrust.txt}), you may re-create the trustdb using these commands: @c man:.RS @example @@ -892,7 +892,7 @@ signing. @item delsig @opindex keyedit:delsig Delete a signature. Note that it is not possible to retract a signature, - once it has been send to the public (i.e. to a keyserver). In that case + once it has been send to the public (i.e., to a keyserver). In that case you better use @code{revsig}. @item revsig @@ -926,7 +926,7 @@ signing. @opindex keyedit:deluid Delete a user ID or photographic user ID. Note that it is not possible to retract a user id, once it has been send to the public - (i.e. to a keyserver). In that case you better use @code{revuid}. + (i.e., to a keyserver). In that case you better use @code{revuid}. @item revuid @opindex keyedit:revuid @@ -1005,13 +1005,13 @@ signing. @item keytocard @opindex keyedit:keytocard Transfer the selected secret subkey (or the primary key if no subkey - has been selected) to a smartcard. The secret key in the keyring will - be replaced by a stub if the key could be stored successfully on the - card and you use the save command later. Only certain key types may be - transferred to the card. A sub menu allows you to select on what card - to store the key. Note that it is not possible to get that key back - from the card - if the card gets broken your secret key will be lost - unless you have a backup somewhere. + has been selected) to a smartcard. The secret key in the keyring + will be replaced by a stub if the key could be stored successfully + on the card and you use the save command later. Only certain key + types may be transferred to the card. A sub menu allows you to + select on what card to store the key. Note that it is not possible + to get that key back from the card --- if the card gets broken your + secret key will be lost unless you have a backup somewhere. @item bkuptocard @var{file} @opindex keyedit:bkuptocard @@ -1046,7 +1046,7 @@ signing. @item delkey @opindex keyedit:delkey Remove a subkey (secondary key). Note that it is not possible to retract - a subkey, once it has been send to the public (i.e. to a keyserver). In + a subkey, once it has been send to the public (i.e., to a keyserver). In that case you better use @code{revkey}. Also note that this only deletes the public part of a key. @@ -1098,7 +1098,7 @@ signing. @item clean @opindex keyedit:clean Compact (by removing all signatures except the selfsig) any user ID - that is no longer usable (e.g. revoked, or expired). Then, remove any + that is no longer usable (e.g., revoked, or expired). Then, remove any signatures that are not usable by the trust calculations. Specifically, this removes any signature that does not validate, any signature that is superseded by a later signature, revoked signatures, @@ -1112,7 +1112,7 @@ signing. @item change-usage @opindex keyedit:change-usage Change the usage flags (capabilities) of the primary key or of - subkeys. These usage flags (e.g. Certify, Sign, Authenticate, + subkeys. These usage flags (e.g., Certify, Sign, Authenticate, Encrypt) are set during key creation. Sometimes it is useful to have the opportunity to change them (for example to add Authenticate) after they have been created. Please take care when @@ -1272,13 +1272,13 @@ behaviour and to change the default configuration. @end menu Long options can be put in an options file (default -"~/.gnupg/gpg.conf"). Short option names will not work - for example, -"armor" is a valid option for the options file, while "a" is not. Do not -write the 2 dashes, but simply the name of the option and any required -arguments. Lines with a hash ('#') as the first non-white-space -character are ignored. Commands may be put in this file too, but that is -not generally useful as the command will execute automatically with -every execution of gpg. +"~/.gnupg/gpg.conf"). Short option names will not work --- for +example, "armor" is a valid option for the options file, while "a" is +not. Do not write the 2 dashes, but simply the name of the option and +any required arguments. Lines with a hash ('#') as the first +non-white-space character are ignored. Commands may be put in this +file too, but that is not generally useful as the command will execute +automatically with every execution of gpg. Please remember that option parsing stops as soon as a non-option is encountered, you can explicitly stop parsing by using the special option @@ -1422,6 +1422,18 @@ give the opposite meaning. The options are: Show all, IETF standard, or user-defined signature notations in the @option{--check-signatures} listings. Defaults to no. + @item show-x509-notations + @opindex list-options:show-x509-notations + Print X.509 certificates embedded in key signatures as PEM data. + This is intended for debugging and the output format may change + without notice. + + @item store-x509-notations + @opindex list-options:store-x509-notations + Store X.509 certificates embedded in key signatures as PEM data + files. The filename consists the 4 byte key ID of the certificate, + a dash, the fingerprint of the key or subkey, and the suffix ".pem". + @item show-keyserver-urls @opindex list-options:show-keyserver-urls Show any preferred keyserver URL in the @@ -1469,10 +1481,10 @@ give the opposite meaning. The options are: @item sort-sigs @opindex list-options:sort-sigs - With --list-sigs and --check-sigs sort the signatures by keyID and - creation time to make it easier to view the history of these - signatures. The self-signature is also listed before other - signatures. Defaults to yes. + With @option{--list-sigs} and @option{--check-sigs} sort the + signatures by keyID and creation time to make it easier to view the + history of these signatures. The self-signature is also listed + before other signatures. Defaults to yes. @end table @@ -1529,12 +1541,12 @@ the opposite meaning. The options are: @itemx --disable-large-rsa @opindex enable-large-rsa @opindex disable-large-rsa -With --generate-key and --batch, enable the creation of RSA secret keys as -large as 8192 bit. Note: 8192 bit is more than is generally -recommended. These large keys don't significantly improve security, -but they are more expensive to use, and their signatures and -certifications are larger. This option is only available if the -binary was build with large-secmem support. +With @option{--generate-key} and @option{--batch}, enable the creation +of RSA secret keys as large as 8192 bit. Note: 8192 bit is more than +is generally recommended. These large keys don't significantly +improve security, but they are more expensive to use, and their +signatures and certifications are larger. This option is only +available if the binary was build with large-secmem support. @item --enable-dsa2 @itemx --disable-dsa2 @@ -1552,9 +1564,9 @@ will be expanded to a filename containing the photo. "%I" does the same, except the file will not be deleted once the viewer exits. Other flags are "%k" for the key ID, "%K" for the long key ID, "%f" for the key fingerprint, "%t" for the extension of the image type -(e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), +(e.g., "jpg"), "%T" for the MIME type of the image (e.g., "image/jpeg"), "%v" for the single-character calculated validity of the image being -viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g. +viewed (e.g., "f"), "%V" for the calculated validity as a string (e.g., "full"), "%U" for a base32 encoded hash of the user ID, and "%%" for an actual percent sign. If neither %i or %I are present, then the photo will be supplied to the viewer on standard input. @@ -2058,7 +2070,7 @@ default), that keyserver is tried. Note that the creator of the signature uses the option @option{--sig-keyserver-url} to specify the preferred keyserver for data signatures. -3. If the signature has the Signer's UID set (e.g. using +3. If the signature has the Signer's UID set (e.g., using @option{--sender} while creating the signature) a Web Key Directory (WKD) lookup is done. This is the default configuration but can be disabled by removing WKD from the auto-key-locate list or by using the @@ -2086,7 +2098,7 @@ option is ignored if the option @option{--with-colons} is used. @item --keyserver @var{name} @opindex keyserver -This option is deprecated - please use the @option{--keyserver} in +This option is deprecated --- please use the @option{--keyserver} in @file{dirmngr.conf} instead. Use @var{name} as your keyserver. This is the server that @@ -2306,7 +2318,7 @@ suppressed on the command line. @itemx --no-require-secmem @opindex require-secmem Refuse to run if GnuPG cannot get secure memory. Defaults to no -(i.e. run, but give a warning). +(i.e., run, but give a warning). @item --require-cross-certification @@ -2438,7 +2450,7 @@ id used to make the signature and embeds that user ID into the created signature (using OpenPGP's ``Signer's User ID'' subpacket). If the option is given multiple times a suitable user ID is picked. However, if the signing key was specified directly by using a mail address -(i.e. not by using a fingerprint or key ID) this option is used and +(i.e., not by using a fingerprint or key ID) this option is used and the mail address is embedded in the created signature. When verifying a signature @var{mbox} is used to restrict the @@ -2547,7 +2559,7 @@ the @option{--status-fd} line ``PROGRESS'' to provide a value for @item --key-origin @var{string}[,@var{url}] @opindex key-origin gpg can track the origin of a key. Certain origins are implicitly -known (e.g. keyserver, web key directory) and set. For a standard +known (e.g., keyserver, web key directory) and set. For a standard import the origin of the keys imported can be set with this option. To list the possible values use "help" for @var{string}. Some origins can store an optional @var{url} argument. That URL can appended to @@ -2669,12 +2681,12 @@ The available filter types are: @item drop-subkey This filter drops the selected subkeys. - Currently only implemented for --export-filter. + Currently only implemented for @option{--export-filter}. @item drop-sig This filter drops the selected key signatures on user ids. Self-signatures are not considered. - Currently only implemented for --import-filter. + Currently only implemented for @option{--import-filter}. @item select This filter is only implemented by @option{--list-filter}. All @@ -2719,13 +2731,13 @@ The available properties are: @itemx key_created_d The first is the timestamp a public key or subkey packet was created. The second is the same but given as an ISO string, - e.g. "2016-08-17". (drop-subkey) + e.g., "2016-08-17". (drop-subkey) @item key_expires @itemx key_expires_d The expiration time of a public key or subkey or 0 if it does not expire. The second is the same but given as an ISO date string or - an empty string e.g. "2038-01-19". + an empty string e.g., "2038-01-19". @item fpr The hexified fingerprint of the current subkey or primary key. @@ -2758,7 +2770,7 @@ The available properties are: @itemx sig_created_d The first is the timestamp a signature packet was created. The second is the same but given as an ISO date string, - e.g. "2016-08-17". (drop-sig) + e.g., "2016-08-17". (drop-sig) @item sig_expires @itemx sig_expires_d @@ -2884,7 +2896,7 @@ obsolete; it does not harm to use it though. @opindex legacy-list-mode Revert to the pre-2.1 public key list mode. This only affects the human readable output and not the machine interface -(i.e. @code{--with-colons}). Note that the legacy format does not +(i.e., @code{--with-colons}). Note that the legacy format does not convey suitable information for elliptic curves. @item --with-fingerprint @@ -2893,12 +2905,15 @@ Same as the command @option{--fingerprint} but changes only the format of the output and may be used together with another command. @item --with-subkey-fingerprint +@itemx --without-subkey-fingerprint @opindex with-subkey-fingerprint +@opindex without-subkey-fingerprint If a fingerprint is printed for the primary key, this option forces printing of the fingerprint for all subkeys. This could also be achieved by using the @option{--with-fingerprint} twice but by using -this option along with keyid-format "none" a compact fingerprint is -printed. +this option along with the default keyid-format "none" a compact +fingerprint is printed. Since version 2.6.0 this option is active by +default; use the ``without'' variant to disable it. @item --with-v5-fingerprint @opindex with-v5-fingerprint @@ -3002,7 +3017,7 @@ to safely override the algorithm chosen by the recipient key preferences, as GPG will only select an algorithm that is usable by all recipients. The most highly ranked digest algorithm in this list is also used when signing without encryption -(e.g. @option{--clear-sign} or @option{--sign}). +(e.g., @option{--clear-sign} or @option{--sign}). @item --personal-compress-preferences @var{string} @opindex personal-compress-preferences @@ -3013,7 +3028,7 @@ allows the user to safely override the algorithm chosen by the recipient key preferences, as GPG will only select an algorithm that is usable by all recipients. The most highly ranked compression algorithm in this list is also used when there are no recipient keys -to consider (e.g. @option{--symmetric}). +to consider (e.g., @option{--symmetric}). @item --s2k-cipher-algo @var{name} @opindex s2k-cipher-algo @@ -3039,7 +3054,7 @@ of times (see @option{--s2k-count}). Specify how many times the passphrases mangling for symmetric encryption is repeated. This value may range between 1024 and 65011712 inclusive. The default is inquired from gpg-agent. Note -that not all values in the 1024-65011712 range are legal and if an +that not all values in the 1024--65011712 range are legal and if an illegal value is selected, GnuPG will round up to the nearest legal value. This option is only meaningful if @option{--s2k-mode} is set to the default of 3. @@ -3131,6 +3146,15 @@ This option adjusts the compliance mode "de-vs" for stricter key size requirements. For example, a value of 3000 turns rsa2048 and dsa2048 keys into non-VS-NfD compliant keys. +@item --require-pqc-encryption +@opindex require-pqc-encryption +This option forces the use of quantum-resistant encryption algorithms. +If not all public keys are quantum-resistant the encryption will fail. +On decryption a warning is printed for all non-quantum-resistant keys. +As of now the Kyber (ML-KEM768 and ML-KEM1024) algorithms are +considered quantum-resistant; Kyber is always used in a composite +scheme along with a classic ECC algorithm. + @item --require-compliance @opindex require-compliance To check that data has been encrypted according to the rules of the @@ -3209,7 +3233,7 @@ however carefully selected to best aid in debugging. @item --debug @var{flags} @opindex debug Set debug flags. All flags are or-ed and @var{flags} may be given -in C syntax (e.g. 0x0042) or as a comma separated list of flag names. +in C syntax (e.g., 0x0042) or as a comma separated list of flag names. To get a list of all supported flags the single word "help" can be used. This option is only useful for debugging and the behavior may change at any time without notice. @@ -3244,7 +3268,7 @@ only useful for certain regression tests. 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. Alternatively @var{epoch} may be given as a full ISO -time string (e.g. "20070924T154812"). +time string (e.g., "20070924T154812"). If you suffix @var{epoch} with an exclamation mark (!), the system time will appear to be frozen at the specified time. @@ -3584,7 +3608,7 @@ are: @opindex no-symkey-cache Disable the passphrase cache used for symmetrical en- and decryption. This cache is based on the message specific salt value -(cf. @option{--s2k-mode}). +(cf.@: @option{--s2k-mode}). @item --request-origin @var{origin} @opindex request-origin @@ -3856,6 +3880,12 @@ This option enables a mode in which filenames of the form @file{-&n}, where n is a non-negative decimal number, refer to the file descriptor n and not to a file with that name. +@item --disable-fd-translation +@opindex disable-fd-translation +This option changes the behaviour for all following options to expect +libc file descriptors instead of HANDLE values on the command line. +The option has an effect only on Windows. + @item --no-expensive-trust-checks @opindex no-expensive-trust-checks Experimental use only. @@ -4672,7 +4702,7 @@ If you don't give any of them, no user ID is created. @item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y]) Set the expiration date for the key (and the subkey). It may either -be entered in ISO date format (e.g. "20000815T145012") or as number of +be entered in ISO date format (e.g., "20000815T145012") or as number of days, weeks, month or years after the creation date. The special notation "seconds=N" is also allowed to specify a number of seconds since creation. Without a letter days are assumed. Note that there diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index d00ad447e..1316318a6 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -136,7 +136,7 @@ Run in server mode and wait for commands on the @code{stdin}. Behave as a Dirmngr client issuing the request @var{command} with the optional list of @var{args}. The output of the Dirmngr is printed stdout. Please note that file names given as arguments should have an -absolute file name (i.e. commencing with @code{/}) because they are +absolute file name (i.e., commencing with @code{/}) because they are passed verbatim to the Dirmngr and the working directory of the Dirmngr might not be the same as the one of this client. Currently it is not possible to pass data via stdin to the Dirmngr. @var{command} @@ -259,7 +259,7 @@ optional @var{pattern}. Those pattern consist of a list of user ids @option{--armor} option a few informational lines are prepended before each block. There is one limitation: As there is no commonly agreed upon way to pack more than one certificate into an ASN.1 structure, -the binary export (i.e. without using @option{armor}) works only for +the binary export (i.e., without using @option{armor}) works only for the export of one certificate. Thus it is required to specify a @var{pattern} which yields exactly one certificate. Ephemeral certificate are only exported if all @var{pattern} are given as @@ -462,7 +462,7 @@ line of the @file{trustlist.txt} @opindex force-crl-refresh Tell the dirmngr to reload the CRL for each request. For better performance, the dirmngr will actually optimize this by suppressing -the loading for short time intervals (e.g. 30 minutes). This option +the loading for short time intervals (e.g., 30 minutes). This option is useful to make sure that a fresh CRL is available for certificates hold in the keybox. The suggested way of doing this is by using it along with the option @option{--with-validation} for a key listing @@ -539,7 +539,7 @@ Create PEM encoded output. Default is binary output. @item --base64 @opindex base64 -Create Base-64 encoded output; i.e. PEM without the header lines. +Create Base-64 encoded output; i.e., PEM without the header lines. @item --assume-armor @opindex assume-armor @@ -639,11 +639,11 @@ done with @code{--with-colons}. @item --no-pretty-dn @opindex no-pretty-dn By default gpgsm prints distinguished names (DNs) like the Issuer or -Subject in a more readable format (e.g. using a well defined order of +Subject in a more readable format (e.g., using a well defined order of the parts). However, this format can't be used as input strings. This option reverts printing to standard RFC-2253 format and thus -avoids the need to use --dump-cert or --with-colons to get the -``real'' name. +avoids the need to use @option{--dump-cert} or @option{--with-colons} +to get the ``real'' name. @end table @@ -754,7 +754,7 @@ key database clear of unneeded certificates stored on smartcards. 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. Alternatively @var{epoch} may be given as a full ISO time string -(e.g. "20070924T154812"). +(e.g., "20070924T154812"). @item --with-ephemeral-keys @opindex with-ephemeral-keys @@ -770,6 +770,18 @@ list of flag names and are OR-ed together. The special flag "none" clears the list and allows one to start over with an empty list. To get a list of available flags the sole word "help" can be used. +@item --enable-special-filenames +@opindex enable-special-filenames +This option enables a mode in which filenames of the form +@file{-&n}, where n is a non-negative decimal number, +refer to the file descriptor n and not to a file with that name. + +@item --disable-fd-translation +@opindex disable-fd-translation +This option changes the behaviour for all following options to expect +libc file descriptors instead of HANDLE values on the command line. +The option has an effect only on Windows. + @item --debug-level @var{level} @opindex debug-level Select the debug level for investigating problems. @var{level} may be @@ -801,7 +813,7 @@ however carefully selected to best aid in debugging. @item --debug @var{flags} @opindex debug Set debug flags. All flags are or-ed and @var{flags} may be given -in C syntax (e.g. 0x0042) or as a comma separated list of flag names. +in C syntax (e.g., 0x0042) or as a comma separated list of flag names. To get a list of all supported flags the single word "help" can be used. This option is only useful for debugging and the behavior may change at any time without notice. @@ -974,9 +986,9 @@ This is plain text file with a few help entries used with @command{gpg} and @command{gpgsm}. The standard file has English help texts; to install localized versions use filenames like @file{help.LL.txt} with LL denoting the locale. GnuPG comes with a set of predefined help -files in the data directory (e.g. @file{@value{DATADIR}/gnupg/help.de.txt}) +files in the data directory (e.g., @file{@value{DATADIR}/gnupg/help.de.txt}) and allows overriding of any help item by help files stored in the -system configuration directory (e.g. @file{@value{SYSCONFDIR}/help.de.txt}). +system configuration directory (e.g., @file{@value{SYSCONFDIR}/help.de.txt}). For a reference of the help file's syntax, please see the installed @file{help.txt} file. @@ -987,11 +999,10 @@ This file is a collection of common certificates used to populated a newly created @file{pubring.kbx}. An administrator may replace this file with a custom one. The format is a concatenation of PEM encoded X.509 certificates. This global file is installed in the data directory -(e.g. @file{@value{DATADIR}/com-certs.pem}). +(e.g., @file{@value{DATADIR}/com-certs.pem}). @end table -@c man:.RE Note that on larger installations, it is useful to put predefined files into the directory @file{/etc/skel/.gnupg/} so that newly created users start up with a working configuration. For existing users a small @@ -1100,7 +1111,7 @@ of a transfer error, a program error or tampering with the message). @end table @item Error verifying a signature -For some reason the signature could not be verified, i.e. it cannot be +For some reason the signature could not be verified, i.e., it cannot be decided whether the signature is valid or invalid. A common reason for this is a missing certificate. @@ -1281,7 +1292,7 @@ provides a regular command line interface which exhibits a full client to this protocol (but uses internal linking). To start @command{gpgsm} as a server the command line the option @code{--server} must be used. Additional options are provided to -select the communication method (i.e. the name of the socket). +select the communication method (i.e., the name of the socket). We assume that the connection has already been established; see the Assuan manual for details. @@ -1345,7 +1356,7 @@ correct. OUTPUT FD[=@var{n}] [--armor|--base64] @end example -Set the file descriptor to be used for the output (i.e. the encrypted +Set the file descriptor to be used for the output (i.e., the encrypted message). Obviously the pipe must be open at that point, the server establishes its own end. If the server returns an error the client should consider this session failed. @@ -1388,11 +1399,11 @@ The decryption is done by using the command DECRYPT @end example -It performs the decrypt operation after doing some check on the internal -state (e.g. that all needed data has been set). Because it utilizes -the GPG-Agent for the session key decryption, there is no need to ask -the client for a protecting passphrase - GpgAgent takes care of this by -requesting this from the user. +It performs the decrypt operation after doing some check on the +internal state (e.g., that all needed data has been set). Because it +utilizes the GPG-Agent for the session key decryption, there is no +need to ask the client for a protecting passphrase --- GpgAgent takes +care of this by requesting this from the user. @node GPGSM SIGN diff --git a/doc/gpgv.texi b/doc/gpgv.texi index 54ab23383..cbaea40e5 100644 --- a/doc/gpgv.texi +++ b/doc/gpgv.texi @@ -91,7 +91,7 @@ Add @var{file} to the list of keyrings. If @var{file} begins with a tilde and a slash, these are replaced by the HOME directory. If the filename does not contain a slash, it is assumed to be in the -home-directory ("~/.gnupg" if --homedir is not used). +home-directory ("~/.gnupg" if @option{--homedir} is not used). @item --output @var{file} @itemx -o @var{file} @@ -184,10 +184,18 @@ If set directory used instead of "~/.gnupg". @mansect files @subsection FILES -@table @asis +Default keyring file is expected in the GnuPG home directory +(@pxref{option --homedir}, @code{GNUPGHOME}). + +@table @file +@item ~/.gnupg/trustedkeys.kbx +@efindex trustedkeys.kbx +The default keyring with the allowed keys, using the new keybox format. @item ~/.gnupg/trustedkeys.gpg -The default keyring with the allowed keys. +@efindex trustedkeys.gpg +When @file{trustedkeys.kbx} is not available, the default keyring with +the allowed keys, using a legacy format. @end table diff --git a/doc/howto-create-a-server-cert.texi b/doc/howto-create-a-server-cert.texi index 30e28bdd0..de5a9470f 100644 --- a/doc/howto-create-a-server-cert.texi +++ b/doc/howto-create-a-server-cert.texi @@ -80,7 +80,7 @@ would anyway ignore such a request. Thus just hit enter. If you want to create a client certificate for email encryption, this would be the place to enter your mail address -(e.g. @email{joe@@example.org}). You may enter as many addresses as you like, +(e.g., @email{joe@@example.org}). You may enter as many addresses as you like, however the CA may not accept them all or reject the entire request. @cartouche diff --git a/doc/keyformat.txt b/doc/keyformat.txt new file mode 100644 index 000000000..dadfed4eb --- /dev/null +++ b/doc/keyformat.txt @@ -0,0 +1,520 @@ +keyformat.txt emacs, please switch to -*- org -*- mode +------------- + + +Some notes on the format of the secret keys used with gpg-agent. + +* Location of keys + +The secret keys[1] are stored on a per file basis in a directory below +the ~/.gnupg home directory. This directory is named + + private-keys-v1.d + +and should have permissions 700. + +The secret keys are stored in files with a name matching the +hexadecimal representation of the keygrip[2] and suffixed with ".key". + +* Extended Private Key Format + +** Overview +GnuPG 2.3+ uses a new format to store private keys that is both +more flexible and easier to read and edit by human beings. The new +format stores name,value-pairs using the common mail and http header +convention. Example (here indented with two spaces): + + Description: Key to sign all GnuPG released tarballs. + The key is actually stored on a smart card. + Use-for-ssh: yes + OpenSSH-cert: long base64 encoded string wrapped so that this + key file can be easily edited with a standard editor. + Token: D2760001240102000005000011730000 OPENPGP.1 - + Token: FF020001008A77C1 PIV.9C - + Key: (shadowed-private-key + (rsa + (n #00AA1AD2A55FD8C8FDE9E1941772D9CC903FA43B268CB1B5A1BAFDC900 + 2961D8AEA153424DC851EF13B83AC64FBE365C59DC1BD3E83017C90D4365B4 + 83E02859FC13DB5842A00E969480DB96CE6F7D1C03600392B8E08EF0C01FC7 + 19F9F9086B25AD39B4F1C2A2DF3E2BE317110CFFF21D4A11455508FE407997 + 601260816C8422297C0637BB291C3A079B9CB38A92CE9E551F80AA0EBF4F0E + 72C3F250461E4D31F23A7087857FC8438324A013634563D34EFDDCBF2EA80D + F9662C9CCD4BEF2522D8BDFED24CEF78DC6B309317407EAC576D889F88ADA0 + 8C4FFB480981FB68C5C6CA27503381D41018E6CDC52AAAE46B166BDC10637A + E186A02BA2497FDC5D1221#) + (e #00010001#) + (shadowed t1-v1 + (#D2760001240102000005000011730000# OPENPGP.1) + ))) + +GnuPG 2.2 is also able to read and write keys using the new format +However, it only makes use of some of the values. + +Keys in the extended format can be recognized by looking at the first +byte of the file. If it starts with a '(' it is a naked S-expression, +otherwise it is a key in extended format. + +*** Names +A name must start with a letter and end with a colon. Valid +characters are all ASCII letters, numbers and the hyphen. Comparison +of names is done case insensitively. Names may be used several times +to represent an array of values. Note that the name "Key" is special +in that it is mandatory and must occur only once. + +*** Values +Values are UTF-8 encoded strings. Values can be wrapped at any point, +and continued in the next line indicated by leading whitespace. A +continuation line with one leading space does not introduce a blank so +that the lines can be effectively concatenated. A blank line as part +of a continuation line encodes a newline. + +*** Comments +Lines containing only whitespace, and lines starting with whitespace +followed by '#' are considered to be comments and are ignored. + +** Well known names +*** Description +This is a human readable string describing the key. + +*** Key +The name "Key" is special in that it is mandatory and must occur only +once. The associated value holds the actual S-expression with the +cryptographic key. The S-expression is formatted using the 'Advanced +Format' (GCRYSEXP_FMT_ADVANCED) that avoids non-printable characters +so that the file can be easily inspected and edited. See section +'Private Key Format' below for details. + +*** Created +The UTC time the key was created in ISO compressed format +(yyyymmddThhmmss). This information can be used to re-create an +OpenPGP key. + +*** Label +This is a short human readable description for the key which can be +used by the software to describe the key in a user interface. For +example as part of the description in a prompt for a PIN or +passphrase. It is often used instead of a comment element as present +in the S-expression of the "Key" item. + +*** OpenSSH-cert +This takes a base64 encoded string wrapped so that this +key file can be easily edited with a standard editor. Several of such +items can be used. + +*** Token +If such an item exists it overrides the info given by the "shadow" +parameter in the S-expression. Using this item makes it possible to +describe a key which is stored on several tokens and also makes it +easy to update this info using a standard editor. The syntax is +similar to the "shadow" parameter: + +- Serialnumber of the token. +- Key reference from the token in full format (e.g. "OpenPGP.2"). +- An optional fixed length of the PIN or "-". +- The human readable serial number of a card. This is usually what is + printed on the actual card. This value is taken directly from the + card but when asking to insert a card it is useful to have this + value available. GnuPG takes care of creating and possibly updating + this entry. This is percent-plus-escaped. + + +*** Use-for-ssh +If given and the value is "yes" or "1" the key is allowed for use by +gpg-agent's ssh-agent implementation. This is thus the same as +putting the keygrip into the 'sshcontrol' file. Only one such item +should exist. If another non-zero value between 1 and 99999 is used, +this is taken to establish the order in which the keys are returned to +ssh; lower numbers are returned first. If a negative value is used +this overrides currently active (inserted) cards and thus allows to +prefer on-disk keys over inserted cards. A value of -1 has the +highest priority; values are capped at -999 and have a lower priority +but still above the positive values, inserted cards or the order in +sshcontrol. + + +*** Use-for-p11 +If given and the value is "yes" or "1" the key is allowed for use by +GnuPG's PKCS#11 interface (Scute). Note that Scute needs to be +configured to use this optimization. + +*** Remote-list +Allow to list the key with the KEYINFO command from a remote machine +via the extra socket. A boolean value is expected; the default is +"no". Note that KEYINFO will anyway provide information if the +keygrip is specified. + +*** Confirm +If given and the value is "yes", a user will be asked confirmation by +a dialog window when the key is about to be used for +PKSIGN/PKAUTH/PKDECRYPT operation. If the value is "restricted", it +is only asked for the access through extra/browser socket. + +*** Prompt +This field is for card key. If given and the value is "yes" +(default), a user will be prompted about insertion of the card by a +dialog window when card is not available. When the value is "no", a +card operation is refused with GPG_ERR_UNUSABLE_SECKEY error. + +*** Backup-info +This gives information for a backup of the key. The following fields +are space delimited: + +- Hexified keygrip (uppercase) to make it easy to identify the + filename. When restoring software should make sure that the keygrip + matches the one derived from the "Key" field. +- Backup time in as ISO string. +- Name of the backup software. +- Arbitrary information. + +* Private Key Format +** Unprotected Private Key Format + +The content of the file is an S-Expression like the ones used with +Libgcrypt. Here is an example of an unprotected file: + +(private-key + (rsa + (n #00e0ce9..[some bytes not shown]..51#) + (e #010001#) + (d #046129F..[some bytes not shown]..81#) + (p #00e861b..[some bytes not shown]..f1#) + (q #00f7a7c..[some bytes not shown]..61#) + (u #304559a..[some bytes not shown]..9b#) + ) + (created-at timestamp) + (uri http://foo.bar x-foo:whatever_you_want) + (comment whatever) +) + +"comment", "created-at" and "uri" are optional. "comment" is +currently used to keep track of ssh key comments. "created-at" is used +to keep track of the creation time stamp used with OpenPGP keys; it is +optional but required for some operations to calculate the fingerprint +of the key. This timestamp should be a string with the number of +seconds since Epoch or an ISO time string (yyyymmddThhmmss). + +** Protected Private Key Format + +A protected key is like this: + +(protected-private-key + (rsa + (n #00e0ce9..[some bytes not shown]..51#) + (e #010001#) + (protected mode (parms) encrypted_octet_string) + (protected-at <isotimestamp>) + ) + (uri http://foo.bar x-foo:whatever_you_want) + (comment whatever) +) + + +In this scheme the encrypted_octet_string is encrypted according to +the algorithm described after the keyword protected; most protection +algorithms need some parameters, which are given in a list before the +encrypted_octet_string. The result of the decryption process is a +list of the secret key parameters. The protected-at expression is +optional; the isotimestamp is 15 bytes long (e.g. "19610711T172000"). + +The currently defined protection modes are: + +*** openpgp-s2k3-sha1-aes-cbc + + This describes an algorithm using AES in CBC mode for + encryption, SHA-1 for integrity protection and the String to Key + algorithm 3 from OpenPGP (rfc4880). + + Example: + + (protected openpgp-s2k3-sha1-aes-cbc + ((sha1 16byte_salt no_of_iterations) 16byte_iv) + encrypted_octet_string + ) + + The encrypted_octet string should yield this S-Exp (in canonical + representation) after decryption: + + ( + ( + (d #046129F..[some bytes not shown]..81#) + (p #00e861b..[some bytes not shown]..f1#) + (q #00f7a7c..[some bytes not shown]..61#) + (u #304559a..[some bytes not shown]..9b#) + ) + (hash sha1 #...[hashvalue]...#) + ) + + For padding reasons, random bytes are appended to this list - they can + easily be stripped by looking for the end of the list. + + The hash is calculated on the concatenation of the public key and + secret key parameter lists: i.e. it is required to hash the + concatenation of these 6 canonical encoded lists for RSA, including + the parenthesis, the algorithm keyword and (if used) the protected-at + list. + + (rsa + (n #00e0ce9..[some bytes not shown]..51#) + (e #010001#) + (d #046129F..[some bytes not shown]..81#) + (p #00e861b..[some bytes not shown]..f1#) + (q #00f7a7c..[some bytes not shown]..61#) + (u #304559a..[some bytes not shown]..9b#) + (protected-at "18950523T000000") + ) + + After decryption the hash must be recalculated and compared against + the stored one - If they don't match the integrity of the key is not + given. + +*** openpgp-s2k3-ocb-aes + + This describes an algorithm using AES-128 in OCB mode, a nonce + of 96 bit, a taglen of 128 bit, and the String to Key algorithm 3 + from OpenPGP (rfc4880). + + Example: + + (protected openpgp-s2k3-ocb-aes + ((sha1 16byte_salt no_of_iterations) 12byte_nonce) + encrypted_octet_string + ) + + The encrypted_octet string should yield this S-Exp (in canonical + representation) after decryption: + + ( + ( + (d #046129F..[some bytes not shown]..81#) + (p #00e861b..[some bytes not shown]..f1#) + (q #00f7a7c..[some bytes not shown]..61#) + (u #304559a..[some bytes not shown]..9b#) + ) + ) + + For padding reasons, random bytes may be appended to this list - + they can easily be stripped by looking for the end of the list. + + The associated data required for this protection mode is the list + forming the public key parameters. For the above example this is + is this canonical encoded S-expression: + + (rsa + (n #00e0ce9..[some bytes not shown]..51#) + (e #010001#) + (protected-at "18950523T000000") + ) + +*** openpgp-native + + This is a wrapper around the OpenPGP Private Key Transport format + which resembles the standard OpenPGP format and allows the use of an + existing key without re-encrypting to the default protection format. + + Example: + + (protected openpgp-native + (openpgp-private-key + (version V) + (algo PUBKEYALGO) + (skey _ P1 _ P2 _ P3 ... e PN) + (csum n) + (protection PROTTYPE PROTALGO IV S2KMODE S2KHASH S2KSALT S2KCOUNT))) + + Note that the public key parameters in SKEY are duplicated and + should be identical to their copies in the standard parameter + elements. Here is an example of an entire protected private key + using this format: + + (protected-private-key + (rsa + (n #00e0ce9..[some bytes not shown]..51#) + (e #010001#) + (protected openpgp-native + (openpgp-private-key + (version 4) + (algo rsa) + (skey _ #00e0ce9..[some bytes not shown]..51# + _ #010001# + e #.........................#) + (protection sha1 aes #aabbccddeeff00112233445566778899# + 3 sha1 #2596f93e85f41e53# 3:190)))) + (uri http://foo.bar x-foo:whatever_you_want) + (comment whatever)) + +** Shadowed Private Key Format + +To keep track of keys stored on IC cards we use a third format for +private keys which are called shadow keys as they are only a reference +to keys stored on a token: + +(shadowed-private-key + (rsa + (n #00e0ce9..[some bytes not shown]..51#) + (e #010001#) + (shadowed protocol (info)) + ) + (uri http://foo.bar x-foo:whatever_you_want) + (comment whatever) +) + +The currently used protocols are "t1-v1" (token info version 1) and +"tpm2-v1" (TPM format key information). The second list with the +information has this layout for "t1-v1": + +(card_serial_number id_string_of_key fixed_pin_length) + +FIXED_PIN_LENGTH is optional. It can be used to store the length of +the PIN; a value of 0 indicates that this information is not +available. The rationale for this field is that some pinpad equipped +readers don't allow passing a variable length PIN. + +This is the (info) layout for "tpm2-v1": + +(parent tpm_private_string tpm_public_string) + +Although this precise format is encapsulated inside the tpm2daemon +itself and nothing in gpg ever uses this. + +More items may be added to the list. + +** OpenPGP Private Key Transfer Format + +This format is used to transfer keys between gpg and gpg-agent. + +(openpgp-private-key + (version V) + (algo PUBKEYALGO) + (curve CURVENAME) + (skey _ P1 _ P2 _ P3 ... e PN) + (csum n) + (protection PROTTYPE PROTALGO IV S2KMODE S2KHASH S2KSALT S2KCOUNT)) + + + * V is the packet version number (3 or 4). + * PUBKEYALGO is a Libgcrypt algo name + * CURVENAME is the name of the curve - only used with ECC. + * P1 .. PN are the parameters; the public parameters are never encrypted + the secret key parameters are encrypted if the "protection" list is + given. To make this more explicit each parameter is preceded by a + flag "_" for cleartext or "e" for encrypted text. + * CSUM is the deprecated 16 bit checksum as defined by OpenPGP. This + is an optional element. + * If PROTTYPE is "sha1" the new style SHA1 checksum is used if it is "sum" + the old 16 bit checksum (above) is used and if it is "none" no + protection at all is used. + * PROTALGO is a Libgcrypt style cipher algorithm name + * IV is the initialization vector. + * S2KMODE is the value from RFC-4880. + * S2KHASH is a libgcrypt style hash algorithm identifier. + * S2KSALT is the 8 byte salt + * S2KCOUNT is the count value from RFC-4880. + +** Persistent Passphrase Format + +Note: That this has not yet been implemented. + +To allow persistent storage of cached passphrases we use a scheme +similar to the private-key storage format. This is a master +passphrase format where each file may protect several secrets under +one master passphrase. It is possible to have several of those files +each protected by a dedicated master passphrase. Clear text keywords +allow listing the available protected passphrases. + +The name of the files with these protected secrets have this form: +pw-<string>.dat. STRING may be an arbitrary string, as a default name +for the passphrase storage the name "pw-default.dat" is suggested. + + +(protected-shared-secret + ((desc descriptive_text) + (key [key_1] (keyword_1 keyword_2 keyword_n)) + (key [key_2] (keyword_21 keyword_22 keyword_2n)) + (key [key_n] (keyword_n1 keyword_n2 keyword_nn)) + (protected mode (parms) encrypted_octet_string) + (protected-at <isotimestamp>) + ) +) + +After decryption the encrypted_octet_string yields this S-expression: + +( + ( + (value key_1 value_1) + (value key_2 value_2) + (value key_n value_n) + ) + (hash sha1 #...[hashvalue]...#) +) + +The "descriptive_text" is displayed with the prompt to enter the +unprotection passphrase. + +KEY_1 to KEY_N are unique identifiers for the shared secret, for +example an URI. In case this information should be kept confidential +as well, they may not appear in the unprotected part; however they are +mandatory in the encrypted_octet_string. The list of keywords is +optional. The order of the "key" lists and the order of the "value" +lists must match, that is the first "key"-list is associated with the +first "value" list in the encrypted_octet_string. + +The protection mode etc. is identical to the protection mode as +described for the private key format. + +list of the secret key parameters. The protected-at expression is +optional; the isotimestamp is 15 bytes long (e.g. "19610711T172000"). + +The "hash" in the encrypted_octet_string is calculated on the +concatenation of the key list and value lists: i.e it is required to +hash the concatenation of all these lists, including the +parenthesis and (if used) the protected-at list. + +Example: + +(protected-shared-secret + ((desc "List of system passphrases") + (key "uid-1002" ("Knuth" "Donald Ervin Knuth")) + (key "uid-1001" ("Dijkstra" "Edsger Wybe Dijkstra")) + (key) + (protected mode (parms) encrypted_octet_string) + (protected-at "20100915T111722") + ) +) + +with "encrypted_octet_string" decoding to: + +( + ( + (value 4:1002 "signal flags at the lock") + (value 4:1001 "taocp") + (value 1:0 "premature optimization is the root of all evil") + ) + (hash sha1 #0102030405060708091011121314151617181920#) +) + +To compute the hash this S-expression (in canonical format) was +hashed: + + ((desc "List of system passphrases") + (key "uid-1002" ("Knuth" "Donald Ervin Knuth")) + (key "uid-1001" ("Dijkstra" "Edsger Wybe Dijkstra")) + (key) + (value 4:1002 "signal flags at the lock") + (value 4:1001 "taocp") + (value 1:0 "premature optimization is the root of all evil") + (protected-at "20100915T111722") + ) + +* Notes + +[1] I usually use the terms private and secret key exchangeable but prefer the +term secret key because it can be visually be better distinguished +from the term public key. + +[2] The keygrip is a unique identifier for a key pair, it is +independent of any protocol, so that the same key can be used with +different protocols. PKCS-15 calls this a subjectKeyHash; it can be +calculated using Libgcrypt's gcry_pk_get_keygrip (). + +[3] Even when canonical representation are required we will show the +S-expression here in a more readable representation. diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi index d57326125..cbb22225d 100644 --- a/doc/scdaemon.texi +++ b/doc/scdaemon.texi @@ -161,7 +161,7 @@ helpers to debug problems. @item --debug @var{flags} @opindex debug Set debug flags. All flags are or-ed and @var{flags} may be given -in C syntax (e.g. 0x0042) or as a comma separated list of flag names. +in C syntax (e.g., 0x0042) or as a comma separated list of flag names. To get a list of all supported flags the single word "help" can be used. This option is only useful for debugging and the behavior may change at any time without notice. @@ -238,7 +238,7 @@ this option only if you know what you are doing. Use @var{library} to access the smartcard reader. The current default on Unix is @file{libpcsclite.so} and on Windows @file{winscard.dll}. 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}). +link to the default file name (e.g., from @file{libpcsclite.so.1}). A Unicode file name may not be used on Windows. @item --disable-ccid @@ -503,7 +503,7 @@ 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 +between operations; i.e., the client can assume that all operations are done on the same card unless he call this function. @example @@ -717,7 +717,7 @@ 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. +command; i.e., to select another application. diff --git a/doc/specify-user-id.texi b/doc/specify-user-id.texi index 64e354bdf..1dc91b6d8 100644 --- a/doc/specify-user-id.texi +++ b/doc/specify-user-id.texi @@ -39,7 +39,7 @@ using the option @option{--with-colons}. @item By fingerprint. This format is deduced from the length of the string and its content or the @code{0x} prefix. Note, that only the 20 byte version fingerprint -is available with @command{gpgsm} (i.e. the SHA-1 hash of the +is available with @command{gpgsm} (i.e., the SHA-1 hash of the certificate). When using @command{gpg} an exclamation mark (!) may be appended to @@ -88,7 +88,7 @@ with left and right angles. @item By partial match on an email address. This is indicated by prefixing the search string with an @code{@@}. This uses a substring search but considers only the mail address -(i.e. inside the angle brackets). +(i.e., inside the angle brackets). @cartouche @example diff --git a/doc/tools.texi b/doc/tools.texi index da537b6d0..9ce0e6bb8 100644 --- a/doc/tools.texi +++ b/doc/tools.texi @@ -124,7 +124,7 @@ $ watchgnupg --time-only @end example This waits for connections on the local socket -(e.g. @file{/var/run/user/1234/gnupg/S.log}) and shows all log +(e.g., @file{/var/run/user/1234/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 suggested entry for the configuration files is: @@ -133,8 +133,8 @@ for the configuration files is: log-file socket:// @end example -If the default socket as given above and returned by "echo $(gpgconf ---list-dirs socketdir)/S.log" is not desired an arbitrary socket name +If the default socket as given above and returned by @code{"echo $(gpgconf +--list-dirs socketdir)/S.log"} is not desired an arbitrary socket name can be specified, for example @file{socket:///home/foo/bar/mysocket}. 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 @@ -1151,13 +1151,21 @@ More fields may be added in future to the output. Under Windows this file is used to install GnuPG as a portable application. An empty file named @file{gpgconf.ctl} is expected in - the same directory as the tool @file{gpgconf.exe}. The root of the + the same directory as the tool @file{gpgconf.exe} or the file must + have a keyword @code{portable} with the value true. The root of the installation is then that directory; or, if @file{gpgconf.exe} has been installed directly below a directory named @file{bin}, its parent directory. You also need to make sure that the following directories exist and are writable: @file{ROOT/home} for the GnuPG home and @file{ROOT@value{LOCALCACHEDIR}} for internal cache files. + On both platforms the keyword @code{gnupg} can be used to change the + standard home directory. For example a value of "gnupg-vsd" will + change the default home directory on unix from @file{~/.gnupg} to + @file{~/.gnupg-vsd}. The socket directory is changed accordingly + unless the @code{socketdir} keyword has been used. On Windows the + Registry keys are modified as well. + @item /etc/gnupg/gpgconf.conf @cindex gpgconf.conf @@ -1284,7 +1292,7 @@ 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}). Scripts should always use the option @option{--with-colons}, which provides the keygrip in a -"grp" line (cf. @file{doc/DETAILS})/ +"grp" line (cf.@: @file{doc/DETAILS})/ @noindent One of the following command options must be given: @@ -1765,7 +1773,7 @@ The return value of this command is @table @code @item 0 -The certificate under question is valid; i.e. there is a valid CRL +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. @@ -2088,9 +2096,9 @@ This option is deprecated in favor of option @option{--directory}. @item --no-compress @opindex no-compress -This option tells gpg to disable compression (i.e. using option -z0). +This option tells gpg to disable compression (i.e., using option -z0). It is useful for archiving only large files which are are already -compressed (e.g. a set of videos). +compressed (e.g., a set of videos). @item --gpg @var{gpgcmd} @opindex gpg @@ -2103,9 +2111,10 @@ Pass the specified extra options to @command{gpg}. @item --tar-args @var{args} @opindex tar-args Assume @var{args} are standard options of the command @command{tar} -and parse them. The only supported tar options are "--directory", -"--files-from", and "--null" This is an obsolete options because those -supported tar options can also be given directly. +and parse them. The only supported tar options are +@option{--directory}, @option{--files-from}, and @option{--null}. +This is an obsolete options because those supported tar options can +also be given directly. @item --tar @var{command} @opindex tar diff --git a/doc/wks.texi b/doc/wks.texi index 2870e52d8..bfdd069f2 100644 --- a/doc/wks.texi +++ b/doc/wks.texi @@ -214,7 +214,7 @@ The default is @file{openpgpkey}. @opindex blacklist This option is used to exclude certain mail addresses from a mirror operation. The format of @var{file} is one mail address (just the -addrspec, e.g. "postel@@isi.edu") per line. Empty lines and lines +addrspec, e.g., "postel@@isi.edu") per line. Empty lines and lines starting with a '#' are ignored. @item --add-revocs |