GNU Privacy Guard (GnuPG) Made Easy Python Bindings HOWTO (English)

There is nothing new in version 1.14.0 because the GPGME Python bindings entered maintenance mode from version 1.13.1 (January, 2019).

Nor will there be anything substantively new added to subsequent versions unless a bug is found or the bindings exit maintenance mode.

See the What's New document for what is new in version 1.13.0.

See the What Was New document for what was new in version 1.12.0.

This is arguably the most popular means of integrating GPG with Python. The package utilises the subprocess module to implement wrappers for the gpg and gpg2 executables normally invoked on the command line (gpg.exe and gpg2.exe on Windows).

The popularity of this package stemmed from its ease of use and capability in providing the most commonly required features.

Unfortunately it has been beset by a number of security issues in the past; most of which stemmed from using unsafe methods of accessing the command line via the subprocess calls. While some effort has been made over the two to three years from 2015 to 2018 to mitigate this, particularly by no longer providing shell access through those subprocess calls, the wrapper is still somewhat limited in the scope of its GnuPG features coverage.

The python-gnupg package is available under the MIT license.

In 2015 Isis Lovecruft from the Tor Project forked and then re-implemented the python-gnupg package as just gnupg. This new package also relied on subprocess to call the gpg or gpg2 binaries, but did so somewhat more securely.

The naming and version numbering selected for this package, however, resulted in conflicts with the original python-gnupg and since its functions were called in a different manner to python-gnupg, the release of this package also resulted in a great deal of consternation when people installed what they thought was an upgrade that subsequently broke the code relying on it.

The gnupg package is available under the GNU General Public License version 3.0 (or any later version). An attempt to have it relicensed under a three clause BSD license failed when permission to do so could not be obtained from all contributors. This project appears to have been effectively abandoned as its lead developer moved on to other projects.

This package is the origin of these bindings, though they are somewhat different now. For details of when and how the PyME package was folded back into GPGME itself see the Short History document.¹

The PyME package was first released in 2002 and was also the first attempt to implement a low level binding to GPGME. In doing so it provided access to considerably more functionality than either the python-gnupg or gnupg packages.

The PyME package is only available for Python 2.6 and 2.7.

Porting the PyME package to Python 3.4 in 2015 is what resulted in it being folded into the GPGME project and the current bindings are the end result of that effort.

The PyME package is available under the same dual licensing as GPGME itself: the GNU General Public License version 2.0 (or any later version) and the GNU Lesser General Public License version 2.1 (or any later version).

Though none of the following are absolute requirements, they are all recommended for use with the Python bindings. In some cases these recommendations refer to which version(s) of CPython to use the bindings with, while others refer to third party modules which provide a significant advantage in some way.

1. If possible, use Python 3 instead of 2.
2. Favour a more recent version of Python since even 3.4 is due to reach EOL soon. In production systems and services, Python 3.6 should be robust enough to be relied on.
3. If possible add the following Python modules which are not part of the standard library: Requests, Cython, Pendulum and hkp4py.

Chances are quite high that at least the first one and maybe two of those will already be installed.

Note that, as with Cython, some of advanced use case scenarios will bring with them additional requirements. Most of these will be fairly well known and commonly installed ones, however, which are in many cases likely to have already been installed on many systems or be familiar to Python programmers.

See the GPGME README file for details of how to install GPGME from source.

Occasionally when installing GPGME with the Python bindings included it may be observed that the make portion of that process induces a very large number of warnings and, eventually, errors which end that part of the build process. Yet following that with make check and make install appears to work seamlessly.

The cause of this is related to the way SWIG needs to be called to dynamically generate the C bindings for GPGME in the first place. So the entire process will always produce lang/python/python2-gpg/ and lang/python/python3-gpg/ directories. These should contain the build output generated during compilation, including the complete bindings and module installed into site-packages.

Occasionally the errors in the early part or some other conflict (e.g. not installing as root or su) may result in nothing being installed to the relevant site-packages directory and the build directory missing a lot of expected files. Even when this occurs, the solution is actually quite simple and will always work.

That solution is simply to run the following commands as either the root user or prepended with sudo -H³ in the lang/python/ directory:

/path/to/pythonX.Y setup.py build
/path/to/pythonX.Y setup.py build
/path/to/pythonX.Y setup.py install

Yes, the build command does need to be run twice. Yes, you still need to run the potentially failing or incomplete steps during the configure, make and make install steps with installing GPGME. This is because those steps generate a lot of essential files needed, both by and in order to create, the bindings (including both the setup.py and gpgme.h files).

Regardless of whether you're installing for one version of Python or several, there will come a point where reinstallation is required. With most Python module installations, the installed files go into the relevant site-packages directory and are then forgotten about. Then the module is upgraded, the new files are copied over the old and that's the end of the matter.

While the same is true of these bindings, there have been intermittent issues observed on some platforms which have benefited significantly from removing all the previous installations of the bindings before installing the updated versions.

Removing the previous version(s) is simply a matter of changing to the relevant site-packages directory for the version of Python in question and removing the gpg/ directory and any accompanying egg-info files for that module.

In most cases this will require root or administration privileges on the system, but the same is true of installing the module in the first place.

For a variety of reasons it may be either necessary or just preferable to install the bindings to alternative installed Python versions which meet the requirements of these bindings.

On POSIX systems this will generally be most simply achieved by running the manual installation commands (build, build, install) as described in the previous section for each Python installation the bindings need to be installed to.

