Mail: SMTP, SPF, DKIM and DMARC

// smtp.cs: a tiny receiving mail server and a sender in one program, to show the SMTP dialog,
// the envelope (MAIL FROM, RCPT TO) and the header (From, To) as two different things.
using System.Net;
using System.Net.Sockets;
using System.Text;

var listener = new TcpListener(IPAddress.Loopback, 0);
listener.Start();
var port = ((IPEndPoint)listener.LocalEndpoint).Port;
var server = ReceiveAsync(listener);

using (var client = new TcpClient())
{
    await client.ConnectAsync(IPAddress.Loopback, port);
    using var stream = client.GetStream();
    var reader = new StreamReader(stream, Encoding.ASCII);
    var writer = new StreamWriter(stream, Encoding.ASCII) { NewLine = "\r\n", AutoFlush = true };

    await ExpectAsync(reader);
    await SendAsync(writer, reader, "EHLO outbound.kladde.example");
    await SendAsync(writer, reader, "MAIL FROM:<bounces@kladde.example>");
    await SendAsync(writer, reader, "RCPT TO:<ada.berger@inbox.example>");
    await SendAsync(writer, reader, "DATA");
    foreach (var line in new[]
    {
        "From: Kladde <appointments@kladde.example>",
        "To: Ada Berger <ada.berger@inbox.example>",
        "Subject: Your appointment on Tuesday",
        "",
        "Hello Ms. Berger, please confirm your appointment.",
    })
    {
        await writer.WriteLineAsync(line);
        Console.WriteLine($"C: {line}".TrimEnd());
    }

    await SendAsync(writer, reader, ".");
    await SendAsync(writer, reader, "QUIT");
}

Console.WriteLine();
Console.WriteLine("What the receiver stored:");
Console.WriteLine(await server);

static async Task SendAsync(StreamWriter writer, StreamReader reader, string line)
{
    await writer.WriteLineAsync(line);
    Console.WriteLine($"C: {line}");
    await ExpectAsync(reader);
}

static async Task ExpectAsync(StreamReader reader)
{
    string? line;
    do
    {
        line = await reader.ReadLineAsync();
        Console.WriteLine($"S: {line}");
    }
    while (line is [_, _, _, '-', ..]); // "250-" means: more lines follow
}

// The receiving side: answers each command with a code and stores the message with what it learned from the envelope.
static async Task<string> ReceiveAsync(TcpListener listener)
{
    using var connection = await listener.AcceptTcpClientAsync();
    using var stream = connection.GetStream();
    var reader = new StreamReader(stream, Encoding.ASCII);
    var writer = new StreamWriter(stream, Encoding.ASCII) { NewLine = "\r\n", AutoFlush = true };
    string helo = "", mailFrom = "", rcptTo = "";
    var body = new StringBuilder();

    await writer.WriteLineAsync("220 mx.inbox.example ESMTP");
    while (await reader.ReadLineAsync() is { } command)
    {
        if (command.StartsWith("EHLO ", StringComparison.OrdinalIgnoreCase))
        {
            helo = command[5..];
            await writer.WriteLineAsync("250-mx.inbox.example");
            await writer.WriteLineAsync("250 SIZE 10485760");
        }
        else if (command.StartsWith("MAIL FROM:", StringComparison.OrdinalIgnoreCase))
        {
            mailFrom = command[10..];
            await writer.WriteLineAsync("250 2.1.0 Sender OK");
        }
        else if (command.StartsWith("RCPT TO:", StringComparison.OrdinalIgnoreCase))
        {
            rcptTo = command[8..];
            await writer.WriteLineAsync("250 2.1.5 Recipient OK");
        }
        else if (command == "DATA")
        {
            await writer.WriteLineAsync("354 Start mail input; end with <CRLF>.<CRLF>");
            while (await reader.ReadLineAsync() is { } line && line != ".")
            {
                body.AppendLine(line);
            }

            await writer.WriteLineAsync("250 2.0.0 OK queued as 7F3A");
        }
        else if (command == "QUIT")
        {
            await writer.WriteLineAsync("221 2.0.0 Bye");
            break;
        }
    }

    // A receiving server adds Return-Path (from MAIL FROM) and a Received line on top; it never changes the header below.
    return $"Return-Path: {mailFrom}\nReceived: from {helo} by mx.inbox.example for {rcptTo}\n{body}";
}

