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