PowerMTA DKIM Signature Failures

DKIM Verification Failure: What It Means

A DKIM verification failure (dkim=fail in Authentication-Results headers) means the receiving MTA retrieved the public key from DNS and found that the DKIM-Signature header in the message does not match. This always indicates either: (1) the message was modified in transit after signing, (2) the private key used for signing does not match the public key in DNS, or (3) the signature was computed over headers that were subsequently rewritten.

Verification failures are more damaging than missing signatures. A missing signature (dkim=none) indicates the sender has not implemented DKIM. A failure (dkim=fail) indicates the sender implemented DKIM incorrectly or the message was modified — which raises the suspicion that the message may have been tampered with.

Diagnosing DKIM Failures

# Step 1: Check if DNS public key matches your private key
# Extract the fingerprint of your private key
openssl rsa -in /etc/pmta/dkim/yourdomain.private -pubout 2>/dev/null | \
  openssl dgst -sha256
# Compare against the fingerprint of the key in DNS

# Retrieve public key from DNS and extract:
dig TXT s1._domainkey.yourdomain.com | \
  awk '{match($0,/p=([^"]+)/,a); print a[1]}' | \
  base64 -d | openssl dgst -sha256

# If fingerprints differ → key mismatch (most common failure cause)

# Step 2: Test DKIM verification manually
# Send a test message to check@dkimvalidator.com
# Or use: https://mxtoolbox.com/dkim.aspx

# Step 3: Check Authentication-Results in a received test message
# Gmail received header shows:
# dkim=fail header.i=@yourdomain.com header.s=s1 header.b=AbCdEf
# The header.b value is the first 8 chars of the signature

Common DKIM Failure Causes and Fixes

PowerMTA DKIM Signing Verification

# Verify PowerMTA is correctly reading and using the DKIM key
pmta check-dkim --domain=yourdomain.com --selector=s1
# Output: DKIM key OK — 2048 bits, selector=s1

# Check PowerMTA log for DKIM signing errors
grep -i "dkim\|signing" /var/log/pmta/pmta.log | tail -20

# Test signing with a live message
# Send a message to a Gmail account and check raw headers:
# DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yourdomain.com;
#   s=s1; h=From:To:Subject:Date:Message-ID; bh=....; b=....
# The 'b=' value is the actual signature — if present, signing is working

Header Canonicalization and Modification Issues

DKIM allows two canonicalization methods for headers: 'simple' (strict, no modifications allowed) and 'relaxed' (allows whitespace normalization and header folding). Use relaxed/relaxed canonicalization in PowerMTA — most mailing list software, CRM platforms, and mail relays that touch messages in transit will rewrite headers in ways that break simple canonicalization.

# Correct PowerMTA DKIM configuration — relaxed canonicalization

    smtp-source-host 185.x.x.10 mail1.yourdomain.com
    dkim-sign domain="yourdomain.com" \
              key-file="/etc/pmta/dkim/yourdomain.private" \
              selector="s1" \
              header-list="From:To:Subject:Date:Message-ID:Content-Type:MIME-Version" \
              # canonicalization defaults to relaxed/relaxed — correct


# Do NOT include headers that are frequently rewritten:
# DO NOT sign: Received, Return-Path, X-* custom headers
# CAUTION: Reply-To (may be rewritten by some ESPs)

Debugging DKIM Failures Systematically

DKIM failure debugging sequence: (1) Verify DNS TXT record is live: dig TXT s1._domainkey.yourdomain.com. (2) Verify private key fingerprint matches DNS public key. (3) Check PowerMTA log for signing errors at startup. (4) Send test message and inspect Authentication-Results header — the header.b field shows the first 8 chars of the signature for cross-reference. (5) If dkim=fail with body hash mismatch, check for intermediary modification of signed headers.

Accounting Log Analysis for This Configuration

Monitor this configuration area through the PowerMTA accounting log's dsnDiag field. Filter accounting records for the specific ISP domains affected by this configuration and group dsnDiag responses by first 60 characters to identify the dominant error patterns. A deferral rate above 5% at any single ISP warrants investigation; above 15% requires immediate volume reduction and configuration review.

The dlvSourceIp field in the accounting log enables per-IP analysis within this configuration context. Comparing per-IP deferral rates identifies whether a configuration issue affects all IPs in a pool uniformly (configuration problem) or just specific IPs (reputation or IP-specific problem). This distinction determines the correct remediation path.

Calibrating to Your Current Environment

The parameter values documented in this reference are appropriate for established, warmed IPs with HIGH reputation at the target ISP. New or warming IPs, and IPs with MEDIUM or LOW reputation, require more conservative values. Move up incrementally as reputation signals confirm the infrastructure can sustain additional throughput. Review ISP-specific configuration monthly — Postmaster Tools reputation tier changes and SNDS status changes are the primary triggers.

Production Deployment Summary

Implementing this PowerMTA configuration correctly in production requires testing the specific parameter values against your actual IP reputation history, ISP distribution, and sending volume. The values documented here represent proven starting points, not fixed constants — your optimal configuration may differ based on your infrastructure's operational history.

After applying any configuration change, monitor the accounting log for the first 2-4 hours to verify the change produced the expected effect on deferral rates. A configuration change that was expected to reduce deferrals but shows no change (or increased deferrals) indicates either: the change addressed the wrong variable, or there is a confounding factor that needs investigation before continuing.

The Cloud Server for Email infrastructure team manages PowerMTA environments daily, applying the configuration principles documented in this reference series across clients with varied volume levels, ISP distributions, and reputation histories. Contact us at infrastructure@cloudserverforemail.com for a technical assessment of your specific PowerMTA configuration requirements.