import from haraka/Haraka

.codeclimate.yml

@@ -1,10 +1,10 @@
 engines:
   eslint:
     enabled: true
-    channel: "eslint-8"
+    channel: 'eslint-8'
     config:
-      config: ".eslintrc.yaml"
+      config: '.eslintrc.yaml'
 
 ratings:
   paths:
-    - "**.js"
+    - '**.js'

.eslintrc.yaml

@@ -4,4 +4,4 @@ env:
   mocha: true
   es2022: true
 
-extends: ["@haraka"]
+extends: ['@haraka']

.github/dependabot.yml

@@ -2,9 +2,9 @@
 
 version: 2
 updates:
-  - package-ecosystem: "npm"
-    directory: "/"
+  - package-ecosystem: 'npm'
+    directory: '/'
     schedule:
-      interval: "monthly"
+      interval: 'monthly'
     allow:
       - dependency-type: production

.github/workflows/codeql.yml

@@ -1,12 +1,12 @@
-name: "CodeQL"
+name: 'CodeQL'
 
 on:
   push:
     branches: [master]
   pull_request:
     branches: [master]
   schedule:
-    - cron: "18 7 * * 4"
+    - cron: '18 7 * * 4'
 
 jobs:
   codeql:

.prettierrc

@@ -0,0 +1,2 @@
+semi: false
+singleQuote: true

CHANGELOG.md

@@ -4,44 +4,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Unreleased
 
-### [1.0.6] - 2024-04-08
+### 1.0.0 - 2024-04-09
 
-- dep: eslint-plugin-haraka -> @haraka/eslint-config
-- lint: remove duplicate / stale rules from .eslintrc
-- populate [files] in package.json. Delete .npmignore.
-- doc: Changes.md -> CHANGELOG.md
-- test: switch to node --test
+- repackaged from haraka/Haraka
 