As per the SWIG documentation: the compilers, libraries and runtime used to build GPGME and the Python Bindings must match those used to compile Python itself, including the version number(s) (at least going by major version numbers and probably minor numbers too).

On most POSIX systems, including OS X, this will very likely be the case in most, if not all, cases. In the rare instance when this is not the case, simply compiling Python from source and using that will solve it.

Note that from GPGME 1.12.1 the default installation installs to each version of Python it can find first. That is that it will currently install for the first copies of Python versions 2.7, 3.4, 3.5, 3.6, and so on up until the current dev branch that it finds. Usually this will be in the same prefix as GPGME itself, but is dictated by the $PATH when the installation is performed. The above instructions can still be performed on other python installations which the installer does not find, including alternative prefixes.

There are semi-regular reports of Windows users having considerable difficulty in installing and using the Python bindings at all. Very often, possibly even always, these reports come from Cygwin users and/or MinGW users and/or Msys2 users. Though not all of them have been confirmed, it appears that these reports have also come from people who installed Python using the Windows installer files from the Python website (i.e. mostly MSI installers, sometimes self-extracting .exe files).

The Windows versions of Python are not built using Cygwin, MinGW or Msys2; they're built using Microsoft Visual Studio. Furthermore the version used is considerably more advanced than the version which MinGW obtained a small number of files from many years ago in order to be able to compile anything at all. Not only that, but there are changes to the version of Visual Studio between some micro releases, though that is is particularly the case with Python 2.7, since it has been kept around far longer than it should have been.

There are two theoretical solutions to this issue:

1. Compile and install the GnuPG stack, including GPGME and the Python bindings using the same version of Microsoft Visual Studio used by the Python Foundation to compile the version of Python installed.

   If there are multiple versions of Python then this will need to be done with each different version of Visual Studio used for those versions of Python.

2. Compile and install Python using the same tools used by choice, such as MinGW or Msys2.

Do NOT use the official Windows installer for Python unless following the first method.

In this type of situation it may even be for the best to accept that there are less limitations on permissive software than free software and simply opt to use a recent version of the Community Edition of Microsoft Visual Studio to compile and build all of it, no matter what.

Investigations into the extent or the limitations of this issue are ongoing.

The following table lists the version of Microsoft Visual Studio which needs to be used when compiling GPGME and the Python bindings with each version of the CPython binary released for Windows:

It is important to note that MingW and Msys2 ship with the Visual C runtime from Microsoft Visual Studio 2005 and are thus incompatible with all the versions of CPython which can be used with the GPGME Python bindings.

It is also important to note that from CPython 3.5 onwards, the Python Foundation has adopted the reworking of the Visual C runtime which was performed for Visual Studio 2015 and aimed at resolving many of these kinds of issues. Much greater detail on these issues and the correct file(s) to link to are available from Matthew Brett's invaluable page, Using Microsoft Visual C with Python. It is also worth reading the Microsoft Developer Network blog post on the universal CRT and Steve Dower's blog posts on Python extensions (part 1 and part 2).

The second of those two posts by Steve Dower contains the details of specific configuration options required for compiling anything to be used with official CPython releases. In addition to those configuration and compiler settings to use, the versions of Visual Studio prior to Visual Studio 2015 did not support 64-bit systems by default. So compiling a 64-bit version of these bindings for a 64-bit version of CPython 2.7 or 3.4 requires additional work.

In addition to the blog posts, the Windows compilers wiki page on the CPython wiki is another essential reference on the relevant versions of Visual Studio to use and the degree of compatibility with CPython releases.

Eventually someone will ask why there isn't an installable binary for Windows, which the GPGME of the licenses do not preclude as long as the source code is available in conjunction with such a release.

The sheer number of versions of Visual Studio in conjunction with differing configuration options depending on the target Windows version and whether the architecture is 64-bit or 32-bit makes it difficult to provide a correct binary installer for Windows users. At the bare minimum doing so would require the GnuPG project compile ten different versions of the bindings with each release; both 32-bit and 64-bit versions for CPython 2.7 and 3.4, with 64-bit versions for both x86-64 (i.e. Intel and AMD) and ARM architectures for CPython 3.5, 3.6, 3.7 and later releases. That's the bare minimum, it'd probably be higher.

Additionally, with only a binary installation used in conjunction with the CPython installer from python.org the advanced options available which utilise Cython will not be able to be used at all. Cython depends on being able to compile the C code it generates and that too would need to utilise a matching runtime to both the installed version of CPython and these bindings in order to work with the bindings.

Considering all of that, what do we recommend?

1. Use a recent version of CPython; at least 3.5, but ideally 3.6 or later.
2. Use Visual Studio 2015 or the standalone build tools for Visual Studio 2017 (or later).
3. Compile both CPython and GPGME with these bindings using the tools selected in step 2.
4. Ignore MingW, Msys2 and the official CPython binary installers.
5. Be thankful the answer to this question wasn't simply to say something like, “install Linux” or “install FreeBSD” (or even Apple's OS X).

There are many reasons for favouring CFFI and proponents of it are quite happy to repeat these things as if all it would take to switch from SWIG to CFFI is repeating that list as if it were a new concept.

The fact is that there are things which Python's CFFI implementation cannot handle in the GPGME C code. Beyond that there are features of SWIG which are simply not available with CFFI at all. SWIG generates the bindings to Python using the gpgme.h file, but that file is not a single version shipped with each release, it too is generated when GPGME is compiled.

