diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/DETAILS | 70 | ||||
| -rw-r--r-- | doc/gpg-agent.texi | 19 | ||||
| -rw-r--r-- | doc/gpg.texi | 122 | ||||
| -rw-r--r-- | doc/gpgsm.texi | 19 | ||||
| -rw-r--r-- | doc/tools.texi | 8 |
5 files changed, 174 insertions, 64 deletions
diff --git a/doc/DETAILS b/doc/DETAILS index a3fe802a2..fd95e511c 100644 --- a/doc/DETAILS +++ b/doc/DETAILS @@ -522,6 +522,11 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: Epoch or an ISO 8601 string which can be detected by the presence of the letter 'T'. +*** ASSERT_SIGNER <fingerprint> + This is emitted for the matching <fingerprint> when option + --assert-signer is used. The fingerprint is printed with + uppercase hex digits. + *** SIG_ID <radix64_string> <sig_creation_date> <sig-timestamp> This is emitted only for signatures of class 0 or 1 which have been verified okay. The string is a signature id and may be used @@ -1151,7 +1156,13 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: - learncard :: Send by the agent and gpgsm while learing the data of a smartcard. - card_busy :: A smartcard is still working - - scd_locked :: Waiting for other clients to unlock the scdaemon + - scd_locked :: Waiting for other clients to unlock the + scdaemon + - gpgtar :: Here <char> has a special meaning: 's' + indicates total size and 'c' file count. A + <total> of zero indicates that gpgtar is in the + scanning phase. A positive <total> is used in + the writing phase. When <what> refers to a file path, it may be truncated. @@ -1177,6 +1188,17 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB: send to the client instead of this status line. Such an inquiry may be used to sync with Pinentry +*** GPGTAR_EXTRACT <tot> <skp> <bad> <sus> <sym> <hrd> <oth> + This status line is emitted after gpgtar has extracted files. + + - tot :: Total number of files extracted and stored + - skp :: Total number of files skipped during extraction + - bad :: Number of files skipped due to a bad file name + - sus :: Number of files skipped due to a suspicious file name + - sym :: Number of symlinks not restored + - hrd :: Number of hard links not restored + - oth :: Number of files not extracted due to other reasons. + ** Obsolete status codes *** SIGEXPIRED Removed on 2011-02-04. This is deprecated in favor of KEYEXPIRED. @@ -1678,6 +1700,7 @@ Description of some debug flags: - RFC-1750 :: Randomness Recommendations for Security - RFC-1991 :: PGP Message Exchange Formats (obsolete) - RFC-2144 :: The CAST-128 Encryption Algorithm + - RFC-2253 :: UTF-8 String Representation of Distinguished Names. - RFC-2279 :: UTF-8, a transformation format of ISO 10646 - RFC-2440 :: OpenPGP (obsolete). - RFC-3156 :: MIME Security with Pretty Good Privacy (PGP). @@ -1700,15 +1723,21 @@ Description of some debug flags: - RFC-5915 :: ECC Private Key Structure - RFC-5958 :: Asymmetric Key Packages - RFC-6337 :: ECC in OpenPGP + - RFC-7748 :: Elliptic Curves for Security (X25519 and X448) + - RFC-8410 :: Algorithm Identifiers for Ed25519, Ed448, X25519, and X448 - RFC-7292 :: PKCS #12: Personal Information Exchange Syntax v1.1 - RFC-8351 :: The PKCS #8 EncryptedPrivateKeyInfo Media Type - RFC-8550 :: S/MIME Version 4.0 Certificate Handling - RFC-8551 :: S/MIME Version 4.0 Message Specification - RFC-2634 :: Enhanced Security Services for S/MIME - RFC-5035 :: Enhanced Security Services (ESS) Update + - RFC-7253 :: The OCB Authenticated-Encryption Algorithm - draft-koch-openpgp-2015-rfc4880bis :: Updates to RFC-4880 + - T6390 :: Notes on use of X25519 in GnuPG (https://dev.gnupg.org/T6390) + + ** v3 fingerprints For packet version 3 we calculate the keyids this way: - RSA :: Low 64 bits of n @@ -1718,17 +1747,10 @@ Description of some debug flags: ** gnupg.org notations - - [email protected] :: Additional decryption subkey. This notation - gives a list of keys an implementation SHOULD - also encrypt to. The data consists of an array - of eight-octet numbers holding the Key ID of an - encryption subkey. This notation is only valid - on an encryption subkey (i.e. with first octet - of the key flags 0x04 or 0x08). Subkeys not on - the same keyblock MUST NOT be considered. For - interoperability this notation SHOULD NOT be - marked as criticial. Due to its nature it MUST - NOT be marked as human readable. + - [email protected] :: Used by Kleopatra to implement the tag feature. + These tags are used to mark keys for easier + searching and grouping. + ** Simplified revocation certificates Revocation certificates consist only of the signature packet; @@ -1797,3 +1819,27 @@ Description of some debug flags: it is also possible to set them direct: Use a "=" character directly followed by a combination of "a" (for authentication), "s" (for signing), or "c" (for certification). + +** extendedKeyUsage and keyUsage in gpgsm + +This table describes how the extended KeyUsage masks the KeyUsage. + + | ExtKeyUsage | Valid KeyUsages | + |-----------------+------------------| + | serverAuth | digitalSignature | + | | keyEncipherment | + | | keyAgreement | + |-----------------+------------------| + | clientAuth | digitalSignature | + | | keyAgreement | + |-----------------+------------------| + | codeSigning | digitalSignature | + |-----------------+------------------| + | emailProtection | digitalSignature | + | | nonRepudiation | + | | keyEncipherment | + | | keyAgreement | + |-----------------+------------------| + | timeStamping | digitalSignature | + | | nonRepudiation | + |-----------------+------------------| diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 921522d53..c8080c7c2 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -615,15 +615,11 @@ remote machine. @itemx --disable-extended-key-format @opindex enable-extended-key-format @opindex disable-extended-key-format -Since version 2.3 keys are created in the extended private key format. -Changing the passphrase of a key will also convert the key to that new -format. This new key format is supported since GnuPG version 2.1.12 -and thus there should be no need to disable it. The disable option -allows to revert to the old behavior for new keys; be aware that keys -are never migrated back to the old format. However if the enable -option has been used the disable option won't have an effect. The -advantage of the extended private key format is that it is text based -and can carry additional meta data. +These options are obsolete and have no effect. The extended key format +is used for years now and has been supported since 2.1.12. Existing +keys in the old format are migrated to the new format as soon as they +are touched. + @anchor{option --enable-ssh-support} @item --enable-ssh-support @@ -817,6 +813,11 @@ This flag has an effect only if used in the global list. This is now the preferred way to mark such CA; the old way of having a separate file @file{qualified.txt} is still supported. +@item de-vs +The CA is part of an approved PKI for the German classification level +VS-NfD. It is only valid in the global trustlist. As of now this is +used only for documentation purpose. + @end table diff --git a/doc/gpg.texi b/doc/gpg.texi index 47aa0a4d0..eb7c35cac 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -264,11 +264,11 @@ out the actual signed data, but there are other pitfalls with this format as well. It is suggested to avoid cleartext signatures in favor of detached signatures. -Note: Sometimes the use of the @command{gpgv} tool is easier than -using the full-fledged @command{gpg} with this option. @command{gpgv} -is designed to compare signed data against a list of trusted keys and -returns with success only for a good signature. It has its own manual -page. +Note: To check whether a file was signed by a certain key the option +@option{--assert-signer} can be used. As an alternative the +@command{gpgv} tool can be used. @command{gpgv} is designed to +compare signed data against a list of trusted keys and returns with +success only for a good signature. It has its own manual page. @item --multifile @@ -622,7 +622,7 @@ outputs an endless stream of hex-encoded octets. The special level @item --gen-prime @var{mode} @var{bits} @opindex gen-prime Use the source, Luke :-). The output format is subject to change -with ant release. +with any release. @item --enarmor @@ -770,6 +770,15 @@ specifying a value, or using ``-'' results in a key expiring in a reasonable default interval. The values ``never'', ``none'' can be used for no expiration date. +@item --quick-add-adsk @var{fpr} @var{adskfpr} +@opindex quick-add-adsk +Directly add an Additional Decryption Subkey to the key identified by +the fingerprint @var{fpr}. @var{adskfpr} is the fingerprint of +another key's encryption subkey. A subkey is commonly used here +because by default a primary key has no encryption capability. Use +the option @option{--with-subkey-fingerprint} with a list command to +display the subkey fingerprints. + @item --generate-key @opindex generate-key @itemx --gen-key @@ -1067,6 +1076,15 @@ signing. "sensitive". If a designated revoker is marked as sensitive, it will not be exported by default (see export-options). + @item addadsk + @opindex keyedit:addadsk + Add an Additional Decryption Subkey. The user is asked to enter the + fingerprint of another encryption subkey. Note that the exact + fingerprint of another key's encryption subkey needs to be entered. + This is because commonly the primary key has no encryption + capability. Use the option @option{--with-subkey-fingerprint} with + a list command to display the subkey fingerprints. + @item passwd @opindex keyedit:passwd Change the passphrase of the secret key. @@ -1405,6 +1423,10 @@ give the opposite meaning. The options are: @opindex list-options:show-unusable-subkeys Show revoked and expired subkeys in key listings. Defaults to no. + @item show-unusable-sigs + @opindex list-options:show-unusable-sigs + Show key signature made using weak or unsupported algorithms. + @item show-keyring @opindex list-options:show-keyring Display the keyring name at the head of key listings to show which @@ -1746,6 +1768,19 @@ recipient's or signator's key. If the given key is not locally available but an LDAP keyserver is configured the missing key is imported from that server. +@item --add-desig-revoker [sensitive:]@var{fingerprint} +@opindex add-desig-revoker +Add the key specified by @var{fingerprint} as a designated revoker to +newly created keys. If the fingerprint is prefixed with the keyword +``sensitive:'' that info is normally not exported wit the key. This +option may be given several time to add more than one designated +revoker. If the keyword ``clear'' is used instead of a fingerprint, +all designated options previously encountered are discarded. +Designated revokers are marked on the key as non-revocable. Note that +a designated revoker specified using a parameter file will also be +added to the key. + + @item --trust-model @{pgp|classic|tofu|tofu+pgp|direct|always|auto@} @opindex trust-model Set what trust model GnuPG should follow. The models are: @@ -1854,6 +1889,24 @@ Set what trust model GnuPG should follow. The models are: must be enabled explicitly. @end table +@item --always-trust +@opindex always-trust +Identical to @option{--trust-model always}. + +@item --assert-signer @var{fpr_or_file} +@opindex assert-signer +This option checks whether at least one valid signature on a file has +been made with the specified key. The key is either specified as a +fingerprint or a file listing fingerprints. The fingerprint must be +given or listed in compact format (no colons or spaces in between). +This option can be given multiple times and each fingerprint is +checked against the signing key as well as the corresponding primary +key. If @var{fpr_or_file} specifies a file, empty lines are ignored +as well as all lines starting with a hash sign. With this option gpg +is guaranteed to return with an exit code of 0 if and only if a +signature has been encountered, is valid, and the key matches one of +the fingerprints given by this option. + @item --auto-key-locate @var{mechanisms} @itemx --no-auto-key-locate @@ -3173,6 +3226,10 @@ Write log output to file descriptor @var{n} and not to STDERR. Same as @option{--logger-fd}, except the logger data is written to file @var{file}. Use @file{socket://} to log to s socket. +@item --log-time +@opindex log-time +Prefix all log output with a timestamp even if no log file is used. + @item --attribute-fd @var{n} @opindex attribute-fd Write attribute subpackets to the file descriptor @var{n}. This is most @@ -3817,10 +3874,6 @@ Display the keyring name at the head of key listings to show which keyring a given key resides on. This option is deprecated: use @option{--list-options [no-]show-keyring} instead. -@item --always-trust -@opindex always-trust -Identical to @option{--trust-model always}. This option is deprecated. - @item --show-notation @itemx --no-show-notation @opindex show-notation @@ -3876,7 +3929,9 @@ current home directory (@pxref{option --homedir}). @efindex common.conf This is an optional configuration file read by @command{@gpgname} on startup. It may contain options pertaining to all components of - GnuPG. Its current main use is for the "use-keyboxd" option. + GnuPG. Its current main use is for the "use-keyboxd" option. If + the default home directory @file{~/.gnupg} does not exist, GnuPG creates + this directory and a @file{common.conf} file with "use_keyboxd". @end table @@ -4327,7 +4382,7 @@ already been reported to our bug tracker at @url{https://bugs.gnupg.org}. @c *************** UNATTENDED ************** @c *************** ************** @c ******************************************* -@manpause +@mansect notes @node Unattended Usage of GPG @section Unattended Usage @@ -4398,32 +4453,21 @@ previous subsection ``The quick key manipulation interface''. The parameters for the key are either read from stdin or given as a file on the command line. The format of the parameter file is as -follows: - -@itemize @bullet - @item Text only, line length is limited to about 1000 characters. - @item UTF-8 encoding must be used to specify non-ASCII characters. - @item Empty lines are ignored. - @item Leading and trailing white space is ignored. - @item A hash sign as the first non white space character indicates - a comment line. - @item Control statements are indicated by a leading percent sign, the - arguments are separated by white space from the keyword. - @item Parameters are specified by a keyword, followed by a colon. Arguments - are separated by white space. - @item - The first parameter must be @samp{Key-Type}; control statements may be - placed anywhere. - @item - The order of the parameters does not matter except for @samp{Key-Type} - which must be the first parameter. The parameters are only used for - the generated keyblock (primary and subkeys); parameters from previous - sets are not used. Some syntactically checks may be performed. - @item - Key generation takes place when either the end of the parameter file - is reached, the next @samp{Key-Type} parameter is encountered or at the - control statement @samp{%commit} is encountered. -@end itemize +follows: Text only, line length is limited to about 1000 characters. +UTF-8 encoding must be used to specify non-ASCII characters. Empty +lines are ignored. Leading and trailing white space is ignored. A +hash sign as the first non white space character indicates a comment +line. Control statements are indicated by a leading percent sign, +their arguments are separated by white space from the keyword. +Parameters are specified by a keyword, followed by a colon; arguments +are separated by white space. The first parameter must be +@samp{Key-Type} but control statements may be placed anywhere. The +order of the parameters does not matter except for @samp{Key-Type}. +The parameters are only used for the generated keyblock (primary and +subkeys); parameters from previous sets are not used. Some syntax +checks may be performed. Key commences when either the end of the +parameter file is reached, the next @samp{Key-Type} parameter is +encountered, or the control statement @samp{%commit} is encountered. @noindent Control statements: @@ -4459,7 +4503,7 @@ See the previous subsection ``Ephemeral home directories''. @item %ask-passphrase @itemx %no-ask-passphrase -This option is a no-op for GnuPG 2.1 and later. +This option is a no-op since GnuPG version 2.1. @item %no-protection Using this option allows the creation of keys without any passphrase diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index a328ea5f0..364345741 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -408,6 +408,10 @@ Do not print a warning when the so called "secure memory" cannot be used. When running in server mode, append all logging output to @var{file}. Use @file{socket://} to log to socket. +@item --log-time +@opindex log-time +Prefix all log output with a timestamp even if no log file is used. + @end table @@ -492,8 +496,10 @@ This usually means that Dirmngr is employed to search for the certificate. Note that this option makes a "web bug" like behavior possible. LDAP server operators can see which keys you request, so by sending you a message signed by a brand new key (which you naturally -will not have on your local keybox), the operator can tell both your IP -address and the time when you verified the signature. +will not have on your local keybox), the operator can tell both your +IP address and the time when you verified the signature. Note that if +CRL checking is not disabled issuer certificates are retrieved in any +case using the caIssuers authorityInfoAccess method. @anchor{gpgsm-option --validation-model} @@ -623,6 +629,15 @@ always listed in @option{--with-colons} mode. Include info about the presence of a secret key in public key listings 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 +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. + @end table @c ******************************************* diff --git a/doc/tools.texi b/doc/tools.texi index e22a2285f..5fa21c66a 100644 --- a/doc/tools.texi +++ b/doc/tools.texi @@ -1907,6 +1907,8 @@ Put given files and directories into a vanilla ``ustar'' archive. @item --extract @opindex extract Extract all files from a vanilla ``ustar'' archive. +If no file name is given (or it is "-") the archive is taken from +stdin. @item --encrypt @itemx -e @@ -1918,7 +1920,8 @@ be decrypted via a secret key or a passphrase. @item --decrypt @itemx -d @opindex decrypt -Extract all files from an encrypted archive. +Extract all files from an encrypted archive. If no file name is given +(or it is "-") the archive is taken from stdin. @item --sign @itemx -s @@ -1929,7 +1932,8 @@ encrypted archive. @item --list-archive @itemx -t @opindex list-archive -List the contents of the specified archive. +List the contents of the specified archive. If no file name is given +(or it is "-") the archive is taken from stdin. @item --symmetric @itemx -c |