emailsec.auth

  1from enum import Enum
  2from dataclasses import dataclass
  3
  4from emailsec.spf.checker import check_spf, SPFCheck, SPFResult
  5from emailsec.dkim.checker import check_dkim, DKIMCheck, DKIMResult
  6from emailsec.dmarc import (
  7    check_dmarc,
  8    DMARCPolicy,
  9    DMARCResult,
 10)
 11from emailsec.arc import check_arc, ARCCheck
 12import emailsec.utils
 13from emailsec import errors
 14
 15
 16class DeliveryAction(Enum):
 17    ACCEPT = "accept"
 18    QUARANTINE = "quarantine"
 19    REJECT = "reject"
 20    DEFER = "defer"  # SMTP server should return 451 4.3.0 Temporary lookup failure
 21
 22
 23@dataclass
 24class SMTPContext:
 25    # Connection info
 26    sender_ip_address: str
 27    client_hostname: str | None  # EHLO/HELO hostname
 28
 29    # Envelope data
 30    mail_from: str  # MAIL FROM address (envelope sender)
 31
 32    # TOOD: timestamp to check for expired signature?
 33
 34
 35@dataclass
 36class AuthenticationConfiguration:
 37    trusted_signers: list[str] | None = None
 38
 39
 40def make_delivery_decision(
 41    spf_check: SPFCheck,
 42    dkim_check: DKIMCheck,
 43    arc_check: ARCCheck,
 44    dmarc_result: DMARCResult,
 45) -> DeliveryAction:
 46    """
 47    Delivery decision logic following RFC 7489.
 48
 49    1. DMARC policy is enforced first (if the sender has one)
 50    2. If DMARC passes → Accept
 51    3. If no DMARC or policy is "none" → Check individual authentications
 52    4. Default to quarantine for unauthenticated mail
 53
 54    RFC 7489: "DMARC-compliant Mail Receivers typically disregard any
 55    mail-handling directive discovered as part of an authentication mechanism
 56    where a DMARC record is also discovered that specifies a policy other than 'none'"
 57
 58    RFC 7489 warns against rejecting on SPF fail before checking DMARC,
 59    as this could prevent legitimate mail that passes DKIM+DMARC.
 60    """
 61    # Defer the delivery decision if SPF or DKIM failed with a temp error
 62    if (
 63        spf_check.result == SPFResult.TEMPERROR
 64        or dkim_check.result == DKIMResult.TEMPFAIL
 65    ):
 66        return DeliveryAction.DEFER
 67
 68    # DMARC policy takes precedence (RFC 7489 Section 6.3)
 69    if dmarc_result.result == "fail":
 70        match dmarc_result.policy:
 71            case DMARCPolicy.REJECT:
 72                # RFC 7489: "the Mail Receiver SHOULD reject the message"
 73                return DeliveryAction.REJECT
 74            case DMARCPolicy.QUARANTINE:
 75                # RFC 7489: "the Mail Receiver SHOULD place the message in
 76                # a quarantine area or folder instead of delivering it"
 77                return DeliveryAction.QUARANTINE
 78            case DMARCPolicy.NONE:
 79                # RFC 7489: "the Domain Owner requests no specific action
 80                # be taken regarding delivery of the message"
 81                pass  # Continue to fallback logic
 82
 83    # If DMARC passes, accept
 84    if dmarc_result.result == "pass":
 85        return DeliveryAction.ACCEPT
 86
 87    # Fallback logic when DMARC is not available or policy is "none"
 88    # RFC 7489: "Final disposition of a message is always a matter of local policy"
 89
 90    # Accept if any DKIM signature passes
 91    if dkim_check.result == DKIMResult.SUCCESS:
 92        return DeliveryAction.ACCEPT
 93
 94    # Accept if SPF passes
 95    if spf_check.result == SPFResult.PASS:
 96        return DeliveryAction.ACCEPT
 97
 98    # TODO: if no DMARC policy (or none), look for a trusted ARC to fallback to accept
 99
100    # Conservative default for unauthenticated mail
101    return DeliveryAction.QUARANTINE
102
103
104@dataclass
105class AuthenticationResult:
106    delivery_action: DeliveryAction
107    spf_check: SPFCheck
108    dkim_check: DKIMCheck
109    dmarc_result: DMARCResult | None
110    arc_check: ARCCheck
111
112
113async def authenticate_message(
114    smtp_context: SMTPContext,
115    raw_email: bytes,
116    configuration: AuthenticationConfiguration | None = None,
117) -> AuthenticationResult:
118    """
119    Authenticate an incoming email using SPF, DKIM, and DMARC.
120
121    Authentication flow:
122    1. SPF (RFC 7208): Verify the sending IP is authorized for the envelope sender domain
123    2. DKIM (RFC 6376): Verify cryptographic signatures on the email
124    3. ARC (RFC 8617): Check authentication chain if present (for forwarded mail)
125    4. DMARC (RFC 7489): Evaluate if SPF/DKIM align with the From header domain
126    5. Make delivery decision based on combined results
127    """
128    body_and_headers = emailsec.utils.body_and_headers_for_canonicalization(raw_email)
129    header_from = emailsec.utils.header_value(body_and_headers[1], "from")
130
131    # Step 1: SPF Check (RFC 7208)
132    # RFC 7489: SPF authenticates the envelope sender domain
133    spf_check = await check_spf(
134        smtp_context.sender_ip_address,
135        smtp_context.mail_from,
136    )
137
138    # Step 2: DKIM Verification (RFC 6376)
139    # Performed independently of SPF per RFC 7489 Section 4.3
140    dkim_check = await check_dkim(raw_email)
141
142    # Step 3: ARC Processing (RFC 8617) - if ARC headers present
143    # RFC 8617 Section 7.2: "allows Internet Mail Handler to potentially base
144    # decisions of message disposition on authentication assessments"
145    arc_check = await check_arc(raw_email, body_and_headers)
146
147    # Step 4: DMARC Evaluation (RFC 7489)
148    # RFC 7489: "A message satisfies the DMARC checks if at least one of the
149    # supported authentication mechanisms produces a 'pass' result"
150    try:
151        dmarc_result = await check_dmarc(
152            header_from=header_from,
153            envelope_from=smtp_context.mail_from,
154            spf_check=spf_check,
155            dkim_check=dkim_check,
156            arc_check=arc_check,
157            configuration=configuration,
158        )
159    except errors.Temperror:
160        return AuthenticationResult(
161            delivery_action=DeliveryAction.DEFER,
162            spf_check=spf_check,
163            dkim_check=dkim_check,
164            dmarc_result=None,
165            arc_check=arc_check,
166        )
167
168    # Step 5: Make delivery decision
169    # RFC 7489: "Final disposition of a message is always a matter of local policy"
170    return AuthenticationResult(
171        delivery_action=make_delivery_decision(
172            spf_check, dkim_check, arc_check, dmarc_result
173        ),
174        spf_check=spf_check,
175        dkim_check=dkim_check,
176        dmarc_result=dmarc_result,
177        arc_check=arc_check,
178    )