mailauth 7.2.0 → 7.3.0

package/lib/dkim2/key.js

@@ -0,0 +1,203 @@
+'use strict';
+
+// DKIM2 public key lookup (draft-ietf-dkim-dkim2-dns-00 section 3.4 and
+// draft-ietf-dkim-dkim2-spec-06 section 11.5). The records are DKIM1 key records, read with
+// the DKIM2 rules: one TXT record per selector, the retired h=, n= and s= tags ignored, and
+// only the rsa and ed25519 key types.
+
+const { Buffer } = require('node:buffer');
+const crypto = require('node:crypto');
+const dns = require('node:dns').promises;
+const { parseTagList, toALabel, isValidDnsName, isBareRsaPublicKey } = require('../tools');
+const { isBase64 } = require('./fields');
+
+const MIN_RSA_KEY_SIZE = 1024;
+// Verifiers MUST handle 1024 to 2048 bits and MAY handle more (section 3.2). Longer keys are not used
+// in practice and only make verification slower
+const MAX_RSA_KEY_SIZE = 8192;
+// section 3.2: "The signing algorithm MUST use a public exponent of 65537"
+const RSA_EXPONENT = 65537n;
+
+// DNS answers that mean there is no record. Anything else could be transient
+const NO_RECORD_CODES = new Set(['ENOTFOUND', 'ENODATA']);
+
+// the key type of each signing algorithm (section 8.9: the k= value has to match the algorithm)
+const ALGORITHM_KEY_TYPES = new Map([
+    ['rsa-sha256', 'rsa'],
+    ['ed25519-sha256', 'ed25519']
+]);
+
+// Section 3.2: why an RSA key can not be used, or null when it can
+const rsaKeyProblem = keyObject => {
+    let details = keyObject.asymmetricKeyDetails;
+    if (details.modulusLength < MIN_RSA_KEY_SIZE) {
+        return 'is too short';
+    }
+    if (details.modulusLength > MAX_RSA_KEY_SIZE) {
+        return 'is too long';
+    }
+    if (details.publicExponent !== RSA_EXPONENT) {
+        return 'has an unsupported exponent';
+    }
+    return null;
+};
+
+// Sections 3.2 and 3.3: the hash name and the data for crypto.sign() and crypto.verify(). RSA
+// PKCS#1 v1.5 hashes the input itself, Ed25519 (PureEdDSA) signs the SHA-256 hash of it
+const signatureData = (algorithm, input) => (algorithm === 'ed25519-sha256' ? [null, crypto.createHash('sha256').update(input).digest()] : ['sha256', input]);
+
+// RFC 8410 SubjectPublicKeyInfo prefix for a raw 32 byte Ed25519 key
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+class KeyError extends Error {
+    /**
+     * @param {String} result "permerror" or "temperror"
+     * @param {String} message The end of the section 11.5 error string, after "public key <selector>"
+     * @param {String} [rr] The key record
+     */
+    constructor(result, message, rr) {
+        super(message);
+        this.result = result;
+        if (rr) {
+            this.rr = rr;
+        }
+    }
+}
+
+const permerror = (reason, rr) => new KeyError('permerror', reason, rr);
+
+/**
+ * Fetches and parses the key record of a selector
+ *
+ * @param {String} name Key record name, "selector._domainkey.domain"
+ * @param {Function} resolver DNS resolver
+ * @returns {Object} { publicKey: KeyObject, keyType, modulusLength, testing, rr }
+ * @throws {KeyError}
+ */
+const fetchKey = async (name, resolver) => {
+    let lookupName = toALabel(name);
+    if (!isValidDnsName(lookupName)) {
+        throw permerror('does not exist');
+    }
+
+    let list;
+    try {
+        list = await resolver(lookupName, 'TXT');
+    } catch (err) {
+        // section 11.5: a timeout is a TEMPERROR, an absent key a PERMERROR
+        if (NO_RECORD_CODES.has(err.code)) {
+            throw permerror('does not exist');
+        }
+        throw new KeyError('temperror', 'could not be fetched');
+    }
+
+    if (!Array.isArray(list) || !list.length) {
+        throw permerror('does not exist');
+    }
+
+    if (list.length > 1) {
+        // draft-ietf-dkim-dkim2-dns-00 section 3.4.2.2, an error per section 11.5
+        throw permerror('has multiple records');
+    }
+
+    // the strings of a TXT record are joined with no whitespace between them
+    let rr = [].concat(list[0]).join('');
+
+    let entry = parseTagList(rr, { strict: true });
+    let tags = entry.parsed;
+    if (entry.syntaxErrors.length) {
+        throw permerror('has a syntax error', rr);
+    }
+
+    // v= is optional, but when present it is "DKIM1" and the first tag. A record with any other
+    // version is discarded
+    if (tags.v && (tags.v.value !== 'DKIM1' || entry.tags[0].name !== 'v')) {
+        throw permerror('has a syntax error', rr);
+    }
+
+    if (!tags.p) {
+        // p= is required
+        throw permerror('has a syntax error', rr);
+    }
+
+    if (!tags.p.value) {
+        // an empty p= means the key has been revoked
+        throw permerror('has been revoked', rr);
+    }
+
+    if (!isBase64(tags.p.value)) {
+        throw permerror('has a syntax error', rr);
+    }
+
+    // k= defaults to "rsa". Unknown key types are ignored, so they never match an algorithm
+    let keyType = tags.k ? tags.k.value : 'rsa';
+    if (!['rsa', 'ed25519'].includes(keyType)) {
+        return { publicKey: null, keyType, rr };
+    }
+
+    let rawKey = Buffer.from(tags.p.value, 'base64');
+    let publicKey;
+    try {
+        if (keyType === 'ed25519') {
+            // RFC 8463 section 4: the bare 32 byte key
+            if (rawKey.length !== 32) {
+                throw new Error('Invalid Ed25519 key length');
+            }
+            publicKey = crypto.createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, rawKey]), format: 'der', type: 'spki' });
+        } else {
+            // an RSAPublicKey, or the SubjectPublicKeyInfo that is published in practice
+            publicKey = crypto.createPublicKey({ key: rawKey, format: 'der', type: isBareRsaPublicKey(rawKey) ? 'pkcs1' : 'spki' });
+        }
+    } catch (err) {
+        throw permerror('has a syntax error', rr);
+    }
+
+    if (publicKey.asymmetricKeyType !== keyType) {
+        throw permerror('has a syntax error', rr);
+    }
+
+    let modulusLength;
+    if (keyType === 'rsa') {
+        modulusLength = publicKey.asymmetricKeyDetails.modulusLength;
+        let problem = rsaKeyProblem(publicKey);
+        if (problem) {
+            throw permerror(problem, rr);
+        }
+    }
+
+    // t= flags. Only "y" means anything to DKIM2, "s" is about the DKIM1 i= tag
+    let flags = String(tags.t?.value || '')
+        .split(':')
+        .map(flag => flag.trim());
+
+    return { publicKey, keyType, modulusLength, testing: flags.includes('y'), rr };
+};
+
+/**
+ * Creates a key lookup for one message, so that every signature naming the same key record
+ * shares one DNS query
+ *
+ * @param {Function} [resolver] DNS resolver, defaults to dns.promises.resolve
+ * @returns {Function} async (domain, selector, algorithm) => key info, throws KeyError
+ */
+const createKeyLookup = resolver => {
+    resolver = resolver || dns.resolve;
+    let cache = new Map();
+
+    return async (domain, selector, algorithm) => {
+        let name = `${selector}._domainkey.${domain}`;
+        if (!cache.has(name)) {
+            let lookup = fetchKey(name, resolver);
+            lookup.catch(() => false);
+            cache.set(name, lookup);
+        }
+
+        let key = await cache.get(name);
+        if (key.keyType !== ALGORITHM_KEY_TYPES.get(algorithm)) {
+            throw permerror('algorithm mismatch', key.rr);
+        }
+        return key;
+    };
+};
+
+module.exports = { createKeyLookup, KeyError, ALGORITHM_KEY_TYPES, rsaKeyProblem, signatureData };

