diff options
Diffstat (limited to 'doc/gpg.texi')
| -rw-r--r-- | doc/gpg.texi | 245 |
1 files changed, 201 insertions, 44 deletions
diff --git a/doc/gpg.texi b/doc/gpg.texi index 420326b..d66259e 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -252,6 +252,14 @@ signed stuff from STDIN, use @samp{-} as the second filename. For security reasons a detached signature cannot read the signed material from STDIN without denoting it in the above way. +Note: When verifying a cleartext signature, @command{gpg} verifies +only what makes up the cleartext signed data and not any extra data +outside of the cleartext signature or header lines following directly +the dash marker line. The option @code{--output} may be used to write +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. + @item --multifile @opindex multifile This modifies certain other commands to accept multiple files for @@ -388,7 +396,7 @@ safeguard against accidental deletion of multiple keys. @item --delete-secret-key @code{name} @opindex delete-secret-key -Remove key from the secret and public keyring. In batch mode the key +Remove key from the secret keyring. In batch mode the key must be specified by fingerprint. @item --delete-secret-and-public-key @code{name} @@ -400,8 +408,8 @@ removed first. In batch mode the key must be specified by fingerprint. @opindex export Either export all keys from all keyrings (default keyrings and those registered via option @option{--keyring}), or if at least one name is given, -those of the given name. The new keyring is written to STDOUT or to the -file given with option @option{--output}. Use together with +those of the given name. The exported keys are written to STDOUT or to the +file given with option @option{--output}. Use together with @option{--armor} to mail those keys. @item --send-keys @code{key IDs} @@ -416,14 +424,30 @@ or changed by you. If no key IDs are given, @command{gpg} does nothing. @itemx --export-secret-subkeys @opindex export-secret-keys @opindex export-secret-subkeys -Same as @option{--export}, but exports the secret keys instead. This is -normally not very useful and a security risk. The second form of the -command has the special property to render the secret part of the -primary key useless; this is a GNU extension to OpenPGP and other -implementations can not be expected to successfully import such a key. +Same as @option{--export}, but exports the secret keys instead. The +exported keys are written to STDOUT or to the file given with option +@option{--output}. This command is often used along with the option +@option{--armor} to allow easy printing of the key for paper backup; +however the external tool @command{paperkey} does a better job for +creating backups on paper. Note that exporting a secret key can be a +security risk if the exported keys are send over an insecure channel. + +The second form of the command has the special property to render the +secret part of the primary key useless; this is a GNU extension to +OpenPGP and other implementations can not be expected to successfully +import such a key. Its intended use is to generated a full key with +an additional signing subkey on a dedicated machine and then using +this command to export the key without the primary key to the main +machine. + +@ifset gpgtwoone +GnuPG may ask you to enter the passphrase for the key. This is +required because the internal protection method of the secret key is +different from the one specified by the OpenPGP protocol. +@end ifset @ifclear gpgtwoone -See the option @option{--simple-sk-checksum} if you want to import such -an exported key with an older OpenPGP implementation. +See the option @option{--simple-sk-checksum} if you want to import an +exported secret key into ancient OpenPGP implementations. @end ifclear @item --import @@ -898,6 +922,24 @@ Signs a public key with your secret key but marks it as non-exportable. This is a shortcut version of the subcommand "lsign" from @option{--edit-key}. +@ifset gpgtwoone +@item --quick-sign-key @code{fpr} [@code{names}] +@itemx --quick-lsign-key @code{name} +@opindex quick-sign-key +@opindex quick-lsign-key +Directly sign a key from the passphrase without any further user +interaction. The @code{fpr} must be the verified primary fingerprint +of a key in the local keyring. If no @code{names} are given, all +useful user ids are signed; with given [@code{names}] only useful user +ids matching one of theses names are signed. The command +@option{--quick-lsign-key} marks the signatures as non-exportable. + +This command uses reasonable defaults and thus does not provide the +full flexibility of the "sign" subcommand from @option{--edit-key}. +Its intended use to help unattended signing using a list of verified +fingerprints. +@end ifset + @ifclear gpgone @item --passwd @var{user_id} @opindex passwd @@ -926,7 +968,9 @@ behaviour and to change the default configuration. * GPG Key related Options:: Key related options. * GPG Input and Output:: Input and Output. * OpenPGP Options:: OpenPGP protocol specific options. +* Compliance Options:: Compliance options. * GPG Esoteric Options:: Doing things one usually don't want to do. +* Deprecated Options:: Deprecated options. @end menu Long options can be put in an options file (default @@ -1167,7 +1211,7 @@ 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"), "%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. -"full"), +"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. @@ -1293,9 +1337,7 @@ encoded in the character set as specified by @option{--display-charset}. These options affect all following arguments. Both options may be used multiple times. -@ifset gpgone -@anchor{option --options} -@end ifset +@anchor{gpg-option --options} @item --options @code{file} @opindex options Read options from @code{file} and do not try to read them from the @@ -1423,7 +1465,9 @@ Set what trust model GnuPG should follow. The models are: trusted. You generally won't use this unless you are using some external validation scheme. This option also suppresses the "[uncertain]" tag printed with signature checks when there is no - evidence that the user ID is bound to the key. + evidence that the user ID is bound to the key. Note that this + trust model still does not allow the use of expired, revoked, or + disabled keys. @item auto @opindex trust-mode:auto @@ -1474,6 +1518,10 @@ mechanisms, in the order they are to be tried: position of this mechanism in the list does not matter. It is not required if @code{local} is also used. + @item clear + Clear all defined mechanisms. This is useful to override + mechanisms given in a config file. + @end table @item --keyid-format @code{short|0xshort|long|0xlong} @@ -1598,16 +1646,29 @@ are available for all keyserver types, some common options are: program uses internally (libcurl, openldap, etc). @item check-cert +@ifset gpgtwoone + This option has no more function since GnuPG 2.1. Use the + @code{dirmngr} configuration options instead. +@end ifset +@ifclear gpgtwoone Enable certificate checking if the keyserver presents one (for hkps or ldaps). Defaults to on. +@end ifclear @item ca-cert-file +@ifset gpgtwoone + This option has no more function since GnuPG 2.1. Use the + @code{dirmngr} configuration options instead. +@end ifset +@ifclear gpgtwoone Provide a certificate store to override the system default. Only necessary if check-cert is enabled, and the keyserver is using a certificate that is not present in a system default certificate list. Note that depending on the SSL library that the keyserver helper is built with, this may actually be a directory or a file. +@end ifclear + @end table @item --completes-needed @code{n} @@ -1688,6 +1749,25 @@ been given. Given that this option is not anymore used by @command{gpg2}, it should be avoided if possible. @end ifset + +@ifclear gpgone +@item --agent-program @var{file} +@opindex agent-program +Specify an agent program to be used for secret key operations. The +default value is the @file{/usr/bin/gpg-agent}. This is only used +as a fallback when the environment variable @code{GPG_AGENT_INFO} is not +set or a running agent cannot be connected. +@end ifclear + +@ifset gpgtwoone +@item --dirmngr-program @var{file} +@opindex dirmngr-program +Specify a dirmngr program to be used for keyserver access. The +default value is @file{/usr/sbin/dirmngr}. This is only used as a +fallback when the environment variable @code{DIRMNGR_INFO} is not set or +a running dirmngr cannot be connected. +@end ifset + @item --lock-once @opindex lock-once Lock the databases the first time a lock is requested @@ -2045,6 +2125,15 @@ Since GnuPG 2.0.10, this mode is always used and thus this option is obsolete; it does not harm to use it though. @end ifclear +@ifset gpgtwoone +@item --legacy-list-mode +@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 +allow to convey suitable information for elliptic curves. +@end ifset + @item --with-fingerprint @opindex with-fingerprint Same as the command @option{--fingerprint} but changes only the format @@ -2054,6 +2143,12 @@ of the output and may be used together with another command. @item --with-keygrip @opindex with-keygrip Include the keygrip in the key listings. + +@item --with-secret +@opindex with-secret +Include info about the presence of a secret key in public key listings +done with @code{--with-colons}. + @end ifset @end table @@ -2185,6 +2280,7 @@ meaningful if @option{--s2k-mode} is 3. @c *************************** @c ******* Compliance ******** @c *************************** +@node Compliance Options @subsection Compliance options These options control what GnuPG is compliant to. Only one of these @@ -2234,10 +2330,18 @@ a message that PGP 2.x will not be able to handle. Note that `PGP 2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x available, but the MIT release is a good common baseline. -This option implies @option{--rfc1991 --disable-mdc ---no-force-v4-certs --escape-from-lines --force-v3-sigs --cipher-algo -IDEA --digest-algo MD5 --compress-algo ZIP}. It also disables -@option{--textmode} when encrypting. +This option implies +@ifset gpgone +@option{--rfc1991 --disable-mdc --no-force-v4-certs +--escape-from-lines --force-v3-sigs +--cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}. +@end ifset +@ifclear gpgone +@option{--rfc1991 --disable-mdc --no-force-v4-certs +--escape-from-lines --force-v3-sigs --allow-weak-digest-algos +--cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}. +@end ifclear +It also disables @option{--textmode} when encrypting. @item --pgp6 @opindex pgp6 @@ -2399,8 +2503,12 @@ protected by the signature. @item --emit-version @itemx --no-emit-version @opindex emit-version -Force inclusion of the version string in ASCII armored output. -@option{--no-emit-version} disables this option. +Force inclusion of the version string in ASCII armored output. If +given once only the name of the program and the major number is +emitted (default), given twice the minor is also emitted, given triple +the micro is added, and given quad an operating system identification +is also emitted. @option{--no-emit-version} disables the version +line. @item --sig-notation @code{name=value} @itemx --cert-notation @code{name=value} @@ -2418,7 +2526,7 @@ check. @code{value} may be any printable string; it will be encoded in UTF8, so you should check that your @option{--display-charset} is set correctly. If you prefix @code{name} with an exclamation mark (!), the notation data will be flagged as critical -(rfc2440:5.2.3.15). @option{--sig-notation} sets a notation for data +(rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data signatures. @option{--cert-notation} sets a notation for key signatures (certifications). @option{--set-notation} sets both. @@ -2440,7 +2548,7 @@ meaningful when using the OpenPGP smartcard. @opindex sig-policy-url @opindex cert-policy-url @opindex set-policy-url -Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19). If +Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20). If you prefix it with an exclamation mark (!), the policy URL packet will be flagged as critical. @option{--sig-policy-url} sets a policy url for data signatures. @option{--cert-policy-url} sets a policy url for key @@ -2611,6 +2719,26 @@ Note that this passphrase is only used if the option @option{--batch} has also been given. This is different from @command{gpg}. @end ifclear +@ifset gpgtwoone +@item --pinentry-mode @code{mode} +@opindex pinentry-mode +Set the pinentry mode to @code{mode}. Allowed values for @code{mode} +are: +@table @asis + @item default + Use the default of the agent, which is @code{ask}. + @item ask + Force the use of the Pinentry. + @item cancel + Emulate use of Pinentry's cancel button. + @item error + Return a Pinentry error (``No Pinentry''). + @item loopback + Redirect Pinentry queries to the caller. Note that in contrast to + Pinentry the user is not prompted again if he enters a bad password. +@end table +@end ifset + @item --command-fd @code{n} @opindex command-fd This is a replacement for the deprecated shared-memory IPC mode. @@ -2669,6 +2797,14 @@ necessary to get as much data as possible out of the corrupt message. However, be aware that a MDC protection failure may also mean that the message was tampered with intentionally by an attacker. +@ifclear gpgone +@item --allow-weak-digest-algos +@opindex allow-weak-digest-algos +Signatures made with the broken MD5 algorithm are normally rejected +with an ``invalid digest algorithm'' message. This option allows the +verification of signatures made with such weak algorithms. +@end ifclear + @item --no-default-keyring @opindex no-default-keyring Do not add the default keyrings to the list of keyrings. Note that @@ -2827,6 +2963,7 @@ on the configuration file. @c ******************************* @c ******* Deprecated ************ @c ******************************* +@node Deprecated Options @subsection Deprecated options @table @gnupgtabopt @@ -2909,7 +3046,7 @@ current home directory (@pxref{option --homedir}). This is the standard configuration file read by @command{@gpgname} on startup. It may contain any valid long option; the leading two dashes may not be entered and the option may not be abbreviated. This default - name may be changed on the command line (@pxref{option --options}). + name may be changed on the command line (@pxref{gpg-option --options}). You should backup this file. @end table @@ -2929,18 +3066,33 @@ files; They all live in in the current home directory (@pxref{option @table @file - @item ~/.gnupg/secring.gpg - The secret keyring. You should backup this file. - - @item ~/.gnupg/secring.gpg.lock - The lock file for the secret keyring. - @item ~/.gnupg/pubring.gpg The public keyring. You should backup this file. @item ~/.gnupg/pubring.gpg.lock The lock file for the public keyring. +@ifset gpgtwoone + @item ~/.gnupg/pubring.kbx + The public keyring using a different format. This file is sharred + with @command{gpgsm}. You should backup this file. + + @item ~/.gnupg/pubring.kbx.lock + The lock file for @file{pubring.kbx}. +@end ifset + + @item ~/.gnupg/secring.gpg +@ifclear gpgtwoone + The secret keyring. You should backup this file. +@end ifclear +@ifset gpgtwoone + A secret keyring as used by GnuPG versions before 2.1. It is not + used by GnuPG 2.1 and later. + + @item ~/.gnupg/.gpg-v21-migrated + File indicating that a migration to GnuPG 2.1 has taken place. +@end ifset + @item ~/.gnupg/trustdb.gpg The trust database. There is no need to backup this file; it is better to backup the ownertrust values (@pxref{option --export-ownertrust}). @@ -2951,6 +3103,9 @@ files; They all live in in the current home directory (@pxref{option @item ~/.gnupg/random_seed A file used to preserve the state of the internal random pool. + @item ~/.gnupg/secring.gpg.lock + The lock file for the secret keyring. + @item /usr[/local]/share/gnupg/options.skel The skeleton options file. @@ -2972,9 +3127,9 @@ Operation is further controlled by a few environment variables: @item GPG_AGENT_INFO Used to locate the gpg-agent. - @ifset gpgone +@ifset gpgone This is only honored when @option{--use-agent} is set. - @end ifset +@end ifset The value consists of 3 colon delimited fields: The first is the path to the Unix Domain Socket, the second the PID of the gpg-agent and the protocol version which should be set to 1. When starting the gpg-agent @@ -3149,8 +3304,8 @@ are almost always required for this. @end menu -@node Unattended GPG key generation,,,Unattended Usage of GPG -@section Unattended key generation +@node Unattended GPG key generation +@subsection Unattended key generation The command @option{--gen-key} may be used along with the option @option{--batch} for unattended key generation. The parameters are @@ -3290,21 +3445,23 @@ 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 (2000-08-15) or as number of days, -weeks, month or years. The special notation "seconds=N" is also -allowed to directly give an Epoch value. Without a letter days are -assumed. Note that there is no check done on the overflow of the type -used by OpenPGP for timestamps. Thus you better make sure that the -given value make sense. Although OpenPGP works with time intervals, -GnuPG uses an absolute value internally and thus the last year we can -represent is 2105. +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 +is no check done on the overflow of the type used by OpenPGP for +timestamps. Thus you better make sure that the given value make +sense. Although OpenPGP works with time intervals, GnuPG uses an +absolute value internally and thus the last year we can represent is +2105. @item Ceation-Date: @var{iso-date} Set the creation date of the key as stored in the key information and which is also part of the fingerprint calculation. Either a date like "1986-04-26" or a full timestamp like "19860426T042640" may be used. -The time is considered to be UTC. If it is not given the current time -is used. +The time is considered to be UTC. The special notation "seconds=N" +may be used to directly specify a the number of seconds since Epoch +(Unix time). If it is not given the current time is used. @item Preferences: @var{string} Set the cipher, hash, and compression preference values for this key. |