CFFI is currently unable to adapt to such a potentially mutable codebase. If there were some means of applying SWIG's dynamic code generation to produce the Python/CFFI API modes of accessing the GPGME libraries (or the source source code directly), but such a thing does not exist yet either and it currently appears that work is needed in at least one of CFFI's dependencies before any of this can be addressed.

So if you're a massive fan of CFFI; that's great, but if you want this project to switch to CFFI then rather than just insisting that it should, I'd suggest you volunteer to bring CFFI up to the level this project needs.

If you're actually seriously considering doing so, then I'd suggest taking the gpgme-tool.c file in the GPGME src/ directory and getting that to work with any of the CFFI API methods (not the ABI methods, they'll work with pretty much anything). When you start running into trouble with "ifdefs" then you'll know what sort of things are lacking. That doesn't even take into account the amount of work saved via SWIG's code generation techniques either.

It is fairly common practice amongst Python developers to, as much as possible, use packages like virtualenv to keep various things that are to be installed from interfering with each other. Given how much of the GPGME bindings is often at odds with the usual pythonic way of doing things, it stands to reason that this would be called into question too.

As it happens the answer as to whether or not the bindings can be used with virtualenv, the answer is both yes and no.

In general we recommend installing to the relevant path and matching prefix of GPGME itself. Which means that when GPGME, and ideally the rest of the GnuPG stack, is installed to a prefix like /usr/local or /opt/local then the bindings would need to be installed to the main Python installation and not a virtualised abstraction. Attempts to separate the two in the past have been known to cause weird and intermittent errors ranging from minor annoyances to complete failures in the build process.

As a consequence we only recommend building with and installing to the main Python installations within the same prefix as GPGME is installed to or which are found by GPGME's configuration stage immediately prior to running the make commands. Which is exactly what the compiling and installing process of GPGME does by default.

Once that is done, however, it appears that a copy of the compiled module may be installed into a virtualenv of the same major and minor version matching the build. Alternatively it is possible to utilise a sites.pth file in the site-packages/ directory of a virtualenv installation, which links back to the system installations corresponding directory in order to import anything installed system wide. This may or may not be appropriate on a case by case basis.

Though extensive testing of either of these options is not yet complete, preliminary testing of them indicates that both are viable as long as the main installation is complete. Which means that certain other options normally restricted to virtual environments are also available, including integration with pythonic test suites (e.g. pytest) and other large projects.

That said, it is worth reiterating the warning regarding non-standard installations. If one were to attempt to install the bindings only to a virtual environment without somehow also including the full GnuPG stack (or enough of it as to include GPGME) then it is highly likely that errors would be encountered at some point and more than a little likely that the build process itself would break.

If a degree of separation from the main operating system is still required in spite of these warnings, then consider other forms of virtualisation. Either a virtual machine (e.g. VirtualBox), a hardware emulation layer (e.g. QEMU) or an application container (e.g. Docker).

Finally it should be noted that the limited tests conducted thus far have been using the virtualenv command in a new directory to create the virtual python environment. As opposed to the standard python3 -m venv and it is possible that this will make a difference depending on the system and version of Python in use. Another option is to run the command python3 -m virtualenv /path/to/install/virtual/thingy instead.

Following installation it is recommended to move the post_installer.py script from the lang/python/examples/howto/ directory to the lang/python/ directory and run it. This will fix or restore files needed by Sphinx which may be removed during a distribution build for release. It will also generate reST files from Org mode files with Pandoc and generate Texinfo files from Org mode files with GNU Emacs and Org mode (in batch mode). Additionally it will fix the UTF-8 declaration line in the Texinfo files (Emacs expects "UTF-8" to be "utf-8").

Counting the number of keys in your public keybox (pubring.kbx), the format which has superseded the old keyring format (pubring.gpg and secring.gpg), or the number of secret keys is a very simple task.

import gpg

c = gpg.Context()
seckeys = c.keylist(pattern=None, secret=True)
pubkeys = c.keylist(pattern=None, secret=False)

seclist = list(seckeys)
secnum = len(seclist)

publist = list(pubkeys)
pubnum = len(publist)

print("""
  Number of secret keys:  {0}
  Number of public keys:  {1}
""".format(secnum, pubnum))

NOTE: The Cython introduction in the Advanced and Experimental section uses this same key counting code with Cython to demonstrate some areas where Cython can improve performance even with the bindings. Users with large public keyrings or keyboxes, for instance, should consider these options if they are comfortable with using Cython.

Here is a variation on the example above which checks the constrained ProtonMail keyserver for ProtonMail public keys.

import gpg
import requests
import sys

print("""
This script searches the ProtonMail key server for the specified key and
imports it.
""")

c = gpg.Context(armor=True)
url = "https://api.protonmail.ch/pks/lookup"
ksearch = []

if len(sys.argv) >= 2:
    keyterm = sys.argv[1]
else:
    keyterm = input("Enter the key ID, UID or search string: ")

if keyterm.count("@") == 2 and keyterm.startswith("@") is True:
    ksearch.append(keyterm[1:])
    ksearch.append(keyterm[1:])
    ksearch.append(keyterm[1:])
elif keyterm.count("@") == 1 and keyterm.startswith("@") is True:
    ksearch.append("{0}@protonmail.com".format(keyterm[1:]))
    ksearch.append("{0}@protonmail.ch".format(keyterm[1:]))
    ksearch.append("{0}@pm.me".format(keyterm[1:]))
elif keyterm.count("@") == 0:
    ksearch.append("{0}@protonmail.com".format(keyterm))
    ksearch.append("{0}@protonmail.ch".format(keyterm))
    ksearch.append("{0}@pm.me".format(keyterm))
elif keyterm.count("@") == 2 and keyterm.startswith("@") is False:
    uidlist = keyterm.split("@")
    for uid in uidlist:
        ksearch.append("{0}@protonmail.com".format(uid))
        ksearch.append("{0}@protonmail.ch".format(uid))
        ksearch.append("{0}@pm.me".format(uid))
elif keyterm.count("@") > 2:
    uidlist = keyterm.split("@")
    for uid in uidlist:
        ksearch.append("{0}@protonmail.com".format(uid))
        ksearch.append("{0}@protonmail.ch".format(uid))
        ksearch.append("{0}@pm.me".format(uid))
else:
    ksearch.append(keyterm)

for k in ksearch:
    payload = {"op": "get", "search": k}
    try:
        r = requests.get(url, verify=True, params=payload)
        if r.ok is True:
            result = c.key_import(r.content)
        elif r.ok is False:
            result = r.content
    except Exception as e:
        result = None

    if result is not None and hasattr(result, "considered") is False:
        print("{0} for {1}".format(result.decode(), k))
    elif result is not None and hasattr(result, "considered") is True:
        num_keys = len(result.imports)
        new_revs = result.new_revocations
        new_sigs = result.new_signatures
        new_subs = result.new_sub_keys
        new_uids = result.new_user_ids
        new_scrt = result.secret_imported
        nochange = result.unchanged
        print("""
The total number of keys considered for import was:  {0}

With UIDs wholely or partially matching the following string:

        {1}

   Number of keys revoked:  {2}
 Number of new signatures:  {3}
    Number of new subkeys:  {4}
   Number of new user IDs:  {5}
Number of new secret keys:  {6}
 Number of unchanged keys:  {7}

The key IDs for all considered keys were:
""".format(num_keys, k, new_revs, new_sigs, new_subs, new_uids, new_scrt,
           nochange))
        for i in range(num_keys):
            print(result.imports[i].fpr)
        print("")
    elif result is None:
        print(e)

Both the above example, pmkey-import.py, and a version which prompts for an alternative GnuPG home directory, pmkey-import-alt.py, are available with the other examples and are executable scripts.

Note that while the ProtonMail servers are based on the SKS servers, their server is related more to their API and is not feature complete by comparison to the servers in the SKS pool. One notable difference being that the ProtonMail server does not permit non ProtonMail users to update their own keys, which could be a vector for attacking ProtonMail users who may not receive a key's revocation if it had been compromised.

Performing the same tasks with the hkp4py module (available via PyPI) is not too much different, but does provide a number of options of benefit to end users. Not least of which being the ability to perform some checks on a key before importing it or not. For instance it may be the policy of a site or project to only import keys which have not been revoked. The hkp4py module permits such checks prior to the importing of the keys found.

import gpg
import hkp4py
import sys

c = gpg.Context()
server = hkp4py.KeyServer("hkps://hkps.pool.sks-keyservers.net")
results = []
keys = []

if len(sys.argv) > 2:
    pattern = " ".join(sys.argv[1:])
elif len(sys.argv) == 2:
    pattern = sys.argv[1]
else:
    pattern = input("Enter the pattern to search for keys or user IDs: ")


if pattern is not None:
    try:
        key = server.search(hex(int(pattern, 16)))
        keyed = True
    except ValueError as ve:
        key = server.search(pattern)
        keyed = False

    if key is not None:
        keys.append(key[0])
        if keyed is True:
            try:
                fob = server.search(pattern)
            except:
                fob = None
            if fob is not None:
                keys.append(fob[0])
        else:
            pass
    else:
        pass

    for logrus in pattern.split():
        try:
            key = server.search(hex(int(logrus, 16)))
            hexed = True
        except ValueError as ve:
            key = server.search(logrus)
            hexed = False

        if key is not None:
            keys.append(key[0])
            if hexed is True:
                try:
                    fob = server.search(logrus)
                except:
                    fob = None
                if fob is not None:
                    keys.append(fob[0])
            else:
                pass
        else:
            pass


if len(keys) > 0:
    for key in keys:
        import_result = c.key_import(key.key_blob)
        results.append(import_result)

for result in results:
    if result is not None and hasattr(result, "considered") is False:
        print(result)
    elif result is not None and hasattr(result, "considered") is True:
        num_keys = len(result.imports)
        new_revs = result.new_revocations
        new_sigs = result.new_signatures
        new_subs = result.new_sub_keys
        new_uids = result.new_user_ids
        new_scrt = result.secret_imported
        nochange = result.unchanged
        print("""
The total number of keys considered for import was:  {0}

   Number of keys revoked:  {1}
 Number of new signatures:  {2}
    Number of new subkeys:  {3}
   Number of new user IDs:  {4}
Number of new secret keys:  {5}
 Number of unchanged keys:  {6}

The key IDs for all considered keys were:
""".format(num_keys, new_revs, new_sigs, new_subs, new_uids, new_scrt,
           nochange))
        for i in range(num_keys):
            print(result.imports[i].fpr)
        print("")
    else:
        pass

Since the hkp4py module handles multiple keys just as effectively as one (keys is a list of responses per matching key), the example above is able to do a little bit more with the returned data before anything is actually imported.

Though this can provide certain benefits even when working with ProtonMail, the scope is somewhat constrained there due to the limitations of the ProtonMail keyserver.

For instance, searching the SKS keyserver pool for the term "gnupg" produces hundreds of results from any time the word appears in any part of a user ID. Performing the same search on the ProtonMail keyserver returns zero results, even though there are at least two test accounts which include it as part of the username.

The cause of this discrepancy is the deliberate configuration of that server by ProtonMail to require an exact match of the full email address of the ProtonMail user whose key is being requested. Presumably this is intended to reduce breaches of privacy of their users as an email address must already be known before a key for that address can be obtained.

There are two methods of exporting public keys, both of which are very similar to the other. The default method, key_export(), will export a public key or keys matching a specified pattern as normal. The alternative, the key_export_minimal() method, will do the same thing except producing a minimised output with extra signatures and third party signatures or certifications removed.

import gpg
import os.path
import sys

print("""
This script exports one or more public keys.
""")

c = gpg.Context(armor=True)

if len(sys.argv) >= 4:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = sys.argv[3]
elif len(sys.argv) == 3:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = input("Enter the GPG configuration directory path (optional): ")
elif len(sys.argv) == 2:
    keyfile = sys.argv[1]
    logrus = input("Enter the UID matching the key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")
else:
    keyfile = input("Enter the path and filename to save the secret key to: ")
    logrus = input("Enter the UID matching the key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")

if homedir.startswith("~"):
    if os.path.exists(os.path.expanduser(homedir)) is True:
        c.home_dir = os.path.expanduser(homedir)
    else:
        pass
elif os.path.exists(homedir) is True:
    c.home_dir = homedir
else:
    pass

try:
    result = c.key_export(pattern=logrus)
except:
    result = c.key_export(pattern=None)

if result is not None:
    with open(keyfile, "wb") as f:
        f.write(result)
else:
    pass

It should be noted that the result will only return None when a search pattern has been entered, but has not matched any keys. When the search pattern itself is set to None this triggers the exporting of the entire public keybox.

import gpg
import os.path
import sys

print("""
This script exports one or more public keys in minimised form.
""")

c = gpg.Context(armor=True)

if len(sys.argv) >= 4:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = sys.argv[3]
elif len(sys.argv) == 3:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = input("Enter the GPG configuration directory path (optional): ")
elif len(sys.argv) == 2:
    keyfile = sys.argv[1]
    logrus = input("Enter the UID matching the key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")
else:
    keyfile = input("Enter the path and filename to save the secret key to: ")
    logrus = input("Enter the UID matching the key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")

if homedir.startswith("~"):
    if os.path.exists(os.path.expanduser(homedir)) is True:
        c.home_dir = os.path.expanduser(homedir)
    else:
        pass
elif os.path.exists(homedir) is True:
    c.home_dir = homedir
else:
    pass

try:
    result = c.key_export_minimal(pattern=logrus)
except:
    result = c.key_export_minimal(pattern=None)

if result is not None:
    with open(keyfile, "wb") as f:
        f.write(result)
else:
    pass

Exporting secret keys is, functionally, very similar to exporting public keys; save for the invocation of pinentry via gpg-agent in order to securely enter the key's passphrase and authorise the export.

The following example exports the secret key to a file which is then set with the same permissions as the output files created by the command line secret key export options.

import gpg
import os
import os.path
import sys

print("""
This script exports one or more secret keys.

The gpg-agent and pinentry are invoked to authorise the export.
""")

c = gpg.Context(armor=True)

if len(sys.argv) >= 4:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = sys.argv[3]
elif len(sys.argv) == 3:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = input("Enter the GPG configuration directory path (optional): ")
elif len(sys.argv) == 2:
    keyfile = sys.argv[1]
    logrus = input("Enter the UID matching the secret key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")
else:
    keyfile = input("Enter the path and filename to save the secret key to: ")
    logrus = input("Enter the UID matching the secret key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")

if len(homedir) == 0:
    homedir = None
elif homedir.startswith("~"):
    userdir = os.path.expanduser(homedir)
    if os.path.exists(userdir) is True:
        homedir = os.path.realpath(userdir)
    else:
        homedir = None
else:
    homedir = os.path.realpath(homedir)

if os.path.exists(homedir) is False:
    homedir = None
else:
    if os.path.isdir(homedir) is False:
        homedir = None
    else:
        pass

if homedir is not None:
    c.home_dir = homedir
else:
    pass

try:
    result = c.key_export_secret(pattern=logrus)
except:
    result = c.key_export_secret(pattern=None)

if result is not None:
    with open(keyfile, "wb") as f:
        f.write(result)
    os.chmod(keyfile, 0o600)
else:
    pass

Alternatively the approach of the following script can be used. This longer example saves the exported secret key(s) in files in the GnuPG home directory, in addition to setting the file permissions as only readable and writable by the user. It also exports the secret key(s) twice in order to output both GPG binary (.gpg) and ASCII armoured (.asc) files.

import gpg
import os
import os.path
import subprocess
import sys

print("""
This script exports one or more secret keys as both ASCII armored and binary
file formats, saved in files within the user's GPG home directory.

The gpg-agent and pinentry are invoked to authorise the export.
""")

if sys.platform == "win32":
    gpgconfcmd = "gpgconf.exe --list-dirs homedir"
else:
    gpgconfcmd = "gpgconf --list-dirs homedir"

a = gpg.Context(armor=True)
b = gpg.Context()
c = gpg.Context()

if len(sys.argv) >= 4:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = sys.argv[3]
elif len(sys.argv) == 3:
    keyfile = sys.argv[1]
    logrus = sys.argv[2]
    homedir = input("Enter the GPG configuration directory path (optional): ")
elif len(sys.argv) == 2:
    keyfile = sys.argv[1]
    logrus = input("Enter the UID matching the secret key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")
else:
    keyfile = input("Enter the filename to save the secret key to: ")
    logrus = input("Enter the UID matching the secret key(s) to export: ")
    homedir = input("Enter the GPG configuration directory path (optional): ")

if len(homedir) == 0:
    homedir = None
elif homedir.startswith("~"):
    userdir = os.path.expanduser(homedir)
    if os.path.exists(userdir) is True:
        homedir = os.path.realpath(userdir)
    else:
        homedir = None
else:
    homedir = os.path.realpath(homedir)

if os.path.exists(homedir) is False:
    homedir = None
else:
    if os.path.isdir(homedir) is False:
        homedir = None
    else:
        pass

if homedir is not None:
    c.home_dir = homedir
else:
    pass

if c.home_dir is not None:
    if c.home_dir.endswith("/"):
        gpgfile = "{0}{1}.gpg".format(c.home_dir, keyfile)
        ascfile = "{0}{1}.asc".format(c.home_dir, keyfile)
    else:
        gpgfile = "{0}/{1}.gpg".format(c.home_dir, keyfile)
        ascfile = "{0}/{1}.asc".format(c.home_dir, keyfile)
else:
    if os.path.exists(os.environ["GNUPGHOME"]) is True:
        hd = os.environ["GNUPGHOME"]
    else:
        try:
            hd = subprocess.getoutput(gpgconfcmd)
        except:
            process = subprocess.Popen(gpgconfcmd.split(),
                                       stdout=subprocess.PIPE)
            procom = process.communicate()
            if sys.version_info[0] == 2:
                hd = procom[0].strip()
            else:
                hd = procom[0].decode().strip()
    gpgfile = "{0}/{1}.gpg".format(hd, keyfile)
    ascfile = "{0}/{1}.asc".format(hd, keyfile)

try:
    a_result = a.key_export_secret(pattern=logrus)
    b_result = b.key_export_secret(pattern=logrus)
except:
    a_result = a.key_export_secret(pattern=None)
    b_result = b.key_export_secret(pattern=None)

if a_result is not None:
    with open(ascfile, "wb") as f:
        f.write(a_result)
    os.chmod(ascfile, 0o600)
else:
    pass

if b_result is not None:
    with open(gpgfile, "wb") as f:
        f.write(b_result)
    os.chmod(gpgfile, 0o600)
else:
    pass

As with the previous section on importing keys, the hkp4py module adds another option with exporting keys in order to send them to the public keyservers.

The following example demonstrates how this may be done.

import gpg
import hkp4py
import os.path
import sys

print("""
This script sends one or more public keys to the SKS keyservers and is
essentially a slight variation on the export-key.py script.
""")

c = gpg.Context(armor=True)
server = hkp4py.KeyServer("hkps://hkps.pool.sks-keyservers.net")

if len(sys.argv) > 2:
    logrus = " ".join(sys.argv[1:])
elif len(sys.argv) == 2:
    logrus = sys.argv[1]
else:
    logrus = input("Enter the UID matching the key(s) to send: ")

if len(logrus) > 0:
    try:
        export_result = c.key_export(pattern=logrus)
    except Exception as e:
        print(e)
        export_result = None
else:
    export_result = c.key_export(pattern=None)

if export_result is not None:
    try:
        try:
            send_result = server.add(export_result)
        except:
            send_result = server.add(export_result.decode())
        if send_result is not None:
            print(send_result)
        else:
            pass
    except Exception as e:
        print(e)
else:
    pass

An expanded version of this script with additional functions for specifying an alternative homedir location is in the examples directory as send-key-to-keyserver.py.

The hkp4py module appears to handle both string and byte literal text data equally well, but the GPGME bindings deal primarily with byte literal data only and so this script sends in that format first, then tries the string literal form.

Once the the Context is set the main issues with encrypting data is essentially reduced to key selection and the keyword arguments specified in the gpg.Context().encrypt() method.

Those keyword arguments are: recipients, a list of keys encrypted to (covered in greater detail in the following section); sign, whether or not to sign the plaintext data, see subsequent sections on signing and verifying signatures below (defaults to True); sink, to write results or partial results to a secure sink instead of returning it (defaults to None); passphrase, only used when utilising symmetric encryption (defaults to None); always_trust, used to override the trust model settings for recipient keys (defaults to False); add_encrypt_to, utilises any preconfigured encrypt-to or default-key settings in the user's gpg.conf file (defaults to False); prepare, prepare for encryption (defaults to False); expect_sign, prepare for signing (defaults to False); compress, compresses the plaintext prior to encryption (defaults to True).

import gpg

a_key = "0x12345678DEADBEEF"
text = b"""Some text to test with.

Since the text in this case must be bytes, it is most likely that
the input form will be a separate file which is opened with "rb"
as this is the simplest method of obtaining the correct data format.
"""

c = gpg.Context(armor=True)
rkey = list(c.keylist(pattern=a_key, secret=False))
ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, sign=False)

