Muacrypt API Reference

Note

While the code documented here is automatically tested against gpg, gpg2, python2 and python3, all of the API here could change during 0.x releases.

muacrypt.account	Account management and processing of incoming / outgoing mails on a per-account basis.
muacrypt.states	All muacrypt states are managed through this module.
muacrypt.chainstore	Storage mechanisms which manage immutable blocks and Chains which consist of hash-linked entries.
muacrypt.mime	Mime message parsing and manipulation functions for Autocrypt usage.
muacrypt.bingpg	BinGPG is a “gpg” or “gpg2” command line wrapper which implements all operations we need for Autocrypt usage.
muacrypt.cmdline	Muacrypt Command line implementation.
muacrypt.bot	Bot command line subcommand to receive and answer with Autocrypt related information for mails to bot@autocrypt.org

account module

Account management and processing of incoming / outgoing mails on a per-account basis.

exception muacrypt.account.AccountException

an exception raised during method calls on an AccountManager instance.

class muacrypt.account.AccountManager(dir, plugin_manager)

Manage multiple accounts and route in/out messages to the appropriate account.

__init__(dir, plugin_manager)

Initialize multi-account configuration.

Parameters:

• dir (unicode) – directory in which muacrypt will states state.
• plugin_manager (pluggy.PluginManager) – a plugin manager instance with hooks registered

add_account(account_name=u'default', email_regex=None, keyhandle=None, gpgbin=u'gpg', gpgmode=u'own')

add a named account to this account.

Parameters:

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

mod_account(account_name=u'default', email_regex=None, keyhandle=None, gpgbin=None, prefer_encrypt=None)

modify a named account.

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

Parameters:

• account_name – name of this account
• email_regex – regular expression which matches all email addresses belonging to this account.
• keyhandle – key fingerprint or uid to use for this account.
• gpgbin – basename of or full path to gpg binary
• prefer_encrypt – prefer_encrypt setting for this account.

Returns:

Account instance

del_account(account_name)

fully remove an account.

get_account_from_emailadr(emailadr, raising=False)

get account for a given email address.

remove()

remove the account directory and re-reset all muacrypt state. You need to add accounts to get working again.

class muacrypt.account.Account(states, name, plugin_manager)

An Account manages all Autocrypt settings (both own keys and settings as well as per-peer ones derived from Autocrypt headers).

__init__(states, name, plugin_manager)

shallow initializer. Call create() for initializing this account. exists() tells whether that has happened already.

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

create all settings, keyrings etc for this account.

Parameters:

• name – name of this account
• email_regex – regular expression which matches all email addresses belonging to this account.
• keyhandle – key fingerprint or uid to use for this account. 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 account directory under the account. “system” will states keys in the user’s system GnuPG keyring.

make_ac_header(emailadr)

return Autocrypt header value which uses our own key and the provided emailadr if one of our account matches it.

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. Return type:unicode Returns:Autocrypt header value (or empty string)

exists()

return True if the account 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.

process_incoming(msg, ignore_existing=False)

process incoming mail message for Autocrypt headers both in the cleartext and encrypted parts which will be decrypted to process Autocrypt-Gossip headers.

Parameters:msg (email.message.Message) – instance of a standard email Message. Return type:ProcessIncomingResult or NoneType if message is known already.

import_keydata_as_autocrypt(addr, keydata, prefer_encrypt)

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

Parameters:

• addr (string or None) – e-mail address or None if should be extracted from UID of keydata.
• keydata (bytes) – keydata to be imported

Return type:

ImportKeyResult

process_gossip_headers(msg, msg_date, msg_id)

process gossip headers from payload mime part of mail message and update state information from any gossip header for the To or Cc recipients of the msg.

Parameters:msg (email.message.Message) – decrypted message returned from decrypt_mime as dec_msg Return type:ProcessIncomingResult

process_outgoing(msg)

add Autocrypt header to outgoing message. :type msg: email.message.Message :param msg: outgoing message in mime format. :rtype: ProcessOutgoingResult

encrypt_mime(msg, toaddrs)

create a new encrypted mime message.

Parameters:

• msg (email.message.Message) – message to be encrypted
• toaddrs (list of e-mail addresses) – e-mail addresses to encrypt to

Return type:

EncryptMimeResult

decrypt_mime(msg)

decrypt an encrypted mime message.

Parameters:msg (email.message.Message) – message to be decrypted Return type:DecryptMimeResult