package/lib/dkim2/message-state.js

@@ -0,0 +1,181 @@
+'use strict';
+
+// One instance of a message as DKIM2 hashes it: the hashed header fields grouped by name, and
+// the body. Applying the Recipe of a Message-Instance gives the previous instance
+// (draft-ietf-dkim-dkim2-spec-06 sections 5, 6 and 11)
+
+const { Buffer } = require('node:buffer');
+const crypto = require('node:crypto');
+const { SimpleHash } = require('../dkim/body/simple');
+const { isHashedField, canonicalHeaderField } = require('./fields');
+const { applySteps } = require('./recipe');
+
+// how much body text is handed to the hash at a time when a body is hashed from its lines
+const HASH_CHUNK_SIZE = 64 * 1024;
+
+// "d" values are JSON strings, the message is handled as 'binary' strings of its bytes
+const utf8ToBinary = value => Buffer.from(value, 'utf8').toString('binary');
+
+/**
+ * Splits a body into lines numbered top down (section 5.2), without the line terminators
+ *
+ * @param {Buffer} body Message body with CRLF line endings
+ * @returns {String[]} Lines as 'binary' strings
+ */
+const splitBodyLines = body => {
+    let str = body.toString('binary');
+    if (!str) {
+        return [];
+    }
+    let lines = str.split('\r\n');
+    if (str.endsWith('\r\n')) {
+        // the terminator of the last line, not an empty line after it
+        lines.pop();
+    }
+    return lines;
+};
+
+// Section 6.1: the body hash of a list of lines, each ending with CRLF
+const hashBodyLines = (lines, algorithm) => {
+    let hasher = new SimpleHash(algorithm);
+    let chunk = '';
+    for (let line of lines) {
+        chunk += line + '\r\n';
+        if (chunk.length >= HASH_CHUNK_SIZE) {
+            hasher.update(Buffer.from(chunk, 'binary'));
+            chunk = '';
+        }
+    }
+    if (chunk) {
+        hasher.update(Buffer.from(chunk, 'binary'));
+    }
+    return hasher.digest('base64');
+};
+
+class MessageState {
+    /**
+     * @param {Map} headers Lower case field name to the canonicalized fields, numbered bottom up
+     * @param {Object|null} body { lines, hashes } where `lines` may be null when the body was not
+     *        kept and `hashes` is a Map of algorithm to base64 hash. null for a body that can not
+     *        be recreated (a null body Recipe)
+     */
+    constructor(headers, body) {
+        this.headers = headers;
+        this.body = body;
+        this.headerHashes = new Map();
+    }
+
+    /**
+     * Builds the state of the message as it is
+     *
+     * @param {Object[]} parsedHeaders Rows from parseHeaders(), top down
+     * @param {Object} body { lines, hashes }
+     * @returns {MessageState}
+     */
+    static fromMessage(parsedHeaders, body) {
+        let headers = new Map();
+        for (let i = parsedHeaders.length - 1; i >= 0; i--) {
+            let row = parsedHeaders[i];
+            if (!isHashedField(row.key)) {
+                continue;
+            }
+            if (!headers.has(row.key)) {
+                headers.set(row.key, []);
+            }
+            headers.get(row.key).push(canonicalHeaderField(row.line));
+        }
+        return new MessageState(headers, body);
+    }
+
+    // Section 6.2: the fields in alphabetical order of their names, fields with the same name
+    // from the bottom up
+    headerHash(algorithm) {
+        if (!this.headerHashes.has(algorithm)) {
+            let hash = crypto.createHash(algorithm);
+            for (let name of Array.from(this.headers.keys()).sort()) {
+                for (let line of this.headers.get(name)) {
+                    hash.update(line);
+                }
+            }
+            this.headerHashes.set(algorithm, hash.digest('base64'));
+        }
+        return this.headerHashes.get(algorithm);
+    }
+
+    // the body hash, or null when the body of this instance can not be recreated
+    bodyHash(algorithm) {
+        if (!this.body) {
+            return null;
+        }
+        if (!this.body.hashes.has(algorithm)) {
+            this.body.hashes.set(algorithm, hashBodyLines(this.body.lines, algorithm));
+        }
+        return this.body.hashes.get(algorithm);
+    }
+
+    /**
+     * Applies a Recipe to get the previous instance of the message
+     *
+     * @param {Object} recipe Parsed Recipe ({ h: Map, b })
+     * @returns {MessageState}
+     * @throws {Error} When the Recipe does not fit this instance
+     */
+    previous(recipe) {
+        let headers = new Map(this.headers);
+        for (let [name, steps] of recipe.h) {
+            // section 5.1: Recipes SHOULD NOT name the fields that are not signed, and the
+            // hash does not see them anyway
+            if (!isHashedField(name)) {
+                continue;
+            }
+            let fields = applySteps(this.headers.get(name) || [], steps, value => canonicalHeaderField(Buffer.from(`${name}:${value}`, 'utf8')));
+            headers.set(name, fields);
+        }
+
+        let body = this.body;
+        if (recipe.b === null || (Array.isArray(recipe.b) && !body)) {
+            // the previous body can not be recreated, or it was built from one that can not
+            body = null;
+        } else if (Array.isArray(recipe.b)) {
+            if (!body.lines) {
+                throw new Error('The message body was not kept for the body Recipe');
+            }
+            body = { lines: applySteps(body.lines, recipe.b, utf8ToBinary), hashes: new Map() };
+        }
+
+        return new MessageState(headers, body);
+    }
+
+    /**
+     * Whether `later` only added header fields to this instance and kept the body, which is what a
+     * donotmodify request allows (section 8.10)
+     *
+     * @param {MessageState} later A later instance of the message
+     * @param {String} algorithm Hash algorithm for comparing the bodies
+     * @returns {Boolean}
+     */
+    isPreservedIn(later, algorithm) {
+        let bodyHash = this.bodyHash(algorithm);
+        if (!bodyHash || bodyHash !== later.bodyHash(algorithm)) {
+            return false;
+        }
+
+        for (let [name, fields] of this.headers) {
+            // every field of this instance is still there, in the same order
+            let laterFields = later.headers.get(name) || [];
+            let pos = 0;
+            for (let field of fields) {
+                while (pos < laterFields.length && !laterFields[pos].equals(field)) {
+                    pos++;
+                }
+                if (pos >= laterFields.length) {
+                    return false;
+                }
+                pos++;
+            }
+        }
+        return true;
+    }
+}
+
+module.exports = { MessageState, splitBodyLines };

