From 2c0cfd358f3856cd1cdf439e7e00ca26769d7dc6 Mon Sep 17 00:00:00 2001 From: Tom Mairs Date: Thu, 13 Jul 2023 06:35:56 +0000 Subject: [PATCH] update dkim info for ed25519 --- docs/userguide/configuration/dkim.md | 55 ++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/userguide/configuration/dkim.md b/docs/userguide/configuration/dkim.md index b97f13a4e..29d832bfd 100644 --- a/docs/userguide/configuration/dkim.md +++ b/docs/userguide/configuration/dkim.md @@ -2,17 +2,14 @@ ## What it is -DomainKeys Identified Mail (DKIM) is a mechanism that allows verification of the source and contents of email messages. Using DKIM, sending domains can include a cryptographic signature in outgoing email messages. A message's signature may be verified by an MTA during transit and by the Mail User Agent (MUA) upon delivery. A verified signature indicates the message was sent by the sending domain and the message was not altered in transit. When a DKIM signature fails verification that indicates the message may have been altered during transit or that the sender is fraudulently using the sending domain name. The DKIM specification is located here: [rfc6376](https://datatracker.ietf.org/doc/html/rfc6376). +DomainKeys Identified Mail (DKIM) is a mechanism that allows verification of the source and contents of email messages. Using DKIM, sending domains can include a cryptographic signature in outgoing email messages. A message's signature may be verified by an MTA during transit and by the Mail User Agent (MUA) upon delivery. A verified signature indicates the message was sent by the sending domain and the message was not altered in transit. When a DKIM signature fails verification that indicates the message may have been altered during transit or that the sender is fraudulently using the sending domain name. -From the RFC ([section 6.2](https://datatracker.ietf.org/doc/html/rfc6376#section-6.2)): -_"Verifiers wishing to communicate the results of verification to other - parts of the mail system may do so in whatever manner they see fit. - For example, implementations might choose to add an email header - field to the message before passing it on. Any such header field - SHOULD be inserted before any existing DKIM-Signature or preexisting - authentication status header fields in the header field block. The - Authentication-Results: header field (RFC5451) MAY be used for this - purpose."_ +The 2011 DKIM specification is located here: [rfc6376](https://datatracker.ietf.org/doc/html/rfc6376). + +The 2018 update reguarding ed25519-sha256 signing algorythm is here: [rfc8463](https://datatracker.ietf.org/doc/html/rfc8463) + +According to the most recent 2018 update, "Signers SHOULD implement and verifiers MUST implement the Ed25519-SHA256 algorithm." +[rfc8463 section 5](https://datatracker.ietf.org/doc/html/rfc8463#section-5) This diagram gives a graphical view of how DKIM works. @@ -48,7 +45,7 @@ When an email is sent by an authorized user within the domain, the DKIM-enabled Generate public and private keys for each signing domain and create the DKIM public key DNS records for those domains. -The OpenSSL cryptography toolkit can be used to generate RSA keys for DKIM. As an example, the following openssl commands are used to generate public and private keys for the a domain you choose with a selector you choose. The files can be stored in any directory such as ~/kumomta/keys/, but the default is /opt/kumomta/etc/dkim/. +The OpenSSL cryptography toolkit can be used to generate RSA or Ed25519 keys for DKIM. The most recent rfc indicates that Ed25519 should be used, but be aware that Ed25519 DKIM support is currently very limited with most email services. RSA keys are also supported and are still more widely accepted. As an example, the following openssl commands are used to generate RSA public and private keys for the a domain you choose with a selector you choose. The files can be stored in any directory such as ~/kumomta/keys/, but the default is /opt/kumomta/etc/dkim/. Replace the domain and selector with your own, then generate signing keys with: ```console @@ -60,9 +57,23 @@ sudo openssl rsa -in /opt/kumomta/etc/dkim/$DOMAIN/$SELECTOR.key -outform PEM -p sudo chown kumod:kumod /opt/kumomta/etc/dkim/$DOMAIN -R ``` +This example shows the same process for Ed25519 keys: + +Replace the domain and selector with your own, then generate signing keys with: +```console +export DOMAIN= +export SELECTOR= +sudo mkdir -p /opt/kumomta/etc/dkim/$DOMAIN +sudo openssl genpkey -algorithm ed25519 -out /opt/kumomta/etc/dkim/$DOMAIN/$SELECTOR.key +sudo openssl pkey -in /opt/kumomta/etc/dkim/$DOMAIN/$SELECTOR.key -pubout -out /opt/kumomta/etc/dkim/$DOMAIN/$SELECTOR.pub +sudo openssl asn1parse -in /opt/kumomta/etc/dkim/$DOMAIN/$SELECTOR.pub -offset 12 -noout -out /opt/kumomta/etc/dkim/$DOMAIN/$SELECTOR.p64 | openssl base64 +sudo chown kumod:kumod /opt/kumomta/etc/dkim/$DOMAIN -R +``` + + Any DKIM verification implementations must support key sizes of 512, 768, 1024, 1536, and 2048 bits. A signer may choose to sign messages using any of these sizes and may use a different size for different selectors. Larger key sizes provide greater security but impose higher CPU costs during message signing and verification. It is not recommended to use a key size lower than 1024 unless absolutely necessary. Note that Google _requires_ senders to sign with a 1024 bit or greater key size. -The resulting public key should look similar to: +The resulting RSA public key should look similar to: ```txt -----BEGIN PUBLIC KEY----- @@ -73,18 +84,32 @@ KPrbKH5ubT9V9pLKawIDAQAB -----END PUBLIC KEY----- ``` +The resulting ed25519 p64 (base64 encoded public key) should look similar to the one below. Notice there is no ASN.1 structure around the key. Use this exactly as it is in the "p" setting in DNS. + +```txt +8IGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDVCpNKu= +``` + Once the public and private keys have been generated, create a DNS text record for ._domainkey. (IE: dkim1024._domainkey.example.com). The DNS record contains several DKIM "tag=value" pairs and should be similiar to the record shown below: +for RSA256: + default._domainkey.example.com. 86400 IN TXT -"v=DKIM1; k=rsa; h=sha256; t=y; p=MIbBa...DaQAB" +"v=DKIM1; k=rsa; h=sha256; p=MIbBa...DaQAB" + +or for ed25519: +default._domainkey.example.com. 86400 IN TXT +"v=DKIM1; k=ed25519; p=8IbBa...DaKu=" + +NOTE: If you plan to use ed25519 keys, plan to double sign messages as many ISPs still are not actively verifying ed25519 signatures. DKIM DNS text record tags are defined below. Do not include the quotes below when including a tag value in the DNS text record. v= DKIM key record version. The value of this tag must be set to "DKIM1". -k= Key type. This tag defines the syntax and semantics of the p= tag value. Currently, this tag should have the value "rsa". +k= Key type. This tag defines the syntax and semantics of the p= tag value. Currently, this tag should have the value "rsa" or "ed25519" as appropriate. -h= Hash algorithm. Currently, this tag should have the value "sha1" or "sha256". +h= Hash algorithm. Currently, this tag should have the value "sha1" or "sha256" if using RSA. t= Flags. The only value currently defined is "y". If specified, this tag indicates the signing domain is testing DKIM.