Autocrypt Python API Reference

Note

While the code documented here is automatically tested against gpg, gpg2, python2 and python3, all of the API here is subject to change during 0.x releases. This doesn’t mean that everything will actually change.

autocrypt.account	Contains Account class which offers all autocrypt related access and manipulation methods.
autocrypt.bot
autocrypt.mime	mime message parsing and manipulation functions for Autocrypt usage.
autocrypt.bingpg	BinGPG is a “gpg” or “gpg2” command line wrapper which implements all operations we need for Autocrypt usage.
autocrypt.pgpycrypto

account module

Contains Account class which offers all autocrypt related access and manipulation methods. It also contains some internal helpers which help to persist config and peer state.

exception autocrypt.account.AccountException

an exception raised during method calls on an Account instance.

class autocrypt.account.Account(dir)

Autocrypt Account class which allows to manipulate autocrypt configuration and state for use from mail processing agents. Autocrypt uses a standalone GPG managed keyring and persists its config to a default app-config location.

You can init an account and then use it to generate Autocrypt headers and process incoming mails to discover and memorize a peer’s Autocrypt headers.

__init__(dir)

Initialize the account configuration and internally used gpggrapper.

Parameters:

• dir (unicode) – directory in which autocrypt will store all state including a gpg-managed keyring.
• gpgpath (unicode) – If the path contains path separators and points to an existing file we use it directly. If it contains no path separators, we lookup the path to the binary under the system’s PATH. If we can not determine an eventual binary we raise ValueError.

add_identity(id_name=u'default', email_regex=u'.*', keyhandle=None, gpgbin=u'gpg', gpgmode=u'own')

add a named identity to this account.

Parameters:

• id_name – name of this identity
• email_regex – regular expression which matches all email addresses belonging to this identity.
• keyhandle – key fingerprint or uid to use for this identity.
• gpgbin – basename of or full path to gpg binary
• gpgmode – “own” (default) keeps all key state inside the identity directory under the account. “system” will store keys in the user’s system gnupg keyring.

mod_identity(id_name=u'default', email_regex=None, keyhandle=None, gpgbin=None, prefer_encrypt=None)

modify a named identity.

All arguments are optional: if they are not specified the underlying identity setting remains unchanged.

Parameters:

• id_name – name of this identity
• email_regex – regular expression which matches all email addresses belonging to this identity.
• keyhandle – key fingerprint or uid to use for this identity.
• gpgbin – basename of or full path to gpg binary
• gpgmode – “own” keeps all key state inside the identity directory under the account. “system” will store keys in the user’s system gnupg keyring.

Returns:

Identity instance

del_identity(id_name)

fully remove an identity.

get_identity_from_emailadr(emailadr_list, raising=False)

get identity for a given email address list.

remove()

remove the account directory and reset this account configuration to empty. You need to add identities to reinitialize.

make_header(emailadr, headername=u'Autocrypt: ')

return an Autocrypt header line which uses our own key and the provided emailadr if this account is managing the emailadr.

Parameters:

• emailadr (unicode) – pure email address which we use as the “addr” attribute in the generated Autocrypt header. An account may generate and send mail from multiple aliases and we advertise the same key across those aliases.
• headername (unicode) – the prefix we use for the header, defaults to “Autocrypt”. By specifying an empty string you just get the header value.

Return type:

unicode

Returns:

autocrypt header with prefix and value (or empty string)

process_incoming(msg, delivto=None)

process incoming mail message and store information from any Autocrypt header for the From/Autocrypt peer which created the message.

Parameters:msg (email.message.Message) – instance of a standard email Message. Return type:PeerInfo

process_outgoing(msg)

process outgoing mail message and add Autocrypt header if it doesn’t already exist.

Parameters:msg (email.message.Message) – instance of a standard email Message. Return type:PeerInfo

class autocrypt.account.Identity(dir)

An Identity manages all Autocrypt settings and keys for a peer and stores it in a directory. Call create() for initializing settings.

__init__(dir)

create(name, email_regex, keyhandle, gpgbin, gpgmode)

create all settings, keyrings etc for this identity.

Parameters:

