GnuPG Made Easy. NOTE: Maintainers are not tracking this mirror. Do not make pull requests here, nor comment any commits, submit them usual way to bug tracker (https://www.gnupg.org/documentation/bts.html) or to the mailing list (https://www.gnupg.org/documentation/mailing-lists.html).
cad1210fb8
* src/gpgme.c (gpgme_set_export_session_keys): New function.
(gpgme_get_export_session_keys): New function.
* src/gpgme.h.in (struct _gpgme_op_decrypt_result): Add session_key
member.
(gpgme_{set,get}_export_session_keys): Declare new functions.
* src/libgpgme.vers, src/gpgme.def: Export new functions in shared
object.
* src/engine.h: (_gpgme_engine_op_decrypt) Add export_session_key
parameter.
(_gpgme_engine_op_decrypt_verify): Add export_session_key parameter.
* src/engine-backend.h: (struct engine_ops): Change function
pointer declarations to match.
* src/context.h (struct gpgme_context): Add export_session_keys member.
* src/decrypt.c (release_op_data): Free result.session_key.
(_gpgme_decrypt_status_handler): Store a copy of the exported session
key.
(decrypt_start): Pass export_session_keys from the context.
* src/decrypt-verify.c (decrypt_verify_start): Pass
export_session_keys from context.
* src/engine.c (_gpgme_engine_op_decrypt): Pass through
export_session_key flag.
(_gpgme_engine_op_decrypt_verify): Pass through export_session_key
flag.
* src/engine-gpg.c (gpg_decrypt): If export_session_key is set, add
--export-session-key to argument list.
* src/engine-gpgsm.c (gpgsm_decrypt): Ignore export_session_key for
now, since gpgsm offers no such mechanism.
* src/engine-uiserver.c (_uiserver_decrypt): If export_session_key is
set, add --export-session-key flag to cmd.
* doc/gpgme.texi: Document new functions and session_key member of
decrypt_result_t.
* doc/uiserver.texi: Add --export-session-key flag to DECRYPT command.
--
gpg(1) documents session key export as useful for key escrow, and is
rightly dubious of that use case. However, session key export is also
useful in other use cases. Two examples from MUA development (where
this functionality would be specifically useful to me right now):
* If the MUA stores a local copy of the session key upon decrypting
the message, it can re-decrypt the message without expensive
asymmetric operations. When rendering a thread with dozens of
encrypted messages, this can represent a significant speedup.
* A user may have expired encryption-capable secret key material,
along with many messages encrypted to that material. If she stores
the session keys for those messages she wants to keep, she can
destroy her secret key material and make any messages she has
deleted completely unrecoverable, even to an attacker who gets her
remaining secret keys in the future.
This patchset makes a two specific implementation decisions that could
have gone in different ways. I welcome feedback on preferred outcomes.
0) session key representation: we currently represent the session key
as an opaque textual string, rather than trying to provide any
sort of in-memory structure. While it wouldn't be hard to parse
the data produced by gpg's --export-session-key, I chose to use
the opaque string rather than lock in a particular data format.
1) API/ABI: i've added a member to gpgme_op_decrypt_result_t. This
has the potential to cause an out-of-bound memory access if
someone uses code compiled against the newer verision, but linked
at runtime against an older version. I've attempted to limit that
risk by documenting that users must verify
gpgme_get_export_session_keys() before accessing this new struct
member -- this means that code expecting this capability will
require the symbol at link-time, and will refuse to link against
older versions.
Another approach to solving this problem would be to avoid
modifying gpgme_op_decrypt_result_t, and to introduce instead a
new function gpgme_op_session_key(), which could be called in the
same places as gpgme_op_decrypt_result(). Depending on the
representation of the session key, this might introduce new
memory-management burdens on the user of the library, and the
session key is certainly part of a decryption result, so it seemed
simpler to go with what i have here.
If anyone has strong preferences that these choices should be solved
in a different way, i'm happy to hear them.
Additionally, I note that i'm also still pretty unclear about how the
"UI Server" fits into this whole ecosystem. In particular, I don't
know whether it's kosher to just add an --export-session-key flag to
the DECRYPT operation without actually having implemented it anywhere,
but i don't see where i would actually implement it either :/
If this patch (or some variant) is adopted, i will supply another
patch that permits offering a session key during decryption (e.g. "gpg
--override-session-key"), but I wanted to get these implementation
choices ironed out first.
Gnupg-Bug-Id: 2754
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
On the concern of adding a new field to a structure: It may not be
clearly documented but we don't expect that a user ever allocates such
a structure - those result structure may only be created bu gpgme and
are read-only for the user. Adding a new member constitutes a
compatible ABI change and thus an older SO may not be used by code
compiled with a header for the newer API. Unless someone tinkers with
the build system, this should never happen. We have added new fields
to result structure may times and I can't remember any problems.
- wk
|
||
|---|---|---|
| build-aux | ||
| contrib | ||
| doc | ||
| lang | ||
| m4 | ||
| src | ||
| tests | ||
| .gitignore | ||
| acinclude.m4 | ||
| AUTHORS | ||
| autogen.rc | ||
| autogen.sh | ||
| ChangeLog | ||
| ChangeLog-2011 | ||
| configure.ac | ||
| COPYING | ||
| COPYING.LESSER | ||
| gpgme.spec.in | ||
| gpgme.txt | ||
| INSTALL | ||
| Makefile.am | ||
| missing | ||
| NEWS | ||
| README | ||
| README.GIT | ||
| THANKS | ||
| TODO | ||
GPGME - GnuPG Made Easy
---------------------------
Copyright 2001-2016 g10 Code GmbH
This file is free software; as a special exception the author gives
unlimited permission to copy and/or distribute it, with or without
modifications, as long as this notice is preserved.
This file is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
Introduction
--------------
GnuPG Made Easy (GPGME) is a C language library that allows to add
support for cryptography to a program. It is designed to make access
to public key crypto engines like GnuPG or GpgSM easier for
applications. GPGME provides a high-level crypto API for encryption,
decryption, signing, signature verification and key management.
GPGME comes with language bindings for Common Lisp, C++, QT, Python2
and Python 3.
GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the
Cryptographic Message Syntax (CMS).
See the files COPYING, COPYING.LESSER, and each file for copyright and
warranty information. The file AUTHORS has a list of authors and
useful web and mail addresses.
Installation
--------------
See the file INSTALL for generic installation instructions.
Check that you have unmodified sources. See below on how to do this.
Don't skip it - this is an important step!
To build GPGME, you need to install libgpg-error (>= 1.11) and
Libassuan (>= 2.0.2).
For support of the OpenPGP protocol (default), you should use the
latest version of GnuPG (>= 1.4) , available at:
ftp://ftp.gnupg.org/gcrypt/gnupg/. For support of the CMS
(Cryptographic Message Syntax) protocol and lot of other features, you
need a GnuPG version >= 2.0.
For building the GIT version of GPGME please see the file README.GIT
for more information.
How to Verify the Source
--------------------------
In order to check that the version of GPGME which you are going to
install is an original and unmodified one, you can do it in one of the
following ways:
a) If you have a trusted Version of GnuPG installed, you can simply check
the supplied signature:
$ gpg --verify gpgme-x.y.z.tar.gz.sig
This checks that the detached signature gpgme-x.y.z.tar.gz.sig is
indeed a a signature of gpgme-x.y.z.tar.gz. The key used to create
this signature is either of:
2048R/4F25E3B6 2011-01-12 [expires: 2019-12-31]
Key fingerprint = D869 2123 C406 5DEA 5E0F 3AB5 249B 39D2 4F25 E3B6
Werner Koch (dist sig)
rsa2048/E0856959 2014-10-29 [expires: 2019-12-31]
Key fingerprint = 46CC 7308 65BB 5C78 EBAB ADCF 0437 6F3E E085 6959
David Shaw (GnuPG Release Signing Key) <dshaw 'at' jabberwocky.com>
rsa2048/33BD3F06 2014-10-29 [expires: 2016-10-28]
Key fingerprint = 031E C253 6E58 0D8E A286 A9F2 2071 B08A 33BD 3F06
NIIBE Yutaka (GnuPG Release Key) <gniibe 'at' fsij.org>
rsa2048/7EFD60D9 2014-10-19 [expires: 2020-12-31]
Key fingerprint = D238 EA65 D64C 67ED 4C30 73F2 8A86 1B1C 7EFD 60D9
Werner Koch (Release Signing Key)
You may retrieve these files from the keyservers using this command
gpg --recv-keys 249B39D24F25E3B6 04376F3EE0856959 \
2071B08A33BD3F06 8A861B1C7EFD60D9
The keys are also available at https://gnupg.org/signature_key.html
and in released GnuPG tarballs in the file g10/distsigkey.gpg .
You have to make sure that these are really the desired keys and
not faked one. You should do this by comparing the fingerprints
with the fingerprints published elsewhere.
b) If you don't have any of the above programs, you have to verify
the SHA1 checksum:
$ sha1sum gpgme-x.y.z.tar.gz
This should yield an output _similar_ to this:
fd9351b26b3189c1d577f0970f9dcadc3412def1 gpgme-x.y.z.tar.gz
Now check that this checksum is _exactly_ the same as the one
published via the announcement list and probably via Usenet.
Documentation
---------------
For information how to use the library you can read the info manual,
which is also a reference book, in the doc/ directory. The programs
in the tests/ directory may also prove useful.
Please subscribe to the gnupg-devel@gnupg.org mailing list if you want
to do serious work.
For hacking on GPGME, please have a look at doc/HACKING.