with open("secret_plans.txt.asc", "wb") as afile:
    afile.write(ciphertext)

Though this is even more likely to be used like this; with the plaintext input read from a file, the recipient keys used for encryption regardless of key trust status and the encrypted output also encrypted to any preconfigured keys set in the gpg.conf file:

import gpg

a_key = "0x12345678DEADBEEF"

with open("secret_plans.txt", "rb") as afile:
    text = afile.read()

c = gpg.Context(armor=True)
rkey = list(c.keylist(pattern=a_key, secret=False))
ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, sign=True,
                                            always_trust=True,
                                            add_encrypt_to=True)

with open("secret_plans.txt.asc", "wb") as afile:
    afile.write(ciphertext)

If the recipients parameter is empty then the plaintext is encrypted symmetrically. If no passphrase is supplied as a parameter or via a callback registered with the Context() then an out-of-band prompt for the passphrase via pinentry will be invoked.

Encrypting to multiple keys essentially just expands upon the key selection process and the recipients from the previous examples.

The following example encrypts a message (text) to everyone with an email address on the gnupg.org domain,⁴ but does not encrypt to a default key or other key which is configured to normally encrypt to.

import gpg

text = b"""Oh look, another test message.

The same rules apply as with the previous example and more likely
than not, the message will actually be drawn from reading the
contents of a file or, maybe, from entering data at an input()
prompt.

Since the text in this case must be bytes, it is most likely that
the input form will be a separate file which is opened with "rb"
as this is the simplest method of obtaining the correct data
format.
"""

