4.7. Crypto

alot.crypto.RFC3156_micalg_from_algo(hash_algo)

Converts a GPGME hash algorithm name to one conforming to RFC3156.

GPGME returns hash algorithm names such as “SHA256”, but RFC3156 says that programs need to use names such as “pgp-sha256” instead.

Parameters:

hash_algo (str) – GPGME hash_algo

Returns:

the lowercase name of of the algorithm with “pgp-” prepended

Return type:

str

alot.crypto.bad_signatures_to_str(error)

Convert a bad signature exception to a text message. This is a workaround for gpg not handling non-ascii data correctly.

Parameters:

error (BadSignatures) – BadSignatures exception

alot.crypto.check_uid_validity(key, email)

Check that a the email belongs to the given key. Also check the trust level of this connection. Only if the trust level is high enough (>=4) the email is assumed to belong to the key.

Parameters:

  • key (gpg.gpgme._gpgme_key) – the GPG key to which the email should belong

  • email (str) – the email address that should belong to the key

Returns:

whether the key can be assumed to belong to the given email

Return type:

bool

alot.crypto.decrypt_verify(encrypted, session_keys=None)

Decrypts the given ciphertext string and returns both the signatures (if any) and the plaintext.

Parameters:

  • encrypted (bytes) – the mail to decrypt

  • session_keys (list[str]) – a list OpenPGP session keys

Returns:

the signatures and decrypted plaintext data

Return type:

tuple[list[gpg.resuit.Signature], str]

Raises:

alot.errors.GPGProblem – if the decryption fails

alot.crypto.detached_signature_for(plaintext_str, keys)

Signs the given plaintext string and returns the detached signature.

A detached signature in GPG speak is a separate blob of data containing a signature for the specified plaintext.

Parameters:

  • plaintext_str (bytes) – bytestring to sign

  • keys (list[gpg.gpgme._gpgme_key]) – list of one or more key to sign with.

Returns:

A list of signature and the signed blob of data

Return type:

tuple[list[gpg.results.NewSignature], str]

alot.crypto.encrypt(plaintext_str, keys)

Encrypt data and return the encrypted form.

Parameters:

  • plaintext_str (bytes) – the mail to encrypt

  • key (list[gpg.gpgme.gpgme_key_t] or None) – optionally, a list of keys to encrypt with

Returns:

encrypted mail

Return type:

str

alot.crypto.get_key(keyid, validate=False, encrypt=False, sign=False, signed_only=False)

Gets a key from the keyring by filtering for the specified keyid, but only if the given keyid is specific enough (if it matches multiple keys, an exception will be thrown).

If validate is True also make sure that returned key is not invalid, revoked or expired. In addition if encrypt or sign is True also validate that key is valid for that action. For example only keys with private key can sign. If signed_only is True make sure that the user id can be trusted to belong to the key (is signed). This last check will only work if the keyid is part of the user id associated with the key, not if it is part of the key fingerprint.

Parameters:

  • keyid (str) – filter term for the keyring (usually a key ID)

  • validate (bool) – validate that returned keyid is valid

  • encrypt (bool) – when validating confirm that returned key can encrypt

  • sign (bool) – when validating confirm that returned key can sign

  • signed_only (bool) – only return keys whose uid is signed (trusted to belong to the key)

Returns:

A gpg key matching the given parameters

Return type:

gpg.gpgme._gpgme_key

Raises:

  • GPGProblem – if the keyid is ambiguous

  • GPGProblem – if there is no key that matches the parameters

  • GPGProblem – if a key is found, but signed_only is true and the key is unused

alot.crypto.list_keys(hint=None, private=False)

Returns a generator of all keys containing the fingerprint, or all keys if hint is None.

The generator may raise exceptions of :class:gpg.errors.GPGMEError, and it is the caller’s responsibility to handle them.

Parameters:

  • hint (str or None) – Part of a fingerprint to usee to search

  • private (bool) – Whether to return public keys or secret keys

Returns:

A generator that yields keys.

Return type:

Generator[gpg.gpgme.gpgme_key_t, None, None]

alot.crypto.validate_key(key, sign=False, encrypt=False)

Assert that a key is valide and optionally that it can be used for signing or encrypting. Raise GPGProblem otherwise.

Parameters:

  • key (gpg.gpgme._gpgme_key) – the GPG key to check

  • sign (bool) – whether the key should be able to sign

  • encrypt (bool) – whether the key should be able to encrypt

Raises:

  • GPGProblem – If the key is revoked, expired, or invalid

  • GPGProblem – If encrypt is true and the key cannot be used to encrypt

  • GPGProblem – If sign is true and th key cannot be used to encrypt

alot.crypto.verify_detached(message, signature)

Verifies whether the message is authentic by checking the signature.

Parameters:

  • message (bytes) – The message to be verified, in canonical form.

  • signature (bytes) – the OpenPGP signature to verify

Returns:

a list of signatures

Return type:

list[gpg.results.Signature]

Raises:

alot.errors.GPGProblem – if the verification fails