X-GreenArrow-DKIM Header

Table of Contents
Header Contents
Object Definition
Interaction with Legacy Headers
Default Behavior
Creating a New Default Signing Behavior
Error Messages
Caveats

The X-GreenArrow-DKIM header can be used to specify what DKIM key(s) GreenArrow should use to sign a message.

This header is supported in:

Email injected by GreenArrow Studio.
Email injected through SimpleMH.
Email injected through an authenticated SMTP connection (either SMTP-AUTH or IP-based authentication).

This header is not supported in:

Email injected through an un-authenticated SMTP connection.
Email injected using the sendmail or qmail-inject commands.

Header Contents

The X-GreenArrow-DKIM header’s value should be a JSON object specifying a single DKIM key or JSON array specifying one or more DKIM keys.

A maximum of 10 DKIM signatures may be added to a single email. The generation of each DKIM signature consumes CPU resources.

Here are a few examples:

Request a single signature using a JSON object:

X-GreenArrow-DKIM: {"domain":"example.com","selector":"foo"}

Request a single signature using a JSON array:

X-GreenArrow-DKIM: [{"domain":"example.com","selector":"foo"}]

Requesting two signatures with one header:

X-GreenArrow-DKIM: [{"domain":"example.com","selector":"foo"},{"domain":"test.example.com","selector":"bar"}]

Request two signatures using two headers. When more than one header is specified, the effect is cumulative:

X-GreenArrow-DKIM: [{"domain":"example.com","selector":"foo"}]
X-GreenArrow-DKIM: [{"domain":"test.example.com","selector":"bar"}]

Header folding is supported:

X-GreenArrow-DKIM: [{"domain":"example.com",
"selector":"foo"}]

The contents of each X-GreenArrow-DKIM header must be shorter than 4 kilobytes.

Object Definition

The header’s value should be a JSON object in the format below, or a JSON array consisting of between 1 and 10 objects that are each in the format below.

domain string / optional	The fully qualified domain name of the DKIM key to sign with. This is used in the `d=` value of the signature, and (in the absence of `use_key_from`) it is be used to find the private key for creating the signature.
from_domain boolean / default: `true`	If a true value (for example, JSON `true` or a number greater than or equal to one), then: If a `Sender` header is not present, the `From` header’s domain is used as if it was specified as a `domain` parameter. If a `Sender` header is present, the `Sender` header’s domain is used as if it was specified as a `domain` parameter.
selector string / optional	The selector of the DKIM key to sign with. This is used in the `s=` value of the signature, and (in the absence of `use_key_from`) it is used to find the private key for creating the signature. If not set: If there is a default DKIM key for the specified domain name, it is used. If no default key is found, an error is logged and no signature added.
use_key_from string / optional	Defines where to get the private key for creating the signature. This is intended to be used when multiple domains all use the same private key. The private key can be loaded into GreenArrow once and then used for signing for various domains. If `use_key_from` is specified then it overrides how to get the private key for creating the signature. The `domain` and `selector` parameters still specify the domain and selector used in the DKIM signature (`d=` and `s=` values). `use_key_from` must be the domain name, optionally followed by a slash and a selector name. For example: `example.com` – use the default key for `example.com`. If there is no default key, then an error is logged. `example.com/foo` – use the key for the domain `example.com` with the selector `foo`. If no such key is found, then an error is logged. When using `use_key_from`, the `selector` parameter must be specified.
allow_duplicate boolean / default: `false`	By default, if the same DKIM key is specified more than once, only the first instance is honored. The others are suppressed to avoid duplicate signatures. Setting `allow_duplicate` to a true value (for example, JSON `true` or a number greater than or equal to one) disables this suppression.

Either domain or from_domain must be specified in each object. Additionally, from_domain may not be true if domain is specified within the same object.

Interaction with Legacy Headers

The X-GreenArrow-DKIM-Only-Using-Domain and X-GreenArrow-Signing-Selector headers are the legacy way that DKIM signing behavior was specified.

These headers are still supported, but we recommend that you do not use them – their support may be removed in a future version.

Here is how they interact with this system:

If only the X-GreenArrow-DKIM-Only-Using-Domain header exists:

This is equivalent to an X-GreenArrow-DKIM header with:

domain – the value of the X-GreenArrow-DKIM-Only-Using-Domain header

For example:

X-GreenArrow-DKIM-Only-Using-Domain: example.com

Is equivalent to:

X-GreenArrow-DKIM: [{"domain":"example.com"}]

If only the X-GreenArrow-Signing-Selector header exists:

This is equivalent to an X-GreenArrow-DKIM header with:

from_domain – true
selector – the value of the X-GreenArrow-Signing-Selector header

For example:

X-GreenArrow-Signing-Selector: foo

Is equivalent to:

X-GreenArrow-DKIM: [{"from_domain":true,"selector":"foo"}]

If both are specified:

These are equivalent to an X-GreenArrow-DKIM header with:

domain – the value of the X-GreenArrow-DKIM-Only-Using-Domain header
selector – the value of the X-GreenArrow-Signing-Selector header

For example:

X-GreenArrow-DKIM-Only-Using-Domain: example.com
X-GreenArrow-Signing-Selector: foo

Is equivalent to:

X-GreenArrow-DKIM: [{"domain":"example.com","selector":"foo"}]

Default Behavior

When no DKIM signing headers are specified, the default behavior is:

If a Sender header is not present, the default DKIM key for the From header’s domain is used to sign, if one exists.
If a Sender header is present, the default DKIM key for the Sender header’s domain is used to sign, if one exists.

This default behavior is equivalent to the header:

X-GreenArrow-DKIM: [{"from_domain":true}]

Any header that specifies DKIM signing behavior replaces, rather than adds to, the default DKIM signing behavior. To add to the default behavior, specify something like this:

X-GreenArrow-DKIM: [{"from_domain":true},{"domain":"example.com"}]

Creating a New Default Signing Behavior

It’s possible to set X-GreenArrow-DKIM header values on multiple levels. The effects of each level are cumulative. For example, if you both specify a default for all GreenArrow Studio mail, and for a specific GreenArrow Studio mailing list, mail sent to that mailing list will have both headers applied. Likewise, if you inject a SimpleMH message into GreenArrow that has an X-GreenArrow-DKIM header set, and it uses a Mail Class that has an X-GreenArrow-DKIM header configured, both headers are applied.

This section described how to create new default DKIM signing behavior on the following levels:

For all SimpleMH and GreenArrow Studio mail.
For a specific SimpleMH Mail Class.
For all GreenArrow Studio mail.
For a specific GreenArrow Studio organization.
For a specific GreenArrow Studio mailing list.

Here are the most common new defaults:

To sign email using a domain name (in this case example.com) in addition to the default signature (which uses the From/Sender domain), add this a custom header:
```
X-GreenArrow-DKIM: [{"from_domain":true},{"domain":"example.com"}]
```
(This is commonly used by ESPs to sign email with their own domain in addition to a customer domain.)
To sign email using a domain name (in this case example.com) instead of the default signature (which uses the From/Sender domain), add this as a custom header:
```
X-GreenArrow-DKIM: [{"domain":"example.com"}]
```
To sign email using a non-default key of the From/Sender domain (in this example, the key with the selector of foo), add this as a custom header:
```
X-GreenArrow-DKIM: [{"from_domain":true,"selector":"foo"}]
```

New Default for All SimpleMH and Studio Mail

To create a new default for all SimpleMH and GreenArrow Studio mail, write the desired header value (excluding the X-GreenArrow-DKIM: prefix) to the /var/hvmail/control/dkim.global_header file. For example:

[{"from_domain":true},{"domain":"example.com"}]

This works by implicitly adding a X-GreenArrow-DKIM header with the contents of this file to every email sent through SimpleMH and GreenArrow Studio.

New Default for a SimpleMH Mail Class

To create a new default for a Mail Class, add the full desired X-GreenArrow-DKIM header to the Custom headers configuration of the Mail Class.

New Defaults within GreenArrow Studio

To create a new default for all of GreenArrow Studio’s mail:

Go to “Admin” => “System” => “Edit System Configuration”.
Enter the full desired header into the SYSTEM GLOBAL EXTRA HEADERS field, then click the Update system configuration button.

To create a new default for a GreenArrow Studio organization:

Go to “Admin” => “Manage Organizations”.
Click the “Edit” (wrench and pencil) icon next to the organization that you wish to update.
Enter the full desired header into the CUSTOM HEADERS field, then click the Update this organization button.

To create a new default for a specific mailing list:

Click on the “Mailing Lists” tab.
Click the “Edit” (wrench and pencil) icon next to the list that you wish to update.
Toggle the USE CUSTOM HEADERS option to YES if it’s not already set that way.
Enter the full desired header into the CUSTOM HEADERS field, then click the Update this mailing list button.

Error Messages

When used with SimpleMH, any error messages created from parsing the headers or looking up keys are logged into the /var/hvmail/log/simplemh and /var/hvmail/log/simplemh2 multilog directories.

Example error messages:

notice: problem dkim signing message: unable to find default key for domain=(example.com)

notice: problem dkim signing message: unable to find key for domain=(test5.greenarrowemail.com) and selector=(foo)

notice: problem dkim signing message: unable to find key for domain=(test5.greenarrowemail.com) and selector=(foo), not valid to specify both 'domain' and 'from_domain'

notice: problem dkim signing message: error decoding JSON

This last error frequently appears when passing the X-GreenArrow-DKIM: header in the GreenArrow Engine’s HTTP Submission API. This is because the array being passed via the API needs to be escaped so that it gets passed through to SimpleMH (instead of being interpreted by the API).

For example, in order to use this header in the API:

X-GreenArrow-DKIM: [{"domain":"example.com","selector":"foo"},{"domain":"test.example.com","selector":"bar"}]

It needs to be escapted in this format:

"X-GreenArrow-DKIM": "[{\"domain\":\"example.com\",\"selector\":\"foo\"},{\"domain\":\"test.example.com\",\"selector\":\"bar\"}]"

Caveats

This feature could be temporarily turned off by GreenArrow System administrators to debug a problem.

If the file /var/hvmail/control/studio.use_direct_injection does not have a true value, then this feature will not function for email from Studio.

These are only options enabled by GreenArrow system administrators when debugging problems. Please do not set these files.