API documentation

GnuPG API

Native Python / GPG API

This API was written to replace the GPGME bindings because the GPGME API has a few problems:

1. it is arcane and difficult to grasp
2. it is very closely bound to the internal GPG data and commandline structures, which are quite confusing
3. GPGME doesn’t actually talk to a GPG library, but interacts with GPG through the commandline
4. GPGME developers are not willing to extend GPGME to cover private key material management and consider this is outside the scope of the project.

The latter two points are especially problematic for this project, and I have therefore started working on a replacement.

Operations are performed mostly through the Keyring or KeyringTmp class (if you do not want to access your regular keyring but an empty temporary one).

This is how you can access keys, which are represented by the OpenPGPkey datastructure, but which will not look in your keyring or on the keyservers itself without the Keyring class.

It seems that I have missed a similar project that’s been around for quite a while (2008-2012):

https://code.google.com/p/python-gnupg/

The above project has a lot of similarities with this implementation, but is better because:

1. it actually parses most status outputs from GPG, in a clean way
2. uses threads so it doesn’t block
3. supports streams
4. supports verification, key generation and deletion
5. has a cleaner and more complete test suite

However, the implementation here has:

1. key signing support
2. a cleaner API

Error handling is somewhat inconsistent here. Some functions rely on exceptions, other on boolean return values. We prefer exceptions as it allows us to propagate error messages to the UI, but make sure to generate a RuntimeError, and not a ProtocolError, which are unreadable to the user.

class monkeysign.gpg.Context

Python wrapper for GnuPG

This wrapper allows for a simpler interface than GPGME or PyME to GPG, and bypasses completely GPGME to interoperate directly with GPG as a process.

It uses the gpg-agent to prompt for passphrases and communicates with GPG over the stdin for commnads (–command-fd) and stdout for status (–status-fd).

build_command(command)

internal helper to build a proper gpg commandline

this will add relevant arguments around the gpg binary.

like the options arguments, the command is expected to be a regular gpg command with the – stripped. the – are added before being called. this is to make the code more readable, and eventually support other backends that actually make more sense.

this uses build_command to create a commandline out of the ‘options’ dictionary, and appends the provided command at the end. this is because order of certain options matter in gpg, where some options (like –recv-keys) are expected to be at the end.

it is here that the options dictionary is converted into a list. the command argument is expected to be a list of arguments that can be converted to strings. if it is not a list, it is cast into a list.

call_command(command, stdin=None)

internal wrapper to call a GPG commandline

this will call the command generated by build_command() and setup a regular pipe to the subcommand.

this assumes that we have the status-fd on stdout and command-fd on stdin, but could really be used in any other way.

we pass the stdin argument in the standard input of gpg and we keep the output in the stdout and stderr array. the exit code is in the returncode variable.

we can optionnally watch for a confirmation pattern on the statusfd.

debug = False

expect(fd, pattern)

look for a specific GNUPG status on the next line of output

this is a stub for expect()

expect_pattern(fd, pattern)

make sure the next line matches the provided pattern

in contrast with seek_pattern(), this will not skip non-matching lines and instead raise an exception if such a line is found.

this therefore looks only at the next line, but may also hang like seek_pattern()

if the beginning of the line matches a pattern which is being ignored, it will skip it and look at the next line

gpg_binary = 'gpg'

options = {'batch': None, 'command-fd': 0, 'fixed-list-mode': None, 'list-options': 'show-sig-subpackets,show-uid-validity,show-unusable-uids,show-unusable-subkeys,show-keyring,show-sig-expire', 'no-tty': None, 'no-verbose': None, 'quiet': None, 'status-fd': 2, 'use-agent': None, 'with-colons': None, 'with-fingerprint': None}

seek(fd, pattern)

look for a specific GNUPG status line in the output

this is a stub for seek_pattern()

seek_pattern(fd, pattern)

iterate over file descriptor until certain pattern is found

fd is a file descriptor pattern a string describing a regular expression to match

this will skip lines not matching pattern until the pattern is found. it will raise an IOError if the pattern is not found and EOF is reached.

this may hang for streams that do not send EOF or are waiting for input.

set_option(option, value=None)

set an option to pass to gpg