package/lib/dkim2/recipe.js

@@ -0,0 +1,134 @@
+'use strict';
+
+// DKIM2 Recipes (draft-ietf-dkim-dkim2-spec-06 section 5): JSON instructions in the r= tag of a
+// Message-Instance header field that recreate the previous instance of the message from the
+// current one. This module validates a Recipe and applies it to a message state.
+
+// RFC 5322 field-name, the keys of the "h" object
+const FIELD_NAME = /^[\x21-\x39\x3b-\x7e]+$/;
+
+const isPlainObject = value => !!value && typeof value === 'object' && !Array.isArray(value);
+const own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+
+// Validates the steps of a header or body Recipe. Every step is an object with exactly one of
+// "c" (copy a range) or "d" (literal data). Other keys are ignored, as section 2 requires for
+// unrecognised JSON fields, although the schema of section 5 does not allow them
+const validateSteps = (steps, label) => {
+    if (!Array.isArray(steps)) {
+        return `${label} is not an array`;
+    }
+
+    let lastEnd = 0;
+    for (let step of steps) {
+        if (!isPlainObject(step) || own(step, 'c') === own(step, 'd')) {
+            return `${label} has a step that is not a "c" or a "d" step`;
+        }
+
+        if (own(step, 'c')) {
+            let range = step.c;
+            if (!Array.isArray(range) || range.length !== 2 || !range.every(value => Number.isSafeInteger(value) && value >= 1)) {
+                return `${label} has an invalid "c" range`;
+            }
+            // the start of every "c" step is after the end of all the earlier ones
+            if (range[0] > range[1] || range[0] <= lastEnd) {
+                return `${label} has "c" ranges out of order`;
+            }
+            lastEnd = range[1];
+        } else {
+            let data = step.d;
+            if (!Array.isArray(data) || !data.length || !data.every(value => typeof value === 'string' && !/[\r\n]/.test(value))) {
+                return `${label} has an invalid "d" step`;
+            }
+        }
+    }
+
+    return null;
+};
+
+/**
+ * Parses and validates the JSON of a Recipe
+ *
+ * @param {String} json Decoded r= value
+ * @returns {Object} { value, error }. `value.h` is a Map of lower case header field name to its
+ *          steps, `value.b` is the body steps, null for a body that can not be recreated, or
+ *          undefined when the body did not change
+ */
+const parseRecipe = json => {
+    let recipe;
+    try {
+        recipe = JSON.parse(json);
+    } catch (err) {
+        return { error: 'not valid JSON' };
+    }
+
+    if (!isPlainObject(recipe)) {
+        return { error: 'not a JSON object' };
+    }
+
+    if (!own(recipe, 'h') && !own(recipe, 'b')) {
+        return { error: 'neither "h" nor "b" is present' };
+    }
+
+    let value = { h: new Map(), b: undefined };
+
+    if (own(recipe, 'h')) {
+        if (!isPlainObject(recipe.h) || !Object.keys(recipe.h).length) {
+            return { error: '"h" is not an object with header field names' };
+        }
+        for (let name of Object.keys(recipe.h)) {
+            // section 5.1: header field names in the JSON keys MUST be in lower case
+            if (!FIELD_NAME.test(name) || name !== name.toLowerCase()) {
+                return { error: `invalid header field name ${JSON.stringify(name)}` };
+            }
+            let error = validateSteps(recipe.h[name], `"h" Recipe for ${name}`);
+            if (error) {
+                return { error };
+            }
+            value.h.set(name, recipe.h[name]);
+        }
+    }
+
+    if (own(recipe, 'b')) {
+        if (recipe.b !== null) {
+            let error = validateSteps(recipe.b, '"b" Recipe');
+            if (error) {
+                return { error };
+            }
+        }
+        value.b = recipe.b;
+    }
+
+    return { value };
+};
+
+/**
+ * Runs the steps of a Recipe against a list of items: header fields of one name numbered
+ * bottom up, or body lines numbered top down. The output keeps the same direction
+ *
+ * @param {Array} items Current items
+ * @param {Object[]} steps Validated Recipe steps
+ * @param {Function} fromData Converts a "d" string to an item
+ * @returns {Array} Items of the previous instance
+ * @throws {Error} When a "c" range goes past the last item
+ */
+const applySteps = (items, steps, fromData) => {
+    let output = [];
+    for (let step of steps) {
+        if (step.c) {
+            let [start, end] = step.c;
+            if (end > items.length) {
+                throw new Error(`"c" range ${start}-${end} is past the last of ${items.length}`);
+            }
+            for (let pos = start - 1; pos < end; pos++) {
+                output.push(items[pos]);
+            }
+        } else {
+            for (let data of step.d) {
+                output.push(fromData(data));
+            }
+        }
+    }
+    return output;
+};
+
+module.exports = { parseRecipe, applySteps };

