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