mailauth 7.1.1 → 7.3.0

package/lib/commands/dkim2-sign.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { dkim2Sign } = require('../dkim2/sign');
+const { GathererStream } = require('../gatherer-stream');
+const fs = require('node:fs');
+
+const cmd = async argv => {
+    let source = argv.email;
+    let stream;
+
+    if (argv.verbose) {
+        console.error(`Reading email message from ${source || 'standard input'}`);
+    }
+
+    stream = source ? fs.createReadStream(source) : process.stdin;
+
+    let privateKeys = argv.privateKey || [];
+    let selectors = argv.selector || [];
+    if (privateKeys.length !== selectors.length) {
+        let err = new Error('Every --private-key needs a --selector, in the same order');
+        throw err;
+    }
+
+    let gatherer = new GathererStream({ gather: !argv.headersOnly });
+    stream.pipe(gatherer);
+    stream.on('error', err => gatherer.emit('error', err));
+
+    let signatureData = [];
+    for (let i = 0; i < privateKeys.length; i++) {
+        signatureData.push({ selector: selectors[i], privateKey: await fs.promises.readFile(privateKeys[i], 'utf-8') });
+    }
+
+    let options = {
+        signingDomain: argv.domain,
+        signatureData,
+        signTime: argv.time ? new Date(argv.time * 1000) : new Date(),
+        flags: argv.flag,
+        nonce: argv.nonce
+    };
+
+    if (argv.hash?.length) {
+        options.hashAlgorithms = argv.hash;
+    }
+
+    if (argv.nextDomain) {
+        options.nextDomain = argv.nextDomain;
+    } else {
+        options.mailFrom = argv.mailFrom;
+        options.rcptTo = argv.rcptTo;
+    }
+
+    if (argv.recipe) {
+        options.recipe = JSON.parse(await fs.promises.readFile(argv.recipe, 'utf-8'));
+    }
+
+    if (argv.verbose) {
+        console.error(`Signing domain: ${options.signingDomain}`);
+        console.error(`Selectors:      ${selectors.join(', ')}`);
+        console.error(`Signing time:   ${options.signTime.toISOString()}`);
+        console.error('--------');
+    }
+
+    let signResult = await dkim2Sign(gatherer, options);
+
+    process.stdout.write(signResult.signatures);
+    if (!argv.headersOnly) {
+        // print the full message as well
+        await new Promise((resolve, reject) => {
+            let msgStream = gatherer.replay();
+            msgStream.pipe(process.stdout, { end: false });
+            msgStream.on('end', resolve);
+            msgStream.on('error', reject);
+        });
+    }
+};
+
+module.exports = cmd;

package/lib/commands/dkim2-verify.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { dkim2Verify } = require('../dkim2/verify');
+const { createResolver } = require('./resolver');
+const fs = require('node:fs');
+
+const cmd = async argv => {
+    let source = argv.email;
+
+    if (argv.verbose) {
+        console.error(`Reading email message from ${source || 'standard input'}`);
+    }
+
+    let stream = source ? fs.createReadStream(source) : process.stdin;
+
+    let opts = {
+        resolver: await createResolver(argv),
+        rcptTo: argv.rcptTo
+    };
+
+    if (typeof argv.mailFrom === 'string') {
+        opts.mailFrom = argv.mailFrom;
+    }
+
+    if (typeof argv.time === 'number') {
+        opts.curTime = new Date(argv.time * 1000);
+    }
+
+    if (typeof argv.maxAge === 'number') {
+        // 0 turns the expiration check off
+        opts.maxSignatureAge = argv.maxAge || false;
+    }
+
+    if (typeof argv.maxFuture === 'number') {
+        // 0 turns the check off, like --max-age
+        opts.maxFutureTime = argv.maxFuture || false;
+    }
+
+    if (typeof argv.maxInstances === 'number') {
+        opts.maxInstances = argv.maxInstances;
+    }
+
+    let result = await dkim2Verify(stream, opts);
+
+    if (argv.verbose) {
+        for (let warning of result.status.warnings || []) {
+            console.error(`Warning: ${warning}`);
+        }
+    }
+
+    if (argv.headersOnly) {
+        process.stdout.write(result.info + '\n');
+        return;
+    }
+
+    process.stdout.write(JSON.stringify(result, false, 2) + '\n');
+};
+
+module.exports = cmd;