• name – name of this identity
• email_regex – regular expression which matches all email addresses belonging to this identity.
• keyhandle – key fingerprint or uid to use for this identity. If it is None we generate a fresh Autocrypt compliant key.
• gpgbin – basename of or full path to gpg binary
• gpgmode – “own” keeps all key state inside the identity directory under the account. “system” will store keys in the user’s system GnuPG keyring.

get_peerinfo(emailadr)

get peerinfo object for a given email address.

Parameters:emailadr (unicode) – pure email address without any prefixes or real names. Return type:PeerInfo or None

exists()

return True if the identity exists.

export_public_key(keyhandle=None)

return armored public key of this account or the one indicated by the key handle.

export_secret_key()

return armored public key for this account.

class autocrypt.account.PeerInfo(identity, d)

Read-Only info coming from the Parsed Autocrypt header from an incoming Mail from a peer. In addition to the public Autocrypt attributes (addr, keydata, type, ...) we process also py-autocrypt internal *date and *keyhandle attributes.

__init__(identity, d)

class autocrypt.account.IdentityInfo(name, email_regex, prefer_encrypt, keyhandle, peers, uuid)

Read only information about an Identity in an account.

__init__(name, email_regex, prefer_encrypt, keyhandle, peers, uuid)

bot module

mime module

mime message parsing and manipulation functions for Autocrypt usage.

autocrypt.mime.parse_ac_headervalue(value)

return a autocrypt attribute dictionary parsed from the specified autocrypt header value. Unspecified default values for prefer-encrypt and the key type are filled in.

autocrypt.mime.parse_email_addr(string)

return a (prefix, emailadr) tuple.

autocrypt.mime.render_mime_structure(msg, prefix=u'\u2514')

msg should be an email.message.Message object

autocrypt.mime.verify_ac_dict(ac_dict)

return a list of errors from checking the autocrypt attribute dict. if the returned list is empty no errors were found.

bingpg module

BinGPG is a “gpg” or “gpg2” command line wrapper which implements all operations we need for Autocrypt usage. It is not meant as a general wrapper outside Autocrypt contexts.

class autocrypt.bingpg.BinGPG(homedir=None, gpgpath=u'gpg')

basic wrapper for gpg command line invocations.

__init__(homedir=None, gpgpath=u'gpg')

autocrypt.bingpg.find_executable(name)

return a path object found by looking at the systems underlying PATH specification. If an executable cannot be found, None is returned. copied and adapted from py.path.local.sysfind.

pgpycrypto module

Note

The “pgpy” backend is tested but not used not used yet because pgpy==0.4.1 are not sufficiently substituting gpg functionality yet.

claimchain module

Note

The claimchain module is not required for, or part of Autocrypt Level 1. It is a prototype and experimental effort which azul and hpk are playing with to allow for helping users protect against MITM attacks or, conversely, to make it more costly for providers or network-level attackers who want to subvert communications. This is part of their involvement on the NEXTLEAP EU project.

Eventually claimchains could be integrated as a Plugin but this requires an according pluginization of py-autocrypt which is better to do after the prototyping stabilizes.

Basic ClaimChain implementation.

Each claimchain is associated with an externally provided identifier which is, however, not part of the claimchain itself. We presume each claimchain instance relates either to an own account or to a remote peer (email address), both of which are represented through a unique identifier.

The storage infrastructure for claimchains works by creating and accessing immutable blocks through the BlockService. Each block serves as a ClaimChain entry which is conceptually an append-only log. The current head (last item of the log) associated with each identifier is obtained and managed through a HeadTracker instance. Both the BlockService and the HeadTracker use the file system for persistent storage. If we could use IPFS libs (see below todo) and a subset of their infrastructure we might also use a distributed global BlockService without much coding change. To protect blocks from public reading we can add symmetric encryption and transfer the according secret in-band as well.

Each claimchain instance starts with a “genesis” entry which contains an Autocrypt public key. When receiving a claimchain from someone it should be framed within a signature with this genesis key. One way to achieve this is to send ClaimChains only within encrypted&signed messages.

Another claimchain entry type is “oob_verification” which expresses successful out-of-band verification of claimchain heads and key material between two users.

todo/to-consider:

• properly implement oob verification
• look into using ipfs’s modules/concepts for serializing and creating “content ids”, i.e. self-describing hash addresses to blocks
• add crypto signing of each entry? For in-band transmission of ClaimChains we can probably just sign the whole chain instead of the single entries.