this adds the given ‘option’ commandline argument with the value ‘value’. to pass a flag without an argument, use ‘None’ for value

unset_option(option)

remove an option from the gpg commandline

version()

return the version of the GPG binary

write(fd, message)

write the specified message to gnupg, usually on stdout

but really, the pipes are often setup outside of here so the fd is hardcoded here

exception monkeysign.gpg.GpgProtocolError

simple exception raised when we have trouble talking with GPG

we try to pass the subprocess.popen.returncode as an errorno and a significant description string

this error shouldn’t be propagated to the user, because it will contain mostly “expect” jargon from the DETAILS.txt file. the gpg module should instead raise a GpgRutimeError with a user-readable error message (e.g. “key not found”).

expected()

found()

match()

exception monkeysign.gpg.GpgRuntimeError

class monkeysign.gpg.Keyring(homedir=None)

Keyring functionalities.

This allows various operations (e.g. listing, signing, exporting data) on a keyring.

Concretely, we talk about a “keyring”, but we really mean a set of public and private keyrings and their trust databases. In practice, this is the equivalent of the GNUPGHOME or –homedir in GPG, and in fact this is implemented by setting a specific homedir to tell GPG to operate on a specific keyring.

We actually use the –homedir parameter to gpg to set the keyring we operate upon.

context = None

decrypt_data(data)

decrypt data using asymetric encryption

returns the plaintext data or raise a GpgRuntimeError if it failed.

del_uid(fingerprint, pattern)

encrypt_data(data, recipient)

encrypt data using asymetric encryption

returns the encrypted data or raise a GpgRuntimeError if it fails

export_data(fpr=None, secret=False)

Export OpenPGP data blocks from the keyring.

This exports actual OpenPGP data, by default in binary format, but can also be exported asci-armored by setting the ‘armor’ option.

fetch_keys(fpr, keyserver=None)

Download keys from a keyserver into the local keyring

This expects a fingerprint (or a at least a key id).

Returns true if the command succeeded.

get_agent_socket()

get the location of the gpg-agent socket for this keyring

get_keys(pattern=None, secret=False, public=True, keys=None)

load keys matching a specific patterns

this uses the (rather poor) list-keys API to load keys information

import_data(data)

Import OpenPGP data blocks into the keyring.

This takes actual OpenPGP data, ascii-armored or not, gpg will gladly take it. This can be signatures, public, private keys, etc.

You may need to set import-flags to import non-exportable signatures, however.

sign_key(pattern, signall=False, local=False)

sign a OpenPGP public key

By default it looks up and signs a specific uid, but it can also sign all uids in one shot thanks to GPG’s optimization on that.

The pattern here should be a full user id if we sign a specific key (default) or any pattern (fingerprint, keyid, partial user id) that GPG will accept if we sign all uids.

@todo that this currently block if the pattern specifies an incomplete UID and we do not sign all keys.

verify_file(sigfile, filename)

class monkeysign.gpg.OpenPGPkey(data=None)

An OpenPGP key.

Some of this datastructure is taken verbatim from GPGME.

algo = -1

creation = 0

disabled = False

expired

expiry

Returns a datetime from the _expiry field or None if the key does not expire

format_fpr()

display a clean version of the fingerprint

this is the display we usually see

fpr = None

get_trust()

invalid = False

keyid(l=8)

length = None

parse_gpg_list(text)

purpose = {}

qualified = False

revoked

Returns whether GnuPG thinks the key has been revoked

This is the second field of the result of the –list-key –with-colons call. Note that this information is only present on public keys, i.e. not on secret keys.

Returns None if it cannot be determined whether this key has been revoked.

secret = False

subkeys = {}

trust = None

trust_map = {'': 'empty', '-': 'unknown', 'd': 'disabled', 'e': 'expired', 'f': 'full', 'i': 'invalid', 'm': 'marginal', 'n': 'none', 'o': 'new', 'q': 'undefined', 'r': 'revoked', 'u': 'ultimate'}

uids = {}

class monkeysign.gpg.OpenPGPuid(uid, trust, creation=0, expire=None, uidhash='')

get_trust()

revoked

Whether this UID has been revoked

Note that, due to GnuPG not exporting that information for secret keys, UIDs of secret keys do not carry that information.