c = gpg.Context(armor=True)
rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
logrus = []

for i in range(len(rpattern)):
    if rpattern[i].can_encrypt == 1:
        logrus.append(rpattern[i])

ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
                                            sign=False, always_trust=True)

with open("secret_plans.txt.asc", "wb") as afile:
    afile.write(ciphertext)

All it would take to change the above example to sign the message and also encrypt the message to any configured default keys would be to change the c.encrypt line to this:

ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
                                            always_trust=True,
                                            add_encrypt_to=True)

The only keyword arguments requiring modification are those for which the default values are changing. The default value of sign is True, the default of always_trust is False, the default of add_encrypt_to is False.

If always_trust is not set to True and any of the recipient keys are not trusted (e.g. not signed or locally signed) then the encryption will raise an error. It is possible to mitigate this somewhat with something more like this:

import gpg

with open("secret_plans.txt.asc", "rb") as afile:
    text = afile.read()

c = gpg.Context(armor=True)
rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
logrus = []

for i in range(len(rpattern)):
    if rpattern[i].can_encrypt == 1:
        logrus.append(rpattern[i])

    try:
        ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
                                                    add_encrypt_to=True)
    except gpg.errors.InvalidRecipients as e:
        for i in range(len(e.recipients)):
            for n in range(len(logrus)):
                if logrus[n].fpr == e.recipients[i].fpr:
                    logrus.remove(logrus[n])
                else:
                    pass
        try:
            ciphertext, result, sign_result = c.encrypt(text,
                                                        recipients=logrus,
                                                        add_encrypt_to=True)
            with open("secret_plans.txt.asc", "wb") as afile:
                afile.write(ciphertext)
        except:
            pass

