chore: Change setup config dkim default key size to 2048 (open-dkim) (#3508)

* chore: Adjust default DKIM size (`open-dkim`) from 4096-bit to 2048-bit

4096-bit is excessive in size for DKIM key. 2048-bit is plenty.

* chore: Additional revisions to `open-dkim` command help output

- The examples use `keysize 2048`, but as that's the new default it makes sense to change that.
- Other help text was also revised.
- Last example for domains did not need to demonstrate the other options. Changed example domains to more appropriate values.

* docs: Revise DKIM docs

Primarily for the change in default key size, but does revise some text to better communicate to the user.
- While the referenced RFC advises 512-bit to 2048-bit key size, we now explicitly discourage `512-bit` as it's not secure. `1024-bit` is still likely safe for most, but `2048-bit` is a good default for those not rotating their keys.
- Adjusted the domains example to match the new `setup config dkim domain` domains example.
- Tip for changing default key size changed to "info" with added clarity of lowering security or increasing it (excessively).
- Rspamd section is minor formatting changes, with the exception of clarifying the "main domain" for the mail accounts is assumed as the DMS FQDN with any subdomain (like `mail.`) stripped away. This is not great, but a legacy issue that needs to be addressed in future.
- `docs-rspamd-override-d` ref removed, and usage replaced with equivalent ref `docs-rspamd-config-dropin`, while `docs-rspamd-config-declarative` ref was not in use and also removed.
- Revised the `<selector>.txt` DNS formatting info section to better communicate with the reader. Additionally it had mixed usage of default `mail` and custom `dkim-rsa` selectors (_file content and output_).

* docs: Sync DKIM commands help messages and update DKIM docs for LDAP

- Adopt the help options format style from the `rspamd-dkim` into `open-dkim` command. And convert `./setup.sh` to `setup`. `selector` option has been implemented. for a while now.
- Update `rspamd-dkim` examples help output to align with `open-dkim` command examples.
- Give both DKIM command tools a consistent description. The two tools differ in support for the `domain` option (_implicit domain sourcing for default account provisioner, and support for multiple domains as input_).
- DKIM docs for LDAP domain support revised to better communicate when explicit domain config is necessary.

* tests: Adjust test-cases for `setup config dkim` change

`rspamd_dkim.bats`:
- Update assert for command help output.
- Don't bother creating a DKIM key at 512-bit size.

`setup_cli.bats`:
- Update assert for command help output of the `setup config dkim` (OpenDKIM) command.

* docs: Update DKIM section for large keys to newer RFC

The linked discussion from 2021 does mention this updated RFC over the original. That removes outdated advice about `512-bit` key length support.

The discussion link is still kept to reference a comment for the reader to better understand the security strength of 2048-bit RSA keys and why larger keys are not worthwhile, especially for DKIM.

* docs: Extract out common DKIM generation command from content tabs

Should be fine to be DRY here, not specific to `open-dkim` or `rspamd` generation/support. Previously rspamd lacked support of an equivalent command in DMS.

* docs: DKIM refactoring

- Shifted out the info admonition on key size advice out of the content tabs as it's now generic information.
- Indented the 4096-bit warning into this, which is less of a concern as the default for our DKIM generation tools is consistently 2048-bit now.
- Reworked the LDAP and Rspamd multi-domain advice. To avoid causing a bad diff, these sections haven't been moved/merged yet.

* docs: Revise DKIM docs

Advice for managing domains individually with LDAP and Rspamd extracted out of the content tabs. Default domain behaviour explained with extra info about OpenDKIM + FILE provisioner sourcing extra domains implicitly.
This commit is contained in:
Brennan Kinney 2023-08-29 09:40:02 +12:00 committed by GitHub
parent 855d9acb53
commit e9f04cf8a7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 115 additions and 102 deletions

View file

@ -8,7 +8,7 @@ if [[ -f /etc/dms-settings ]] && [[ $(_get_dms_env_value 'ENABLE_RSPAMD') -eq 1
exit
fi
KEYSIZE=4096
KEYSIZE=2048
SELECTOR=mail
DOMAINS=
@ -16,37 +16,40 @@ function __usage() {
printf '%s' "${PURPLE}OPEN-DKIM${RED}(${YELLOW}8${RED})
${ORANGE}NAME${RESET}
open-dkim - configure DomainKeys Identified Mail (DKIM)
open-dkim - Configure DKIM (DomainKeys Identified Mail)
${ORANGE}SYNOPSIS${RESET}
./setup.sh config dkim [ OPTIONS${RED}...${RESET} ]
setup config dkim [ OPTIONS${RED}...${RESET} ]
${ORANGE}DESCRIPTION${RESET}
Configures DKIM keys. OPTIONS can be used to configure a more complex setup.
LDAP setups require these options.
Creates DKIM keys and configures them within DMS for OpenDKIM.
OPTIONS can be used when your requirements are not met by the defaults.
When not using 'ACCOUNT_PROVISIONER=FILE' (default), you may need to explicitly
use the 'domain' option to generate DKIM keys for your mail account domains.
${ORANGE}OPTIONS${RESET}
${BLUE}Generic Program Information${RESET}
help Print the usage information.
help Print the usage information.
${BLUE}Configuration adjustments${RESET}
keysize Set the size of the keys to be generated. Possible are 1024, 2048 and 4096 (default).
selector Set a manual selector (default is 'mail') for the key. (${LCYAN}ATTENTION${RESET}: NOT IMPLEMENTED YET!)
domain Provide the domain(s) for which keys are to be generated.
keysize Set the size of the keys to be generated.
Possible values: 1024, 2048 and 4096
Default: 2048
selector Set a manual selector for the key.
Default: mail
domain Provide the domain(s) for which to generate keys for.
Default: The FQDN assigned to DMS, excluding any subdomain.
'ACCOUNT_PROVISIONER=FILE' also sources domains from mail accounts.
${ORANGE}EXAMPLES${RESET}
${LWHITE}./setup.sh config dkim keysize 2048${RESET}
Creates keys of length 2048 bit in a default setup where domains are obtained from
your accounts.
${LWHITE}setup config dkim keysize 4096${RESET}
Creates keys with their length increased to a size of 4096-bit.
${LWHITE}./setup.sh config dkim keysize 2048 selector 2021-dkim${RESET}
Creates keys of length 2048 bit in a default setup where domains are obtained from
your accounts. The DKIM selector used is '2021-dkim'.
${LWHITE}setup config dkim keysize 1024 selector 2023-dkim${RESET}
Creates 1024-bit sized keys, and changes the DKIM selector to '2023-dkim'.
${LWHITE}./setup.sh config dkim keysize 2048 selector 2021-dkim domain 'whoami.com,whoareyou.org'${RESET}
Appropriate for an LDAP setup. Creates keys of length 2048 bit in a default setup
where domains are obtained from your accounts. The DKIM selector used is '2021-dkim'.
The domains for which DKIM keys are generated are 'whoami.com' and 'whoareyou.org'.
${LWHITE}setup config dkim domain 'example.com,another-example.com'${RESET}
Only generates DKIM keys for the specified domains: 'example.com' and 'another-example.com'.
${ORANGE}EXIT STATUS${RESET}
Exit status is 0 if command was successful. If wrong arguments are provided or arguments contain

View file

@ -16,14 +16,14 @@ function __usage() {
echo -e "${PURPLE}RSPAMD-DKIM${RED}(${YELLOW}8${RED})
${ORANGE}NAME${RESET}
rspamd-dkim - Configure DomainKeys Identified Mail (DKIM) via Rspamd
rspamd-dkim - Configure DKIM (DomainKeys Identified Mail)
${ORANGE}SYNOPSIS${RESET}
setup config dkim [ OPTIONS${RED}...${RESET} ]
${ORANGE}DESCRIPTION${RESET}
This script aids in creating DKIM signing keys. The keys are created and managed by Rspamd.
OPTIONS can be used to configure a more complex setup.
Creates DKIM keys and configures them within DMS for Rspamd.
OPTIONS can be used when your requirements are not met by the defaults.
${ORANGE}OPTIONS${RESET}
${BLUE}Generic Program Information${RESET}
@ -32,30 +32,27 @@ ${ORANGE}OPTIONS${RESET}
help Print the usage information.
${BLUE}Configuration adjustments${RESET}
keytype Set the type of key you want to use
keytype Set the type of key you want to use.
Possible values: rsa, ed25519
Default: rsa
keysize Set the size of the keys to be generated
keysize Set the size of the keys to be generated.
Possible values: 1024, 2048 and 4096
Default: 2048
Only applies when using keytype=rsa
selector Set a manual selector for the key
selector Set a manual selector for the key.
Default: mail
domain Provide the domain for which keys are to be generated
Default: primary domain name of DMS
domain Provide the domain for which to generate keys for.
Default: The FQDN assigned to DMS, excluding any subdomain.
${ORANGE}EXAMPLES${RESET}
${LWHITE}setup config dkim keysize 2048${RESET}
Creates keys of length 2048 bit in a default setup where domains are obtained from
your accounts.
${LWHITE}setup config dkim keysize 4096${RESET}
Creates keys with their length increased to a size of 4096-bit.
${LWHITE}setup config dkim keysize 512 selector 2023-dkim${RESET}
Creates keys of length 512 bit in a default setup where domains are obtained from
your accounts. The DKIM selector used is '2023-dkim'.
${LWHITE}setup config dkim keysize 1024 selector 2023-dkim${RESET}
Creates 1024-bit sized keys, and changes the DKIM selector to '2023-dkim'.
${LWHITE}setup config dkim keysize 1024 selector 2023-dkim domain whoami.com${RESET}
Creates keys of length 1024 bit in a default setup where domains are obtained from your accounts.
The DKIM selector used is '2023-dkim'. The domain for which DKIM keys are generated is whoami.com.
${LWHITE}setup config dkim domain example.com${RESET}
Generate the DKIM key for a different domain (example.com).
${ORANGE}EXIT STATUS${RESET}
Exit status is 0 if command was successful. If wrong arguments are provided or arguments contain