[git] GnuPG - branch, master, updated. gnupg-2.1.16-131-gca02a8b
by Justus Winter
cvs at cvs.gnupg.org
Fri Dec 16 14:31:09 CET 2016
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "The GNU Privacy Guard".
The branch, master has been updated
via ca02a8b78fca8815388a859962584d75169ae3ee (commit)
via 116a78eb869c4c589228bd0d6deff7c7a9f92dfb (commit)
from fea9da4a8afab6f3a49cdbbcc4a7a21f27a6d3e8 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit ca02a8b78fca8815388a859962584d75169ae3ee
Author: Justus Winter <justus at g10code.com>
Date: Fri Dec 16 13:52:03 2016 +0100
doc: Improve section on unattended key generation.
* doc/gpg.texi: Improve the subsection on unattended key generation by
suggesting the quick key manipulation interface as an alternative, and
by suggesting alternatives to '%pubring' and '%secring'. Simplify
examples accordingly.
GnuPG-bug-id: 2400
Signed-off-by: Justus Winter <justus at g10code.com>
diff --git a/doc/gpg.texi b/doc/gpg.texi
index a7e9204..b1e1a2a 100644
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@@ -3796,9 +3796,14 @@ interface is described in the subsection ``How to manage your keys''.
@subsection Unattended key generation
The command @option{--generate-key} may be used along with the option
- at 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:
+ at 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.
@@ -3841,16 +3846,21 @@ Perform the key generation. Note that an implicit commit is done at
the next @asis{Key-Type} parameter.
@item %pubring @var{filename}
- at 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
- at 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.
+
+ at 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
@@ -3968,8 +3978,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
@@ -3981,23 +3992,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:
@@ -4010,8 +4019,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
commit 116a78eb869c4c589228bd0d6deff7c7a9f92dfb
Author: Justus Winter <justus at g10code.com>
Date: Fri Dec 16 13:49:16 2016 +0100
doc: Add documentation for programmatic use of GnuPG.
* doc/gpg.texi: New subsections on programmatic use of GnuPG,
ephemeral home directories, and the quick key manipulation interface.
Signed-off-by: Justus Winter <justus at g10code.com>
diff --git a/doc/gpg.texi b/doc/gpg.texi
index ab0289d..a7e9204 100644
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@@ -3742,10 +3742,56 @@ 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
+ at node Programmatic use of GnuPG
+ at 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.
+
+ at node Ephemeral home directories
+ at 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
+ at 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.
+
+ at node The quick key manipulation interface
+ at 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
-----------------------------------------------------------------------
Summary of changes:
doc/gpg.texi | 91 +++++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 72 insertions(+), 19 deletions(-)
hooks/post-receive
--
The GNU Privacy Guard
http://git.gnupg.org
More information about the Gnupg-commits
mailing list