envelope 2.2.0__tar.gz → 2.3.0__tar.gz

{envelope-2.2.0 → envelope-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: envelope
-Version: 2.2.0
+Version: 2.3.0
 Summary: Insert a message and attachments and send e-mail / sign / encrypt contents by a single line.
 License: LGPL-3.0-or-later
 Author: Edvard Rejthar
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
 
 [![Build Status](https://github.com/CZ-NIC/envelope/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/envelope/actions) [![Downloads](https://static.pepy.tech/badge/envelope)](https://pepy.tech/project/envelope)
 
-Quick layer over [python-gnupg](https://bitbucket.org/vinay.sajip/python-gnupg/src), [M2Crypto](https://m2crypto.readthedocs.io/), [smtplib](https://docs.python.org/3/library/smtplib.html), [magic](https://pypi.org/project/python-magic/) and [email](https://docs.python.org/3/library/email.html?highlight=email#module-email) handling packages. Their common use cases merged into a single function. Want to sign a text and tired of forgetting how to do it right? You do not need to know everything about GPG or S/MIME, you do not have to bother with importing keys. Do not hassle with reconnecting to an SMTP server. Do not study various headers meanings to let your users unsubscribe via a URL.
+Quick layer over [python-gnupg](https://bitbucket.org/vinay.sajip/python-gnupg/src), [cryptography](https://github.com/pyca/cryptography), [M2Crypto](https://m2crypto.readthedocs.io/), [smtplib](https://docs.python.org/3/library/smtplib.html), [magic](https://pypi.org/project/python-magic/) and [email](https://docs.python.org/3/library/email.html?highlight=email#module-email) handling packages. Their common use cases merged into a single function. Want to sign a text and tired of forgetting how to do it right? You do not need to know everything about GPG or S/MIME, you do not have to bother with importing keys. Do not hassle with reconnecting to an SMTP server. Do not study various headers meanings to let your users unsubscribe via a URL.
 You insert a message, attachments and inline images and receive signed and/or encrypted output to the file or to your recipients' e-mail.
 Just single line of code. With the great help of the examples below.
 
@@ -692,6 +692,16 @@ if xarf := Envelope.load(path="xarf.eml")._report():
   print(xarf['SourceIp'])  # '192.0.2.1'
 ```
 
+* `_check_auth()`: To determine whether DMACR, SPF and DKIM are alright in a loaded message.
+```python3
+from envelope import Envelope
+auth = Envelope.load(path="test.eml")._check_auth()
+auth # <AuthResult spf='pass', dkim='pass', dmarc='pass', spf_received='pass', verdict='pass', failure_reason=None>
+if auth:  # Use the output object as bool. It is True only if all present checks are 'pass'.
+  ...
+```
+
+
 ## Envelope object
 
 ### Converting object to str or bool

{envelope-2.2.0 → envelope-2.3.0}/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://github.com/CZ-NIC/envelope/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/envelope/actions) [![Downloads](https://static.pepy.tech/badge/envelope)](https://pepy.tech/project/envelope)
 
-Quick layer over [python-gnupg](https://bitbucket.org/vinay.sajip/python-gnupg/src), [M2Crypto](https://m2crypto.readthedocs.io/), [smtplib](https://docs.python.org/3/library/smtplib.html), [magic](https://pypi.org/project/python-magic/) and [email](https://docs.python.org/3/library/email.html?highlight=email#module-email) handling packages. Their common use cases merged into a single function. Want to sign a text and tired of forgetting how to do it right? You do not need to know everything about GPG or S/MIME, you do not have to bother with importing keys. Do not hassle with reconnecting to an SMTP server. Do not study various headers meanings to let your users unsubscribe via a URL.
+Quick layer over [python-gnupg](https://bitbucket.org/vinay.sajip/python-gnupg/src), [cryptography](https://github.com/pyca/cryptography), [M2Crypto](https://m2crypto.readthedocs.io/), [smtplib](https://docs.python.org/3/library/smtplib.html), [magic](https://pypi.org/project/python-magic/) and [email](https://docs.python.org/3/library/email.html?highlight=email#module-email) handling packages. Their common use cases merged into a single function. Want to sign a text and tired of forgetting how to do it right? You do not need to know everything about GPG or S/MIME, you do not have to bother with importing keys. Do not hassle with reconnecting to an SMTP server. Do not study various headers meanings to let your users unsubscribe via a URL.
 You insert a message, attachments and inline images and receive signed and/or encrypted output to the file or to your recipients' e-mail.
 Just single line of code. With the great help of the examples below.
 
@@ -671,6 +671,16 @@ if xarf := Envelope.load(path="xarf.eml")._report():
   print(xarf['SourceIp'])  # '192.0.2.1'
 ```
 
+* `_check_auth()`: To determine whether DMACR, SPF and DKIM are alright in a loaded message.
+```python3
+from envelope import Envelope
+auth = Envelope.load(path="test.eml")._check_auth()
+auth # <AuthResult spf='pass', dkim='pass', dmarc='pass', spf_received='pass', verdict='pass', failure_reason=None>
+if auth:  # Use the output object as bool. It is True only if all present checks are 'pass'.
+  ...
+```
+
+
 ## Envelope object
 
 ### Converting object to str or bool

{envelope-2.2.0 → envelope-2.3.0}/envelope/__main__.py

@@ -171,7 +171,11 @@ def main():
                 or args["subject"] is True \
                 or args["message"] is True \
                 or select.select([sys.stdin, ], [], [], 0.0)[0]:
-            instance = Envelope.load(sys.stdin.read())
+            stdin = sys.stdin.read()
+            if "\r" in stdin or "\n" in stdin:
+                instance = Envelope.load(stdin)
+            else:
+                instance = Envelope(message=stdin)
     except select.error:  # XX check if using `select` to detect STDIN does not mess up Windows
         pass
     del args["load"]

envelope-2.3.0/envelope/_auth.py

@@ -0,0 +1,79 @@
+from dataclasses import dataclass
+from email.message import EmailMessage
+import re
+from typing import Optional
+
+
+@dataclass
+class AuthResult:
+    verdict: str
+    spf: Optional[str] = None
+    dkim: Optional[str] = None
+    dmarc: Optional[str] = None
+    spf_received: Optional[str] = None
+    failure_reason: Optional[str] = None
+
+    def __bool__(self):
+        return self.verdict == "pass"
+
+    def __repr__(self):
+        return (f"<AuthResult spf={self.spf!r}, dkim={self.dkim!r}, dmarc={self.dmarc!r}, "
+                f"spf_received={self.spf_received!r}, verdict={self.verdict!r}, failure_reason={self.failure_reason!r}>")
+
+    @staticmethod
+    def _extract_results_from_text(text: str) -> dict:
+        def extract(key: str):
+            match = re.search(fr"{key}=([\w\-]+)", text, re.IGNORECASE)
+            return match.group(1).lower() if match else None
+
+        return extract("spf"), extract("dkim"), extract("dmarc")
+
+    @staticmethod
+    def from_headers(headers: EmailMessage) -> "AuthResult":
+
+        # Merge Authentication-Results and ARC-Authentication-Results hlavičky dohromady
+        auth_results_headers: list[str] = []
+        auth_results_headers += headers.get_all("Authentication-Results", [])
+        auth_results_headers += headers.get_all("ARC-Authentication-Results", [])
+
+        combined_auth_results = "; ".join(auth_results_headers)
+
+        # Extract from text
+        spf, dkim, dmarc = AuthResult._extract_results_from_text(combined_auth_results)
+
+        # SPF from Received-SPF
+        received_spf = headers.get("Received-SPF", "")
+        spf_received_match = re.search(r"([\w\-]+)", received_spf)
+        spf_received = spf_received_match.group(1).lower() if spf_received_match else None
+
+        # Determine the verdict
+        failure_reason = None
+        if spf and spf_received and spf != spf_received:
+            verdict = "fail"
+            failure_reason = f"SPF mismatch: Authentication-Results={spf}, Received-SPF={spf_received}"
+
+        elif dmarc == "pass":
+            verdict = "pass"
+
+        elif any(v == "fail" for v in [spf, dkim, dmarc, spf_received]):
+            verdict = "fail"
+            failure_reason = "At least one mechanism failed"
+
+        elif any(v == "softfail" for v in [spf, spf_received]):
+            verdict = "softfail"
+            failure_reason = "SPF softfail detected"
+
+        elif all(v == "pass" for v in [spf, dkim] if v and v != 'none'):
+            verdict = "pass"
+        else:
+            verdict = "none"
+            failure_reason = "No usable authentication results"
+
+        return AuthResult(
+            spf=spf,
+            dkim=dkim,
+            dmarc=dmarc,
+            spf_received=spf_received,
+            verdict=verdict,
+            failure_reason=failure_reason
+        )

{envelope-2.2.0 → envelope-2.3.0}/envelope/envelope.py

@@ -24,6 +24,7 @@ from quopri import decodestring
 from types import GeneratorType
 from typing import Literal, Union, Optional, Any
 
+from ._auth import AuthResult
 from .address import Address, _getaddresses
 from .attachment import Attachment
 from .constants import ISSUE_LINK, smime_import_error, gnupg, CRLF, AUTO, PLAIN, HTML, SIMULATION, SAFE_LOCALE
@@ -205,13 +206,25 @@ class Envelope:
         :param key: S/MIME key to decrypt with.
         :param cert: S/MIME cert to decrypt with. (If not bundled with the key.)
         :param gnupg_home: Path to the GNUPG_HOME or None if the environment default should be used.
+
+        :raise ValueError: If the message cannot be loaded.
         """
         if path:
             message = Path(path)
         elif isinstance(message, Message):
             message = str(message)
 
-        o = message_from_bytes(assure_fetched(message, bytes))
+        msg_ = assure_fetched(message, bytes)
+        o = message_from_bytes(msg_)
+
+        # NOTE this breaks up .load("hello text")
+        # quick check
+        for _ in o.keys():
+            break
+        else:  # there are no headers
+            if not path and b"\n" not in msg_ and b"\r" not in msg_:
+                raise ValueError(f"Message cannot be loaded. Didn't you forgot to use the `Envelope.load(path=...)`?")
+
         e = Envelope()
         try:
             return Parser(e, key=key, cert=cert, gnupg_home=gnupg_home or e._get_gnupg_home()) \
@@ -406,7 +419,8 @@ class Envelope:
             split_addresses = []
             for address in addresses:
                 split_addresses.extend(address.replace(';', ',').split(','))
-            split_addresses = [x.strip() for x in split_addresses if x.strip()]  # remove empty and whitespace-only strings
+            # remove empty and whitespace-only strings
+            split_addresses = [x.strip() for x in split_addresses if x.strip()]
             registry += (a for a in Address.parse(split_addresses) if a not in registry)
 
     def to(self, email_or_more=None) -> Union["Envelope", list[Address]]:
@@ -607,7 +621,8 @@ class Envelope:
         :param one_click: If True, rfc8058 List-Unsubscribe-Post header is added.
             This says user can unsubscribe with a single click that is realized by a POST request
             in order to prevent e-mail scanner to access the unsubscribe page by mistake. A 'https' url must be present.
-        :param web: URL. Ex: "example.com/unsubscribe", "http://example.com/unsubscribe"
+        :param web: URL. Ex: "https://example.com/unsubscribe"
+            Without protocol, `https://` is prepended, "example.com/unsubscribe" -> "https://example.com/unsubscribe"
         :param email: E-mail address. Ex: "me@example.com", "mailto:me@example.com"
         :return: self
         """
@@ -1260,29 +1275,32 @@ class Envelope:
     def _import_cryptoraphy_modules(self):
         try:
             from cryptography.hazmat.primitives.serialization import load_pem_private_key, pkcs7
-            from cryptography.x509 import load_pem_x509_certificate
+            from cryptography.x509 import load_pem_x509_certificates, load_pem_x509_certificate
             from cryptography.hazmat.primitives import hashes, serialization
-            return load_pem_private_key, pkcs7, load_pem_x509_certificate, hashes, serialization
+            return load_pem_private_key, pkcs7, load_pem_x509_certificates, load_pem_x509_certificate, hashes, serialization
         except ImportError:
             raise ImportError(smime_import_error)
-        
+
     def smime_sign_only(self, email, sign):
-        load_pem_private_key, pkcs7, load_pem_x509_certificate, hashes, serialization = self._import_cryptoraphy_modules()
+        load_pem_private_key, pkcs7, load_pem_x509_certificates, _, hashes, serialization = self._import_cryptoraphy_modules()
         # get sender's cert
         # cert and private key can be one file
 
         # if certfile is not provided, sign has to have both private key and certificate
         # cert is not in sign (--sign_path file), it is cert.pem
         if self._cert:
-            cert = self._cert
+            certs = self._cert
         else:
             # certificate is in sign (--sign_path file), it is key-cert-together.pem
-            cert = sign
+            certs = sign
 
         try:
-            cert = load_pem_x509_certificate(cert)
+            certs = load_pem_x509_certificates(certs)
         except ValueError as e:
             raise ValueError(f"Certificate not found: {e}")
+        # no certificate found
+        if len(certs) == 0:
+            raise ValueError("Certificate not found")
 
         # get senders private key for signing
         try:
@@ -1297,29 +1315,36 @@ class Envelope:
 
         options = [pkcs7.PKCS7Options.DetachedSignature]
 
-        signed_email = pkcs7.PKCS7SignatureBuilder().set_data(
+        signature_builder = pkcs7.PKCS7SignatureBuilder().set_data(
             email
         ).add_signer(
-            cert, key, hashes.SHA256()
-        ).sign(
+            certs[0], key, hashes.SHA256()
+        )
+        # add the whole certificate chain
+        for cert in certs[1:]:
+            signature_builder = signature_builder.add_certificate(cert)
+
+        signed_email = signature_builder.sign(
             serialization.Encoding.SMIME, options
         )
 
         return signed_email
 
     def smime_sign_encrypt(self, email, sign, encrypt):
-        load_pem_private_key, pkcs7, load_pem_x509_certificate, hashes, serialization = self._import_cryptoraphy_modules()
+        load_pem_private_key, pkcs7, load_pem_x509_certificates, load_pem_x509_certificate, hashes, serialization = self._import_cryptoraphy_modules()
 
         if self._cert:
-            sender_cert = self._cert
+            sender_certs = self._cert
         else:
             # certificate is in sign (--sign_path file), it is key-cert-together.pem
-            sender_cert = sign
+            sender_certs = sign
 
         try:
-            sender_cert = load_pem_x509_certificate(sender_cert)
+            sender_certs = load_pem_x509_certificates(sender_certs)
         except ValueError as e:
             logger.warning(f"Certificate not found: {e}")
+        if len(sender_certs) == 0:
+            raise ValueError("Certificate not found")
 
         # get senders private key for signing
         try:
@@ -1333,7 +1358,10 @@ class Envelope:
 
         # sign the message first
         signature_builder = pkcs7.PKCS7SignatureBuilder().set_data(email)
-        signature_builder = signature_builder.add_signer(sender_cert, sender_key, hash_algorithm=hashes.SHA256())
+        signature_builder = signature_builder.add_signer(sender_certs[0], sender_key, hash_algorithm=hashes.SHA256())
+        # add the whole certificate chain
+        for cert in sender_certs[1:]:
+            signature_builder = signature_builder.add_certificate(cert)
         signed_email = signature_builder.sign(serialization.Encoding.SMIME, [pkcs7.PKCS7Options.DetachedSignature])
 
         # get recipent's certificate for encryption
@@ -1370,7 +1398,7 @@ class Envelope:
 
     def smime_encrypt_only(self, email, encrypt):
 
-        _, pkcs7, load_pem_x509_certificate, _, serialization = self._import_cryptoraphy_modules()
+        _, pkcs7, _, load_pem_x509_certificate, _, serialization = self._import_cryptoraphy_modules()
 
         if self._cert:
             certificates = [self._cert]
@@ -1716,6 +1744,11 @@ class Envelope:
             passed *= bool(self._smtp.connect())  # check SMTP
         return passed
 
+    def _check_auth(self):
+        """ Experimental. """
+        # NOTE Do not know how to map in API. Because .check() seems to be for sending and this one for receiving.
+        return AuthResult.from_headers(self._headers)
+
     def smtp_quit(self=None):
         """ Explicitly closes cached SMTP connections. Either class or instance can be called.
         Envelope.smtp_quit() → closing all

{envelope-2.2.0 → envelope-2.3.0}/envelope/smtp_handler.py

@@ -33,6 +33,8 @@ class SMTPHandler:
         d = locals()
         del d["self"]
         self.key = repr(d)
+        d["password"] = "********"
+        self.obfuscated_key = repr(d)
 
     def connect(self):
         if self.instance:  # we received this instance as is so we suppose it is already connected
@@ -55,13 +57,13 @@ class SMTPHandler:
                     smtp.login(self.user, self.password)
                 except SMTPAuthenticationError as e:
                     logger.error(
-                        f"SMTP authentication failed: {self.key}.\n{e}")
+                        f"SMTP authentication failed: {self.obfuscated_key}.\n{e}")
                     return False
         except SMTPException as e:
-            logger.error(f"SMTP connection failed: {self.key}.\n{e}")
+            logger.error(f"SMTP connection failed: {self.obfuscated_key}.\n{e}")
             return False
         except (gaierror, ConnectionError):
-            logger.error(f"SMTP connection refused: {self.key}.")
+            logger.error(f"SMTP connection refused: {self.obfuscated_key}.")
             return False
         return smtp
 

{envelope-2.2.0 → envelope-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "envelope"
-version = "2.2.0"
+version = "2.3.0"
 description = "Insert a message and attachments and send e-mail / sign / encrypt contents by a single line."
 authors = ["Edvard Rejthar <edvard.rejthar@nic.cz>"]
 license = "LGPL-3.0-or-later"