<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library\mail;
use seekquarry\yioop\configs as C;
/**
* Evaluates Sender Policy Framework (SPF, RFC 7208) records to decide
* whether a connecting client address is authorized to send mail for
* a domain. Given the connecting IP, the envelope-sender domain, and
* the HELO name, it fetches the domain's v=spf1 TXT record and walks
* its mechanisms, returning one of the standard SPF results.
*
* This implementation covers the mechanisms in everyday use: all,
* ip4, ip6, a, mx, include, and exists, the redirect= modifier, and
* the +, -, ~, and ? qualifiers. It enforces the RFC 7208 limit of
* ten DNS-querying mechanisms to bound work and prevent abuse,
* returning permerror when that limit is exceeded. Macro expansion
* beyond the common %{d}, %{s}, %{l}, %{o}, and %{i} forms is not
* performed; a record relying on uncommon macros may evaluate to
* permerror, which DMARC treats as a non-aligned result rather than
* a pass, so the failure is safe.
*
* Looked-up SPF records are cached through MailRecordCache so the
* same domain is not re-queried on every message.
*
* @author Chris Pollett
*/
class SpfCheck
{
/**
* The connecting client passed the domain's policy.
*/
const PASS = 'pass';
/**
* The policy explicitly disallows the client (-all reached, or a
* matched mechanism with a fail qualifier).
*/
const FAIL = 'fail';
/**
* The policy disallows the client only softly (~all).
*/
const SOFTFAIL = 'softfail';
/**
* The policy is neutral about the client (?all or no match).
*/
const NEUTRAL = 'neutral';
/**
* The domain publishes no SPF record.
*/
const NONE = 'none';
/**
* A DNS lookup failed temporarily; the check could be retried.
*/
const TEMPERROR = 'temperror';
/**
* The record could not be evaluated: malformed, too many DNS
* lookups, or relying on an unsupported construct.
*/
const PERMERROR = 'permerror';
/**
* Maximum number of DNS-querying mechanisms and modifiers a
* single evaluation may perform, per RFC 7208 4.6.4.
*/
const MAX_LOOKUPS = 10;
/**
* Evaluates SPF for a connecting client. Fetches the sender
* domain's policy and walks it, returning one of the result
* constants.
*
* @param string $ip the connecting client's IP address
* @param string $domain the envelope-sender domain (the part
* after @ in MAIL FROM, or the HELO name when MAIL FROM
* has an empty reverse path)
* @param string $helo the HELO/EHLO name the client gave, used
* to expand macros and as the sender for a null reverse
* path
* @return string one of the SpfCheck result constants
*/
public static function check($ip, $domain, $helo = '')
{
$ip = trim((string) $ip);
$domain = strtolower(trim((string) $domain));
if ($ip === '' || $domain === '') {
return self::NONE;
}
$client = self::parseIp($ip);
if ($client === null) {
return self::PERMERROR;
}
$lookups = 0;
return self::evaluateDomain($domain, $client, $domain,
(string) $helo, $lookups);
}
/**
* Fetches and evaluates the SPF record for one domain. Used for
* the initial domain and, recursively, for include and redirect
* targets. The sender and helo are carried through unchanged so
* macros expand against the original message; only the domain
* whose record is being read changes.
*
* @param string $domain domain whose v=spf1 record to evaluate
* @param array $client parsed connecting address from parseIp
* @param string $sender_domain original envelope-sender domain
* @param string $helo original HELO name
* @param int &$lookups running count of DNS-querying terms,
* shared across recursion to enforce the limit
* @return string one of the SpfCheck result constants
*/
private static function evaluateDomain($domain, $client,
$sender_domain, $helo, &$lookups)
{
$record = self::fetchSpfRecord($domain);
if ($record === null) {
return self::TEMPERROR;
}
if ($record === '') {
return self::NONE;
}
$terms = preg_split('/\s+/', trim($record));
$redirect = '';
foreach ($terms as $term) {
if ($term === '' || strtolower($term) === 'v=spf1') {
continue;
}
if (stripos($term, 'redirect=') === 0) {
$redirect = substr($term, strlen('redirect='));
continue;
}
if (stripos($term, 'exp=') === 0) {
continue;
}
$parsed = self::parseMechanism($term);
if ($parsed === null) {
return self::PERMERROR;
}
list($qualifier, $name, $value) = $parsed;
$matched = self::matchMechanism($name, $value, $client,
$domain, $sender_domain, $helo, $lookups);
if ($matched === self::PERMERROR ||
$matched === self::TEMPERROR) {
return $matched;
}
if ($matched === true) {
return self::qualifierResult($qualifier);
}
}
if ($redirect !== '') {
if ($lookups >= self::MAX_LOOKUPS) {
return self::PERMERROR;
}
$lookups++;
return self::evaluateDomain(strtolower($redirect),
$client, $sender_domain, $helo, $lookups);
}
return self::NEUTRAL;
}
/**
* Splits a mechanism term into its qualifier, name, and value.
* The qualifier is one of +, -, ~, ? and defaults to + when
* absent. The name is the lowercased mechanism word; the value
* is whatever followed a colon or slash, used by ip4, ip6, a,
* mx, include, and exists.
*
* @param string $term one whitespace-delimited SPF term
* @return array|null [qualifier, name, value], or null when the
* term is not a recognized mechanism
*/
private static function parseMechanism($term)
{
$qualifier = '+';
$first = substr($term, 0, 1);
if ($first === '+' || $first === '-' || $first === '~' ||
$first === '?') {
$qualifier = $first;
$term = substr($term, 1);
}
if ($term === '') {
return null;
}
$value = '';
$separator = strcspn($term, ':/=');
if ($separator < strlen($term)) {
$name = substr($term, 0, $separator);
$value = substr($term, $separator);
$lead = substr($value, 0, 1);
if ($lead === ':' || $lead === '=') {
/* The grammar uses ip4:1.2.3.4; some published
records mistakenly write ip4=1.2.3.4. Accept the
equals form for ip4/ip6 so a common typo does not
turn into a permerror, which would otherwise fail
an authorized sender. */
$value = substr($value, 1);
}
} else {
$name = $term;
}
$name = strtolower($name);
$known = ['all', 'ip4', 'ip6', 'a', 'mx', 'include',
'exists', 'ptr'];
if (!in_array($name, $known)) {
return null;
}
return [$qualifier, $name, $value];
}
/**
* Decides whether one mechanism matches the connecting client.
* DNS-querying mechanisms increment the shared lookup count and
* may return PERMERROR when the limit is hit or TEMPERROR on a
* failed query; non-matching mechanisms return false and
* matching ones return true.
*
* @param string $name mechanism name from parseMechanism
* @param string $value mechanism value from parseMechanism
* @param array $client parsed connecting address
* @param string $domain domain whose record is being evaluated
* @param string $sender_domain original envelope-sender domain
* @param string $helo original HELO name
* @param int &$lookups running DNS-lookup count
* @return bool|string true on match, false on no match, or a
* PERMERROR/TEMPERROR result constant on a lookup problem
*/
private static function matchMechanism($name, $value, $client,
$domain, $sender_domain, $helo, &$lookups)
{
if ($name === 'all') {
return true;
}
if ($name === 'ip4' || $name === 'ip6') {
return self::matchIpMechanism($name, $value, $client);
}
if ($name === 'ptr') {
/* ptr is deprecated and discouraged; treat as no match
rather than performing its reverse lookups. */
return false;
}
if ($lookups >= self::MAX_LOOKUPS) {
return self::PERMERROR;
}
$lookups++;
$target = ($value === '') ? $domain :
strtolower(self::expandMacros($value, $sender_domain,
$client, $helo));
if ($name === 'a') {
return self::matchAddressRecords($target, $client);
}
if ($name === 'mx') {
return self::matchMxRecords($target, $client, $lookups);
}
if ($name === 'include') {
$result = self::evaluateDomain($target, $client,
$sender_domain, $helo, $lookups);
if ($result === self::PASS) {
return true;
}
if ($result === self::TEMPERROR ||
$result === self::PERMERROR) {
return $result;
}
return false;
}
if ($name === 'exists') {
$records = AsyncDnsResolver::query($target,
AsyncDnsResolver::TYPE_A);
return !empty($records);
}
return false;
}
/**
* Matches an ip4 or ip6 mechanism: parses the value as an
* address with an optional CIDR prefix and tests whether the
* connecting client falls in that range and is of the same
* family.
*
* @param string $name 'ip4' or 'ip6'
* @param string $value address or address/prefix from the term
* @param array $client parsed connecting address
* @return bool whether the client is within the range
*/
private static function matchIpMechanism($name, $value, $client)
{
$prefix = null;
$slash = strpos($value, '/');
if ($slash !== false) {
$prefix = (int) substr($value, $slash + 1);
$value = substr($value, 0, $slash);
}
$family = ($name === 'ip4') ? 4 : 6;
$range = self::parseIp($value);
if ($range === null || $range['family'] !== $family ||
$client['family'] !== $family) {
return false;
}
if ($prefix === null) {
$prefix = ($family === 4) ? 32 : 128;
}
return self::inRange($client['packed'], $range['packed'],
$prefix, $family);
}
/**
* Matches an a mechanism by resolving the target's A and AAAA
* records and testing the client against each.
*
* @param string $target host name to resolve
* @param array $client parsed connecting address
* @return bool whether the client equals one of the addresses
*/
private static function matchAddressRecords($target, $client)
{
$type = ($client['family'] === 4) ? AsyncDnsResolver::TYPE_A :
AsyncDnsResolver::TYPE_AAAA;
$field = ($client['family'] === 4) ? 'ip' : 'ipv6';
$records = AsyncDnsResolver::query($target, $type);
if (empty($records)) {
return false;
}
foreach ($records as $record) {
$address = $record[$field] ?? '';
$parsed = self::parseIp($address);
if ($parsed !== null &&
$parsed['packed'] === $client['packed']) {
return true;
}
}
return false;
}
/**
* Matches an mx mechanism by resolving the target's MX hosts and
* then each host's address records. The MX resolution and each
* host resolution are bounded by the shared lookup count.
*
* @param string $target domain whose MX hosts to resolve
* @param array $client parsed connecting address
* @param int &$lookups running DNS-lookup count
* @return bool|string true on match, false on none, or a
* PERMERROR result when the lookup limit is exceeded
*/
private static function matchMxRecords($target, $client,
&$lookups)
{
$hosts = SmtpClient::resolveMxHosts($target);
foreach ($hosts as $host) {
if ($lookups >= self::MAX_LOOKUPS) {
return self::PERMERROR;
}
$lookups++;
if (self::matchAddressRecords($host, $client)) {
return true;
}
}
return false;
}
/**
* Fetches a domain's v=spf1 TXT record, using and populating the
* shared mail-record cache. Returns the record text when found,
* the empty string when the domain publishes none, or null on a
* DNS lookup failure (so the caller can report temperror).
*
* @param string $domain domain to read the SPF record for
* @return string|null the v=spf1 record, '' for none, or null
* on lookup failure
*/
private static function fetchSpfRecord($domain)
{
$cache = MailRecordCache::getInstance();
$cached = $cache->get(MailRecordCache::TYPE_SPF, $domain);
if ($cached !== null) {
return $cached;
}
$records = AsyncDnsResolver::query($domain,
AsyncDnsResolver::TYPE_TXT);
$record = '';
$time_to_live = 0;
foreach ($records as $entry) {
$text = trim((string) ($entry['txt'] ?? ''));
if (stripos($text, 'v=spf1') === 0) {
$record = $text;
$time_to_live = (int) ($entry['ttl'] ?? 0);
break;
}
}
$cache->put(MailRecordCache::TYPE_SPF, $domain, $record,
$time_to_live);
return $record;
}
/**
* Expands the common SPF macros in a mechanism value: %{d} the
* domain, %{s} the sender, %{l} the sender local part, %{o} the
* sender domain, and %{i} the client IP. Other macro letters are
* left untouched, which for an unsupported macro yields a target
* that will not resolve -- a safe non-match rather than a wrong
* pass.
*
* @param string $value mechanism value possibly containing
* macros
* @param string $sender_domain original envelope-sender domain
* @param array $client parsed connecting address
* @param string $helo original HELO name
* @return string the value with known macros expanded
*/
private static function expandMacros($value, $sender_domain,
$client, $helo)
{
if (strpos($value, '%') === false) {
return $value;
}
$local = 'postmaster';
$sender = $local . '@' . $sender_domain;
$replacements = ['%{d}' => $sender_domain,
'%{s}' => $sender, '%{l}' => $local,
'%{o}' => $sender_domain, '%{i}' => $client['display'],
'%{h}' => $helo, '%%' => '%', '%_' => ' '];
return strtr($value, $replacements);
}
/**
* Parses an IP address string into a family marker, its packed
* binary form for range tests, and a normalized display form.
* Returns null when the string is not a valid IPv4 or IPv6
* address.
*
* @param string $ip address text
* @return array|null ['family'=>4|6, 'packed'=>binary,
* 'display'=>string], or null when invalid
*/
private static function parseIp($ip)
{
$ip = trim($ip);
if ($ip === '') {
return null;
}
$packed = @inet_pton($ip);
if ($packed === false) {
return null;
}
$family = (strlen($packed) === 4) ? 4 : 6;
return ['family' => $family, 'packed' => $packed,
'display' => $ip];
}
/**
* Tests whether two packed addresses share their leading prefix
* bits, the comparison behind a CIDR range match.
*
* @param string $client packed client address
* @param string $range packed range base address
* @param int $prefix number of leading bits that must match
* @param int $family 4 or 6, to bound the prefix
* @return bool whether the client lies in the range
*/
private static function inRange($client, $range, $prefix,
$family)
{
$width = ($family === 4) ? 32 : 128;
if ($prefix < 0 || $prefix > $width) {
return false;
}
$whole = intdiv($prefix, 8);
if ($whole > 0 && strncmp($client, $range, $whole) !== 0) {
return false;
}
$bits = $prefix % 8;
if ($bits === 0) {
return true;
}
$mask = 0xff << (8 - $bits) & 0xff;
$client_byte = ord($client[$whole]);
$range_byte = ord($range[$whole]);
return ($client_byte & $mask) === ($range_byte & $mask);
}
/**
* Maps a matched mechanism's qualifier to its SPF result.
*
* @param string $qualifier one of +, -, ~, ?
* @return string the corresponding result constant
*/
private static function qualifierResult($qualifier)
{
if ($qualifier === '-') {
return self::FAIL;
}
if ($qualifier === '~') {
return self::SOFTFAIL;
}
if ($qualifier === '?') {
return self::NEUTRAL;
}
return self::PASS;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software