zdkimgenkey(8)

NAME
zdkimgenkey - DKIM key generator

SYNOPSIS
zdkimgenkey [option...]

DESCRIPTION
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 /etc/courier/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 /etc/courier/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.

OPTIONS
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 /etc/courier/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.

FILES

/etc/courier/filters/keys
    Default directory for links to private keys.

AUTHOR
Alessandro Vesely <vesely@tana.it>

SEE ALSO

zdkimfilter.conf(5)
    Explains each configuration option, excluding those for database.

RFC 6376
    DomainKeys Identified Mail (DKIM) signatures.