mailauth 7.1.0 → 7.2.0

package/lib/dkim/dkim-signer.js

@@ -14,7 +14,7 @@ const {
     createError,
     splitAlgorithm
 } = require('../../lib/tools');
-const { DOMAIN_NAME, SELECTOR, MAX_ARC_INSTANCE, ARC_HEADER_KEYS } = require('./syntax');
+const { DOMAIN_NAME, SELECTOR, LOCAL_PART, MAX_ARC_INSTANCE, ARC_HEADER_KEYS } = require('./syntax');
 const { MessageParser } = require('./message-parser');
 const { dkimBody } = require('./body');
 const { generateCanonicalizedHeader } = require('./header');
@@ -30,6 +30,9 @@ const MAX_TIMESTAMP = 999999999999;
 // RFC 8617 section 4.1.2: header fields an ARC-Message-Signature never covers
 const ARC_EXCLUDED_FIELDS = [...ARC_HEADER_KEYS, 'authentication-results'];
 
+// the header and body canonicalization algorithms of RFC 6376 section 3.4
+const CANONICALIZATIONS = ['simple', 'relaxed'];
+
 // RFC 8301 section 3.2: signers MUST use RSA keys of at least 1024 bits
 const MIN_RSA_KEY_SIZE = 1024;
 
@@ -78,7 +81,8 @@ class DkimSigner extends MessageParser {
         this.getARChain = getARChain;
         // decides the instance of an ARC set that has none set, from the message headers
         this.getArcInstance = getArcInstance;
-        if (this.arc.signingDomain && this.arc.selector && this.arc.privateKey) {
+        if (this.arc.signingDomain || this.arc.selector || this.arc.privateKey) {
+            // an incomplete set of values is reported by finalize() instead of being skipped
             this.signatureData.push({
                 type: 'ARC',
                 signingDomain: this.arc.signingDomain, // d=
@@ -111,11 +115,14 @@ class DkimSigner extends MessageParser {
         this.warn(warning);
     }
 
+    // The header and body canonicalization, and the c= value written for them. A value without
+    // a body part uses "simple" for the body (RFC 6376 section 3.5)
     getCanonicalization(signatureData) {
-        let canonicalization = signatureData?.canonicalization || this.canonicalization;
-        let headerCanon = canonicalization.split('/').shift().toLowerCase().trim();
-        let bodyCanon = (canonicalization.split('/')[1] || 'simple').toLowerCase().trim();
-        return { canonicalization, headerCanon, bodyCanon };
+        let [headerCanon, ...bodyParts] = (signatureData?.canonicalization || this.canonicalization).toString().split('/');
+        headerCanon = headerCanon.toLowerCase().trim();
+        // anything after a second slash stays in the body part, which then is not valid
+        let bodyCanon = (bodyParts.join('/') || 'simple').toLowerCase().trim();
+        return { canonicalization: `${headerCanon}/${bodyCanon}`, headerCanon, bodyCanon };
     }
 
     getAlgorithm(signatureData) {
@@ -139,6 +146,11 @@ class DkimSigner extends MessageParser {
             let { hashAlgo } = this.getAlgorithm(signatureData);
             let { bodyCanon } = this.getCanonicalization(signatureData);
 
+            if (!CANONICALIZATIONS.includes(bodyCanon)) {
+                // there is no body hash to calculate, finalize() reports the error
+                continue;
+            }
+
             let hashKey = `${bodyCanon}:${hashAlgo}:${signatureData.maxBodyLength}`;
 
             if (!this.bodyHashes.has(hashKey)) {
@@ -152,24 +164,15 @@ class DkimSigner extends MessageParser {
         }
     }
 
-    validateCanonicalization(canonicalization) {
-        try {
-            let [header, body] = canonicalization.split('/');
-
-            if (!['relaxed', 'simple'].includes(header)) {
-                let error = new Error('Unknown header canonicalization');
-                error.canonicalization = header;
-                throw error;
-            }
+    // Throws for a header or body canonicalization that is not known, takes the values
+    // getCanonicalization returns
+    validateCanonicalization({ headerCanon, bodyCanon }) {
+        if (!CANONICALIZATIONS.includes(headerCanon)) {
+            throw createError('Unknown header canonicalization', 'EINVALIDCANON', { canonicalization: headerCanon });
+        }
 
-            if (!['relaxed', 'simple'].includes(body)) {
-                let error = new Error('Unknown body canonicalization');
-                error.canonicalization = body;
-                throw error;
-            }
-        } catch (err) {
-            err.code = 'EINVALIDCANON';
-            throw err;
+        if (!CANONICALIZATIONS.includes(bodyCanon)) {
+            throw createError('Unknown body canonicalization', 'EINVALIDCANON', { canonicalization: bodyCanon });
         }
     }
 
@@ -213,6 +216,12 @@ class DkimSigner extends MessageParser {
             throw err;
         }
 
+        let localPart = identity.substring(0, atPos);
+        if ((localPart && !LOCAL_PART.test(localPart)) || !DOMAIN_NAME.test(domain)) {
+            // sig-i-tag = [ Local-part ] "@" domain-name
+            this.violation(`Invalid identity ${JSON.stringify(signatureData.identity)}`, 'EINVALIDIDENTITY', 'identity-syntax');
+        }
+
         if (!isSameOrSubdomain(domain, signatureData.signingDomain)) {
             // "The domain part of the address MUST be the same as, or a subdomain of, the value
             // of the d= tag", or every verifier ignores the signature
@@ -308,11 +317,15 @@ class DkimSigner extends MessageParser {
     }
 
     async finalize() {
-        for (let signatureData of this.signatureData || []) {
-            if (!signatureData.privateKey) {
-                continue;
-            }
+        if (!this.signatureData.length) {
+            // the signing domain, selector and key of a DKIM signature are read from the
+            // entries of signatureData only, so there is nothing to sign
+            this.errors.push({
+                err: createError('No signature configured, set signingDomain, selector and privateKey in signatureData', 'ENOSIGNATURE')
+            });
+        }
 
+        for (let signatureData of this.signatureData) {
             const pushError = (err, extra) => {
                 this.errors.push(
                     Object.assign(
@@ -327,6 +340,12 @@ class DkimSigner extends MessageParser {
                 );
             };
 
+            if (!signatureData.privateKey) {
+                // a key that was not loaded, for example from an unset environment variable
+                pushError(createError('Missing private key', 'ENOKEY'));
+                continue;
+            }
+
             let signingHeaderLines = getSigningHeaderLines(this.headers.parsed, this.getFieldNames(signatureData));
 
             if (!signingHeaderLines.headers.some(header => header.key === 'from')) {
@@ -363,11 +382,12 @@ class DkimSigner extends MessageParser {
             }
 
             let { algorithm, signAlgo, hashAlgo } = this.getAlgorithm(signatureData);
-            let { canonicalization, bodyCanon } = this.getCanonicalization(signatureData);
+            let canonParts = this.getCanonicalization(signatureData);
+            let { canonicalization, bodyCanon } = canonParts;
 
             try {
                 // throws if invalid
-                this.validateCanonicalization(canonicalization);
+                this.validateCanonicalization(canonParts);
             } catch (err) {
                 this.errors.push({
                     algorithm,
@@ -468,7 +488,7 @@ class DkimSigner extends MessageParser {
                         instance: signatureData.type === 'ARC' ? instance : false, // ARC only
                         identity, // DKIM only
                         algorithm,
-                        canonicalization: this.getCanonicalization(signatureData).canonicalization,
+                        canonicalization,
 
                         signTime: this.signTime,
                         expires: this.expires,

package/lib/dkim/dkim-verifier.js

@@ -8,28 +8,34 @@ const {
     getAlignment,
     getCurTime,
     toALabel,
+    isHostNameDomain,
     normalizeDomainName,
     isSameOrSubdomain,
     addWarning,
     KEY_ERROR_COMMENTS,
+    isValidDnsName,
     splitAlgorithm,
     isSupportedAlgorithm,
     createKeyCache
 } = require('../../lib/tools');
-const { DOMAIN_NAME, SELECTOR, TIMESTAMP, BODY_LENGTH } = require('./syntax');
+const { DOMAIN_NAME, SELECTOR, LOCAL_PART, TIMESTAMP, BODY_LENGTH } = require('./syntax');
 const { MessageParser } = require('./message-parser');
 const { dkimBody } = require('./body');
 const { generateCanonicalizedHeader } = require('./header');
-const { getARChain } = require('../arc');
+const { getARChain, getHighestArcInstance } = require('../arc');
 const addressparser = require('nodemailer/lib/addressparser');
+const { parseFromHeader, getAuthorDomain } = require('../dmarc/author-domain');
 const crypto = require('node:crypto');
 const libmime = require('libmime');
 
 // RFC 6376 section 3.5 syntax, used by the strict mode
 // sig-a-tag-alg = sig-a-tag-k "-" sig-a-tag-h, both ALPHA *(ALPHA / DIGIT)
 const ALGORITHM = /^[A-Za-z][A-Za-z0-9]*-[A-Za-z][A-Za-z0-9]*$/;
-// RFC 5322 dot-atom-text with the UTF-8 of RFC 6531, or a quoted-string, for the i= local-part
-const LOCAL_PART = /^(?:(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+(?:\.(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+)*|"(?:[^"\\\r\n]|\\.)*")$/;
+
+// sig-c-tag-alg is "simple", "relaxed" or a hyphenated-word, sig-c-tag one or two of them
+// separated by "/" (RFC 6376 section 3.5). An empty c= is not an omitted one (section 3.2)
+const C_TAG_ALG = '[A-Za-z](?:[A-Za-z0-9-]*[A-Za-z0-9])?';
+const CANONICALIZATION = new RegExp(`^${C_TAG_ALG}(?:/${C_TAG_ALG})?$`);
 
 // Required tags of a DKIM-Signature (RFC 6376 section 3.5)
 const REQUIRED_DKIM_TAGS = ['v', 'a', 'b', 'bh', 'd', 'h', 's'];
@@ -73,6 +79,10 @@ class DkimVerifier extends MessageParser {
 
         this.headerFrom = [];
         this.fromFields = 0;
+        // "valid", "lax" or "invalid", see parseFromHeader
+        this.fromSyntax = 'valid';
+        // the Author Domain result of getAuthorDomain, set when there is a From address
+        this.author = false;
         this.envelopeFrom = false;
 
         // ARC verification info, `warnings` lists what the lenient mode accepted in the chain
@@ -83,8 +93,9 @@ class DkimVerifier extends MessageParser {
         this.keyCache = createKeyCache(this.resolver);
         Object.defineProperty(this.arc, 'keyCache', { value: this.keyCache, enumerable: false, configurable: true, writable: true });
 
-        // should we also seal this message using ARC
-        this.seal = this.options.seal;
+        // should we also seal this message using ARC. A copy, so the body hash stored on it
+        // below never ends up on the caller's object, which may be shared by concurrent calls
+        this.seal = this.options.seal ? Object.assign({}, this.options.seal) : false;
 
         if (this.seal) {
             // calculate body hash for the seal
@@ -106,6 +117,9 @@ class DkimVerifier extends MessageParser {
         } catch (err) {
             this.arc.error = err;
         }
+        // the cv= of the newest ARC-Seal in the header fields, also when the chain could not be
+        // parsed. arc() uses it to decide whether a failed chain is sealed with cv=fail
+        this.arc.latestCv = getHighestArcInstance(headers).latestCv;
 
         this.signatureHeaders = headers.parsed
             .filter(h => h.key === 'dkim-signature')
@@ -125,19 +139,22 @@ class DkimVerifier extends MessageParser {
             if (splitterPos >= 0) {
                 fromHeader = fromHeader.substr(splitterPos + 1);
             }
-            let from = addressparser(fromHeader.trim());
-            for (let addr of from) {
-                // RFC 6854 allows a group in From, and the mailboxes of the group are authors
-                // like any other. Leaving them out would leave DMARC without an Author Domain
-                for (let mailbox of [].concat(addr?.group || addr || [])) {
-                    if (mailbox && mailbox.address) {
-                        // the full addr-spec, the domain is what follows its last "@"
-                        this.headerFrom.push(mailbox.address);
-                    }
-                }
+            // the full addr-specs, including the mailboxes of a group (RFC 6854). A general
+            // purpose address parser guesses at malformed input, which could hand DMARC a domain
+            // that is not the one a reader sees, so the RFC 5322 grammar is followed instead
+            let { addresses, syntax } = parseFromHeader(fromHeader);
+            this.headerFrom.push(...addresses);
+            if (syntax === 'invalid' || this.fromSyntax === 'valid') {
+                this.fromSyntax = syntax;
             }
         }
 
+        if (this.headerFrom.length) {
+            // the same Author Domain rules as the DMARC check: a From header field that does
+            // not yield a single Author Domain aligns with no signature
+            this.author = getAuthorDomain(this.headerFrom, this.fromFields, { fromSyntax: this.fromSyntax, strict: this.strict });
+        }
+
         if (this.options.sender) {
             let returnPath = addressparser(this.options.sender);
             this.envelopeFrom = returnPath.length && returnPath[0].address ? returnPath[0].address : false;
@@ -258,9 +275,12 @@ class DkimVerifier extends MessageParser {
         signatureHeader.algorithm = (parsed.a?.value || '').toString();
         Object.assign(signatureHeader, splitAlgorithm(signatureHeader.algorithm));
 
-        signatureHeader.canonicalization = (parsed.c?.value || '').toString();
-        signatureHeader.headerCanon = signatureHeader.canonicalization.split('/').shift().toLowerCase().trim() || 'simple';
-        signatureHeader.bodyCanon = getBodyCanon(signatureHeader.canonicalization);
+        let canonicalization = (parsed.c?.value || '').toString();
+        signatureHeader.headerCanon = canonicalization.split('/').shift().toLowerCase().trim() || 'simple';
+        signatureHeader.bodyCanon = getBodyCanon(canonicalization);
+        // the canonicalization as read here, for the header canonicalizer. The c= text itself
+        // can be malformed, "/relaxed" has no header part
+        signatureHeader.canonicalization = `${signatureHeader.headerCanon}/${signatureHeader.bodyCanon}`;
 
         signatureHeader.signingDomain = (parsed.d?.value || '').toString();
         signatureHeader.selector = (parsed.s?.value || '').toString();
@@ -331,12 +351,31 @@ class DkimVerifier extends MessageParser {
                 return;
             }
 
+            // the lenient mode reads a missing part as "simple" and ignores a third one
+            let canonError = parsed.c && !CANONICALIZATION.test((rawTags.get('c') || '').replace(/[ \t\r\n]+/g, ''));
+            if (canonError && violation('signature syntax error', 'tag-syntax')) {
+                return;
+            }
+
             // "This list MUST NOT be empty", the From check below covers the lenient mode
             if (parsed.h && !normalizeFieldList(parsed.h.value).length && violation('signature syntax error')) {
                 return;
             }
 
-            let invalidNames = !DOMAIN_NAME.test(toALabel(signatureHeader.signingDomain)) || !SELECTOR.test(toALabel(signatureHeader.selector));
+            // toALabel converts each label on its own, so these also make up the key record name
+            let signingDomainALabel = toALabel(signatureHeader.signingDomain);
+            let selectorALabel = toALabel(signatureHeader.selector);
+            if (!isHostNameDomain(signingDomainALabel)) {
+                signatureHeader.invalid = 'signature syntax error';
+                return;
+            }
+
+            // DOMAIN_NAME limits the length of each label, the key record name has to fit in
+            // the 253 octets of a DNS name as well
+            let invalidNames =
+                !DOMAIN_NAME.test(signingDomainALabel) ||
+                !SELECTOR.test(selectorALabel) ||
+                !isValidDnsName(`${selectorALabel}._domainkey.${signingDomainALabel}`);
             if (invalidNames && violation('signature syntax error', 'tag-syntax')) {
                 return;
             }
@@ -467,6 +506,7 @@ class DkimVerifier extends MessageParser {
      * @returns {Object} Signature result
      */
     async verifySignature(signatureHeader, fallback) {
+        // the canonicalization as prepareSignature() read it
         const canonicalization = fallback ? signatureHeader.fallbackCanonicalization : signatureHeader.canonicalization;
         const bodyHashKey = fallback ? signatureHeader.fallbackBodyHashKey : signatureHeader.bodyHashKey;
 
@@ -493,8 +533,8 @@ class DkimVerifier extends MessageParser {
             header: this.getStatusHeader(signatureHeader)
         };
 
-        if (signatureHeader.type === 'DKIM' && this.headerFrom?.length) {
-            status.aligned = getAlignment(this.headerFrom[0].split('@').pop(), [signatureHeader.signingDomain])?.domain || false;
+        if (signatureHeader.type === 'DKIM' && this.author) {
+            status.aligned = (this.author.authorDomain && getAlignment(this.author.authorDomain, [signatureHeader.signingDomain])?.domain) || false;
         }
 
         const bodyHasher = this.bodyHashes.get(bodyHashKey);
@@ -503,11 +543,22 @@ class DkimVerifier extends MessageParser {
 
         const warnings = [].concat(signatureHeader.warnings || []);
 
-        if (signatureHeader.invalid) {
+        // RFC 6376 section 3.5 l=: "This value MUST NOT be larger than the actual number of
+        // octets in the canonicalized message body"
+        let invalidBodyLength =
+            signatureHeader.type === 'DKIM' &&
+            typeof signatureHeader.maxBodyLength === 'number' &&
+            typeof bodyHasher?.canonicalizedLength === 'number' &&
+            signatureHeader.maxBodyLength > bodyHasher.canonicalizedLength;
+        if (invalidBodyLength && !this.strict) {
+            addWarning(warnings, 'tag-syntax');
+        }
+
+        if (signatureHeader.invalid || (invalidBodyLength && this.strict)) {
             // RFC 6376 section 6.1.1 PERMFAIL, reported as neutral, which RFC 8601 section
             // 2.7.1 uses for a signature with syntax errors. The key is not looked up
             status.result = 'neutral';
-            status.comment = signatureHeader.invalid;
+            status.comment = signatureHeader.invalid || 'signature syntax error';
         } else if (signatureHeader.parsed?.bh?.value !== bodyHash) {
             // RFC 6376 section 6.1.3 step 3 is a PERMFAIL, which RFC 8601 reports as "fail".
             // The lenient mode keeps reporting neutral, as it always has
@@ -542,9 +593,10 @@ class DkimVerifier extends MessageParser {
                 }
 
                 let keyError = false;
-                if (this.strict && res?.keyType && res.keyType !== signatureHeader.signAlgo) {
-                    // RFC 6376 section 6.1.2 step 8. The lenient mode lets the crypto library
-                    // report the mismatch, as it always has
+                if (res?.keyType && res.keyType !== signatureHeader.signAlgo) {
+                    // RFC 6376 section 6.1.2 step 8, in every mode. The crypto library does not
+                    // catch every mismatch: an RSA key verifies a PKCS#1 v1.5 signature over the
+                    // digest that an ed25519-sha256 signature is made over
                     keyError = 'inappropriate key algorithm';
                 } else if (
                     res?.flags?.includes('s') &&

package/lib/dkim/header/simple.js

@@ -1,10 +1,10 @@
 'use strict';
 
 const { Buffer } = require('node:buffer');
-const { stripSignatureValue } = require('../../../lib/tools');
+const { stripSignatureValue, toLineBytes } = require('../../../lib/tools');
 const { buildSignatureOpts } = require('./signature-opts');
 
-const formatSimpleLine = (line, suffix) => Buffer.from(line.toString('binary') + (suffix ? suffix : ''), 'binary');
+const formatSimpleLine = (line, suffix) => Buffer.concat([toLineBytes(line), Buffer.from(suffix ? suffix : '', 'binary')]);
 
 // generate headers for signing
 const simpleHeaders = (type, signingHeaderLines, options) => {

package/lib/dkim/syntax.js

@@ -13,6 +13,15 @@ const SELECTOR = new RegExp(`^${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})*$`);
 // sig-t-tag and sig-x-tag are 1*12DIGIT, sig-l-tag is 1*76DIGIT
 const TIMESTAMP = /^[0-9]{1,12}$/;
 const BODY_LENGTH = /^[0-9]{1,76}$/;
+// the Local-part of an i= value (RFC 6376 section 3.5): RFC 5322 dot-atom-text with the UTF-8
+// of RFC 6531, or a quoted-string
+const LOCAL_PART = /^(?:(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+(?:\.(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+)*|"(?:[^"\\\r\n]|\\.)*")$/;
+
+// The characters of a host name, after U-labels are converted to A-labels. A d= with anything
+// else (such as "/", "?", "#", "@" or ":") can not name the zone of its key record, so a
+// DKIM-Signature, ARC-Seal or ARC-Message-Signature with it is a syntax error in every mode
+// (RFC 6376 section 3.5)
+const HOST_NAME_CHARS = /^[A-Za-z0-9_.-]+$/;
 
 // RFC 8617 section 4.2.1: instance values range from 1 to 50
 const MAX_ARC_INSTANCE = 50;
@@ -24,6 +33,8 @@ module.exports = {
     DOMAIN_LABEL,
     DOMAIN_NAME,
     SELECTOR,
+    LOCAL_PART,
+    HOST_NAME_CHARS,
     TIMESTAMP,
     BODY_LENGTH,
     MAX_ARC_INSTANCE,

package/lib/dkim/verify.js

@@ -11,6 +11,7 @@ const dkimVerify = async (input, options) => {
         //headers: dkimVerifier.headers,
         headerFrom: dkimVerifier.headerFrom,
         fromFields: dkimVerifier.fromFields,
+        fromSyntax: dkimVerifier.fromSyntax,
         envelopeFrom: dkimVerifier.envelopeFrom,
         results: dkimVerifier.results
     };