package/lib/dkim2/sign.d.ts

@@ -0,0 +1,3 @@
+// Type definitions for mailauth/lib/dkim2/sign
+
+export { dkim2Sign, Dkim2SignStream } from '../../index';

package/lib/dkim2/sign.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { writeToStream } = require('../tools');
+const { DkimSignStream, formatSignatures } = require('../dkim/sign');
+const { Dkim2Signer } = require('./dkim2-signer');
+
+/**
+ * Signs a message with DKIM2: adds a DKIM2-Signature header field and, when needed, a
+ * Message-Instance header field (draft-ietf-dkim-dkim2-spec-06 section 9)
+ *
+ * @param {ReadableStream|Buffer|String} input RFC 5322 message
+ * @param {Object} options Signing options, see README
+ * @returns {Object} { signatures, signature, messageInstance, i, m }. `signatures` holds the
+ *          header lines to prepend to the message, each ending with CRLF
+ * @throws {Error} For invalid options, an invalid DKIM2 chain on the message, or a recipe that
+ *         does not recreate the previous instance
+ */
+const dkim2Sign = async (input, options) => {
+    let signer = new Dkim2Signer(options);
+    await writeToStream(signer, input);
+
+    return {
+        signatures: formatSignatures(signer.signatureHeaders),
+        signature: signer.signatureHeaders[0],
+        messageInstance: signer.signatureHeaders[1] || null,
+        i: signer.i,
+        m: signer.m
+    };
+};
+
+// Transform stream that outputs the message with the DKIM2 header fields on top
+class Dkim2SignStream extends DkimSignStream {
+    createSigner(options) {
+        return new Dkim2Signer(options);
+    }
+}
+
+module.exports = { dkim2Sign, Dkim2SignStream };

