mailauth 6.0.0 → 7.0.0

package/lib/dkim/dkim-signer.js

@@ -6,28 +6,66 @@ const {
     defaultDKIMFieldNames,
     defaultARCFieldNames,
     validateAlgorithm,
-    getPrivateKey
+    getPrivateKey,
+    getCurTime,
+    toALabel,
+    isSameOrSubdomain,
+    addWarning,
+    createError,
+    splitAlgorithm
 } = require('../../lib/tools');
+const { DOMAIN_NAME, SELECTOR, MAX_ARC_INSTANCE, ARC_HEADER_KEYS } = require('./syntax');
 const { MessageParser } = require('./message-parser');
 const { dkimBody } = require('./body');
 const { generateCanonicalizedHeader } = require('./header');
 const crypto = require('node:crypto');
 
+// Characters that can never be in a tag value (RFC 6376 section 3.2): the semicolon ends the
+// tag, and whitespace, CR and LF would change the header itself. Anything that is not
+// printable ASCII once converted to an A-label is not a DNS name either
+const UNSAFE_TAG_VALUE = /[^\x21-\x3a\x3c-\x7e]/;
+// t= and x= are 1*12DIGIT (RFC 6376 section 3.5)
+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'];
+
+// RFC 8301 section 3.2: signers MUST use RSA keys of at least 1024 bits
+const MIN_RSA_KEY_SIZE = 1024;
+
+// Turns a header list option (a colon separated string or an array of names) into the
+// colon separated string getSigningHeaderLines expects, or false if there is none
+const normalizeHeaderList = headerList => {
+    if (Array.isArray(headerList)) {
+        headerList = headerList
+            .map(entry => (entry || '').toString().trim())
+            .filter(entry => entry)
+            .join(':');
+    }
+    return typeof headerList === 'string' && headerList.trim() ? headerList : false;
+};
+
 class DkimSigner extends MessageParser {
     constructor(options) {
         super();
 
-        let { canonicalization, algorithm, signTime, headerList, signatureData, arc, bodyHash, headers, getARChain, expires } = options || {};
+        let { canonicalization, algorithm, signTime, headerList, signatureData, arc, bodyHash, headers, getARChain, getArcInstance, expires, strict } =
+            options || {};
 
         this.algorithm = algorithm || false;
         this.canonicalization = canonicalization || 'relaxed/relaxed';
 
+        // follow RFC 6376 and RFC 8301 exactly instead of the lenient defaults
+        this.strict = !!strict;
+
         this.errors = [];
+        // what was signed although the strict mode would have refused it, as short codes
+        this.warnings = [];
 
         this.expires = expires;
         this.signTime = signTime;
 
-        this.headerList = headerList;
+        this.headerList = normalizeHeaderList(headerList);
 
         this.signatureData = [].concat(signatureData || []).map(entry => {
             entry.type = 'DKIM';
@@ -38,6 +76,8 @@ class DkimSigner extends MessageParser {
 
         this.arc = Object.assign({ chain: false }, arc);
         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) {
             this.signatureData.push({
                 type: 'ARC',
@@ -45,7 +85,8 @@ class DkimSigner extends MessageParser {
                 selector: this.arc.selector, // s=
                 privateKey: this.arc.privateKey,
                 canonicalization: 'relaxed/relaxed',
-                algorithm: 'rsa-sha256' // fixed for now, throws if non-rsa key is used
+                // rsa-sha256 or ed25519-sha256, follows the key type when not set
+                algorithm: this.arc.algorithm || false
             });
         }
 
@@ -58,6 +99,18 @@ class DkimSigner extends MessageParser {
         this.setupHashes();
     }
 
+    warn(warning) {
+        addWarning(this.warnings, warning);
+    }
+
+    // A rule the strict mode enforces: throws in the strict mode, notes the warning otherwise
+    violation(message, code, warning) {
+        if (this.strict) {
+            throw createError(message, code);
+        }
+        this.warn(warning);
+    }
+
     getCanonicalization(signatureData) {
         let canonicalization = signatureData?.canonicalization || this.canonicalization;
         let headerCanon = canonicalization.split('/').shift().toLowerCase().trim();
@@ -66,11 +119,12 @@ class DkimSigner extends MessageParser {
     }
 
     getAlgorithm(signatureData) {
-        let algorithm = (signatureData?.algorithm || this.algorithm || '').toLowerCase().trim();
-        let signAlgo = algorithm.split('-').shift().toLowerCase().trim() || false; // default is derived from key
-        let hashAlgo = algorithm.split('-').pop().toLowerCase().trim() || 'sha256';
+        // the shared algorithm option is for DKIM signatures, an ARC-Message-Signature has its own
+        let algorithm = (signatureData?.algorithm || (signatureData?.type === 'ARC' ? '' : this.algorithm) || '').toLowerCase().trim();
+        let { signAlgo, hashAlgo } = splitAlgorithm(algorithm);
 
-        return { algorithm, signAlgo, hashAlgo };
+        // the signing algorithm defaults to the key type
+        return { algorithm, signAlgo: signAlgo || false, hashAlgo: hashAlgo || 'sha256' };
     }
 
     setupHashes() {
@@ -119,15 +173,89 @@ class DkimSigner extends MessageParser {
         }
     }
 
+    // Validates the d= and s= values (RFC 6376 section 3.5) and returns them as A-labels.
+    // A value that would break out of its tag or out of the header is refused in every mode
+    validateSigningIdentifiers(signatureData) {
+        let checks = [
+            ['signingDomain', 'd=', DOMAIN_NAME, 'EINVALIDDOMAIN'],
+            ['selector', 's=', SELECTOR, 'EINVALIDSELECTOR']
+        ];
+
+        for (let [key, tag, format, code] of checks) {
+            let value = typeof signatureData[key] === 'string' ? signatureData[key].trim() : '';
+            let aLabel = toALabel(value);
+
+            if (!value || UNSAFE_TAG_VALUE.test(aLabel)) {
+                let err = new Error(value ? `Invalid ${tag} value ${JSON.stringify(signatureData[key])}` : `Missing ${tag} value`);
+                err.code = code;
+                throw err;
+            }
+
+            if (!format.test(aLabel)) {
+                this.violation(`Invalid ${tag} value ${JSON.stringify(signatureData[key])}`, code, key === 'signingDomain' ? 'd-syntax' : 's-syntax');
+            }
+        }
+    }
+
+    // The i= value of a DKIM-Signature, from the `identity` option (RFC 6376 section 3.5)
+    getIdentity(signatureData) {
+        if (signatureData.type !== 'DKIM' || !signatureData.identity) {
+            return false;
+        }
+
+        let identity = signatureData.identity.toString().trim();
+        let atPos = identity.lastIndexOf('@');
+        let domain = atPos >= 0 ? toALabel(identity.substring(atPos + 1)) : '';
+
+        if (atPos < 0 || !domain || /[\s;\x00-\x1f\x7f]/.test(identity)) {
+            let err = new Error(`Invalid identity ${JSON.stringify(signatureData.identity)}`);
+            err.code = 'EINVALIDIDENTITY';
+            throw err;
+        }
+
+        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
+            this.violation(`Identity domain is not the same as or a subdomain of ${signatureData.signingDomain}`, 'EINVALIDIDENTITY', 'identity-domain');
+        }
+
+        return identity;
+    }
+
+    // The t= and x= values in seconds (RFC 6376 section 3.5), false for a tag that is left out
+    getTimestamps() {
+        let timestamp = Math.floor(getCurTime(this.signTime).getTime() / 1000);
+        let expiration = this.expires ? Math.floor(getCurTime(this.expires).getTime() / 1000) : false;
+
+        let validTimestamp = value => Number.isInteger(value) && value >= 0 && value <= MAX_TIMESTAMP;
+
+        if (!validTimestamp(timestamp)) {
+            // 1*12DIGIT can not hold a time before 1970 or after the year 33658
+            this.violation('Signing time can not be represented in a t= tag', 'EINVALIDTIME', 'invalid-signtime');
+            timestamp = false;
+        }
+
+        if (expiration !== false && !validTimestamp(expiration)) {
+            this.violation('Expiration time can not be represented in an x= tag', 'EINVALIDTIME', 'invalid-expiration');
+            expiration = false;
+        }
+
+        if (expiration !== false && timestamp !== false && expiration <= timestamp) {
+            // "The value of the x= tag MUST be greater than the value of the t= tag"
+            this.violation('Expiration time must be later than the signing time', 'EINVALIDTIME', 'invalid-expiration');
+        }
+
+        return { timestamp, expiration };
+    }
+
     async messageHeaders(headers) {
         this.headers = headers;
 
         if (this.getARChain) {
             try {
-                this.arc.chain = this?.getARChain(headers);
+                this.arc.chain = this.getARChain(headers);
                 if (this.arc.chain?.length) {
                     this.arc.lastEntry = this.arc.chain[this.arc.chain.length - 1];
-                    this.arc.instance = this.arc.instance ? this.arc.instance : this.arc.lastEntry.i + 1;
                 }
             } catch (err) {
                 this.arc.error = err;
@@ -162,27 +290,44 @@ class DkimSigner extends MessageParser {
         return this.finalize();
     }
 
+    // The header fields to sign for a signature: its own headerList, the shared one, or the
+    // default list of its type. An ARC-Message-Signature never covers ARC header fields or
+    // Authentication-Results (RFC 8617 section 4.1.2)
+    getFieldNames(signatureData) {
+        let fieldNames =
+            normalizeHeaderList(signatureData.headerList) || this.headerList || (signatureData.type === 'ARC' ? defaultARCFieldNames : defaultDKIMFieldNames);
+
+        if (signatureData.type === 'ARC') {
+            fieldNames = fieldNames
+                .split(':')
+                .filter(name => !ARC_EXCLUDED_FIELDS.includes(name.trim().toLowerCase()))
+                .join(':');
+        }
+
+        return fieldNames;
+    }
+
     async finalize() {
         for (let signatureData of this.signatureData || []) {
             if (!signatureData.privateKey) {
                 continue;
             }
 
-            let fieldNames = this.headerList && this.headerList.length ? this.headerList : false;
-            if (!fieldNames) {
-                switch (signatureData.type) {
-                    case 'ARC':
-                        fieldNames = defaultARCFieldNames;
-                        break;
-
-                    case 'DKIM':
-                    default:
-                        fieldNames = defaultDKIMFieldNames;
-                        break;
-                }
-            }
+            const pushError = (err, extra) => {
+                this.errors.push(
+                    Object.assign(
+                        {
+                            type: signatureData.type,
+                            selector: signatureData.selector,
+                            signingDomain: signatureData.signingDomain
+                        },
+                        extra || {},
+                        { err }
+                    )
+                );
+            };
 
-            let signingHeaderLines = getSigningHeaderLines(this.headers.parsed, this.headerList);
+            let signingHeaderLines = getSigningHeaderLines(this.headers.parsed, this.getFieldNames(signatureData));
 
             if (!signingHeaderLines.headers.some(header => header.key === 'from')) {
                 // RFC 6376 section 5.4: the From header field MUST be signed, and section
@@ -191,12 +336,29 @@ class DkimSigner extends MessageParser {
                 // empty h= tag, which is not even valid sig-h-tag syntax
                 let err = new Error('Can not sign a message that has no From header');
                 err.code = 'ENOFROM';
-                this.errors.push({
-                    type: signatureData.type,
-                    selector: signatureData.selector,
-                    signingDomain: signatureData.signingDomain,
-                    err
-                });
+                pushError(err);
+                continue;
+            }
+
+            let identity, timestamps, instance;
+            try {
+                // throws on a value that is not safe to put into the header
+                this.validateSigningIdentifiers(signatureData);
+                identity = this.getIdentity(signatureData);
+                timestamps = this.getTimestamps();
+
+                if (signatureData.type === 'ARC') {
+                    // createSeal decides where a set without an explicit instance goes
+                    instance = this.arc.instance || (this.getArcInstance ? this.getArcInstance(this.headers) : 1);
+                    if (!Number.isInteger(instance) || instance < 1 || instance > MAX_ARC_INSTANCE) {
+                        // RFC 8617 section 4.2.1, an ARC chain holds at most 50 sets
+                        let err = new Error(`ARC instance ${instance} is out of range (1-${MAX_ARC_INSTANCE})`);
+                        err.code = 'EINVALIDINSTANCE';
+                        throw err;
+                    }
+                }
+            } catch (err) {
+                pushError(err);
                 continue;
             }
 
@@ -252,6 +414,15 @@ class DkimSigner extends MessageParser {
                 }
 
                 algorithm = `${signAlgo}-${hashAlgo}`;
+
+                if (keyType === 'rsa' && privateKeyObj.asymmetricKeyDetails?.modulusLength < MIN_RSA_KEY_SIZE) {
+                    // RFC 8301 section 3.2, verifiers MUST NOT accept such a signature
+                    this.violation(
+                        `RSA key too short (${privateKeyObj.asymmetricKeyDetails.modulusLength} bits, at least ${MIN_RSA_KEY_SIZE} required)`,
+                        'ESHORTKEY',
+                        'weak-key'
+                    );
+                }
             } catch (err) {
                 this.errors.push({
                     selector: signatureData.selector,
@@ -262,8 +433,20 @@ class DkimSigner extends MessageParser {
             }
 
             try {
-                // throws if invalid
-                validateAlgorithm(algorithm);
+                if (this.strict && hashAlgo === 'sha1') {
+                    // RFC 8301 section 3.1, "rsa-sha1 MUST NOT be used for signing"
+                    let err = new Error('rsa-sha1 is not allowed for signing');
+                    err.code = 'EINVALIDALGO';
+                    throw err;
+                }
+
+                // throws if invalid, also for ed25519-sha1, which is not an algorithm. ARC
+                // signatures are never made with sha1, no ARC validator accepts them
+                validateAlgorithm(algorithm, signatureData.type === 'ARC');
+
+                if (hashAlgo === 'sha1') {
+                    this.warn('rsa-sha1');
+                }
             } catch (err) {
                 this.errors.push({
                     algorithm,
@@ -282,12 +465,15 @@ class DkimSigner extends MessageParser {
                     {},
                     signatureData,
                     {
-                        instance: 'instance' in this.arc && (this.arc.instance || 1), // ARC only
+                        instance: signatureData.type === 'ARC' ? instance : false, // ARC only
+                        identity, // DKIM only
                         algorithm,
                         canonicalization: this.getCanonicalization(signatureData).canonicalization,
 
                         signTime: this.signTime,
                         expires: this.expires,
+                        timestamp: timestamps.timestamp,
+                        expiration: timestamps.expiration,
 
                         bodyHash: this.bodyHashes.has(hashKey) ? this.bodyHashes.get(hashKey).hash : null
                     },