gpg: Emit new status DECRYPTION_KEY
[gnupg.git] / doc / gpg.texi
index 753bec3..78dd651 100644 (file)
@@ -117,11 +117,6 @@ perform a reasonable action depending on the type of file it is given
 as input (an encrypted message is decrypted, a signature is verified,
 a file containing keys is listed, etc.).
 
-Please remember that option and command parsing stops as soon as a
-non-option is encountered.  Thus, options must precede the command.
-You can explicitly stop parsing by using the special option
-@option{--}.
-
 
 @menu
 * General GPG Commands::        Commands not specific to the functionality.
@@ -146,7 +141,8 @@ cannot abbreviate this command.
 @itemx -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
-Note that you cannot abbreviate this command.
+Note that you cannot arbitrarily abbreviate this command
+(though you can use its short form @option{-h}).
 
 @item --warranty
 @opindex warranty
@@ -260,6 +256,13 @@ 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.
+
+
 @item --multifile
 @opindex multifile
 This modifies certain other commands to accept multiple files for
@@ -367,7 +370,9 @@ values are dumped and not only their lengths.  Note that the output of
 this command may change with new releases.
 
 
-@item --card-edit
+@item --edit-card
+@opindex edit-card
+@itemx --card-edit
 @opindex card-edit
 Present a menu to work with a smartcard. The subcommand "help" provides
 an overview on available commands. For a detailed description, please
@@ -382,7 +387,7 @@ Show the content of the smart card.
 @opindex change-pin
 Present a menu to allow changing the PIN of a smartcard. This
 functionality is also available as the subcommand "passwd" with the
-@option{--card-edit} command.
+@option{--edit-card} command.
 
 @item --delete-keys @code{name}
 @itemx --delete-keys @code{name}
@@ -616,8 +621,8 @@ This section explains the main commands for key management.
 
 @table @gnupgtabopt
 
-@item --quick-gen-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
-@opindex quick-gen-key
+@item --quick-generate-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
+@opindex quick-generate-key
 This is a simple command to generate a standard key with one user id.
 In contrast to @option{--generate-key} the key is generated directly
 without the need to answer a bunch of prompts.  Unless the option
@@ -634,15 +639,18 @@ created and no prompts are shown.  To specify an expiration date but
 still create a primary and subkey use ``default'' or
 ``future-default'' for @code{algo} and ``default'' for @code{usage}.
 For a description of these optional arguments see the command
-@code{--quick-addkey}.  The @code{usage} accepts also the value
+@code{--quick-add-key}.  The @code{usage} accepts also the value
 ``cert'' which can be used to create a certification only primary key;
 the default is to a create certification and signing key.
 
 The @code{expire} argument can be used to specify an expiration date
-for the key.  Several formats are supported; commonly the ISO
-YYYY-MM-DD format is used.  The values ``never'', ``none'' can be used
-for no expiration date.  Not specifying a value, or using ``-''
-results in a key expiring in a reasonable default interval.
+for the key.  Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively.  Not
+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.
 
 If this command is used with @option{--batch},
 @option{--pinentry-mode} has been set to @code{loopback}, and one of
@@ -658,8 +666,8 @@ Directly set the expiration time of the primary key to @code{expire}.
 To remove the expiration time @code{0} can be used.
 
 
-@item --quick-addkey @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
-@opindex quick-addkey
+@item --quick-add-key @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
+@opindex quick-add-key
 Directly add a subkey to the key identified by the fingerprint
 @code{fpr}.  Without the optional arguments an encryption subkey is
 added.  If any of the arguments are given a more specific subkey is
@@ -679,15 +687,20 @@ Depending on the given @code{algo} the subkey may either be an
 encryption subkey or a signing subkey.  If an algorithm is capable of
 signing and encryption and such a subkey is desired, a @code{usage}
 string must be given.  This string is either ``default'' or ``-'' to
-keep the default or a comma delimited list of keywords: ``sign'' for a
-signing subkey, ``auth'' for an authentication subkey, and ``encr''
-for an encryption subkey (``encrypt'' can be used as alias for
-``encr'').  The valid combinations depend on the algorithm.
+keep the default or a comma delimited list (or space delimited list)
+of keywords: ``sign'' for a signing subkey, ``auth'' for an
+authentication subkey, and ``encr'' for an encryption subkey
+(``encrypt'' can be used as alias for ``encr'').  The valid
+combinations depend on the algorithm.
 
 The @code{expire} argument can be used to specify an expiration date
-for the subkey.  Several formats are supported; commonly the ISO
-YYYY-MM-DD format is used.  The values ``never'', ``none'', or ``-''
-can be used for no expiration date.
+for the key.  Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively.  Not
+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 --generate-key
 @opindex generate-key
