Ciphering¶
Cipher standard method¶
If neither gpg nor smime is specified explicitly, the method is auto-detected: envelope tries to parse whatever you passed to sign/encrypt as a PEM-encoded S/MIME private key (for signing) or certificate (for encrypting); if that parses, S/MIME is used, otherwise it falls back to GPG.
Envelope(message="Hello world", sign=True) # no PEM key given → signed with the default GPG key
Envelope(message="Hello world", sign=Path("key.pem")) # key.pem parses as an S/MIME key → signed with S/MIME
You may bypass the auto-detection and pick the method yourself:
- gpg: True to prefer GPG over S/MIME or home path to GNUPG rings (otherwise default ~/.gnupg is used)
- --gpg [path]
- .gpg(gnugp_home=True)
- Envelope(gpg=True)
- .smime: Prefer S/MIME over GPG
- --smime
- .smime()
- Envelope(smime=True)
Signing¶
- sign: Sign the message.
keyparameter- GPG:
- Blank (CLI) or True (module) for user default key
- "auto" for turning on signing if there is a key matching to the "from" header
- key ID/fingerprint
- e-mail address of the identity whose key is to be signed with
- Any attainable contents with the key to be signed with (will be imported into keyring)
- S/MIME: Any attainable contents with key to be signed with. May contain signing certificate as well.
- GPG:
- --sign key: (for
keysee above) - --sign-path: Filename with the From\'s private key. (Alternative to the
signparameter.) - --passphrase: Passphrase to the key if needed.
- --attach-key: GPG: Blank for appending public key to the attachments when sending.
- --cert: S/MIME: Certificate contents if not included in the key.
- --cert-path: S/MIME: Filename with the From's private cert if cert not included in the key. (Alternative to the
certparameter.) - .sign(key=True, passphrase=, attach_key=False, cert=None, key_path=None): Sign now (and you may specify the parameters). (For
keysee above.) - .signature(key=True, passphrase=, attach_key=False, cert=None, key_path=None): Sign later (when launched with .sign(), .encrypt() or .send() functions
- Envelope(sign=key): (for
keysee above) - Envelope(passphrase=): Passphrase to the signing key if needed.
- Envelope(attach_key=): If true, append GPG public key as an attachment when sending.
- Envelope(cert=): S/MIME: Any attainable contents
Encrypting¶
-
encrypt: Recipient GPG public key or S/MIME certificate to be encrypted with.
keyparameter- GPG:
- Blank (CLI) or True (module) to force encrypt with the user default keys (identities in the "from", "to", "cc" and "bcc" headers)
- "auto" for turning on encrypting if there is a matching key for every recipient
- key ID/fingerprint
- e-mail address of the identity whose key is to be encrypted with
- Any attainable contents with the key to be encrypted with (will be imported into keyring)
- an iterable with the identities specified by key ID / fingerprint / e-mail address / raw key data
- S/MIME any attainable contents with a certificate to be encrypted with or more in an iterable. If the sender's
certis set, the message is encrypted for it too (so that the sender can read their own message).
- GPG:
- --encrypt [key]: (for
keysee above) Put 0/false/no to disableencrypt-path. - --encrypt-path (CLI only): Filename(s) with the recipient\'s public key(s). (Alternative to the
encryptparameter.) - .encrypt(key=True, sign=, key_path=):
signSee signing, ex: you may specify boolean or default signing key ID/fingerprint or "auto" for GPG or any attainable contents with an S/MIME key + signing certificate.key_path: Key/certificate contents (alternative to thekeyparameter)
- .encryption(key=True, key_path=): Encrypt later (when launched with .sign(), .encrypt() or .send() functions. If needed, in the parameters specify any attainable contents with GPG encryption key or S/MIME encryption certificate.
- Envelope(encrypt=key): (for
keysee above)# message gets encrypted for multiple S/MIME certificates envelope --smime --encrypt-path recipient1.pem recipient2.pem --message "Hello" # message gets encrypted with the default GPG key envelope --message "Encrypted GPG message!" --subject "Secret subject will not be shown" --encrypt --from person@example.com --to person@example.com # message not encrypted for the sender (from Bash) envelope --message "Encrypted GPG message!" --subject "Secret subject will not be shown" --encrypt receiver@example.com receiver2@example.com --from person@example.com --to receiver@example.com receiver2@example.com
GPG notes¶
- If the GPG encryption fails, it tries to determine which recipient misses the key.
- By default, GPG encrypts with the key of the from header recipient too.
- Key ID/fingerprint is internally ignored right now, GPG decides itself which key is to be used.