package/lib/dkim2/verify.d.ts

@@ -0,0 +1,3 @@
+// Type definitions for mailauth/lib/dkim2/verify
+
+export { dkim2Verify } from '../../index';

package/lib/dkim2/verify.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { writeToStream } = require('../tools');
+const { Dkim2Verifier } = require('./dkim2-verifier');
+
+/**
+ * Verifies the DKIM2 header fields of a message (draft-ietf-dkim-dkim2-spec-06 section 11)
+ *
+ * @param {ReadableStream|Buffer|String} input RFC 5322 message
+ * @param {Object} [options] Verification options, see Dkim2Verifier
+ * @returns {Object} Verification result, see docs/dkim2.md
+ */
+const dkim2Verify = async (input, options) => {
+    let verifier = new Dkim2Verifier(options);
+    await writeToStream(verifier, input);
+    return verifier.result;
+};
+
+module.exports = { dkim2Verify };

package/lib/mailauth.js

@@ -2,6 +2,9 @@
 
 const { dkimSign, DkimSignStream } = require('./dkim/sign');
 const { dkimVerify } = require('./dkim/verify');
+const { dkim2Sign, Dkim2SignStream } = require('./dkim2/sign');
+const { dkim2Verify } = require('./dkim2/verify');
+const { dkim2Hash } = require('./dkim2/hash');
 const { spf } = require('./spf');
 const { dmarc, evaluateDmarc } = require('./dmarc');
 const { arc, createSeal, sealMessage, getARChain, verifyASChain } = require('./arc');
