cdist-contrib/type/__opendkim_genkey/man.rst
evilham ecd10de2d3
[__opendkim*] FreeBSD support and minor fixes
While adding FreeBSD support to the type I noticed various issues:

- We were making sure that the KeyTable and SigningTable were created in
  __opendkim_genkey, but that was being done with the default cdist permissions
  (0400) which could result in issues when reloading the service after privilege
  drop.
  This is addressed by checking that it exists/creating it in __opendkim (just
  once, not once per __opendkim_genkey call) with laxer permissions (0444).
- In __opendkim, the service was being started after the config file was
  installed. This is insufficient as OpenDKIM will refuse to start with the
  generated config if either SigningTable or KeyTable do not exist yet.
- __opendkim_genkey had the implicit assumption that the --directory parameter
  always ended in a slash. This was not documented and error-prone; we are now
  a bit laxer and add the trailing slash if it is missing.
- __opendkim_genkey was not changing permissions for the resulting .txt file.
  This was not critical for it to function, but it was inconsistent.
- As documented in #17, __opendkim allows for a --userid parameter that might
  cause issues with keys generated by __opendkim_genkey.
  This issue has not been addressed yet, but I recommend deprecating the
  --userid parameter.
2022-03-10 20:08:51 +01:00

97 lines
2.4 KiB
ReStructuredText

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. Then, a line with the domain,
selector and keyname in the `$selector._domainkey.$domain` format will be added
to the OpenDKIM key table located at `/etc/opendkim/KeyTable`. Finally, a line
will be added to the OpenDKIM signing table, using either the domain or the
provided key for the `domain:selector:keyfile` value in the table. An existing
key will not be overwritten.
Currently, this type is only implemented for Alpine Linux and FreeBSD.
Please contribute an implementation if you can.
REQUIRED PARAMETERS
-------------------
domain
The domain to generate the key for.
selector
The DKIM selector to generate the key for.
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.
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.
BOOLEAN PARAMETERS
------------------
no-subdomains
Disallows subdomain signing by this key.
unrestricted
Do not restrict this key to email signing usage.
EXAMPLES
--------
.. code-block:: sh
__opendkim \
--socket inet:8891@localhost \
--basedir /var/lib/opendkim \
--canonicalization relaxed/simple \
--subdomains no \
--umask 002 \
--syslog
require='__opendkim' \
__opendkim_genkey default \
--domain example.com \
--selector default
__opendkim_genkey myfoo \
--domain foo.com \
--selector backup
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.