class muacrypt.account.DecryptMimeResult(enc_msg, dec_msg, keyinfos)

Result returned from decrypt_mime() with ‘enc_msg’ (encrypted message) ‘dec_msg’ (decrypted message) and ‘keyinfos’ (keys for which the message was encrypted).

__init__(enc_msg, dec_msg, keyinfos)

x.__init__(…) initializes x; see help(type(x)) for signature

class muacrypt.account.EncryptMimeResult(enc_msg, keyhandles)

Result returned from encrypt_mime() with ‘msg’ (encrypted message) and ‘keyhandles’ (list of public key handles used for encryption) attributes

__init__(enc_msg, keyhandles)

x.__init__(…) initializes x; see help(type(x)) for signature

states module

All muacrypt states are managed through this module. We follow the Kappa architecture style (http://milinda.pathirage.org/kappa-architecture.com/) i.e. all state changes are added to append-only chains and they contain immutable entries that may cross-reference other entries (even from other chains). The linking between entries is done using crytographic hashes.

class muacrypt.states.States(dirpath)

Persisting Muacrypt and per-account settings.

__init__(dirpath)

class muacrypt.states.PeerState(chain)

Synthesized Autocrypt state from parsing messages from a peer.

latest_gossip_entry()

Return latest gossip entry.

__init__(chain)

x.__init__(…) initializes x; see help(type(x)) for signature

class muacrypt.states.OwnState(chain)

Synthesized own state for an account.

__init__(chain)

x.__init__(…) initializes x; see help(type(x)) for signature

class muacrypt.states.OOBState(chain)

Synthesized Out of Band verification state for an account.

__init__(chain)

x.__init__(…) initializes x; see help(type(x)) for signature

class muacrypt.states.AccountManagerState(chain)

Synthesized AccountManagerState.

__init__(chain)

x.__init__(…) initializes x; see help(type(x)) for signature

chainstore module

Storage mechanisms which manage immutable blocks and Chains which consist of hash-linked entries.

The HeadTracker keeps track of named “heads” which can be queried through the States class. Both the current BlockService and the HeadTracker use the file system for persistent storage.

class muacrypt.chainstore.BlockService(basedir)

Filesystem Blockservice for storing and getting immutable blocks for use from Chain instances.

__init__(basedir)

class muacrypt.chainstore.Block(cid, data, bs)

Basic entry for claim chains. Each Block has the following attributes: - cid: the content address of this block - parent_cid: the parent content address or None - timestamp: when this block was created in seconds since epoch - args: the block-specific payload

__init__(cid, data, bs)

parent

parent block or None.

class muacrypt.chainstore.HeadTracker(path)

Filesystem implementation for the mutable ID->HEAD mappings

__init__(path)

class muacrypt.chainstore.Chain(blockservice, headtracker, chain_name)

A Chain maintains an append-only log where each entry in the chain has its own content-based address so that chains can cross-reference entries from the same or other chains. Each entry in a chain carries a timestamp and a parent CID (block hash) and Entry-specific extra data.

__init__(blockservice, headtracker, chain_name)

x.__init__(…) initializes x; see help(type(x)) for signature

mime module

Mime message parsing and manipulation functions for Autocrypt usage.

muacrypt.mime.parse_email_addr(string)

return the routable email address part from a email-field string.

If the address is of type bytes and not ascii, it is returned in quoted printable encoding.

muacrypt.mime.parse_ac_headervalue(value)

return a Result object with keydata/addr/prefer_encrypt/extra_attr/error attributes.

If the error attribute is set on the result object then all other attribute values are undefined.

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

msg should be an email.message.Message object

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.

exception muacrypt.bingpg.InvocationFailure(ret, cmd, out, err, extrainfo=None)

__init__(ret, cmd, out, err, extrainfo=None)

x.__init__(…) initializes x; see help(type(x)) for signature

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

basic wrapper for gpg command line invocations.

exception InvocationFailure(ret, cmd, out, err, extrainfo=None)

__init__(ret, cmd, out, err, extrainfo=None)

x.__init__(…) initializes x; see help(type(x)) for signature

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

Parameters:

• homedir (unicode or None) – gpg home directory, if None system gpg homedir is used.
• 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.

muacrypt.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.

cmdline module

Muacrypt Command line implementation.

bot module

Bot command line subcommand to receive and answer with Autocrypt related information for mails to bot@autocrypt.org