Keymanager is the Bitmask component that does key management, including generation, discovery and validation. It is, esentially, a nicknym client that uses Soledad as its storage layer.

Keymanager handles the creation of a OpenPGP transparently in user’s behalf. When bootstrapping a new account, keymanager will generate a new key pair. The key pair is stored encrypted inside soledad (and therefore able to be synced by other replicas). After generating it, the public key is sent to the provider, which will replace any prior keys for the same address in its database.

To discover keys for other users, the nicknym client in keymanager will query the nicknym server associated with user’s provider, and will process the keys that the server returns. This query has the following form:

It is up to the the provider’s service to determine the sources for the keys.

Keymanager currently implements all the levels defined in the Transitional Key Validation spec, although the mechanisms for validation currently in place only reach level 2 of what’s contemplated in the spec.

Sources of public keys

Currently Bitmask can discover new public keys from different sources:

  • Keys attached to incoming emails. Simple .asc attachments with the keys will be taken into account, like the ones produced by enigmail.
  • OpenPGP header in incoming emails. The only field taken into account is the url and it will only be used if it’s an https address from the same domain as the senders email address.
  • When sending emails, if the recipient key is not known, Bitmask will ask for the key to its nicknym provider. The nicknym provider will try to discover the key from other nicknym providers. If provider discovery does not bring any results, the key will be fetched from the sks key servers. Note that this sks discovery mechanism is probably going to be removed at some time in the future as it provides too many unused keys.

Other methods are planned to be added in the future, like discovery from signatures in emails, headers (autocrypt spec) or other kind of key servers.

Key expiration dates

KeyManager creates the OpenPGP key with the default expiration of gnupg, that currently is 2 years after the key creation. We want keys with expiration date, to be able to roll new ones if the key material get lost.

We will reduce the default expiration lenght in the future. That will require the rest of OpenPGP ecosystem to have good refresh mechanisms for keys, situation that is improving in the last years.

KeyManager extends one year the expiration date automatically two months before the key gets expired.

Implementation: using Soledad Documents

KeyManager uses two types of Soledad Documents for the keyring:

  • key document, that stores each gpg key.
  • active document, that relates an address to its corresponding key.

Each key can have 0 or more active documents with a different email address each:

.-------------.          .-------------.
| |          | |
'-------------'          '-------------'
       |                        |
       |      .-----------.     |
       |      |           |     |
       |      |    key    |     |
       '----->|           |<----'
              |           |

Fields in a key document:

  • uids
  • fingerprint
  • key_data
  • private. bool marking if the key is private or public
  • length
  • expiry_date
  • refreshed_at
  • version = 1
  • type = “OpenPGPKey”
  • tags = [“keymanager-key”]

Fields in an active document:

  • address
  • fingerprint
  • private
  • validation
  • last_audited_at
  • encr_used
  • sign_used
  • version = 1
  • type = “OpenPGPKey-active”
  • tags = [“keymanager-active”]

The meaning of validation, encr_used and sign_used is related to the Transitional Key Validation