dotnet run smtp.cs

S: 220 mx.inbox.example ESMTP
C: EHLO outbound.kladde.example
S: 250-mx.inbox.example
S: 250 SIZE 10485760
C: MAIL FROM:<bounces@kladde.example>
S: 250 2.1.0 Sender OK
C: RCPT TO:<ada.berger@inbox.example>
S: 250 2.1.5 Recipient OK
C: DATA
S: 354 Start mail input; end with <CRLF>.<CRLF>
C: From: Kladde <appointments@kladde.example>
C: To: Ada Berger <ada.berger@inbox.example>
C: Subject: Your appointment on Tuesday
C:
C: Hello Ms. Berger, please confirm your appointment.
C: .
S: 250 2.0.0 OK queued as 7F3A
C: QUIT
S: 221 2.0.0 Bye

What the receiver stored:
Return-Path: <bounces@kladde.example>
Received: from outbound.kladde.example by mx.inbox.example for <ada.berger@inbox.example>
From: Kladde <appointments@kladde.example>
To: Ada Berger <ada.berger@inbox.example>
Subject: Your appointment on Tuesday

Hello Ms. Berger, please confirm your appointment.

Received: from mx.inbox.example (198.51.100.7) by mailbox.inbox.example
 with LMTP; Tue, 4 Mar 2025 09:14:05 +0000
Authentication-Results: mx.inbox.example;
 spf=pass (sender IP is 203.0.113.25) smtp.mailfrom=kladde.example;
 dkim=pass (signature was verified) header.d=kladde.example;
 dmarc=pass action=none header.from=kladde.example
Received: from out-12.outbound.example (203.0.113.25) by mx.inbox.example
 (198.51.100.7) with ESMTPS (TLS1_3); Tue, 4 Mar 2025 09:14:04 +0000
Received: from mailbox.outbound.example (2001:db8:12::7) by out-12.outbound.example
 with HTTPS; Tue, 4 Mar 2025 09:14:02 +0000
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kladde.example;
 s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version;
 bh=3q2+7w1Jx0e0ZfX7c0yYkq1mR9n0TqkZ7Wq3m0bC1hY=; b=Vb7tK2...
Return-Path: <appointments@kladde.example>
From: Kladde <appointments@kladde.example>
To: Ada Berger <ada.berger@inbox.example>
Subject: Your appointment on Tuesday
Date: Tue, 4 Mar 2025 09:14:01 +0000
Message-ID: <a1b2c3d4@kladde.example>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"

Hello Ms. Berger, ...

// headers.cs: reads the header of a mail saved as text and shows the way it took and what the receiving server checked.
// dotnet run headers.cs -- <file>
using System.Text.RegularExpressions;

var fields = new List<(string Name, string Value)>();
foreach (var line in File.ReadLines(args[0]))
{
    if (line.Length == 0)
    {
        break; // the header ends at the first empty line, the body follows
    }

    if (line[0] is ' ' or '\t' && fields.Count > 0)
    {
        fields[^1] = (fields[^1].Name, $"{fields[^1].Value} {line.Trim()}"); // a folded line continues the field above
    }
    else if (line.IndexOf(':') is > 0 and var colon)
    {
        fields.Add((line[..colon].Trim(), line[(colon + 1)..].Trim()));
    }
}

Console.WriteLine("Path of the mail, the first step is at the very bottom of the header:");
var step = 0;
foreach (var received in All("Received").Reverse())
{
    var hop = Find(received, @"(from (\S+)( \([^)]*\))? )?by (\S+)");
    var source = hop.Groups[2].Success ? hop.Groups[2].Value + hop.Groups[3].Value : "?";
    var time = received.Contains(';') ? received[(received.LastIndexOf(';') + 1)..].Trim() : "";
    Console.WriteLine($"  {++step}. {source} -> {hop.Groups[4].Value}, {time}");
}