-### 1.0.5 - 2023-12-12
-
-- ci: run tests on PR
-- ci(publish): add on.release trigger
-- deps(dev\*): pin versions
-
-### [1.0.3] - 2022-06-05
-
-- ci: replace hard coded vers with node-lts-versions
-- ci(publish): add secrets: inherit
-- ci: use reusable workflows (#18)
-
-### [1.0.2] - 2022-05-23
-
-- ci: replace hard coded node vers with node-lts-versions
-- ci(publish): add secrets: inherit
-- ci: use reusable workflows (#18)
-- packaging updates
-
-### [1.0.1] - 2021-02-04
-
-- test: added example tests that set up conn/txn
-- ci: add automated package publishing
-- ci(GHA): consolidate \*nix & win tests
-
-### 1.0.0 - 2017-02-02
-
-- initial release
-
-[1.0.1]: https://github.com/haraka/haraka-plugin-template/releases/tag/1.0.1
-[1.0.2]: https://github.com/haraka/haraka-plugin-template/releases/tag/1.0.2
-[1.0.3]: https://github.com/haraka/haraka-plugin-template/releases/tag/1.0.3
-[1.0.6]: https://github.com/haraka/haraka-plugin-template/releases/tag/v1.0.6
+[1.0.0]: https://github.com/haraka/haraka-plugin-template/releases/tag/v1.0.0

README.md

@@ -3,74 +3,152 @@
 
 [![NPM][npm-img]][npm-url]
 
-# haraka-plugin-template
+# haraka-plugin-dkim
 
-Clone me, to create a new Haraka plugin!
+## INSTALL
+
+```sh
+cd /path/to/local/haraka
+npm install haraka-plugin-dkim
+echo "dkim" >> config/plugins
+service haraka restart
+```
 
-# Template Instructions
+### Configuration
+
+If the default configuration is not sufficient, copy the config file from the distribution into your haraka config dir and then modify it:
 
-These instructions will not self-destruct after use. Use and destroy.
+```sh
+cp node_modules/haraka-plugin-dkim/config/dkim.ini config/dkim.ini
+$EDITOR config/dkim.ini
+```
 
-See also, [How to Write a Plugin](https://github.com/haraka/Haraka/wiki/Write-a-Plugin) and [Plugins.md](https://github.com/haraka/Haraka/blob/master/docs/Plugins.md) for additional plugin writing information.
+## SIGNING
 
-## Create a new repo for your plugin
+This plugin implements the [DKIM Core specification](dkimcore.org).
 
-Haraka plugins are named like `haraka-plugin-something`. All the namespace after `haraka-plugin-` is yours for the taking. Please check the [Plugins](https://github.com/haraka/Haraka/blob/master/Plugins.md) page and a Google search to see what plugins already exist.
+### Getting Started
 
-Once you've settled on a name, create the GitHub repo. On the repo's main page, click the _Clone or download_ button and copy the URL. Then paste that URL into a local ENV variable with a command like this:
+Generate a DKIM selector and keys for your domain:
 
 ```sh
-export MY_GITHUB_ORG=haraka
-export MY_PLUGIN_NAME=haraka-plugin-SOMETHING
+cd /path/to/haraka/config/dkim
+./dkim_key_gen.sh example.org
 ```
 
-Clone and rename the template repo:
+Within the config/dkim/${domain} directory will be 4 files:
 
 ```sh
-git clone [email protected]:haraka/haraka-plugin-template.git
-mv haraka-plugin-template $MY_PLUGIN_NAME
-cd $MY_PLUGIN_NAME
-git remote rm origin
-git remote add origin "[email protected]:$MY_GITHUB_ORG/$MY_PLUGIN_NAME.git"
+ls config/dkim/example.org/
+dns private public selector
 ```
 
-Now you'll have a local git repo to begin authoring your plugin
+The selector file contains the DNS label where the DKIM public key is published. The `private` and `public` files contain the DKIM keys.
 
-## rename boilerplate
+The `dns` file contains a formatted record of the public key suitable for copy/pasting into your domains zone file. It also has suggestions for DKIM, SPF, and DMARC policy records.
 
-Replaces all uses of the word `template` with your plugin's name.
+The DKIM DNS record will look like this:
 
-./redress.sh [something]
+    may2013._domainkey TXT "v=DKIM1;p=[public key stripped of whitespace];"
 
-You'll then be prompted to update package.json and then force push this repo onto the GitHub repo you've created earlier.
+The values in the address have the following meaning:
 
-# Add your content here
+    hash: h=[ sha1 | sha256 ]
+    test; t=[ s | s:y ]
+    granularity: g=[ ]
+    notes: n=[ ]
+    services: s=[email]
+    keytypes: [ rsa ]
 
-## INSTALL
+## Key size
 
-```sh
-cd /path/to/local/haraka
-npm install haraka-plugin-template
-echo "template" >> config/plugins
-service haraka restart
+The default key size created by `dkim_key_gen.sh` is 2048. That is considered secure as of mid-2024.
+
+# What to sign
+
+The DKIM signing key for messages from example.org _should_ be signed with
+a DKIM key for example.org. Failing to do so will result in messages not
+having an _aligned_ DKIM signature. For DMARC enabled domains, this will
+likely result in deliverability problems.
+
+For correct alignment, Haraka signs each message with that domains DKIM key.
+For an alternative, see the legacy Single Domain Configuration below.
+
+# Configuration
+
+DKIM signing is configured in the sign section of `dkim.ini`.
+
+```ini
+[sign]
+enabled = [ 1 | true | yes ], default=false
+headers = list, of; headers (REQUIRED)
+
+; for single domain configuration
+selector = name
+domain = name
 ```
 
-### Configuration
+* headers: the list of headers that should be signed, separated by commas, colons or semi-colons. Signing prevents tampering with the specified headers. The 'From' header is required by the RFC and will be added if missing.
 
-If the default configuration is not sufficient, copy the config file from the distribution into your haraka config dir and then modify it:
+## Single Domain Configuration
+
+To sign all messages with a single DKIM key, you must set the selector and domain in dkim.ini. You must also save your DKIM private key in the file `dkim.private.key` in the Haraka config directory.
+
+- selector - Set this to the selector name published in DNS under the \_domainkey sub-domain of the domain referenced below.
+- domain - Set this to the domain name that will be used to sign messages which don't match a per-domain DKIM key. The DNS TXT entry for:
+
+    <selector>.\_domainkey.<domain>
+
+Test that your DKIM key is published properly with a DNS request like this:
 
 ```sh
-cp node_modules/haraka-plugin-template/config/template.ini config/template.ini
-$EDITOR config/template.ini
+drill TXT $SELECTOR._domainkey.$DOMAIN
+dig TXT $SELECTOR._domainkey.$DOMAIN +short
+```
+
+### Example DNS query
+
+```sh
+export SELECTOR=mar2013
+export DOMAIN=simerson.net
+$ dig TXT $SELECTOR._domainkey.$DOMAIN +short
+"v=DKIM1;p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoyUzGOTSOmakY8BcxXgi0mN/nFegLBPs7aaGQUtjHfa8yUrt9T2j6GSXgdjLuG3R43WjePQv3RHzc+bwwOkdw0XDOXiztn5mhrlaflbVr5PMSTrv64/cpFQKLtgQx8Vgqp7Dh3jw13rLomRTqJFgMrMHdhIibZEa69gtuAfDqoeXo6QDSGk5JuBAeRHEH27FriHulg5ob" "4F4lmh7fMFVsDGkQEF6jaIVYqvRjDyyQed3R3aTJX3fpb3QrtRqvfn/LAf+3kzW58AjsERpsNCSTD2RquxbnyoR/1wdGKb8cUlD/EXvqtvpVnOzHeSeMEqex3kQI8HOGsEehWZlKd+GqwIDAQAB"
+```
+
+# DKIM VERIFY
+
+Verify DKIM signatures as defined by RFC 6376 and add an Authentication-Results header as appropriate.
+
+## Configuration
+
+```ini
+[verify]
+; allowed_time_skew = (How far can we stretch on time matching, in secs. Useful when clock is skewed.)
+; sigerror_log_level =
 ```
 
-## USAGE
+## Testing
+
+This plugin provides a command-line test tool that can be used to
+debug DKIM issues or to check results.
+
+```
+# dkimverify < message
+identity="@gmail.com" domain="gmail.com" result=pass
+```
+
+You can add `--debug` to the option arguments to see a full trace of the processing.
+
+## Notes
+
+This plugin and underlying library do not currently support DKIM body length limits (l=).
+
 
 <!-- leave these buried at the bottom of the document -->
 
-[ci-img]: https://github.com/haraka/haraka-plugin-template/actions/workflows/ci.yml/badge.svg
-[ci-url]: https://github.com/haraka/haraka-plugin-template/actions/workflows/ci.yml
-[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-template/badges/gpa.svg
-[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-template
-[npm-img]: https://nodei.co/npm/haraka-plugin-template.png
-[npm-url]: https://www.npmjs.com/package/haraka-plugin-template
+[ci-img]: https://github.com/haraka/haraka-plugin-dkim/actions/workflows/ci.yml/badge.svg
+[ci-url]: https://github.com/haraka/haraka-plugin-dkim/actions/workflows/ci.yml
+[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-dkim/badges/gpa.svg
+[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-dkim
+[npm-img]: https://nodei.co/npm/haraka-plugin-dkim.png
+[npm-url]: https://www.npmjs.com/package/haraka-plugin-dkim

bin/dkimverify

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+// DKIM test tool
+
+const nopt = require('nopt')
+const path = require('path')
+const base_path = path.join(__dirname, '..')
+const dkim = require(`${base_path}/lib/dkim`)
+const DKIMVerifyStream = dkim.DKIMVerifyStream
+
+const parsed = nopt({ debug: Boolean, time_skew: Number, help: Boolean })
+
+function print_usage() {
+  console.log('Usage: dkimverify [--debug] [--time_skew=123] < message')
+  process.exit(1)
+}
+
+if (parsed.help) print_usage()
+
+if (!parsed.debug) {
+  dkim.DKIMObject.prototype.debug = function (str) {}
+  DKIMVerifyStream.prototype.debug = function (str) {}
+}
+
+const opts = {}
+if (parsed.time_skew) opts.allowed_time_skew = parsed.time_skew
+
+const verifier = new DKIMVerifyStream(opts, (err, result, results) => {
+  if (err) console.log(err.message)
+  if (Array.isArray(results)) {
+    results.forEach(function (res) {
+      console.log(
+        `identity="${res.identity}" domain="${res.domain}" result=${res.result} ${res.error ? `(${res.error})` : ''}`,
+      )
+    })
+  } else {
+    console.log(`Result: ${result}`)
+  }
+})
+
+process.stdin.pipe(verifier)

config/dkim.ini

@@ -0,0 +1,18 @@
+
+[main]
+
+
+[sign]
+enabled = false
+selector = mail
+domain = example.com
+headers = From, Sender, Reply-To, Subject, Date, Message-ID, To, Cc, MIME-Version
+
+
+[verify]
+; Recommended (but not default) values presented below.
+
+; in secs
+;allowed_time_skew = 60
+;
+;sigerror_log_level = info