package/lib/commands/report.js

@@ -2,7 +2,7 @@
 
 const { authenticate } = require('../mailauth');
 const fs = require('node:fs');
-const { resolve } = require('node:dns').promises;
+const { createResolver } = require('./resolver');
 
 const cmd = async argv => {
     let source = argv.email;
@@ -27,18 +27,23 @@ const cmd = async argv => {
     const opts = {
         trustReceived: true,
         strict: !!argv.strict,
-        rejectRsaSha1: !!argv.rejectRsaSha1
+        rejectRsaSha1: !!argv.rejectRsaSha1,
+        dkim2: !!argv.dkim2
     };
 
+    if (argv.rcptTo) {
+        opts.rcptTo = argv.rcptTo;
+    }
+
     if (argv.clientIp) {
         opts.ip = argv.clientIp;
     }
 
-    if (argv.maxLookups) {
+    if (typeof argv.maxLookups === 'number') {
         opts.maxResolveCount = argv.maxLookups;
     }
 
-    if (argv.maxVoidLookups) {
+    if (typeof argv.maxVoidLookups === 'number') {
         opts.maxVoidCount = argv.maxVoidLookups;
     }
 
@@ -48,37 +53,7 @@ const cmd = async argv => {
         }
     }
 
-    if (argv.dnsCache) {
-        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
-
-        opts.resolver = async (name, rr) => {
-            let match = dnsCache?.[name]?.[rr];
-
-            if (argv.verbose) {
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
-            }
-
-            if (!match) {
-                let err = new Error('Error');
-                err.code = 'ENOTFOUND';
-                throw err;
-            }
-
-            return match;
-        };
-    } else if (argv.verbose) {
-        opts.resolver = async (name, rr) => {
-            let match;
-            try {
-                match = await resolve(name, rr);
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
-                return match;
-            } catch (err) {
-                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
-                throw err;
-            }
-        };
-    }
+    opts.resolver = await createResolver(argv);
 
     let result = await authenticate(stream, opts);
     process.stdout.write(JSON.stringify(result, false, 2) + '\n');

package/lib/commands/resolver.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('node:fs');
+const { resolve } = require('node:dns').promises;
+
+/**
+ * The DNS resolver for a command: answers from the --dns-cache file, or real DNS queries that are
+ * logged with --verbose. Undefined when neither is set, so the library uses its default resolver
+ *
+ * @param {Object} argv Command options
+ * @returns {Function|undefined} async (name, rrtype) resolver
+ */
+const createResolver = async argv => {
+    if (argv.dnsCache) {
+        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
+
+        return async (name, rr) => {
+            let match = dnsCache?.[name]?.[rr];
+
+            if (argv.verbose) {
+                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
+            }
+
+            if (!match) {
+                let err = new Error('Error');
+                err.code = 'ENOTFOUND';
+                throw err;
+            }
+
+            return match;
+        };
+    }
+
+    if (argv.verbose) {
+        return async (name, rr) => {
+            let match;
+            try {
+                match = await resolve(name, rr);
+                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
+                return match;
+            } catch (err) {
+                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
+                throw err;
+            }
+        };
+    }
+
+    return undefined;
+};
+
+module.exports = { createResolver };

package/lib/commands/seal.js

@@ -5,7 +5,7 @@ const { authenticate } = require('../mailauth');
 const { createSeal } = require('../arc');
 const fs = require('node:fs');
 const { GathererStream } = require('../gatherer-stream');
-const { resolve } = require('node:dns').promises;
+const { createResolver } = require('./resolver');
 
 const writeMessageBody = async gatherer =>
     new Promise((resolve, reject) => {
@@ -75,6 +75,9 @@ const cmd = async argv => {
     if (argv.authResults || argv.authResultsFile) {
         // Seal-only mode: embed the caller-provided Authentication-Results value without authenticating the message
         let authResults = argv.authResultsFile ? (await fs.promises.readFile(argv.authResultsFile, 'utf-8')).trim() : argv.authResults;
+        // a folded value from a file usually has LF line endings, header folding needs CRLF.
+        // createSeal refuses any line break that does not continue the header with whitespace
+        authResults = authResults.replace(/\r?\n/g, '\r\n');
 
         let sealOpts = Object.assign({}, signatureOpts, {
             authResults,
@@ -95,7 +98,7 @@ const cmd = async argv => {
             console.error('--------');
         }
 
-        let { headers, errors, warnings } = await createSeal(gatherer, { seal: sealOpts });
+        let { headers, errors, warnings, instance } = await createSeal(gatherer, { seal: sealOpts });
 
         if (!headers.length) {
             // nothing was sealed, say why instead of printing the message as if it had been
@@ -103,20 +106,19 @@ const cmd = async argv => {
             throw err;
         }
 
-        // createSeal writes the instance it actually used back into the seal options
-        if (sealOpts.i > 1 && !argv.cv) {
-            console.error(`warning: sealed with i=${sealOpts.i} and cv=none; a chain with i>1 only validates when cv=pass (use --cv pass)`);
+        if (instance > 1 && !argv.cv) {
+            console.error(`warning: sealed with i=${instance} and cv=none; a chain with i>1 only validates when cv=pass (use --cv pass)`);
         }
 
         for (let warning of warnings || []) {
             switch (warning) {
                 case 'arc-instance-gap':
-                    console.error(`warning: sealed with i=${sealOpts.i}, which does not follow the existing ARC chain`);
+                    console.error(`warning: sealed with i=${instance}, which does not follow the existing ARC chain`);
                     break;
                 case 'arc-cv-instance':
                     // covered by the message above for the default cv
                     if (argv.cv) {
-                        console.error(`warning: cv=${argv.cv} is not valid for i=${sealOpts.i} (i=1 takes cv=none, later sets take cv=pass or cv=fail)`);
+                        console.error(`warning: cv=${argv.cv} is not valid for i=${instance} (i=1 takes cv=none, later sets take cv=pass or cv=fail)`);
                     }
                     break;
                 default:
@@ -159,37 +161,7 @@ const cmd = async argv => {
         }
     }
 
-    if (argv.dnsCache) {
-        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
-
-        opts.resolver = async (name, rr) => {
-            let match = dnsCache?.[name]?.[rr];
-
-            if (argv.verbose) {
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
-            }
-
-            if (!match) {
-                let err = new Error('Error');
-                err.code = 'ENOTFOUND';
-                throw err;
-            }
-
-            return match;
-        };
-    } else if (argv.verbose) {
-        opts.resolver = async (name, rr) => {
-            let match;
-            try {
-                match = await resolve(name, rr);
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
-                return match;
-            } catch (err) {
-                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
-                throw err;
-            }
-        };
-    }
+    opts.resolver = await createResolver(argv);
 
     let result = await authenticate(gatherer, opts);
 

package/lib/commands/spf.js

@@ -1,8 +1,7 @@
 'use strict';
 
 const { spf } = require('../spf');
-const fs = require('node:fs');
-const { resolve } = require('node:dns').promises;
+const { createResolver } = require('./resolver');
 
 const cmd = async argv => {
     let address = argv.sender;
@@ -24,11 +23,11 @@ const cmd = async argv => {
         opts.ip = argv.clientIp;
     }
 
-    if (argv.maxLookups) {
+    if (typeof argv.maxLookups === 'number') {
         opts.maxResolveCount = argv.maxLookups;
     }
 
-    if (argv.maxVoidLookups) {
+    if (typeof argv.maxVoidLookups === 'number') {
         opts.maxVoidCount = argv.maxVoidLookups;
     }
 
@@ -46,37 +45,7 @@ const cmd = async argv => {
         }
     }
 
-    if (argv.dnsCache) {
-        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
-
-        opts.resolver = async (name, rr) => {
-            let match = dnsCache?.[name]?.[rr];
-
-            if (argv.verbose) {
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
-            }
-
-            if (!match) {
-                let err = new Error('Error');
-                err.code = 'ENOTFOUND';
-                throw err;
-            }
-
-            return match;
-        };
-    } else if (argv.verbose) {
-        opts.resolver = async (name, rr) => {
-            let match;
-            try {
-                match = await resolve(name, rr);
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
-                return match;
-            } catch (err) {
-                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
-                throw err;
-            }
-        };
-    }
+    opts.resolver = await createResolver(argv);
 
     let result;
     try {

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,