What is it?
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.
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.
Installing from PyPI
You can install this package from the Python Package Index (pyPI) by running:
pip install python-gnupg
There is at least one fork of this project, which was apparently created
because an earlier version of this software used the
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.
Installing from a source distribution archive
To install this package from a source distribution archive, do the following:
- Extract all the files in the distribution archive to some directory on your system.
- In that directory, run
python setup.py install.
- Optionally, run
python test_gnupg.pyto ensure that the package is working as expected.
- The developers of the GNU Privacy Guard.
- The original version of this module was developed by Andrew Kuchling.
- It was improved by Richard Jones.
- It was further improved by Steve Traugott.
The present incarnation, based on the earlier versions, uses the
module and so works on Windows as well as Unix/Linux platforms. It's not,
however, 100% backwards-compatible with earlier incarnations.
GCnn refers to an issue nn on Google Code.
Released: Not yet.
- 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 #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 support for CI using AppVeyor.
Fixed #108: Changed how any return value from the
on_datacallable is processed. In earlier versions, the return value was ignored. In this version, if the return value is
False, the data received from
gpgis not buffered. Otherwise (if the value is
True, for example), the data is buffered as normal. This functionality can be used to do your own buffering, or to prevent buffering altogether.
on_datacallable is also called once with an empty byte-string to signal the end of data from
Fixed #97: Added an additional attribute
GPGinstances, which defaults to
False. It seems that
gpgis 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
Trueto 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.
- Added --no-verbose to the gpg command line, in case verbose is specified in gpg.conf - we don't need verbose output.
- Fixed #81: Subkey information is now collected and returned in a
subkey_infodictionary keyed by the subkey's ID.
- Fixed #84: GPG2 version is now correctly detected on OS X.
- Fixed #94: Added
expect_passphrasepassword for use on GnuPG >= 2.1 when passing passphrase to
- Fixed #95: Provided a
trust_keysmethod 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.
- 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
--with-colons. Thanks to Daniel Kahn Gillmor for the patch.
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.
close_filekeyword argument to verify_file to allow the file closing to be made optional. Current behaviour is maintained -
close_file=Falsecan be passed to skip closing the file being verified.
- Added the
extra_argskeyword parameter to allow custom arguments to be passed to the
- Instances of the
GPGclass now have an additional
on_dataattribute, 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
gpgexecutable. The callable can do whatever it likes with the chunks passed to it - e.g. write them to a separate stream. The callable should not raise any exceptions (unless it wants the current operation to fail).
- Added support for
KEY_CONSIDEREDin 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
- Ensured that utf-8 encoding is used when the
--with-columnmode is used. Thanks to Yann Leboulanger for the patch.
--fixed-list-mode. Thanks to Werner Koch for the pointer.
- 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
FAILUREmessage caused by passing an incorrect passphrase is handled.
EXPORT_RESmessages 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
- 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.
- Fixed #22: handled
PROGRESSmessages during verification and signing.
- Fixed #26: handled
PINENTRY_LAUNCHEDmessages during verification, decryption and key generation.
- Fixed #28: Allowed a default Name-Email to be computed even when neither of
USERNAMEare 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_LAUNCHEDmessages 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_keysmethod 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_mapdict 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.
Signed with PGP key: Vinay Sajip (CODE SIGNING KEY) <firstname.lastname@example.org>
Key Fingerprint : CA74 9061 914E AC13 8E66 EADB 9147 B477 339A 9B86
- Added an
outputkeyword parameter to the
sign_filemethods, to allow writing the signature to a file. Thanks to Jannis Leidel for the patch.
- Allowed specifying
signkeyword 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().
SearchKeysclasses to maximise use of common functions.
- Fixed GC94: Added
armoroptions when exporting keys. This addition was inadvertently left out of 0.3.6.
- Fixed GC82: Enabled fast random tests on gpg as well as gpg2.
- Fixed GC85: Avoided deleting temporary file to preserve its permissions.
- Fixed GC87: Avoided writing passphrase to log.
- Fixed GC95: Added
verify_data()method to allow verification of signatures in memory.
- Fixed GC96: Regularised end-of-line characters.
- Fixed GC98: Rectified problems with earlier fix for shell injection.
- Added improved shell quoting to guard against shell injection.
- Fixed GC76: Added
- Fixed GC77: Allowed specifying a symmetric cipher algorithm.
- Fixed GC78: Fell back to utf-8 encoding when no other could be determined.
- Fixed GC79: Default key length is now 2048 bits.
- Fixed GC80: Removed the Name-Comment default in key generation.
- Fixed GC65: Fixed encoding exception when getting version.
- Fixed GC66: Now accepts sets and frozensets where appropriate.
- Fixed GC67: Hash algorithm now captured in sign result.
- Fixed GC68: Added support for
- Fixed GC70: Added support for multiple keyrings.
- Fixed GC57: Handled control characters in
- Fixed GC61: Enabled fast random for testing.
- Fixed GC62: Handled
- Fixed GC63: Handled
- Fixed GC56: Disallowed blank values in key generation.
- Fixed GC57: Handled colons and other characters in
- Fixed GC59/GC60: Handled
INV_SGNRstatus during verification and removed calls requiring interactive password input from doctests.
- Fixed GC45: Allowed additional arguments to gpg executable.
- Fixed GC50: Used latin-1 encoding in tests when it's known to be required.
- Fixed GC51: Test now returns non-zero exit status on test failure.
- Fixed GC53: Now handles
- Fixed GC55: Verification and decryption now return trust level of signer in integer and text form.
- Fixed GC49: Reinstated Yann Leboulanger's change to support subkeys (accidentally left out in 0.2.7).
- Fixed GC36: Now handles
- Fixed GC40: Now handles
random_binary_data fileis no longer shipped, but constructed by the test suite if needed.
- Fixed GC29: Now handles
- Fixed GC30: Fixed an encoding problem.
- Fixed GC33: Quoted arguments for added safety.
- Fixed GC24: License is clarified as BSD.
- Fixed GC25: Incorporated Daniel Folkinshteyn's changes.
- Fixed GC26: Incorporated Yann Leboulanger's subkey change.
- Fixed GC27: Incorporated hysterix's support for symmetric encryption.
- Did some internal cleanups of Unicode handling.
- Fixed GC14: Should be able to accept passphrases from GPG-Agent.
- Fixed GC19: Should be able to create a detached signature.
- Fixed GC21/GC23: Better handling of less common responses from GPG.
- Fixed GC11/GC16: Detached signatures can now be created.
- Fixed GC3: Detached signatures can be verified.
- Fixed GC12: Better support for RSA and IDEA.
- Fixed GC15/GC17: Better support for non-ASCII input.
- Fixed GC9: Now allows encryption without armor and the ability to encrypt and decrypt directly to/from files.
- Fixed GC7: Made sending data to process threaded and added a test case. With a test data file used by the test case, the archive size has gone up to 5MB (the size of the test file).
- Fixed GC5/GC6: Added
--passphrase-fdand changed the name of the distribution file to add the
- Fixed GC2: Added
handle_status()method to the
- Various changes made to support Python 3.0.
- Initial release.