cdist-type__opendkim_genkey(7)
==============================

NAME
----
cdist-type__opendkim_genkey - Generate DKIM keys suitable for OpenDKIM


DESCRIPTION
-----------

This type uses the `opendkim-genkey(8)` to generate signing keys suitable for
usage by `opendkim(8)` to sign outgoing emails.

It also manages the key, identified by its `$__object_id` in OpenDKIM's
KeyTable and sets its `s=` and `d=` parameters (see: `--selector` and
`--sigdomain` respectively).

This type will also manage the entries in the OpenDKIM's SigningTable by
associating any given `sigkey` values to this key.

Take into account that if you use this type without the `--domain` and
`--selector` parameters, the `$__object_id` must be in form `$domain/$selector`.

Currently, this type is only implemented for Alpine Linux and FreeBSD.
Please contribute an implementation if you can.

NOTE: the name of the key file under `--directory` will default to
`$__object_id.private`, but if that fails and `--selector` is used,
`SELECTOR.private` will be considered.
Take care when using unrelated keys that might collide this way.
For more information see:
https://code.ungleich.ch/ungleich-public/cdist-contrib/issues/20


OPTIONAL PARAMETERS
-------------------
bits
  The size of the generated key, in bits. The default is 1024, the recommended
  by the DKIM standard.

directory
  The directory in which to generate the key, `/var/db/dkim/` by default.

domain
  The domain to generate the key for.
  If omitted, `--selector` must be omitted as well and `$__object_id` must be
  in form: `$domain/$selector`.

selector
  The DKIM selector to generate the key for.
  If omitted, `--domain` must be omitted as well and `$__object_id` must be
  in form: `$domain/$selector`.

sigdomain
  Specified in the KeyTable, the domain to use in the signature's "d=" value.
  Defaults to the specified domain. If `%`, it will be replaced by the apparent
  domain of the sender when generating a signature.
  Note you probably don't want to set both `--sigdomain` and `--sigkey` to `%`.
  See `KeyTable` in `opendkim.conf(5)` for more information.


OPTIONAL MULTIPLE PARAMETERS
----------------------------
sigkey
  The key used in the `SigningTable` for this signing key. Defaults to the
  specified domain. If `%`, OpenDKIM will replace it with the domain found
  in the `From:` header. See `opendkim.conf(5)` for more options.
  Note you probably don't want to set both `--sigdomain` and `--sigkey` to `%`.
  This can be passed multiple times, resulting in multiple lines in the
  SigningTable, which can be used to support signing of subdomains or multiple
  domains with the same key; in that case, you probably want to set
  `--sigdomain` to `%`, else the domains will not be aligned.


BOOLEAN PARAMETERS
------------------
no-subdomains
  Disallows subdomain signing by this key.

unrestricted
  Do not restrict this key to email signing usage.


EXAMPLES
--------

.. code-block:: sh

    # Setup the OpenDKIM service
    __opendkim \
        --socket inet:8891@localhost \
        --basedir /var/lib/opendkim \
        --canonicalization relaxed/simple \
        --subdomains no \
        --umask 002 \
        --syslog

    # Continue only after the service has been set up
    export require="__opendkim"

    # Generate a key for 'example.com' with selector 'default'
    __opendkim_genkey default \
        --domain example.com \
        --selector default

    # Generate a key for 'foo.com' with selector 'backup'
    __opendkim_genkey 'foo.com/backup'

    # Generate a key for 'example.org' with selector 'main'
    # that can also sign 'cdi.st' and subdomains of 'example.org'
    __opendkim_genkey 'example.org/main' \
        --sigdomain '%' \
        --sigkey 'example.org' \
        --sigkey '.example.org' \
        --sigkey 'cdi.st'


SEE ALSO
--------
`opendkim(8)`
`opendkim-genkey(8)`
`cdist-type__opendkim(7)`


AUTHORS
-------
Joachim Desroches <joachim.desroches@epfl.ch>
Evilham <contact@evilham.com>


COPYING
-------
Copyright \(C) 2022 Joachim Desroches, Evilham. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.