|badge1| |badge2| |badge3|
.. |badge1| image:: https://img.shields.io/github/actions/workflow/status/vsajip/python-gnupg/python-package.yml :alt: GitHub test status
.. |badge2| image:: https://img.shields.io/codecov/c/github/vsajip/python-gnupg :target: https://app.codecov.io/gh/vsajip/python-gnupg :alt: GitHub coverage status
.. |badge3| image:: https://img.shields.io/pypi/v/python-gnupg :target: https://pypi.org/project/python-gnupg/ :alt: PyPI package
The GNU Privacy Guard (gpg, or gpg.exe on Windows) is a command-line program which provides support for programmatic access via spawning a separate process to run it and then communicating with that process from your program.
This project, python-gnupg, implements a Python library which takes care
of the internal details and allows its users to generate and manage keys,
encrypt and decrypt data, and sign and verify messages.
You can install this package from the Python Package Index (pyPI) by running::
pip install python-gnupg.. important::
There is at least one fork of this project, which was apparently created
because an earlier version of this software used the subprocess module
with shell=True, making it vulnerable to shell injection. This is no
longer the case.
Forks may not be drop-in compatible with this software, so take care to use
the correct version, as indicated in the pip install command above.
To install this package from a source distribution archive, do the following:
pip install ., referencing a suitable pip (e.g. one
from a specific venv which you want to install to).python test_gnupg.py to ensure that the package is
working as expected.The present incarnation, based on the earlier versions, uses the subprocess
module and so works on Windows as well as Unix/Linux platforms. It's not,
however, 100% backwards-compatible with earlier incarnations.
.. note:: GCnn refers to an issue nn on Google Code.
Released: Not yet
Released: 2024-09-20
Fix #117: Add WKD (Web Key Directory) support for auto-locating keys. Thanks to Myzel394 for the patch.
Fix #237: Ensure local variable is initialized even when an exception occurs.
Fix #239: Remove logging of decryption result.
Released: 2023-12-12
Fix #228: Clarify documentation for encryption/decryption.
Make I/O buffer size configurable via buffer_size attribute on a GPG instance.
Released: 2023-07-22
Added TRUST_EXPIRED to trust_keys. Thanks to Leif Liddy for the patch.
Fix #206: Remove deprecated --always-trust in favour of --trust-model always
Fix #208: Add status_detail attribute to result objects which is populated when
the status is 'invalid recipient' (encryption/decryption) or 'invalid signer'
(signing). This attribute will be set when the result object's status attribute is
set to invalid recipient and will contain more information about the failure in the
form of reason:ident where reason is a text description of the reason, and
ident identifies the recipient key.
Add scan_keys_mem() function to scan keys in a string. Thanks to Sky Moore
for the patch.
Fix #214: Handle multiple signatures when one of them is invalid or unverified.
A problems attribute was added which holds problems reported by gpg
during verification. This is a list of dictionaries, one for each reported
problem. Each dictionary will have status and keyid keys indicating
the problem and the corresponding key; other information in the dictionaries
will be error specific.
Fix #217: Use machine-readable interface to query the gpg version. Thanks to Justus
Winter for the patch.
Added the ability to export keys to a file. Thanks to Leif Liddy for the patch.
Released: 2022-08-23
Fixed #181: Added the ability to pass file paths to encrypt_file, decrypt_file, sign_file, verify_file, get_recipients_file and added import_keys_file.
Fixed #183: Handle FAILURE and UNEXPECTED conditions correctly. Thanks to sebbASF for the patch.
Fixed #185: Handle VALIDSIG arguments more robustly.
Fixed #188: Remove handling of DECRYPTION_FAILED from Verify code, as not required there. Thanks to sebbASF for the patch.
Fixed #190: Handle KEY_CREATED more robustly.
Fixed #191: Handle NODATA messages during verification.
Fixed #196: Don't log chunk data by default, as it could contain sensitive information (during decryption, for example).
Added the ability to pass an environment to the gpg executable. Thanks to Edvard Rejthar for the patch.
Released: 2022-05-20
Fixed #161: Added a status attribute to the returned object from gen_key() which is set to 'ok' if a key was successfully created, or 'key not created' if that was reported by gpg, or None in any other case.
Fixed #164: Provided the ability to add subkeys. Thanks to Daniel Kilimnik for the feature request and patch.
Fixed #166: Added keygrip values to the information collected when keys are listed. Thanks to Daniel Kilimnik for the feature request and patch.
Fixed #173: Added extra_args to send_keys(), recv_keys() and search_keys() to allow passing options relating to key servers.
Released: 2021-11-24
Fixed #147: Return gpg's return code in all result instances.
Fixed #152: Add check for invalid file objects.
Fixed #157: Provide more useful status message when a secret key is absent.
Fixed #158: Added a get_recipients() API to find the recipients of an encrypted message without decrypting it.
Released: 2021-03-11
Fixed #129, #141: Added support for no passphrase during key generation.
Fixed #143: Improved permission-denied test. Thanks to Elliot Cameron for the patch.
Fixed #144: Updated logging to only show partial results.
Fixed #146: Allowed a passphrase to be passed to import_keys(). Thanks to Chris de Graaf for the patch.
Released: 2020-04-17
Fixed #122: Updated documentation about gnupghome needing to be an existing directory.
Fixed #123: Handled error conditions from gpg when calling trust_keys().
Fixed #124: Avoided an exception being raised when ImportResult.summary() was called after a failed recv_keys().
Fixed #128: Added ECC support by changing key generation parameters. (The Key-Length value isn't added if a curve is specified.)
Fixed #130: Provided a mechanism to provide more complete error messages.
Support for Python versions 3.5 and under is discontinued, except for Python 2.7.
Released: 2019-08-12
Fixed #107: Improved documentation.
Fixed #112: Raised a ValueError if a gnupghome is specified which is not an existing directory.
Fixed #113: Corrected stale link in the documentation.
Fixed #116: Updated documentation to clarify when spurious key-expired/ signature-expired messages might be seen.
Fixed #119: Added --yes to avoid pinentry when deleting secret keys with GnuPG >= 2.1.
A warning is logged if gpg returns a non-zero return code.
Added extra_args to import_keys.
Added support for CI using AppVeyor.
Released: 2019-01-24
Fixed #108: Changed how any return value from the on_data callable is
processed. In earlier versions, the return value was ignored. In this version,
if the return value is False, the data received from gpg is not
buffered. Otherwise (if the value is None or True, for example), the
data is buffered as normal. This functionality can be used to do your own
buffering, or to prevent buffering altogether.
The on_data callable is also called once with an empty byte-string to
signal the end of data from gpg.
Fixed #97: Added an additional attribute check_fingerprint_collisions to
GPG instances, which defaults to False. It seems that gpg is happy
to have duplicate keys and fingerprints in a keyring, so we can't be too
strict. A user can set this attribute of an instance to True to trigger a
check for collisions.
Fixed #111: With GnuPG 2.2.7 or later, provide the fingerprint of a signing key for a failed signature verification, if available.
Fixed #21: For verification where multiple signatures are involved, a mapping of signature_ids to fingerprint, keyid, username, creation date, creation timestamp and expiry timestamp is provided.
Added a check to disallow certain control characters ('\r', '\n', NUL) in passphrases.
Released: 2018-06-13
Released: 2018-03-28
Fixed #81: Subkey information is now collected and returned in a subkey_info
dictionary keyed by the subkey's ID.
Fixed #84: GPG2 version is now correctly detected on OS X.
Fixed #94: Added expect_passphrase password for use on GnuPG >= 2.1 when
passing passphrase to gpg via pinentry.
Fixed #95: Provided a trust_keys method to allow setting the trust level
for keys. Thanks to William Foster for a suggested implementation.
Made the exception message when the gpg executable is not found contain the path of the executable that was tried. Thanks to Kostis Anagnostopoulos for the suggestion.
Fixed #100: Made the error message less categorical in the case of a failure with an unspecified reason, adding some information from gpg error codes when available.
Released: 2017-07-06
Updated message handling logic to no longer raise exceptions when a message isn't recognised. Thanks to Daniel Kahn Gillmor for the patch.
Always use always use --fixed-list-mode, --batch and
--with-colons. Thanks to Daniel Kahn Gillmor for the patch.
Improved scan_keys() handling on GnuPG >= 2.1. Thanks to Daniel Kahn
Gillmor for the patch.
Improved test behaviour with GnuPG >= 2.1. Failures when deleting test directory trees are now ignored. Thanks to Daniel Kahn Gillmor for the patch.
Added close_file keyword argument to verify_file to allow the file closing
to be made optional. Current behaviour is maintained - close_file=False
can be passed to skip closing the file being verified.
Added the extra_args keyword parameter to allow custom arguments to be
passed to the gpg executable.
Instances of the GPG class now have an additional on_data attribute,
which defaults to None. It can be set to a callable which will be called
with a single argument - a binary chunk of data received from the gpg
executable. The callable can do whatever it likes with the chunks passed to it
Released: 2017-01-29
Added support for KEY_CONSIDERED in more places - encryption /
decryption, signing, key generation and key import.
Partial fix for #32 (GPG 2.1 compatibility). Unfortunately, better support cannot be provided at this point, unless there are certain changes (relating to pinentry popups) in how GPG 2.1 works.
Fixed #60: An IndexError was being thrown by scan_keys().
Ensured that utf-8 encoding is used when the --with-column mode is
used. Thanks to Yann Leboulanger for the patch.
list_keys() now uses --fixed-list-mode. Thanks to Werner Koch
for the pointer.
Released: 2016-09-10
Fixed #38: You can now request information about signatures against keys. Thanks to SunDwarf for the suggestion and patch, which was used as a basis for this change.
Fixed #49: When exporting keys, no attempt is made to decode the output when armor=False is specified.
Fixed #53: A FAILURE message caused by passing an incorrect passphrase
is handled.
Handled EXPORTED and EXPORT_RES messages while exporting keys. Thanks
to Marcel Pörner for the patch.
Fixed #54: Improved error message shown when gpg is not available.
Fixed #55: Added support for KEY_CONSIDERED while verifying.
Avoided encoding problems with filenames under Windows. Thanks to Kévin Bernard-Allies for the patch.
Fixed #57: Used a better mechanism for comparing keys.
Released: 2015-09-24
Fixed #22: handled PROGRESS messages during verification and signing.
Fixed #26: handled PINENTRY_LAUNCHED messages during verification,
decryption and key generation.
Fixed #28: Allowed a default Name-Email to be computed even when neither of
LOGNAME and USERNAME are in the environment.
Fixed #29: Included test files missing from the tarball in previous versions.
Fixed #39: On Python 3.x, passing a text instead of a binary stream caused
file decryption to hang due to a UnicodeDecodeError. This has now been
correctly handled: The decryption fails with a "no data" status.
Fixed #41: Handled Unicode filenames correctly by encoding them on 2.x using the file system encoding.
Fixed #43: handled PINENTRY_LAUNCHED messages during key export. Thanks
to Ian Denhardt for looking into this.
Hide the console window which appears on Windows when gpg is spawned. Thanks to Kévin Bernard-Allies for the patch.
Subkey fingerprints are now captured.
The returned value from the list_keys method now has a new attribute,
key_map, which is a dictionary mapping key and subkey fingerprints to
the corresponding key's dictionary. With this change, you don't need to
iterate over the (potentially large) returned list to search for a key with
a given fingerprint - the key_map dict will take you straight to the key
info, whether the fingerprint you have is for a key or a subkey. Thanks to
Nick Daly for the initial suggestion.
Released: 2014-12-07
Signed with PGP key: Vinay Sajip (CODE SIGNING KEY) vinay_sajip@yahoo.co.uk
Key Fingerprint : CA74 9061 914E AC13 8E66 EADB 9147 B477 339A 9B86
Added an output keyword parameter to the sign and
sign_file methods, to allow writing the signature to a file.
Thanks to Jannis Leidel for the patch.
Allowed specifying True for the sign keyword parameter,
which allows use of the default key for signing and avoids having to
specify a key id when it's desired to use the default. Thanks to
Fabian Beutel for the patch.
Used a uniform approach with subprocess on Windows and POSIX: shell=True is not used on either.
When signing/verifying, the status is updated to reflect any expired or revoked keys or signatures.
Handled 'NOTATION_NAME' and 'NOTATION_DATA' during verification.
Fixed #1, #16, #18, #20: Quoting approach changed, since now shell=False.
Fixed #14: Handled 'NEED_PASSPHRASE_PIN' message.
Fixed #8: Added a scan_keys method to allow scanning of keys without the need to import into a keyring. Thanks to Venzen Khaosan for the suggestion.
Fixed #5: Added '0x' prefix when searching for keys. Thanks to Aaron Toponce for the report.
Fixed #4: Handled 'PROGRESS' message during encryption. Thanks to Daniel Mills for the report.
Fixed #3: Changed default encoding to Latin-1.
Fixed #2: Raised ValueError if no recipients were specified for an asymmetric encryption request.
Handled 'UNEXPECTED' message during verification. Thanks to David Andersen for the patch.
Replaced old range(len(X)) idiom with enumerate().
Refactored ListKeys / SearchKeys classes to maximise use of common
functions.
Fixed GC94: Added export-minimal and armor options when exporting
keys. This addition was inadvertently left out of 0.3.6.
Released: 2014-02-05
verify_data() method to allow verification of
signatures in memory.Released: 2013-08-30
search_keys() and send_keys() methods.Released: 2013-06-05
--secret-keyring.Released: 2013-03-11
list_keys().KEYEXPIRED status.NO_SGNR status.Released: 2013-01-17
list_keys().INV_SGNR status during verification and removed
calls requiring interactive password input from doctests.Released: 2012-09-01
INV_SGNR and KEY_NOT_CREATED statuses.Released: 2012-05-12
Released: 2012-03-29
CARDCTRL and POLICY_URL messages.DECRYPTION_INFO, DECRYPTION_FAILED and
DECRYPTION_OKAY messages.random_binary_data file is no longer shipped, but constructed by the
test suite if needed.Released: 2011-09-02
IMPORT_RES while verifying.Released: 2011-04-10
Released: 2011-01-25
Released: 2010-10-13
Released: 2010-03-01
Released: 2010-01-07
Released: 2009-10-06
--batch when specifying --passphrase-fd and
changed the name of the distribution file to add the python- prefix.Released: 2009-08-07
handle_status() method to the ListKeys class.Released: 2009-07-16
Released: 2009-07-04