ZDKIMGENKEY(8)

zdkimgenkey - DKIM key generator  

zdkimgenkey [option...]  

zdkimgenkey is a bash script that invokes certtool or openssl to generate a DKIM key, and formats the public key in order to ease its publication in the DNS.

The output of the script consists of two files in the /local/courier/etc/path/filters/keys directory. File names are based on the selector name, given as option.

selector.private

A PEM-formatted private key, for use by zdkimfilter when signing messages.

selector.txt

A DNS TXT record suitable for insertion into or inclusion by a DNS zone file in order to publish the public key for verifiers. This file contains the public key. The public key can be obtained from the private one whenever needed, so you can dispose of this file after use.

To start using a key, link it to a domain name by using symbolic links.

zdkimfilter looks for a file having the same name as the domain, in a directory configured using the domain_keys configuration option. By default, this is /local/courier/etc/path/filters/keys. The file should be a soft link to the actual key created using this script.

The soft link and its target can be in different directories. The basename of the linked-to file contains the selector. If the basename starts with the same string as the domain name, then that initial part and an optional dot are discarded. In addition, an extension of ".private" or ".pem" is also discarded. For example, the following will all result in assigning selector sel as the key for example.com:

        example.com -> ../anywhere/sel.private
        example.com -> ../anywhere/sel
        example.com -> ../anywhere/example.com.sel
        example.com -> ../anywhere/example.comsel
        example.com -> ../anywhere/example.com.sel.private
        example.com -> ../anywhere/example.comsel.private
        example.com -> ../anywhere/example.com.sel.pem
        example.com -> ../anywhere/example.comsel.pem
        example.com -> ../anywhere/sel.pem

The public key must be published on the DNS in order to make it possible for remote receivers to verify the signatures. Domain owners should change selector on a regular basis, or whenever they think the private key might have been compromised. The soft link that enables signing with a given private key should be set after publishing the corresponding public key. The file existence is going to be effective on the next message. It is not necessary to restart zdkimfilter for that to take effect.

The DKIM standard provides for other tags, for example <t=y> to signal test mode. See the IANA page for a complete list:

https://www.iana.org/assignments/dkim-parameters/dkim-parameters.xhtml

Additional tags, can be added manually at publication time, like the domain name itself. They don't affect the key.  

The most important option is the selector, "-s", which defines the output file name. Options below are in collating order.

-a

Use the alternative tool, certtool vs openssl. The default is certtool if available at configuration time.

-b bits

Specify key size for RSA keys. The default is 2048. RFC 8301 says:

   Signers MUST use RSA keys of at least 1024 bits for all keys.
   Signers SHOULD use RSA keys of at least 2048 bits.
   Verifiers MUST be able to validate signatures with keys ranging from
   1024 bits to 4096 bits, and they MAY be able to validate signatures
   with larger keys.

-d domain

The signing domain. By default this is set to "example.com". It is only used to generate the DKIM record in selector.txt and can be as well filled in at the time the record is published in the DNS.

-e

Generate an ed25519, not an RSA key.

-h

Print a summary of options.

-D directory

Set the output directory. The default is /local/courier/etc/path/filters/keys.

-s name

The selector name. The default is "default". This determines the basename of the output files, and is also used as the label of the public key DKIM record.

 

/local/courier/etc/path/filters/keys

Default directory for links to private keys.

 

Alessandro Vesely <vesely@tana.it>  

zdkimfilter.conf(5)

Explains each configuration option, excluding those for database.

RFC 6376

DomainKeys Identified Mail (DKIM) signatures.