# 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