Skip to content

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.
    • key parameter
      • 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.
    • --sign key: (for key see above)
    • --sign-path: Filename with the From\'s private key. (Alternative to the sign parameter.)
    • --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 cert parameter.)
    • .sign(key=True, passphrase=, attach_key=False, cert=None, key_path=None): Sign now (and you may specify the parameters). (For key see 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 key see 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.

    • key parameter
      • 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 cert is set, the message is encrypted for it too (so that the sender can read their own message).
    • --encrypt [key]: (for key see above) Put 0/false/no to disable encrypt-path.
    • --encrypt-path (CLI only): Filename(s) with the recipient\'s public key(s). (Alternative to the encrypt parameter.)
    • .encrypt(key=True, sign=, key_path=):
      • sign See 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 the key parameter)
    • .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 key see 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
      
    # message not encrypted for the sender (from Python)
    Envelope()
        .message("Encrypted GPG message!")
        .subject("Secret subject will not be shown")
        .from_("person@example.com")
        .to(("receiver@example.com", "receiver2@example.com"))
        .encrypt(("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.