Creating a New DKIM Key

Table of Contents
Introduction
Web-Based DKIM Configuration
Command Line DKIM Configuration
Using a Custom Selector
DNS and Yahoo’s Feedback Loop

Introduction

DKIM is normally configured via GreenArrow Engine’s web interface. However, command line configuration is also possible. This page documents both options.

Web-Based DKIM Configuration

The first step in configuring DKIM is to create the private key that’s used to digitally sign messages.

Complete the following steps to create a new private key:

Login to GreenArrow Engine’s web interface.
Navigate to Configure => DKIM Keys:
Click the Add DKIM Key button:
Enter the domain that you wish to generate the new DKIM key for in the Domain field, then click Save. In most situations, we recommend leaving the remaining fields at their default values:
If you wish to import an existing DKIM Private key, uncheck the box next to Generate a new private key and paste your private key into the text entry block that opened:
Be sure to complete the final setup steps.

Command Line DKIM Configuration

You can configure DKIM keys on the command using the define_dkim_keys_in_config_file and dkim_domain configuration directives.

Alternatively, you can edit the /var/hvmail/control/dkim.json file. The rest of this section describes the /var/hvmail/control/dkim.json approach.

If there are any conflicts between the contents of this file and the web-based configuration, then the web-based configuration takes precedence. For example, if the same domain/selector combination is configured in both locations, then the key that’s configured in the web interface is used for signing.

The format of this configuration file is a JSON array containing one object per DKIM key. Each object should have the following keys:

domain string	The key’s domain name.
selector string	The key’s selector.
default_for_domain integer / default: `0`	`1` to make this the default DKIM key for the domain. `0` to not.
key_private string	The PEM encoded private key. Since this is being stored in a JSON document, line ending should be encoded. For example, the configuration below encodes line endings as line feeds (`\n`).

Here’s an example configuration:

[
  {
    "domain": "example.com",
    "selector": "default",
    "default_for_domain": 1,
    "key_private": "-----BEGIN RSA PRIVATE KEY-----\nMIICWwIBAAKBgQDRzSh5YUKsZrfG6h0KObZikPXMbUqMtoBvY8RTF24frqxFKNeF\nHSCaD2oTu3eFqyi4lxndYmAFqUmWl5EhqS/EHqCCKso/gRLCL6pqHvUPGBiZqT8f\nqOF9Ccl7FK5asQ6bK6zYpwQQUVBPOvMW52AUlKCVQP1VAtQ7t29PoC+w2wIDAQAB\nAoGAL7sbIDJOduaPnQOaQ79JjTcplK6wrT7ADZeHDNhhx3d33ewizDgKOMKVAZQ+\n5vw/sW8/BSziZ6dSBJ7K9/uD0BLYGh7EzzlfmWtUblwHRhK23zsVcPmYsSyrd4pf\nDvd5csyvorIreqDfua5mv3zFIQqA2ZDarNq6sjsez2qeZnECQQD6x3yJRyGUWqaN\na4HK3GeaO6N2J1L99MUi9Ozy6l4BZ17gf+WxlMJo6rUsVza7INhN2HxSXHPYoady\nEx1TbJvNAkEA1itIVlyWlxAJlvNdwuGkDtPlphV/a61iIgU14escaBU4Rg0yHLdM\n3x6Cf4Jl1HcKSODSD45FyhbimikXHOVnRwJAYxWKqRrHs7wVbm75u1NWQ+Qoc7iZ\n2+loMqWfMWNUfS2AmScvc/iYz6dcqgZTg6A4lplglZId24wTgsj2n02cSQJAQqVR\na16Alh2tfkXZRY3F6b9S1W4XKsDXqtKIQ/dP7au8yT/N+lWoHD54SYmgeo9Yqfkc\nJS8W1J5ugZ6LzLgufQJAW5WlGtyo8RfEbbnGRfeGHRFIf8vHt0a3BThEsh51QRJ3\neT3U4ajMxJfeXFdhzfLDzxtpSM78qfj70DtFWUDcUQ==\n-----END RSA PRIVATE KEY-----"
  },
  {
    "domain": "example2.com",
    "selector": "default",
    "default_for_domain": 1,
    "key_private": "-----BEGIN RSA PRIVATE KEY-----\nMIICWwIBAAKBgQDRzSh5YUKsZrfG6h0KObZikPXMbUqMtoBvY8RTF24frqxFKNeF\nHSCaD2oTu3eFqyi4lxndYmAFqUmWl5EhqS/EHqCCKso/gRLCL6pqHvUPGBiZqT8f\nqOF9Ccl7FK5asQ6bK6zYpwQQUVBPOvMW52AUlKCVQP1VAtQ7t29PoC+w2wIDAQAB\nAoGAL7sbIDJOduaPnQOaQ79JjTcplK6wrT7ADZeHDNhhx3d33ewizDgKOMKVAZQ+\n5vw/sW8/BSziZ6dSBJ7K9/uD0BLYGh7EzzlfmWtUblwHRhK23zsVcPmYsSyrd4pf\nDvd5csyvorIreqDfua5mv3zFIQqA2ZDarNq6sjsez2qeZnECQQD6x3yJRyGUWqaN\na4HK3GeaO6N2J1L99MUi9Ozy6l4BZ17gf+WxlMJo6rUsVza7INhN2HxSXHPYoady\nEx1TbJvNAkEA1itIVlyWlxAJlvNdwuGkDtPlphV/a61iIgU14escaBU4Rg0yHLdM\n3x6Cf4Jl1HcKSODSD45FyhbimikXHOVnRwJAYxWKqRrHs7wVbm75u1NWQ+Qoc7iZ\n2+loMqWfMWNUfS2AmScvc/iYz6dcqgZTg6A4lplglZId24wTgsj2n02cSQJAQqVR\na16Alh2tfkXZRY3F6b9S1W4XKsDXqtKIQ/dP7au8yT/N+lWoHD54SYmgeo9Yqfkc\nJS8W1J5ugZ6LzLgufQJAW5WlGtyo8RfEbbnGRfeGHRFIf8vHt0a3BThEsh51QRJ3\neT3U4ajMxJfeXFdhzfLDzxtpSM78qfj70DtFWUDcUQ==\n-----END RSA PRIVATE KEY-----"
  }
]

Changes to the configuration file are automatically applied within 20 seconds.

You can check for configuration errors by monitoring the /var/hvmail/log/config-agent/current log file for errors after applying changes. For example, the following line suggests that there’s something wrong with example.com’s private key:

2018-08-10 15:37:44.374183500 Error: invalid format or missing private key in /var/hvmail/control/dkim.json for domain=(example.com), selector=(default)

Using a Custom Selector

GreenArrow’s default selector is literally named default. You may overwrite this with another selector if you wish.

DNS and Yahoo’s Feedback Loop

After a new DKIM key is created, the next step is to create the DNS records for it and testing to make sure it passes.

Yahoo’s Feedback Loop is DKIM based, so you’ll probably want to register any newly created DKIM keys with Yahoo.