Internet DRAFT - draft-jones-dkim-key-wrapper
draft-jones-dkim-key-wrapper
Network Working Group S. Jones, Ed.
Internet-Draft DMARC.org
Intended status: Experimental N. Selenu
Expires: 13 April 2023 ActiveCampaign
10 October 2022
DKIM Key Wrapper Format
draft-jones-dkim-key-wrapper-00
Abstract
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.
Status of This Memo
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 Notice
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.
Jones, Ed. & Selenu Expires 13 April 2023 [Page 1]
Internet-Draft dkimkeywrapper October 2022
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Document Conventions . . . . . . . . . . . . . . . . . . 3
2. Terminology and Definitions . . . . . . . . . . . . . . . . . 3
2.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1. Domain Owner . . . . . . . . . . . . . . . . . . . . 4
2.1.2. Key Generator . . . . . . . . . . . . . . . . . . . . 4
2.1.3. DNS Operator . . . . . . . . . . . . . . . . . . . . 4
2.1.4. Email Sender . . . . . . . . . . . . . . . . . . . . 4
3. Wrapper Format . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.1. Public versus Private Keys . . . . . . . . . . . . . 5
3.2. Data Fields . . . . . . . . . . . . . . . . . . . . . . . 5
3.2.1. contact . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.2. domain . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.3. k . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.4. name . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.5. p . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.6. r . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.7. size . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.8. type . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.9. v . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3. Record Types . . . . . . . . . . . . . . . . . . . . . . 7
3.3.1. DKIM-PUB-KEY . . . . . . . . . . . . . . . . . . . . 8
3.3.2. DKIM-PRIV-KEY . . . . . . . . . . . . . . . . . . . . 8
3.4. Filenames . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4.1. Filename Extensions . . . . . . . . . . . . . . . . . 9
3.5. File Contents . . . . . . . . . . . . . . . . . . . . . . 9
3.5.1. Combined Files . . . . . . . . . . . . . . . . . . . 10
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5.1. Why Support Private Keys? . . . . . . . . . . . . . . . . 10
5.2. Private Key Disclosure . . . . . . . . . . . . . . . . . 10
6. Normative References . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11
A.1. An RSA Key . . . . . . . . . . . . . . . . . . . . . . . 11
A.2. An Elliptic Curve Key . . . . . . . . . . . . . . . . . . 11
A.3. Manually Decoding A Wrapped Key . . . . . . . . . . . . . 11
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 12
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
Jones, Ed. & Selenu Expires 13 April 2023 [Page 2]
Internet-Draft dkimkeywrapper October 2022
1. Introduction
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.
1.1. Goals
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.
1.2. Document Conventions
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.
2. Terminology and Definitions
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.
Jones, Ed. & Selenu Expires 13 April 2023 [Page 3]
Internet-Draft dkimkeywrapper October 2022
2.1. Roles
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.
2.1.1. Domain Owner
The Domain Owner is the party who controls or owns a given domain,
and presumably is seeking to benefit from deploying DKIM.
2.1.2. Key Generator
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).
2.1.3. DNS Operator
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.
2.1.4. Email Sender
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.
3. Wrapper Format
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.
Jones, Ed. & Selenu Expires 13 April 2023 [Page 4]
Internet-Draft dkimkeywrapper October 2022
3.1. Encoding
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-----
3.1.1. Public versus Private Keys
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.
3.2. Data Fields
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.
Jones, Ed. & Selenu Expires 13 April 2023 [Page 5]
Internet-Draft dkimkeywrapper October 2022
3.2.1. contact
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"
3.2.2. domain
This is the Internet domain or sub-domain that the key was generated
for.
Example:
"domain": "example.com"
3.2.3. k
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"
3.2.4. name
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"
3.2.5. p
The *p*ublic key data, the actual key material. This is formatted as
described in [@RFC6376, see section 3.6.1].
Example:
"p": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDeJDNac6gFTwjLzylDEgwvOlbNSDG07qYGXy+xScqyh/ceb3zDtxvTdjSnadSOZv2mXTjdb77e5yiIifKmRAgfahqzsGJQq2RdoscY6GX18LZlc6sXHbpDE4C3ZLRhFQGC1tOoqSFyhFrkEAxYmWd6pIMj5g5gvWyIRn4SzzgxswIDAQAB"
Jones, Ed. & Selenu Expires 13 April 2023 [Page 6]
Internet-Draft dkimkeywrapper October 2022
3.2.6. r
The p*r*ivate 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=="
3.2.7. size
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"
3.2.8. type
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"
3.2.9. v
The version of the DKIM key. This is the same value as specified for
the "v=" tag in [@RFC6376, see section 3.6.1], with all the
corresponding normative constraints.
Example:
"v": "DKIM1"
3.3. Record Types
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.
Jones, Ed. & Selenu Expires 13 April 2023 [Page 7]
Internet-Draft dkimkeywrapper October 2022
3.3.1. DKIM-PUB-KEY
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:
* k
* name
* p
* type
* v
Optional fields:
* contact
* domain
* size
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"
}
3.3.2. DKIM-PRIV-KEY
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:
* k
* name
* r
* type
* v
Optional fields:
Jones, Ed. & Selenu Expires 13 April 2023 [Page 8]
Internet-Draft dkimkeywrapper October 2022
* contact
* domain
* size
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"
}
3.4. Filenames
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:
* example.com-public-20220921.wdkim
* EnterpriseName-keyname.wdkim
* pubkey-example.net-20220831.wdkim
3.4.1. Filename Extensions
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.
3.5. File Contents
Each file SHOULD contain a single wrapped DKIM key block.
Jones, Ed. & Selenu Expires 13 April 2023 [Page 9]
Internet-Draft dkimkeywrapper October 2022
3.5.1. Combined Files
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.
4. IANA Considerations
TODO IANA
5. Security Considerations
5.1. Why Support Private Keys?
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.
5.2. Private Key Disclosure
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.
6. Normative References
Jones, Ed. & Selenu Expires 13 April 2023 [Page 10]
Internet-Draft dkimkeywrapper October 2022
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
[RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed.,
"DomainKeys Identified Mail (DKIM) Signatures", STD 76,
RFC 6376, DOI 10.17487/RFC6376, September 2011,
<https://www.rfc-editor.org/info/rfc6376>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
Appendix A. Examples
A.1. An RSA Key
TODO rsa key
A.2. An Elliptic Curve Key
TODO ec key
A.3. Manually Decoding A Wrapped 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%
Jones, Ed. & Selenu Expires 13 April 2023 [Page 11]
Internet-Draft dkimkeywrapper October 2022
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$
Appendix B. Acknowledgements
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.
Appendix C. Change Log
[RFC Editor: Please remove this section prior to publicaion.]
TODO Change Log
Authors' Addresses
Steven M Jones
DMARC.org
Email: smj@dmarc.org
Nicola Selenu
ActiveCampaign
Jones, Ed. & Selenu Expires 13 April 2023 [Page 12]
Internet-Draft dkimkeywrapper October 2022
Email: votan.nospam@gmail.com
Jones, Ed. & Selenu Expires 13 April 2023 [Page 13]
