jhermsmeier / node-dkim

DomainKeys Identified Mail

DomainKeys Identified Mail (DKIM)

Install via npm

$ npm install --save dkim

References

• RFC 6368 - DomainKeys Identified Mail (DKIM) Signatures
• RFC 8301 - Cryptographic Algorithm and Key Usage Update to DomainKeys Identified Mail (DKIM)
• RFC 8463 - A New Cryptographic Signature Method for DomainKeys Identified Mail (DKIM)
• RFC 8616 - Email Authentication for Internationalized Mail
• RFC 7489 - Domain-based Message Authentication, Reporting, and Conformance (DMARC)

API

DKIM : Object

Kind: global variable

• DKIM : Object
  • .Signature
    • new DKIM.Signature()
  • .Key
    • new DKIM.Key()
  • .NONE : String
  • .OK : String
  • .TEMPFAIL : String
  • .PERMFAIL : String
  • .getKey(domain, [selector], callback)
  • .processBody(message, method) ⇒ String
  • .processHeader(headers, signHeaders, method) ⇒ String
  • .verifySignature(body, headers, callback)
  • .verify(message, callback)
    • .filterSignatureHeaders(headers, signatureHeader) ⇒ Array.<String>

---

DKIM.Signature

Kind: static class of DKIM
See: dkim-signature

---

new DKIM.Signature()

DKIM Signature

---

DKIM.Key

Kind: static class of DKIM
See: dkim-key

---

new DKIM.Key()

DKIM Key

---

DKIM.NONE : String

Kind: static property of DKIM

---

DKIM.OK : String

Kind: static property of DKIM

---

DKIM.TEMPFAIL : String

Kind: static property of DKIM

---

DKIM.PERMFAIL : String

Kind: static property of DKIM

---

DKIM.getKey(domain, [selector], callback)

Retrieve a domain key

Kind: static method of DKIM
Todo

• DNS seems to FORMERR on unregistered / expired domains, which maybe should be a TEMPFAIL (?)
• make this public_key = dkim_find_key(q_val, d_val, s_val), where *_val are the signature's attribute values
• Throw error if the public key is not a Buffer

Params

• domain String
• [selector] String
• callback function

---

DKIM.processBody(message, method) ⇒ String

Canonicalize the message body according to methods defined in RFC[XXXX]

Kind: static method of DKIM
Throws:

• Error If canonicalization method is unsupported

Params

• message Buffer | String
• method String - (simple|relaxed)

---

DKIM.processHeader(headers, signHeaders, method) ⇒ String

Canonicalize the message header according to methods defined in RFC[6376]

Kind: static method of DKIM
Throws:

• Error If canonicalization method is unsupported

Params

• headers Array.<String> - Each header is formatted as <field>: <value>
• signHeaders Array
• method String - (simple|relaxed)

Example

DKIM.processHeader( [ 'A: X', 'B : Y\t\r\n\tZ  '], [ 'A' ], 'relaxed' )

---

DKIM.verifySignature(body, headers, callback)

Verify a message signature

Kind: static method of DKIM
Params

• body Buffer
• headers Array
• callback function

---

DKIM.verify(message, callback)

Verify a message's signatures

Kind: static method of DKIM
Throws:

• Error If input is not a buffer

Params

• message Buffer
• callback function

---

verify.filterSignatureHeaders(headers, signatureHeader) ⇒ Array.<String>

Filter out signature headers other than the specified signatureHeader

Kind: static method of verify
Returns: Array.<String> - filtered headers
Params

• headers Array.<String> - list of headers to filter
• signatureHeader String - signature header to keep

---

node-dkim's Issues

Core bugs in this package make it unusable

I attempted to use this package in https://forwardemail.net, however I continuously had reports of failures. These errors came up frequently from common mail servers (e.g. Yahoo, Earthlink, Mindspring).

• Body hash did not verify

I think there is a bug somewhere with the crypto portion of signature verification. Very tired right now but if I can help more let me know.

hangs if no signatures found

because you call the callback inside the signatures.forEach loop, if there are no DKIM signatures then it hangs...

receiving "Body hash did not verify" on every DKIM signature

The signature hashes are failing to verify 😦

can you document `verify` method further?

The source code is quite confusing

node-dkim/lib/verify-signature.js

Line 76 in 2866c2f

return callback( error, result )

. So if one record fails verification, do all? What does the object look like? Is there a way to just get a true/false on an email if it passes DKIM? Do we have to do it like the test where you iterate over every result and ensure result.verified is true? Is result always an object?

Thanks again!!!

Error: Unknown field name "darn"

When utilizing the dkim.verify() method after receiving an email that was sent by Gmail, the following error is received:

Error: Unknown field name "darn"
    at Signature.parse (/root/EmailServer/node_modules/dkim-signature/lib/signature.js:141:15)
    at Signature.parse (/root/EmailServer/node_modules/dkim-signature/lib/signature.js:87:26)
    at Object.verifySignature (/root/EmailServer/node_modules/dkim/lib/verify-signature.js:27:51)
    at verifyNextSignature (/root/EmailServer/node_modules/dkim/lib/verify.js:50:10)
    at /root/EmailServer/node_modules/dkim/lib/verify.js:53:7
    at /root/EmailServer/node_modules/dkim/lib/verify-signature.js:86:5
    at QueryReqWrap.callback (/root/EmailServer/node_modules/dkim/lib/get-key.js:80:5)
    at QueryReqWrap.onresolve [as oncomplete] (node:internal/dns/callback_resolver:47:10) {
  code: 'PERMFAIL'
}