@@ -727,7 +740,9 @@ published, which is best done by sending the key to a keyserver
 to a file which is then send to frequent communication partners.
 
 
-@item --desig-revoke @code{name}
+@item --generate-designated-revocation @code{name}
+@opindex generate-designated-revocation
+@itemx --desig-revoke @code{name}
 @opindex desig-revoke
 Generate a designated revocation certificate for a key. This allows a
 user (with the permission of the keyholder) to revoke someone else's
@@ -931,7 +946,8 @@ signing.
   @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
-  that case you better use @code{revkey}.
+  that case you better use @code{revkey}.  Also note that this only
+  deletes the public part of a key.
 
   @item revkey
   @opindex keyedit:revkey
@@ -1070,16 +1086,16 @@ full flexibility of the "sign" subcommand from @option{--edit-key}.
 Its intended use is to help unattended key signing by utilizing a list
 of verified fingerprints.
 
-@item --quick-adduid  @var{user-id} @var{new-user-id}
-@opindex quick-adduid
+@item --quick-add-uid  @var{user-id} @var{new-user-id}
+@opindex quick-add-uid
 This command adds a new user id to an existing key.  In contrast to
 the interactive sub-command @code{adduid} of @option{--edit-key} the
 @var{new-user-id} is added verbatim with only leading and trailing
 white space removed, it is expected to be UTF-8 encoded, and no checks
 on its form are applied.
 
-@item --quick-revuid  @var{user-id} @var{user-id-to-revoke}
-@opindex quick-revuid
+@item --quick-revoke-uid  @var{user-id} @var{user-id-to-revoke}
+@opindex quick-revoke-uid
 This command revokes a User ID on an existing key.  It cannot be used
 to revoke the last User ID on key (some non-revoked User ID must
 remain), with revocation reason ``User ID is no longer valid''.  If
@@ -1414,7 +1430,7 @@ Note that this adds a keyring to the current list. If the intent is to
 use the specified keyring alone, use @option{--keyring} along with
 @option{--no-default-keyring}.
 
-If the the option @option{--no-keyring} has been used no keyrings will
+If the option @option{--no-keyring} has been used no keyrings will
 be used at all.
 
 
@@ -2276,6 +2292,12 @@ opposite meaning. The options are:
   the most recent self-signature on each user ID. This option is the
   same as running the @option{--edit-key} command "minimize" after import.
   Defaults to no.
+
+  @item restore
+  @itemx import-restore
+  Import in key restore mode.  This imports all data which is usually
+  skipped during import; including all GnuPG specific data.  All other
+  contradicting options are overridden.
 @end table
 
 @item --import-filter @code{@var{name}=@var{expr}}
@@ -2386,6 +2408,13 @@ opposite meaning. The options are:
   @c when the exported subkey is to be used on an unattended machine where
   @c a passphrase doesn't necessarily make sense. Defaults to no.
 
+  @item backup
+  @itemx export-backup
+  Export for use as a backup.  The exported data includes all data
+  which is needed to restore the key or keys later with GnuPG.  The
+  format is basically the OpenPGP format but enhanced with GnuPG
+  specific data.  All other contradicting options are overridden.
+
   @item export-clean
   Compact (remove all signatures from) user IDs on the key being
   exported if the user IDs are not usable. Also, do not export any
@@ -2741,6 +2770,9 @@ 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").
 
+If you suffix @var{epoch} with an exclamation mark (!), the system time
+will appear to be frozen at the specified time.
+
 @item --enable-progress-filter
 @opindex enable-progress-filter
 Enable certain PROGRESS status outputs. This option allows frontends
@@ -3359,7 +3391,7 @@ For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
 For internal purposes @command{@gpgname} creates and maintains a few other
