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

• • *