@@ -9,6 +12,7 @@ const { bimi, validateVMC: validateBimiVmc } = require('./bimi');
 const { validateSvg: validateBimiSvg } = require('./bimi/validate-svg');
 const { parseReceived, getClientAddress, getClientHelo } = require('./parse-received');
 const { formatDomain, getAlignment, formatAuthservId } = require('./tools');
+const { buffer: readStream } = require('node:stream/consumers');
 const libmime = require('libmime');
 const os = require('node:os');
 const { isIP } = require('net');
@@ -33,6 +37,9 @@ const { isIP } = require('net');
  * @param {Boolean} [opts.disableDmarc=false] If true then do not perform DMARC check
  * @param {Boolean} [opts.disableBimi=false] If true then do not perform BIMI check
  * @param {Boolean} [opts.strict=false] If true then every check follows its RFC exactly instead of the lenient defaults
+ * @param {Boolean} [opts.dkim2=false] If true then DKIM2 header fields are verified as well (draft-ietf-dkim-dkim2-spec-06)
+ * @param {String|String[]} [opts.rcptTo] RCPT TO addresses of the delivery, checked against the DKIM2 chain of custody
+ * @param {Object} [opts.dkim2Options] Extra options for the DKIM2 verifier (maxSignatureAge, maxFutureTime, maxInstances, checkReplay, curTime)
  * @returns Authentication result
  */
 const authenticate = async (input, opts) => {
@@ -45,6 +52,11 @@ const authenticate = async (input, opts) => {
     // quoted, or throws under strict, before any work is done
     const authservId = formatAuthservId(opts.mta, opts.strict);
 
+    if (opts.dkim2 && typeof input?.on === 'function') {
+        // DKIM2 reads the message a second time, so a stream is read into memory first
+        input = await readStream(input);
+    }
+
     const dkimResult = await dkimVerify(input, {
         resolver: opts.resolver,
         sender: opts.sender, // defaults to Return-Path header
@@ -97,7 +109,24 @@ const authenticate = async (input, opts) => {
         opts.helo = `[${opts.helo}]`;
     }
 
+    // DKIM2 runs alongside SPF. The delivery is compared with the highest DKIM2-Signature only
+    // when it is known
+    const dkim2Verification =
+        opts.dkim2 &&
+        dkim2Verify(
+            input,
+            Object.assign({}, opts.dkim2Options, {
+                resolver: opts.resolver,
+                mailFrom: typeof opts.sender === 'string' ? opts.sender : undefined,
+                rcptTo: opts.rcptTo
+            })
+        );
+    // a rejection is handled by the await below, this keeps it from being reported as unhandled
+    // while SPF runs
+    dkim2Verification?.catch?.(() => false);
+
     const spfResult = await spf(opts);
+    const dkim2Result = await dkim2Verification;
 
     let arcResult;
     if (!opts.disableArc) {
@@ -118,6 +147,12 @@ const authenticate = async (input, opts) => {
         arHeader.push(`${libmime.foldLines(row.info, 160)}`);
     });
 
+    if (dkim2Result?.info) {
+        // draft-gondwana-dkim2-authres-00: the method is not registered yet. DKIM2 results do not
+        // take part in DMARC, that is an open question (draft-ietf-dkim-dkim2-bcp-01 section 7.2)
+        arHeader.push(libmime.foldLines(dkim2Result.info, 160));
+    }
+
     if (spfResult) {
         arHeader.push(libmime.foldLines(spfResult.info, 160));
         receivedSpfHeader = spfResult.header;
@@ -237,6 +272,7 @@ const authenticate = async (input, opts) => {
 
     const result = {
         dkim: dkimResult,
+        dkim2: dkim2Result || false,
         spf: spfResult,
         dmarc: dmarcResult || false,
         arc: arcResult || false,
@@ -260,6 +296,10 @@ module.exports = {
     dkimSign,
     DkimSignStream,
     dkimVerify,
+    dkim2Sign,
+    Dkim2SignStream,
+    dkim2Verify,
+    dkim2Hash,
     spf,
     dmarc,
     arc,

package/lib/tools.js

@@ -1357,6 +1357,7 @@ module.exports = {
     addWarning,
     KEY_ERROR_COMMENTS,
     isValidDnsName,
+    isBareRsaPublicKey,
 
     defaultDKIMFieldNames,
     defaultARCFieldNames,