-files; They all live in in the current home directory (@pxref{option
+files; They all live in the current home directory (@pxref{option
 --homedir}).  Only the @command{@gpgname} program may modify these files.
 
 
@@ -3738,17 +3770,68 @@ way to do this.  The options @option{--status-fd} and @option{--batch}
 are almost always required for this.
 
 @menu
+* Programmatic use of GnuPG:: Programmatic use of GnuPG
+* Ephemeral home directories:: Ephemeral home directories
+* The quick key manipulation interface:: The quick key manipulation interface
 * Unattended GPG key generation::  Unattended key generation
 @end menu
 
 
+@node Programmatic use of GnuPG
+@subsection Programmatic use of GnuPG
+
+Please consider using GPGME instead of calling @command{@gpgname}
+directly.  GPGME offers a stable, backend-independent interface for
+many cryptographic operations.  It supports OpenPGP and S/MIME, and
+also allows interaction with various GnuPG components.
+
+GPGME provides a C-API, and comes with bindings for C++, Qt, and
+Python.  Bindings for other languages are available.
+
+@node Ephemeral home directories
+@subsection Ephemeral home directories
+
+Sometimes you want to contain effects of some operation, for example
+you want to import a key to inspect it, but you do not want this key
+to be added to your keyring.  In earlier versions of GnuPG, it was
+possible to specify alternate keyring files for both public and secret
+keys.  In modern GnuPG versions, however, we changed how secret keys
+are stored in order to better protect secret key material, and it was
+not possible to preserve this interface.
+
+The preferred way to do this is to use ephemeral home directories.
+This technique works across all versions of GnuPG.
+
+Create a temporary directory, create (or copy) a configuration that
+meets your needs, make @command{@gpgname} use this directory either
+using the environment variable @var{GNUPGHOME}, or the option
+@option{--homedir}.  GPGME supports this too on a per-context basis,
+by modifying the engine info of contexts.  Now execute whatever
+operation you like, import and export key material as necessary.  Once
+finished, you can delete the directory.  All GnuPG backend services
+that were started will detect this and shut down.
+
+@node The quick key manipulation interface
+@subsection The quick key manipulation interface
+
+Recent versions of GnuPG have an interface to manipulate keys without
+using the interactive command @option{--edit-key}.  This interface was
+added mainly for the benefit of GPGME (please consider using GPGME,
+see the manual subsection ``Programmatic use of GnuPG'').  This
+interface is described in the subsection ``How to manage your keys''.
+
 @node Unattended GPG key generation
 @subsection Unattended key generation
 
 The command @option{--generate-key} may be used along with the option
-@option{--batch} for unattended key generation.  The parameters are
-either read from stdin or given as a file on the command line.
-The format of the parameter file is as follows:
+@option{--batch} for unattended key generation.  This is the most
+flexible way of generating keys, but it is also the most complex one.
+Consider using the quick key manipulation interface described in the
+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.
@@ -3791,16 +3874,21 @@ Perform the key generation.  Note that an implicit commit is done at
 the next @asis{Key-Type} parameter.
 
 @item %pubring @var{filename}
-@itemx %secring @var{filename}
 Do not write the key to the default or commandline given keyring but
 to @var{filename}.  This must be given before the first commit to take
 place, duplicate specification of the same filename is ignored, the
 last filename before a commit is used.  The filename is used until a
 new filename is used (at commit points) and all keys are written to
 that file. If a new filename is given, this file is created (and
-overwrites an existing one).  For GnuPG versions prior to 2.1, both
-control statements must be given. For GnuPG 2.1 and later
-@samp{%secring} is a no-op.
+overwrites an existing one).
+
+See the previous subsection ``Ephemeral home directories'' for a more
+robust way to contain side-effects.
+
+@item %secring @var{filename}
+This option is a no-op for GnuPG 2.1 and later.
+
+See the previous subsection ``Ephemeral home directories''.
 
 @item %ask-passphrase
 @itemx %no-ask-passphrase
@@ -3918,8 +4006,9 @@ generation to associate a key parameter block with a status line.
 @end table
 
 @noindent
-Here is an example on how to create a key:
+Here is an example on how to create a key in an ephemeral home directory:
 @smallexample
+$ export GNUPGHOME="$(mktemp -d)"
 $ cat >foo <<EOF
      %echo Generating a basic OpenPGP key
      Key-Type: DSA
@@ -3931,23 +4020,21 @@ $ cat >foo <<EOF
      Name-Email: joe@@foo.bar
      Expire-Date: 0
      Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
      # Do a commit here, so that we can later print "done" :-)
      %commit
      %echo done
 EOF
 $ @gpgname --batch --generate-key foo
  [...]
-$ @gpgname --no-default-keyring --secret-keyring ./foo.sec \
-       --keyring ./foo.pub --list-secret-keys
-/home/wk/work/gnupg-stable/scratch/foo.sec
-------------------------------------------
-sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
-ssb  1024g/8F70E2C0 2000-03-09
+$ @gpgname --list-secret-keys
+/tmp/tmp.0NQxB74PEf/pubring.kbx
+-------------------------------
+sec   dsa1024 2016-12-16 [SCA]
+      768E895903FC1C44045C8CB95EEBDB71E9E849D0
+uid           [ultimate] Joe Tester (with stupid passphrase) <joe@@foo.bar>
+ssb   elg1024 2016-12-16 [E]
 @end smallexample
 
-
 @noindent
 If you want to create a key with the default algorithms you would use
 these parameters:
@@ -3960,8 +4047,6 @@ these parameters:
      Name-Email: joe@@foo.bar
      Expire-Date: 0
      Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
      # Do a commit here, so that we can later print "done" :-)
      %commit
      %echo done