This will attempt to encrypt to all the keys searched for, then remove invalid recipients if it fails and try again.

By default GPGME and the Python bindings will use the default key configured for the user invoking the GPGME API. If there is no default key specified and there is more than one secret key available it may be necessary to specify the key or keys with which to sign messages and files.

import gpg

logrus = input("Enter the email address or string to match signing keys to: ")
hancock = gpg.Context().keylist(pattern=logrus, secret=True)
sig_src = list(hancock)

The signing examples in the following sections include the explicitly designated signers parameter in two of the five examples; once where the resulting signature would be ASCII armoured and once where it would not be armoured.

While it would be possible to enter a key ID or fingerprint here to match a specific key, it is not possible to enter two fingerprints and match two keys since the patten expects a string, bytes or None and not a list. A string with two fingerprints won't match any single key.

The normal or default signing process is essentially the same as is most often invoked when also encrypting a message or file. So when the encryption component is not utilised, the result is to produce an encoded and signed output which may or may not be ASCII armoured and which may or may not also be compressed.

By default compression will be used unless GnuPG detects that the plaintext is already compressed. ASCII armouring will be determined according to the value of gpg.Context().armor.

The compression algorithm is selected in much the same way as the symmetric encryption algorithm or the hash digest algorithm is when multiple keys are involved; from the preferences saved into the key itself or by comparison with the preferences with all other keys involved.