// Only the topmost Authentication-Results comes from your own provider; lower ones may be the sender's own words.
var results = All("Authentication-Results").FirstOrDefault() ?? "";
var from = AfterAt(Find(All("From").FirstOrDefault() ?? "", @"@([^>\s]+)").Value);
var mailFrom = AfterAt(Find(results, @"smtp\.mailfrom=([^\s;]+)").Groups[1].Value);
var dkimDomain = AfterAt(Find(results, @"header\.[di]=([^\s;]+)").Groups[1].Value); // some providers write header.i=@domain
var selector = Find(All("DKIM-Signature").FirstOrDefault() ?? "", @"(^|;)\s*s=([^\s;]+)").Groups[2].Value;

Console.WriteLine($"Sender in the header (From):          {from}");
Console.WriteLine($"Sender in the envelope (Return-Path): {AfterAt(Find(All("Return-Path").FirstOrDefault() ?? "", @"@([^>\s]+)").Value)}");
Console.WriteLine($"SPF   {Result("spf"),-5} for {mailFrom,-18} {Aligned(mailFrom)}");
Console.WriteLine($"DKIM  {Result("dkim"),-5} for {dkimDomain,-18} {Aligned(dkimDomain)}, selector {selector}");
Console.WriteLine($"DMARC {Result("dmarc"),-5} {Find(results, @"dmarc=\w+([^;]*)").Groups[1].Value.Trim()}");

IEnumerable<string> All(string name) => fields.Where(f => f.Name.Equals(name, StringComparison.OrdinalIgnoreCase)).Select(f => f.Value);

string Result(string method) => Find(results, $@"\b{method}=(\w+)").Groups[1].Value;

// DMARC "relaxed": the same organizational domain, here simply the last two labels (the real rule uses the public suffix list).
string Aligned(string domain) => domain.Length == 0 ? "" : Organization(domain) == Organization(from) ? "matches From" : "doesn't match From";

static string Organization(string domain) => string.Join('.', domain.Split('.').TakeLast(2));

static string AfterAt(string value) => value[(value.LastIndexOf('@') + 1)..];

// A header is text from strangers: linear expressions only, so no input can make them run for long.
static Match Find(string text, string pattern) => Regex.Match(text, pattern, RegexOptions.NonBacktracking | RegexOptions.IgnoreCase);

dotnet run headers.cs -- appointment.txt

Path of the mail, the first step is at the very bottom of the header:
  1. mailbox.outbound.example (2001:db8:12::7) -> out-12.outbound.example, Tue, 4 Mar 2025 09:14:02 +0000
  2. out-12.outbound.example (203.0.113.25) -> mx.inbox.example, Tue, 4 Mar 2025 09:14:04 +0000
  3. mx.inbox.example (198.51.100.7) -> mailbox.inbox.example, Tue, 4 Mar 2025 09:14:05 +0000
Sender in the header (From):          kladde.example
Sender in the envelope (Return-Path): kladde.example
SPF   pass  for kladde.example     matches From
DKIM  pass  for kladde.example     matches From, selector selector1
DMARC pass  action=none header.from=kladde.example

kladde.example.  3600  TXT  "v=spf1 include:spf.protection.outlook.com -all"

// dkim.cs: DKIM in small. The sender signs a hash of the body and some header fields with its private key; the receiver
// checks them with the public key it reads from DNS. Simplified (no folded lines, only rsa-sha256), with the real "relaxed" rules.
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;

using var privateKey = RSA.Create(2 * 1024); // bits
var publicKey = Convert.ToBase64String(privateKey.ExportSubjectPublicKeyInfo());
var dns = new Dictionary<string, string> { ["selector1._domainkey.kladde.example"] = $"v=DKIM1; k=rsa; p={publicKey}" };
Console.WriteLine("TXT selector1._domainkey.kladde.example");
Console.WriteLine($"  v=DKIM1; k=rsa; p={publicKey[..32]}... ({publicKey.Length} characters)");

(string Name, string Value)[] header =
[
    ("From", "Kladde <appointments@kladde.example>"),
    ("To", "Ada Berger <ada.berger@inbox.example>"),
    ("Subject", "Your appointment on Tuesday"),
];
var body = "Hello Ms. Berger,\r\n\r\nYour appointment: Tuesday, 10:00.\r\n";