Return None if it cannot be determined whether this UID has been revoked. Try again with the public key.

class monkeysign.gpg.TempKeyring

CLI Interface

class monkeysign.cli.MonkeysignCli(args=None)

sign a key in a safe fashion.

This command signs a key based on the fingerprint or user id specified on the commandline, encrypt the result and mail it to the user. This leave the choice of publishing the certification to that person and makes sure that person owns the identity signed.

This program assumes you have gpg-agent configured to prompt for passwords.

acknowledge(prompt)

choose_uid(prompt, key)

present the user with a list of UIDs and let him choose one

main()

main code execution loop

we expect to have the commandline parsed for us

prompt_line(prompt)

prompt_pass(prompt)

yes_no(prompt, default=None)

default UI is not interactive, so we assume yes all the time

GTK Interface

class monkeysign.gtkui.MonkeysignScan

about_dialog(widget, data=None)

add_video_device(name, label, path, i)

helper function to add an entry for a video device

clip_qrcode(widget=None)

copy the qrcode to the clipboard

create_menu()

create the main menu

create_qrcode_display()

create the QR code display

create_secret_keys_display()

list the secret keys for selection somewhere

create_video_controls()

create controls to choose the video device

create_webcam_display(video_found)

create the webcam preview widgets

decoded(zbar, data)

callback invoked when a barcode is decoded by the zbar widget. checks for an openpgp fingerprint

destroy(widget, data=None)

close the application

documentation_dialog(widget, data=None)

draw_qrcode()

draw the qrcode from the key fingerprint

edit_preferences(operation=None)

expose_event(widget, event)

When window is resized, regenerate the QR code

image_to_pixbuf(image)

Utility function to convert a PIL image instance to Pixbuf

import_image(widget)

Use a file chooser dialog to import an image containing a QR code

make_qrcode(fingerprint)

Given a fingerprint, generate a QR code image with appropriate prefix

print_op(widget=None)

handler for the print QR code menu

print_qrcode(operation=None, context=None, page_nr=None)

actually print the qr code

process_scan(data)

process zbar-scanned data

qr_code_event(thing, event)

qr_code_right_click_menu(event)

resume_capture()

restart capture

save_qrcode(widget=None)

Use a file chooser dialog to enable user to save the current QR code as a PNG image file

scan_image(filename)

Scan an image for QR codes

set_icon()

ui = '<ui>\n <menubar name="menu">\n <menu action="file">\n <menuitem action="open"/>\n <menuitem action="save"/>\n <menuitem action="print"/>\n <separator name="FileSeparator2"/>\n <menuitem action="quit"/>\n </menu>\n <menu action="edit">\n <menuitem action="copy"/>\n <menuitem action="preferences"/>\n </menu>\n <menu action="identity"/>\n <menu action="video"/>\n <menu action="help">\n <menuitem action="about"/>\n <menuitem action="documentation"/>\n </menu>\n </menubar>\n </ui>'

uid_changed(action, key)

refresh the qrcode when the selected key changes

update_progress_callback(*args)

callback invoked for pulsating progressbar

video_changed(action, path)

callback invoked when a new video device is selected from the drop-down list. sets the new device for the zbar widget, which will eventually cause it to be opened and enabled

watch_out_callback(pid, condition)

callback invoked when gpg key download is finished

class monkeysign.gtkui.MonkeysignScanUi(args=None)

sign a key in a safe fashion using a webcam to scan for qr-codes

This command will fire up a graphical interface and turn on the webcam (if available) on this computer. It will also display a qr-code of your main OpenPGP key.

The webcam is used to capture an OpenPGP fingerprint represented as a qrcode (or whatever the zbar library can parse) and then go through a signing process.

The signature is then encrypted and mailed to the user. This leave the choice of publishing the certification to that person and makes sure that person owns the identity signed.

This program assumes you have gpg-agent configure to prompt for passwords.

abort(prompt)

we don’t actually abort, just exit threads and resume capture

acknowledge(prompt)

untested

choose_uid(prompt, key)

main(**kargs)

classmethod sysinfo()

warn(prompt)

display the message but let things go

yes_no(prompt, default=None)

we ignore default! gotta fix that