import gpg

text0 = """Declaration of ... something.

"""
text = text0.encode()

c = gpg.Context(armor=True, signers=sig_src)
signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.NORMAL)

with open("/path/to/statement.txt.asc", "w") as afile:
    afile.write(signed_data.decode())

Though everything in this example is accurate, it is more likely that reading the input data from another file and writing the result to a new file will be performed more like the way it is done in the next example. Even if the output format is ASCII armoured.

import gpg

with open("/path/to/statement.txt", "rb") as tfile:
    text = tfile.read()

c = gpg.Context()
signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.NORMAL)

with open("/path/to/statement.txt.sig", "wb") as afile:
    afile.write(signed_data)

Detached signatures will often be needed in programmatic uses of GPGME, either for signing files (e.g. tarballs of code releases) or as a component of message signing (e.g. PGP/MIME encoded email).

import gpg

text0 = """Declaration of ... something.

"""
text = text0.encode()

c = gpg.Context(armor=True)
signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.DETACH)

with open("/path/to/statement.txt.asc", "w") as afile:
    afile.write(signed_data.decode())

As with normal signatures, detached signatures are best handled as byte literals, even when the output is ASCII armoured.

import gpg

with open("/path/to/statement.txt", "rb") as tfile:
    text = tfile.read()