// The sender (Microsoft 365 for the Kladde) signs with the private key; the selector says where the public key is.
var unsigned = $"v=1; a=rsa-sha256; c=relaxed/relaxed; d=kladde.example; s=selector1; h=from:to:subject; bh={BodyHash(body)}; b=";
var signature = unsigned + Convert.ToBase64String(
    privateKey.SignData(Encoding.ASCII.GetBytes(SignedText(header, unsigned)), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1));
Console.WriteLine($"DKIM-Signature: {unsigned}... ({signature.Length - unsigned.Length} characters)");

Console.WriteLine("At the receiver:");
Check("unchanged", header, body);
Check("Trailing spaces", header, body.Replace("Berger,", "Berger,   "));
Check("Time in the text changed", header, body.Replace("10:00", "11:00"));
Check("Subject changed", [header[0], header[1], ("Subject", "Your appointment on Wednesday")], body);

void Check(string change, (string Name, string Value)[] received, string receivedBody) =>
    Console.WriteLine($"  {change,-26} {Verify(received, receivedBody, signature, dns)}");

// The receiver: compares the body hash, then checks the signature over the named header fields with the key from DNS.
static string Verify((string Name, string Value)[] header, string body, string signature, Dictionary<string, string> dns)
{
    var tags = Tags(signature);
    if (BodyHash(body) != tags["bh"])
    {
        return "dkim=fail (body hash did not verify)";
    }

    using var publicKey = RSA.Create();
    publicKey.ImportSubjectPublicKeyInfo(Convert.FromBase64String(Tags(dns[$"{tags["s"]}._domainkey.{tags["d"]}"])["p"]), out _);
    var signed = Encoding.ASCII.GetBytes(SignedText(header, signature[..(signature.LastIndexOf("; b=") + 4)]));
    var valid = publicKey.VerifyData(signed, Convert.FromBase64String(tags["b"]), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
    return valid ? $"dkim=pass header.d={tags["d"]}" : "dkim=fail (signature did not verify)";
}

// "relaxed" for the body: spaces at the end of a line go, runs of spaces become one, empty lines at the end go.
static string BodyHash(string body)
{
    var lines = body.Split("\r\n").Select(line => Regex.Replace(line, "[ \t]+", " ").TrimEnd()).ToList();
    while (lines.Count > 0 && lines[^1].Length == 0)
    {
        lines.RemoveAt(lines.Count - 1);
    }

    var canonical = lines.Count == 0 ? "" : string.Join("\r\n", lines) + "\r\n";
    return Convert.ToBase64String(SHA256.HashData(Encoding.UTF8.GetBytes(canonical)));
}

// What the signature covers: the fields named in h= ("relaxed": lower-case name, single spaces), then the DKIM-Signature field itself with an empty b=.
static string SignedText((string Name, string Value)[] header, string signatureWithoutB)
{
    var text = new StringBuilder();
    foreach (var name in Tags(signatureWithoutB)["h"].Split(':'))
    {
        var value = header.First(field => field.Name.Equals(name, StringComparison.OrdinalIgnoreCase)).Value;
        text.Append($"{name}:{Regex.Replace(value, "[ \t]+", " ").Trim()}\r\n");
    }

    return text.Append($"dkim-signature:{signatureWithoutB}").ToString();
}

static Dictionary<string, string> Tags(string record) => record.Split(';', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries)
    .ToDictionary(tag => tag[..tag.IndexOf('=')], tag => tag[(tag.IndexOf('=') + 1)..]);

dotnet run dkim.cs

TXT selector1._domainkey.kladde.example
  v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A... (392 characters)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kladde.example; s=selector1; h=from:to:subject; bh=nstiGZ5jYtrCiw33AYHBtK5mIMgIZMuxC46zt398ry4=; b=... (344 characters)
At the receiver:
  unchanged                  dkim=pass header.d=kladde.example
  Trailing spaces            dkim=pass header.d=kladde.example
  Time in the text changed   dkim=fail (body hash did not verify)
  Subject changed            dkim=fail (signature did not verify)

_dmarc.kladde.example.  3600  TXT  "v=DMARC1; p=quarantine; sp=reject; rua=mailto:dmarc-reports@kladde.example"

// dmarc.cs: decides like a receiving server whether a mail passes DMARC for the domain in its From field,
// and what that domain's policy asks for when it does not. Each case says what should come out.
var dns = new Dictionary<string, string>
{
    ["_dmarc.kladde.example"] = "v=DMARC1; p=quarantine; sp=reject; rua=mailto:dmarc-reports@kladde.example",
};

(string Name, string From, string MailFrom, string Spf, string DkimDomain, string Dkim, string Expected)[] cases =
[
    ("Confirmation from the mailbox", "kladde.example", "kladde.example", "pass", "kladde.example", "pass", "deliver"),
    ("forwarded, text unchanged", "kladde.example", "kladde.example", "fail", "kladde.example", "pass", "deliver"),
    ("forwarded, footer added", "kladde.example", "kladde.example", "fail", "kladde.example", "fail", "quarantine"),
    ("Newsletter service, not set up", "kladde.example", "mailer.example", "pass", "mailer.example", "pass", "quarantine"),
    ("Newsletter service on news.kladde.example", "news.kladde.example", "bounce.news.kladde.example", "pass", "news.kladde.example", "pass", "deliver"),
    ("Forgery, envelope uses its own domain", "kladde.example", "fraud.example", "pass", "", "none", "quarantine"),
    ("Forgery, invented subdomain", "invoice.kladde.example", "invoice.kladde.example", "none", "", "none", "reject"),
];

var failed = 0;
Console.WriteLine($"{"Case",-41} {"SPF",-12} {"DKIM",-12} {"DMARC",-6} Outcome");
foreach (var mail in cases)
{
    // The policy: the From domain's own record, else the organizational domain's, whose sp= then applies.
    var own = dns.TryGetValue($"_dmarc.{mail.From}", out var record);
    var policy = Tags(own ? record! : dns.GetValueOrDefault($"_dmarc.{Organization(mail.From)}", "v=DMARC1; p=none"));
    var applies = own ? policy["p"] : policy.GetValueOrDefault("sp", policy["p"]);

    // Passed means: SPF or DKIM passed AND its domain matches the From domain ("aligned").
    var spfAligned = mail.Spf == "pass" && Aligned(mail.MailFrom, mail.From, policy.GetValueOrDefault("aspf", "r"));
    var dkimAligned = mail.Dkim == "pass" && Aligned(mail.DkimDomain, mail.From, policy.GetValueOrDefault("adkim", "r"));
    var passed = spfAligned || dkimAligned;
    var outcome = passed || applies == "none" ? "deliver" : applies;

    var ok = outcome == mail.Expected;
    failed += ok ? 0 : 1;
    Console.WriteLine($"{mail.Name,-41} {Show(mail.Spf, spfAligned),-12} {Show(mail.Dkim, dkimAligned),-12} {(passed ? "pass" : "fail"),-6} " +
        $"{outcome}{(ok ? "" : $"  EXPECTED {mail.Expected}")}");
}

Console.WriteLine(failed == 0 ? "All cases as expected." : $"Cases that differ: {failed}.");
return failed == 0 ? 0 : 1;

// r (relaxed): the same organizational domain; s (strict): exactly the same name.
static bool Aligned(string domain, string from, string mode) =>
    mode == "s" ? domain == from : Organization(domain) == Organization(from);

// Simplified: the last two labels. The real rule uses the public suffix list, so that example.co.uk works too.
static string Organization(string domain) => string.Join('.', domain.Split('.').TakeLast(2));

static string Show(string result, bool aligned) => result == "pass" ? (aligned ? "pass, match" : "pass, other") : result;

static Dictionary<string, string> Tags(string record) => record.Split(';', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries)
    .ToDictionary(tag => tag[..tag.IndexOf('=')], tag => tag[(tag.IndexOf('=') + 1)..]);

dotnet run dmarc.cs

Case                                      SPF          DKIM         DMARC  Outcome
Confirmation from the mailbox             pass, match  pass, match  pass   deliver
forwarded, text unchanged                 fail         pass, match  pass   deliver
forwarded, footer added                   fail         fail         fail   quarantine
Newsletter service, not set up            pass, other  pass, other  fail   quarantine
Newsletter service on news.kladde.example pass, match  pass, match  pass   deliver
Forgery, envelope uses its own domain     pass, other  none         fail   quarantine
Forgery, invented subdomain               none         none         fail   reject
All cases as expected.