The CA Key¶

We create a key (batzenca.database.keys.Key) for the Certification Authority (CA). First, we generate the GnuPG key:

>>> from batzenca import *
>>> session.gnupg.import_secret_key("filename.sec") # not implemented yet, use gpg directly

Alternatively, we can generate a fresh secret key for the CA:

>>> from batzenca.util import import_secret_key
>>> session.gnupg.generate_secret_key() # not implemented yet, use gpg directly

The Policy¶

Now, we create is a policy (batzenca.database.policies.Policy) which specifies constraints on keys on our mailing list. In our case keys must have at least 2048 bits, we only accept RSA and keys must expire within 720 days of creation:

>>> import datetime
>>> algorithms = (session.gnupg.GPGME_PK_RSA,)
>>> policy = Policy("main policy", datetime.date(2014,1,1), ca=ca, 2048, 720, algorithms)

The Mailing List¶

We can now create a mailing list object (batzenca.database.mailinglists.MailingList). Mailing lists have few message templates attached to it. In particular, a message (template) may be provided which is sent when a new user (batzenca.database.peers.Peer) joins the list (batzenca.database.mailinglists.MailingList.new_member_msg) which is rendered by batzenca.database.releases.Release.welcome_messages:

Hello {peer},

you are now subscribed to {mailinglist} <{mailinglist_email}>.

Best regards,
{ca} <{ca_email}>

Secondly, we need a message (batzenca.database.mailinglists.MailingList.key_update_msg) template for actual releases (batzenca.database.releases.Release) of bundles of keys (batzenca.database.keys.Key) which is rendered by batzenca.database.releases.Release.__call__:

Hello {mailinglist},

Users
-----

The following people joined:

{peers_in}

The following people have a new key:

{peers_changed}

The following people have left this list:

{peers_out}

Keys
----

The following keys are new:

{keys_in}

The following keys are no longer to be used:

{keys_out}

The complete list of all keys to be used is:

{keys}

{dead_man_switch}

Best regards,
{ca} <{ca_email}>

For the meaning of these fields see (batzenca.database.mailinglists.MailingList). Note, that the he expansion of {peers_in} and {peers_out} is a comma separated list of peers, while {keys*} is structured by line breaks.

Thirdly, a message template can be provided which is turned into a message sent to users when their keys are about to expire by batzenca.database.releases.Release.key_expiry_warning_messages:

Hello {peer},

your key with key id {keyid} is going to expire on {expiry_date}.

This key is used to encrypt messages for you on {mailinglist} <{mailinglist_email}>.

Please provide a new key to continue receiving messages on this list.

Best regards,
{ca} <{ca_email}>

Finally, a dead man switch message may be provided. This message is used to replace the field {dead_man_switch} in batzenca.database.mailinglists.MailingList.key_update_msg if still_alive = True when calling batzenca.database.releases.Release.__call__:

This CA has not received any requests to disclose and/or modify any data for this
mailinglist. Watch this space for this message to disappear.

With these in place, we can construct our batzenca.database.mailinglists.MailingList object (split over multiple lines for readability):

>>> ml = MailingList(name="batzenca", email="batzenca@thereisnohost.thereisnodomain", policy=policy)
>>> ml.new_member_msg = new_member_msg
>>> ml.key_update_msg = key_update_msg
>>> ml.key_expiry_warning_msg = dead_man_switch_msg
>>> ml.dead_man_switch_msg = dead_man_switch_msg

The Peers¶

Users can have multiple keys over time. This is addressed by creating batzenca.database.peers.Peer objects which point to all the keys of a particular user:

>>> keys = Key.from_filename("hansolo.asc")
>>> keys[0].sign(ca)
>>> han = Peer("Han Solo", keys)

The Releases¶

Finally, we can create an actual release (batzenca.database.releases.Release) which is what we send out to our users:

>>> rel = ml.new_release()
>>> rel.add_key(han.key)

The Database¶

Nothing what we’ve done so far was added to the database, except for the operations with GnuPG. To add our objects (keys, peers, mailing lists, releases) to the database we have to add it:

>>> session.add(ml)

We only need to add our mailing list as it points to all other objects created so far and add automatically cascades. However, this still isn’t persisent. We need to commit our changes to the database:

>>> session.commit()

Where is my Data?¶

BatzenCA does not interfere with your normal OpenPGP public-key or secret-key ring. Instead, it uses an independent GnuPG key database or keyring. By default it is located in $HOME/.batzenca/gnupg. This default can be changed by setting the environment variable BATZENCADIR. If BATZENCA is set, then the GnuPG keyring will be located in $BATZENCADIR/gnupg. The currently used home dir can be queried as follows:

>>> session.gnupg.home_dir

To work with the GnuPG directly you can run:

$ gpg --homedir=$HOME/.batzenca/gnupg

GnuPG¶

PGP/MIME¶

Where is my Data?¶

Peers, keys, policies, mailinglists and releases are stored in an SQLite database. By default it is located in $HOME/.batzenca/batzenca.db. This default can be changed by setting the environment variable BATZENCADIR. If BATZENCA is set, then the database will be located at $BATZENCADIR/batzenca.db.

Design¶

• New objects of type Foo are created from scratch using Foo.__init__. For querying the database class methods like Foo.from_bar are provided which query the database for bar and return – if found – the object of type Foo matching bar. Some classes have additional class methods for creating fresh objects from scratch. For example, batzenca.database.keys.Key has methods to create new objects from PGP keys stored in a file on disk.

• Newly created objects are were not added to the current session automatically. The caller is responsible for calling:

  >>> session.add(obj)
  

• To save changes to the database the caller must call:

  >>> session.commit()
  

EntryNotFound¶

Key¶

Peer¶

Policy¶

MailingList¶

Release¶