Skip to main content

3.6 Key Management and Representation

3.6. Key Management and Representation​

Signature applications require some level of assurance that the verification public key is associated with the claimed Signer. Many applications achieve this by using public-key certificates issued by a trusted third party. However, DKIM can achieve a sufficient level of security, with significantly enhanced scalability, by simply having the Verifier query the purported Signer's DNS entry (or some security-equivalent) in order to retrieve the public key.

DKIM keys can potentially be stored in multiple types of key servers and in multiple formats. The storage and format of keys are irrelevant to the remainder of the DKIM algorithm.

Parameters to the key lookup algorithm are the type of the lookup (the "q=" tag), the domain of the Signer (the "d=" tag of the DKIM-Signature header field), and the selector (the "s=" tag).

public_key = dkim_find_key(q_val, d_val, s_val)

This document defines a single binding, using DNS TXT RRs to distribute the keys. Other bindings may be defined in the future.

3.6.1. Textual Representation​

It is expected that many key servers will choose to present the keys in an otherwise unstructured text format (for example, an XML form would not be considered to be unstructured text for this purpose). The following definition MUST be used for any DKIM key represented in an otherwise unstructured textual form.

The overall syntax is a tag-list as described in Section 3.2. The current valid tags are described below. Other tags MAY be present and MUST be ignored by any implementation that does not understand them.

v= Version of the DKIM key record (plain-text; RECOMMENDED, default is "DKIM1"). If specified, this tag MUST be set to "DKIM1" (without the quotes). This tag MUST be the first tag in the record. Records beginning with a "v=" tag with any other value MUST be discarded. Note that Verifiers must do a string comparison on this value; for example, "DKIM1" is not the same as "DKIM1.0".

ABNF:

key-v-tag    = %x76 [FWS] "=" [FWS] %x44.4B.49.4D.31

h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to allowing all algorithms). A colon-separated list of hash algorithms that might be used. Unrecognized algorithms MUST be ignored. Refer to Section 3.3 for a discussion of the hash algorithms implemented by Signers and Verifiers. The set of algorithms listed in this tag in each record is an operational choice made by the Signer.

ABNF:

key-h-tag       = %x68 [FWS] "=" [FWS] key-h-tag-alg
                  *( [FWS] ":" [FWS] key-h-tag-alg )
key-h-tag-alg   = "sha1" / "sha256" / x-key-h-tag-alg
x-key-h-tag-alg = hyphenated-word   ; for future extension

k= Key type (plain-text; OPTIONAL, default is "rsa"). Signers and Verifiers MUST support the "rsa" key type. The "rsa" key type indicates that an ASN.1 DER-encoded [ITU-X660-1997] RSAPublicKey (see [RFC3447], Sections 3.1 and A.1.1) is being used in the "p=" tag. (Note: the "p=" tag further encodes the value using the base64 algorithm.) Unrecognized key types MUST be ignored.

ABNF:

key-k-tag        = %x76 [FWS] "=" [FWS] key-k-tag-type
key-k-tag-type   = "rsa" / x-key-k-tag-type
x-key-k-tag-type = hyphenated-word   ; for future extension

n= Notes that might be of interest to a human (qp-section; OPTIONAL, default is empty). No interpretation is made by any program. This tag should be used sparingly in any key server mechanism that has space limitations (notably DNS). This is intended for use by administrators, not end users.

ABNF:

key-n-tag    = %x6e [FWS] "=" [FWS] qp-section

p= Public-key data (base64; REQUIRED). An empty value means that this public key has been revoked. The syntax and semantics of this tag value before being encoded in base64 are defined by the "k=" tag.

INFORMATIVE RATIONALE: If a private key has been compromised or otherwise disabled (e.g., an outsourcing contract has been terminated), a Signer might want to explicitly state that it knows about the selector, but all messages using that selector should fail verification. Verifiers SHOULD return an error code for any DKIM-Signature header field with a selector referencing a revoked key. (See Section 6.1.2 for details.)

ABNF:

key-p-tag    = %x70 [FWS] "=" [ [FWS] base64string]

INFORMATIVE NOTE: A base64string is permitted to include whitespace (FWS) at arbitrary places; however, any CRLFs must be followed by at least one WSP character. Implementers and administrators are cautioned to ensure that selector TXT RRs conform to this specification.

s= Service Type (plain-text; OPTIONAL; default is "*"). A colon-separated list of service types to which this record applies. Verifiers for a given service type MUST ignore this record if the appropriate type is not listed. Unrecognized service types MUST be ignored. Currently defined service types are as follows:

  • * matches all service types
  • email electronic mail (not necessarily limited to SMTP)

This tag is intended to constrain the use of keys for other purposes, should use of DKIM be defined by other services in the future.

ABNF:

key-s-tag        = %x73 [FWS] "=" [FWS] key-s-tag-type
                   *( [FWS] ":" [FWS] key-s-tag-type )
key-s-tag-type   = "email" / "*" / x-key-s-tag-type
x-key-s-tag-type = hyphenated-word   ; for future extension

t= Flags, represented as a colon-separated list of names (plain-text; OPTIONAL, default is no flags set). Unrecognized flags MUST be ignored. The defined flags are as follows:

  • y This domain is testing DKIM. Verifiers MUST NOT treat messages from Signers in testing mode differently from unsigned email, even should the signature fail to verify. Verifiers MAY wish to track testing mode results to assist the Signer.

  • s Any DKIM-Signature header fields using the "i=" tag MUST have the same domain value on the right-hand side of the "@" in the "i=" tag and the value of the "d=" tag. That is, the "i=" domain MUST NOT be a subdomain of "d=". Use of this flag is RECOMMENDED unless subdomaining is required.

ABNF:

key-t-tag        = %x74 [FWS] "=" [FWS] key-t-tag-flag
                   *( [FWS] ":" [FWS] key-t-tag-flag )
key-t-tag-flag   = "y" / "s" / x-key-t-tag-flag
x-key-t-tag-flag = hyphenated-word   ; for future extension

3.6.2. DNS Binding​

A binding using DNS TXT RRs as a key service is hereby defined. All implementations MUST support this binding.

3.6.2.1. Namespace​

All DKIM keys are stored in a subdomain named "_domainkey". Given a DKIM-Signature field with a "d=" tag of "example.com" and an "s=" tag of "foo.bar", the DNS query will be for "foo.bar._domainkey.example.com".

3.6.2.2. Resource Record Types for Key Storage​

The DNS Resource Record type used is specified by an option to the query-type ("q=") tag. The only option defined in this base specification is "txt", indicating the use of a TXT RR. A later extension of this standard may define another RR type.

Strings in a TXT RR MUST be concatenated together before use with no intervening whitespace. TXT RRs MUST be unique for a particular selector name; that is, if there are multiple records in an RRset, the results are undefined.

TXT RRs are encoded as described in Section 3.6.1.

Last updated on