c = gpg.Context(signers=sig_src)
signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.DETACH)

with open("/path/to/statement.txt.sig", "wb") as afile:
    afile.write(signed_data)

Though PGP/in-line messages are no longer encouraged in favour of PGP/MIME, there is still sometimes value in utilising in-line signatures. This is where clear-signed messages or text is of value.

import gpg

text0 = """Declaration of ... something.

"""
text = text0.encode()

c = gpg.Context()
signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.CLEAR)

with open("/path/to/statement.txt.asc", "w") as afile:
    afile.write(signed_data.decode())

In spite of the appearance of a clear-signed message, the data handled by GPGME in signing it must still be byte literals.

import gpg

with open("/path/to/statement.txt", "rb") as tfile:
    text = tfile.read()

c = gpg.Context()
signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.CLEAR)

with open("/path/to/statement.txt.asc", "wb") as afile:
    afile.write(signed_data)

By comparison to creating primary keys and subkeys, adding a new user ID to an existing key is much simpler. The method used to do this is key_add_uid and the only arguments it takes are for the key and the new uid.

import gpg

c = gpg.Context()
c.home_dir = "~/.gnupg-dm"

dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
key = c.get_key(dmfpr, secret=True)
uid = "Danger Mouse <danger.mouse@secret.example.net>"

c.key_add_uid(key, uid)

Unsurprisingly the result of this is:

bash-4.4$ gpg --homedir ~/.gnupg-dm -K
~/.gnupg-dm/pubring.kbx
----------------------
sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
      177B7C25DB99745EE2EE13ED026D2F19E99E63AA
uid           [ultimate] Danger Mouse <danger.mouse@secret.example.net>
uid           [ultimate] Danger Mouse <dm@secret.example.net>
ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]

bash-4.4$

Revoking a user ID is a fairly similar process, except that it uses the key_revoke_uid method.

import gpg

c = gpg.Context()
c.home_dir = "~/.gnupg-dm"

dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
key = c.get_key(dmfpr, secret=True)
uid = "Danger Mouse <danger.mouse@secret.example.net>"

c.key_revoke_uid(key, uid)

import gpg
import time

c = gpg.Context()
dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
keys = list(c.keylist(pattern=dmuid, mode=gpg.constants.keylist.mode.SIGS))
key = keys[0]

for user in key.uids:
    for sig in user.signatures:
        print("0x{0}".format(sig.keyid), "", time.ctime(sig.timestamp), "",
              sig.uid)

Which for Danger Mouse displays the following:

0x92E3F6115435C65A  Thu Mar 15 13:17:44 2018  Danger Mouse <dm@secret.example.net>
0x321E4E2373590E5D  Mon Nov 26 12:46:05 2018  Ben McGinnes <ben@adversary.org>

The two key signatures listed are for the self-certification of Danger Mouse's key made when the key was created in March, 2018; and the second is a signature made by the author and set to expire at the end of the year. Note that the second signature was made with the following code (including the preceding code to display the output of the certifications or key signatures):

import gpg
import math
import pendulum
import time

hd = "/home/dm/.gnupg"
c = gpg.Context()
d = gpg.Context(home_dir=hd)
dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
dmuid = "Danger Mouse <dm@secret.example.net>"
dkeys = list(c.keylist(pattern=dmuid))
dmkey = dkeys[0]

c.key_import(d.key_export(pattern=None))

tp = pendulum.period(pendulum.now(tz="local"), pendulum.datetime(2019, 1, 1))
ts = tp.total_seconds()
total_secs = math.ceil(ts)
c.key_sign(dmkey, uids=dmuid, expires_in=total_secs)

d.key_import(c.key_export(pattern=dmuid))
keys = list(c.keylist(pattern=dmuid, mode=gpg.constants.keylist.mode.SIGS))
key = keys[0]

for user in key.uids:
    for sig in user.signatures:
        print("0x{0}".format(sig.keyid), "", time.ctime(sig.timestamp), "",
              sig.uid)

Note that this final code block includes the use of a module which is not part of Python's standard library, the pendulum module. Unlike the standard datetime module, pendulum makes working with dates and times significantly easier in Python; just as the requests module makes working with HTTP and HTTPS easier than the builtin modules do.

Though neither requests nor pendulum are required modules for using the GPGME Python bindings, they are both highly recommended more generally.

The hkp4py module returns key data via requests as string literals (r.text) instead of byte literals (r.content). This means that the returned key data must be encoded to UTF-8 when importing that key material using the gpg.Context().key_import() method.

For this reason an alternative method has been added to the search function of hkp4py.KeyServer() which returns the key in the correct format as expected by key_import. When importing using this module, it is now possible to import with this:

for key in keys:
    if key.revoked is False:
        gpg.Context().key_import(key.key_blob)
    else:
        pass

Without that recent addition it would have been necessary to encode the contents of each hkp4py.KeyServer().search()[i].key in hkp4py.KeyServer().search() before trying to import it.

An example of this is included in the Importing Keys section of this HOWTO and the corresponding executable version of that example is available in the lang/python/examples/howto directory as normal; the executable version is the import-keys-hkp.py file.