| Internet-Draft | dkimkeywrapper | October 2022 |
| Jones, Ed. & Selenu | Expires 13 April 2023 | [Page] |
This experimental RFC seeks to document a DKIM key interchange format intended to avoid provisioning errors where different parties are generating keys and publishing DNS records for a given domain.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 13 April 2023.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
DomainKeys Internet Mail (DKIM) requires that an email sending domain publish DKIM public keys in the Domain Name System (DNS) with very specific formatting. But when DKIM keys are published in the DNS with incorrect formatting, all signature validation will fail and the entire deployment may be abandoned.¶
A common reason for this failure mode is that an Email Service Provider (ESP) or other party will generate the DKIM keys for the domain owner, who may not be familiar with DNS management. They then may have to determine how to enter the key data into a user interface provided by a web hosting company. Often they will include formatting characters that should be omitted, or include metadata like the TTL in the payload or RDATA.¶
This Independent Submission proposes a wrapper format for DKIM key information. This format provides a simple block of printable ASCII text, which is much more easily shared without being inadvertently corrupted. And because the format is well-documented, a DNS operator can easily extract the key material and provision the necessary records.¶
The goal of this submission is to solicit partners for a proof-of-concept implementation using this format, to complete testing by mid-2023 at the latest. Experience in the field will show whether this concept warrants further development.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. As each of these terms was intentionally and carefully chosen to improve interoperability, each use of these terms is to be treated as a conformance requirement.¶
Because this proposal discusses the handling of DKIM key material, the terminology will be as close to [RFC6376] as possible. However as some aspects of this proposal may concern actors not fully identified in previous documents, some new elements may be identified.¶
There are so many different "real world" scenarios where different parties are responsible for different functions, that it is easy to cause ambiguity by using common terms. This document will try to use the following role definitions when describing actions.¶
The Domain Owner is the party who controls or owns a given domain, and presumably is seeking to benefit from deploying DKIM.¶
This is the party that has generated the public keypair that will be used for DKIM signing messages. In all likelihood they will also fulfill one of the other roles, like the DNS Operator or an Email Service Provider (ESP).¶
A DNS Operator in this context is the party operating nameservers that are authoritative for the domain where DKIM is being deployed. The DNS Operator may be a website hosting company, or a MailBox Provider (MBP), for example.¶
The Email Sender in this context is a third party sending email on behalf of the Domain Owner. This could be an Email Service Provider, whose primary service is to send email messages; or a vendor primarily providing some other service who happens to also send email.¶
The information inside the wrapper is a series of key/value pairs using the JavaScript Object Notation (JSON) format, as described in [RFC8259]. The set of fields used depends on whether a public or private key is being represented.¶
This data is then encoded as described below.¶
A Key Wrapper consists of Base64 encoded text as described in [RFC4648], and SHOULD have no more than 65 characters per line, appearing between delimiters that identify it as wrapped DKIM key material. The result is very similar in appearance to the PEM format used by OpenSSL and similar software.¶
An encoded key wrapper might look like the following example:¶
-----BEGIN WRAPPED PUBLIC DKIM KEY----- eyJ0eXBlIjoiREtJTS1QVUItS0VZIiwibmFtZSI6ImtleTIwMjIwNTE1IiwidiI6Ik RLSU0xIiwicCI6Ik1JR2ZNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0R05BRENCaVFLQmdR RGVKRE5hYzZnRlR3akx6eWxERWd3dk9sYk5TREcwN3FZR1h5K3hTY3F5aC9jZWIzek R0eHZUZGpTbmFkU09adjJtWFRqZGI3N2U1eWlJaWZLbVJBZ2ZhaHF6c0dKUXEyUmRv c2NZNkdYMThMWmxjNnNYSGJwREU0QzNaTFJoRlFHQzF0T29xU0Z5aEZya0VBeFltV2 Q2cElNajVnNWd2V3lJUm40U3p6Z3hzd0lEQVFBQiIsImsiOiJyc2EifQo= -----END WRAPPED PUBLIC DKIM KEY-----¶
In order to help users avoid inadvertant disclosure of private keys, the tags surrounding encoded keys should indicate which type of key it contains.¶
Public keys should use the string "WRAPPED PUBLIC DKIM KEY", preceded by the strings "BEGIN" or "END" depending on their position relative to the encoded data.¶
Private keys should use the string "WRAPPED PRIVATE DKIM KEY", preceded by the strings "BEGIN" or "END" depending on their position relative to the encoded data.¶
The JSON formatted data consists of key/value pairs. Which keys appear in a given wrapper will depend on what type of key material is being represented.¶
This following sections document the names of the fields that appear in the JSON formatted data. Some fields correspond to the "tags" defined for the DNS TXT RR binding in [RFC6376] Section 3.6.¶
This field may include contact information for the Key Generator or the Domain Owner. It is intended to be brief, and might typically include an organization name, email address, telephone number, or URI.¶
Example:¶
"contact": "Hosting Company Key Services, keys@example.com, +1-123-555-1212"¶
This is the Internet domain or sub-domain that the key was generated for.¶
Example:¶
"domain": "example.com"¶
The key type. Historically this has almost always been "rsa", but new key types are being used more often on the Internet.¶
Example:¶
"k": "edd25519"¶
The common name of the key. For a DKIM public key where the full DNS label is "selector._domainkey.example.com", the value of the name field would be "selector".¶
Example:¶
"name": "selector"¶
The public key data, the actual key material. This is formatted as
described in [@RFC6376, see section 3.6.1].¶
Example:¶
"p": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDeJDNac6gFTwjLzylDEgwvOlbNSDG07qYGXy+xScqyh/ceb3zDtxvTdjSnadSOZv2mXTjdb77e5yiIifKmRAgfahqzsGJQq2RdoscY6GX18LZlc6sXHbpDE4C3ZLRhFQGC1tOoqSFyhFrkEAxYmWd6pIMj5g5gvWyIRn4SzzgxswIDAQAB"¶
The private key data. This is formatted in the manner for public key data ("p=" tag) described in [@RFC6376, see section 3.6.1].¶
Example:¶
"r": "MIIBOwIBAAJBAODmxiUEZdxP34cYT1g2p7NvZkOKwdkOcjQljOFikQgZXSAwTWdgnsedt1V7V37Bc9iO3cUQSESKRGZCCz1CbD0CAwEAAQJBAKZe8Vt26mdVCvVkLWYDYIGjuhHi9s28Gw2qbZJZmRJUVgSG7mJItIN7FMTdjBRU9GoYgbtdnyE36nOiRZUlzEECIQDxoVuwBvwo8xIMBuLdhFrBHjPBBzY+M9y6mgiyi54ksQIhAO5Gu0utP5qg5mKs1WWfbLVnpNKS0djF9a+2ql9ojFNNAiEApOMJoFuD46XLoO1qDuPs0m/7vTNgrp3ReHz4hm6EImECIFucLDSLVpHv3MQBaUZaBiS0xYUEV9P9QFmfZF+sRY9dAiBIdJ7uoXHG8l3zaFX1v0qxUI9KTRB92mDK6nxG+OPzGQ=="¶
This field reflects the size of the key in bits, and is intended for informational purposes. It is much easier to glance at this field, than extract the key material and determine the key size programmatically.¶
Example:¶
"size": "1024"¶
This field indicates the type of key material encoded in this file. Examples are "DKIM-PUB-KEY" and "DKIM-PRIV-KEY". The value of this field determines what other fields must be present.¶
Valid values are currently "DKIM-PUB-KEY" and "DKIM-PRIV-KEY". The use of any other value means that the entire record MUST be ignored.¶
Example:¶
"type": "DKIM-PUB-KEY"¶
There are two record types defined, which correspond to public and private keys. Each type requires a specific set of data fields. Any fields not included for a given record type below MUST be ignored.¶
This record type presents DKIM public key data. It is the type of record that would be given to a DNS Operator for publication as a DNS TXT RR.¶
Required fields:¶
Optional fields:¶
Example:¶
{
"contact": "Hosting Company Key Services, keys@example.com, +1-123-555-1212",
"domain": "example.com",
"k": "rsa",
"name": "selector",
"p": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDeJDNac6gFTwjLzylDEgwvOlbNSDG07qYGXy+xScqyh/ceb3zDtxvTdjSnadSOZv2mXTjdb77e5yiIifKmRAgfahqzsGJQq2RdoscY6GX18LZlc6sXHbpDE4C3ZLRhFQGC1tOoqSFyhFrkEAxYmWd6pIMj5g5gvWyIRn4SzzgxswIDAQAB",
"size": "2048",
"type": "DKIM-PUB-KEY",
"v": "DKIM1"
}
¶
This record type presents the DKIM private key data. It is the type of record that would be given to an Email Sender, who needs the private key to produce DKIM signatures for email messages being sent.¶
Required fields:¶
Optional fields:¶
Example:¶
{
"contact": "Hosting Company Key Services, keys@example.com, +1-123-555-1212",
"domain": "example.com",
"k": "rsa",
"name": "selector",
"r": "MIIBOwIBAAJBAODmxiUEZdxP34cYT1g2p7NvZkOKwdkOcjQljOFikQgZXSAwTWdgnsedt1V7V37Bc9iO3cUQSESKRGZCCz1CbD0CAwEAAQJBAKZe8Vt26mdVCvVkLWYDYIGjuhHi9s28Gw2qbZJZmRJUVgSG7mJItIN7FMTdjBRU9GoYgbtdnyE36nOiRZUlzEECIQDxoVuwBvwo8xIMBuLdhFrBHjPBBzY+M9y6mgiyi54ksQIhAO5Gu0utP5qg5mKs1WWfbLVnpNKS0djF9a+2ql9ojFNNAiEApOMJoFuD46XLoO1qDuPs0m/7vTNgrp3ReHz4hm6EImECIFucLDSLVpHv3MQBaUZaBiS0xYUEV9P9QFmfZF+sRY9dAiBIdJ7uoXHG8l3zaFX1v0qxUI9KTRB92mDK6nxG+OPzGQ=="
"size": "2048",
"type": "DKIM-PRIV-KEY",
"v": "DKIM1"
}
¶
This proposal does not attempt to mandate a specific file naming convention. Filenames SHOULD use a standard filename extension, described below. The main file name may be whatever is sensible to the party creating or using the file.¶
Example:¶
There is a well-established practice of using so-called filename extensions to indicate what the contents of a file are. For example, ".txt" indicating a file containing some kind of text, or ".pem" indicating that a file contains PEM encoded certificate data.¶
Users of this proposal SHOULD use the filename extension ".wdkim" to indicate the contents are a wrapped DKIM key.¶
Each file SHOULD contain a single wrapped DKIM key block.¶
Users that wish to store more than one wrapped key per file are strongly urged to only combine the public and private key of the same keypair in a single file.¶
Combined files that contain private keys pose a significant risk if they are disclosed unintentionally. Users are advised to treat any combined files containing private keys as they would treat the private key alone.¶
TODO IANA¶
How sensitive information is handled is not dictated by a file format.¶
DKIM uses keypairs, with both a public and private key. Any standardized representation of one can very easily support the other. From the perspective of a standard that represents DKIM keys, why wouldn't it make sense to represent private keys?¶
Parties handling large numbers of DKIM keys may benefit from using a standardized format. Indeed, they may have a need to archive the public and private keys for a given client or instance together.¶
Possession of private DKIM keys allows an actor to send email posing as the associated domain that successfully passes DKIM checks. As a result they need to be treated as very sensitive credentials, and protected accordingly.¶
While combined files containing both the public and private DKIM keys may be attractive from, for example, an archival perspective, there is always a risk that a party intending to share only the public key will send the combined file. Users are again strongly encouraged to keep private keys separate.¶
TODO rsa key¶
TODO ec key¶
The following sequence shows a user on a UNIX-like system manually decoding a Wrapped DKIM Key using common command-line tools.¶
212 host$ cat sample-public-key.wdkim -----BEGIN WRAPPED PUBLIC DKIM KEY----- eyJ0eXBlIjoiREtJTS1QVUItS0VZIiwibmFtZSI6ImtleTIwMjIwNTE1IiwidiI6Ik RLSU0xIiwicCI6Ik1JR2ZNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0R05BRENCaVFLQmdR RGVKRE5hYzZnRlR3akx6eWxERWd3dk9sYk5TREcwN3FZR1h5K3hTY3F5aC9jZWIzek R0eHZUZGpTbmFkU09adjJtWFRqZGI3N2U1eWlJaWZLbVJBZ2ZhaHF6c0dKUXEyUmRv c2NZNkdYMThMWmxjNnNYSGJwREU0QzNaTFJoRlFHQzF0T29xU0Z5aEZya0VBeFltV2 Q2cElNajVnNWd2V3lJUm40U3p6Z3hzd0lEQVFBQiIsImsiOiJyc2EifQo= -----END WRAPPED PUBLIC DKIM KEY----- 213 host%¶
In the following example, "base64" is a command line utility that performs base64 encoding and decoding. "awk" is a common text processing utility, used here to extract the delimiter lines. "jq" is a common command line JSON processor.¶
TODO: Which decoding example?
$ egrep -v '^-----' sample-public-key.wdkim | base64 -d - | jq .
{
"contact": "Hosting Company Key Services, keys@example.com, +1-123-555-1212",
"domain": "example.com",
"k": "rsa",
"name": "selector",
"p": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDeJDNac6gFTwjLzylDEgwvOlbNSDG07qYGXy+xScqyh/ceb3zDtxvTdjSnadSOZv2mXTjdb77e5yiIifKmRAgfahqzsGJQq2RdoscY6GX18LZlc6sXHbpDE4C3ZLRhFQGC1tOoqSFyhFrkEAxYmWd6pIMj5g5gvWyIRn4SzzgxswIDAQAB",
"size": "2048",
"type": "DKIM-PUB-KEY",
"v": "DKIM1"
}
214 host$
¶
M3AAWG (www.m3aawg.org) supports a DKIM Enablement initiative, and on-going discussion by participants around DKIM provisioning. The authors are grateful for the support of this organization.¶
Todd Herr¶
Todd Herr solicited interested parties to shepherd the DKIM Enablement topic at the M3AAWG meeting in February 2022, and the authors put their names forward. This proposal came out of a suggestion made in a M3AAWG Slack channel, and subsequent discussions between these gentlemen.¶
[RFC Editor: Please remove this section prior to publicaion.]¶
TODO Change Log¶