This type of error does not occur, however, when you attempt to verify an email from Zoho Mail, Outlook, etc.

Expose methods that returns promises

It would be great if this library could expose methods that return promises instead of expecting callbacks. I can create a PR that does that if authors are ok with that.

we should remove X-Google-DKIM-Signature, it's not to RFC standards

Fix relaxed header canonicalization

Relaxed verification issues

Hi 👋 – I'm currently working on PHPMailer/DKIMValidator, running into troubles of my own, and took a look at yours to see how I compare!

I just saw this comment and have some candidates for the problem.

When unfolding headers, you replace the break and FWS with an empty string. This is incorrect. RFC5322 says:

Unfolding is accomplished by simply removing any CRLF that is immediately followed by FWS.

It's easy to get this wrong - it says to remove the CRLF, but that does not include the FWS that follows it. This means that this:

Subject: abc
    xyz

unfolds to Subject: abc xyz (with 4 spaces in the gap), not Subject: abcxyz.

The next canonicalization step collapses whitespace, so that line would become Subject: abc xyz (with 1 space).

Your next thought will be "but that means you end up with random spaces in the unfolded headers" – and you would be entirely correct. This can cause all sorts of problems – but so can collapsing the FWS to nothing, for example Subject: hello world might be folded to:

Subject: hello
 world

and unfolding it as you are would turn it into Subject: helloworld. This is a difficult problem to solve, and in fact the email RFCs don't have a good answer for it, especially in an edge case like a header that contains an unbroken char sequence of > 998 chars, as for example a signature might do. Fortunately there is a reasonable workaround, which is to use RFC2047 encoding, which allows you to fold an unbroken line into multiple lines, but the encoding means that when it's decoded, the unfolded FWS disappears. Apple Mail does this, and so does PHPMailer. Gmail and Outlook don't even try, and simply allow messages to break RFC.

Next I can hear you thinking, "but if a space appears in the middle of a DKIM signature, it will break the signature", and again, you're quite right, and this one had me baffled for ages, but there's a solution to this in DKIM:

Note that all whitespace, including SPACE, CR, and LF characters, MUST be encoded. After encoding, FWS
MAY be added at arbitrary locations in order to avoid excessively long lines; such whitespace is NOT part of the value, and MUST be removed before decoding.

The upshot of this is while the canonicalized DKIM-Signature header may include arbitrary spaces after unfolding, those spaces should be removed before processing it.

doesn't support rsa 2048 keys?

doesn't seem to support long multi-line keys

e.g.

"v=DKIM1; k=rsa; p="
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA72KY0zgC+o140+5D6SuS"
"5+2I5Q6dLgZnLGCs0vlHcHvINutUlM4gKDuQ17ENaphKMosmzaA1lCzlZyZdPHN8"
"dLe8VOjQgkcxFpkB9r3SciE70BmkpRDbBqeU4CRPqYtv+g+VtBEvuEbV0j057xpJ"
"pRTHjBLEHbe3+2dzTk5T8vkGKX6nftjSzmpd1JkPxHDR4lykxemp6dC7CSyf+5Jo"
"0Tdp1YgItRJySk663DqJQ67yPpWqRhhljIkhMVeB5EHYPdThihWOi3Gj9BG6/oRM"
"XxeKCdipYXzD3JKJucD0GTqo53Ym2yCAAjWdxD25y/Ti3fkQSu9PxtUcdZ00kjXJ"
"owIDAQAB"

gets read as

records [ [ '0Tdp1YgItRJySk663DqJQ67yPpWqRhhljIkhMVeB5EHYPdThihWOi3Gj9BG6/oRM' ],
  [ '5+2I5Q6dLgZnLGCs0vlHcHvINutUlM4gKDuQ17ENaphKMosmzaA1lCzlZyZdPHN8' ],
  [ 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA72KY0zgC+o140+5D6SuS' ],
  [ 'XxeKCdipYXzD3JKJucD0GTqo53Ym2yCAAjWdxD25y/Ti3fkQSu9PxtUcdZ00kjXJ' ],
  [ 'dLe8VOjQgkcxFpkB9r3SciE70BmkpRDbBqeU4CRPqYtv+g+VtBEvuEbV0j057xpJ' ],
  [ 'owIDAQAB' ],
  [ 'pRTHjBLEHbe3+2dzTk5T8vkGKX6nftjSzmpd1JkPxHDR4lykxemp6dC7CSyf+5Jo' ],
  [ 'v=DKIM1; k=rsa; p=' ] ]

and doesn't get concatenated/joined so key.key is empty and toString() can't be called

dkim.verify does not work with a raw email?

I have a raw email and convert to buffer Buffer.from(rawEmail) and then pass it to dkim.verify but the dkim verification ALWAYS fails with No key for signature even though it has a valid DKIM signature

I was using validateDKIM here https://github.com/Flolagale/mailin/blob/fac7dcf59404691e551568f987caaaa464303b6b/lib/mailUtilities.js#L27 but that didn't work for google dkim