3.5. The DKIM-Signature Header Field

The signature of the email is stored in the DKIM-Signature header field. This header field contains all of the signature and key-fetching data. The DKIM-Signature value is a tag-list as described in Section 3.2.

The DKIM-Signature header field SHOULD be treated as though it were a trace header field as defined in Section 3.6 of [RFC5322] and hence SHOULD NOT be reordered and SHOULD be prepended to the message.

The DKIM-Signature header field being created or verified is always included in the signature calculation, after the rest of the header fields being signed; however, when calculating or verifying the signature, the value of the "b=" tag (signature value) of that DKIM-Signature header field MUST be treated as though it were an empty string. Unknown tags in the DKIM-Signature header field MUST be included in the signature calculation but MUST be otherwise ignored by Verifiers. Other DKIM-Signature header fields that are included in the signature should be treated as normal header fields; in particular, the "b=" tag is not treated specially.

The encodings for each field type are listed below. Tags described as qp-section are encoded as described in Section 6.7 of MIME Part One [RFC2045], with the additional conversion of semicolon characters to "=3B"; intuitively, this is one line of quoted-printable encoded text. The dkim-quoted-printable syntax is defined in Section 2.11.

Tags on the DKIM-Signature header field along with their type and requirement status are shown below. Unrecognized tags MUST be ignored.

DKIM-Signature Tags

v= Version

Type: plain-text; REQUIRED

This tag defines the version of this specification that applies to the signature record. It MUST have the value "1" for implementations compliant with this version of DKIM.

ABNF:

sig-v-tag = %x76 [FWS] "=" [FWS] 1*DIGIT

INFORMATIVE NOTE: DKIM-Signature version numbers may increase arithmetically as new versions of this specification are released.

a= Algorithm

Type: plain-text; REQUIRED

The algorithm used to generate the signature. Verifiers MUST support "rsa-sha1" and "rsa-sha256"; Signers SHOULD sign using "rsa-sha256". See Section 3.3 for a description of the algorithms.

ABNF:

sig-a-tag = %x61 [FWS] "=" [FWS] sig-a-tag-alg
sig-a-tag-alg = sig-a-tag-k "-" sig-a-tag-h
sig-a-tag-k = "rsa" / x-sig-a-tag-k
sig-a-tag-h = "sha1" / "sha256" / x-sig-a-tag-h
x-sig-a-tag-k = ALPHA *(ALPHA / DIGIT)  ; for later extension
x-sig-a-tag-h = ALPHA *(ALPHA / DIGIT)  ; for later extension

b= Signature Data

Type: base64; REQUIRED

The signature data. Whitespace is ignored in this value and MUST be ignored when reassembling the original signature. In particular, the signing process can safely insert FWS in this value in arbitrary places to conform to line-length limits. See "Signer Actions" (Section 5) for how the signature is computed.

ABNF:

sig-b-tag = %x62 [FWS] "=" [FWS] sig-b-tag-data
sig-b-tag-data = base64string

bh= Body Hash

Type: base64; REQUIRED

The hash of the canonicalized body part of the message as limited by the "l=" tag. Whitespace is ignored in this value and MUST be ignored when reassembling the original signature. In particular, the signing process can safely insert FWS in this value in arbitrary places to conform to line-length limits. See Section 3.7 for how the body hash is computed.

ABNF:

sig-bh-tag = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data
sig-bh-tag-data = base64string

c= Canonicalization

Type: plain-text; OPTIONAL (default is "simple/simple")

This tag informs the Verifier of the type of canonicalization used to prepare the message for signing. It consists of two names separated by a "slash" (%d47) character, corresponding to the header and body canonicalization algorithms, respectively. These algorithms are described in Section 3.4. If only one algorithm is named, that algorithm is used for the header and "simple" is used for the body. For example, "c=relaxed" is treated the same as "c=relaxed/simple".

ABNF:

sig-c-tag = %x63 [FWS] "=" [FWS] sig-c-tag-alg ["/" sig-c-tag-alg]
sig-c-tag-alg = "simple" / "relaxed" / x-sig-c-tag-alg
x-sig-c-tag-alg = hyphenated-word  ; for later extension

d= Signing Domain Identifier (SDID)

Type: plain-text; REQUIRED

The SDID claiming responsibility for an introduction of a message into the mail stream. Hence, the SDID value is used to form the query for the public key. The SDID MUST correspond to a valid DNS name under which the DKIM key record is published. The conventions and semantics used by a Signer to create and use a specific SDID are outside the scope of this specification, as is any use of those conventions and semantics. When presented with a signature that does not meet these requirements, Verifiers MUST consider the signature invalid.

Internationalized domain names MUST be encoded as A-labels, as described in Section 2.3 of [RFC5890].

ABNF:

sig-d-tag = %x64 [FWS] "=" [FWS] domain-name
domain-name = sub-domain 1*("." sub-domain)
              ; from [RFC5321] Domain, excluding address-literal

h= Signed Header Fields

Type: plain-text; REQUIRED

A colon-separated list of header field names that identify the header fields presented to the signing algorithm. The field MUST contain the complete list of header fields in the order presented to the signing algorithm. The field MAY contain names of header fields that do not exist when signed; nonexistent header fields do not contribute to the signature computation (that is, they are treated as the null input, including the header field name, the separating colon, the header field value, and any CRLF terminator). The field MAY contain multiple instances of a header field name, meaning multiple occurrences of the corresponding header field are included in the header hash. The field MUST NOT include the DKIM-Signature header field that is being created or verified but may include others. Folding whitespace (FWS) MAY be included on either side of the colon separator. Header field names MUST be compared against actual header field names in a case-insensitive manner. This list MUST NOT be empty. See Section 5.4 for a discussion of choosing header fields to sign and Section 5.4.2 for requirements when signing multiple instances of a single field.

ABNF:

sig-h-tag = %x68 [FWS] "=" [FWS] hdr-name *( [FWS] ":" [FWS] hdr-name )

INFORMATIVE EXPLANATION: By "signing" header fields that do not actually exist, a Signer can allow a Verifier to detect insertion of those header fields after signing. However, since a Signer cannot possibly know what header fields might be defined in the future, this mechanism cannot be used to prevent the addition of any possible unknown header fields.

INFORMATIVE NOTE: "Signing" fields that are not present at the time of signing not only prevents fields and values from being added but also prevents adding fields with no values.

i= Agent or User Identifier (AUID)

Type: dkim-quoted-printable; OPTIONAL (default is an empty local-part followed by an "@" followed by the domain from the "d=" tag)

The AUID on behalf of which the SDID is taking responsibility. The syntax is a standard email address where the local-part MAY be omitted. The domain part of the address MUST be the same as, or a subdomain of, the value of the "d=" tag.

Internationalized domain names MUST be encoded as A-labels, as described in Section 2.3 of [RFC5890].

ABNF:

sig-i-tag = %x69 [FWS] "=" [FWS] [ Local-part ] "@" domain-name

The AUID is specified as having the same syntax as an email address but it need not have the same semantics. Notably, the domain name need not be registered in the DNS -- so it might not resolve in a query -- and the local-part MAY be drawn from a namespace unrelated to any mailbox. The details of the structure and semantics for the namespace are determined by the Signer. Any knowledge or use of those details by Verifiers or Assessors is outside the scope of this specification. The Signer MAY choose to use the same namespace for its AUIDs as its users' email addresses or MAY choose other means of representing its users. However, the Signer SHOULD use the same AUID for each message intended to be evaluated as being within the same sphere of responsibility, if it wishes to offer receivers the option of using the AUID as a stable identifier that is finer grained than the SDID.

INFORMATIVE NOTE: The local-part of the "i=" tag is optional because in some cases a Signer may not be able to establish a verified individual identity. In such cases, the Signer might wish to assert that although it is willing to go as far as signing for the domain, it is unable or unwilling to commit to an individual user name within the domain. It can do so by including the domain part but not the local-part of the identity.

l= Body Length Count

Type: plain-text unsigned decimal integer; OPTIONAL (default is entire body)

This tag informs the Verifier of the number of octets in the body of the email after canonicalization included in the cryptographic hash, starting from 0 immediately following the CRLF preceding the body. This value MUST NOT be larger than the actual number of octets in the canonicalized message body. See further discussion in Section 8.2.

INFORMATIVE NOTE: The value of the "l=" tag is constrained to 76 decimal digits. This constraint is not intended to predict the size of future messages or to require implementations to use an integer representation large enough to represent the maximum possible value but is intended to remind the implementer to check the length of this and all other tags during verification and to test for integer overflow when decoding the value.

ABNF:

sig-l-tag = %x6c [FWS] "=" [FWS] 1*76DIGIT

q= Query Methods

Type: plain-text; OPTIONAL (default is "dns/txt")

A colon-separated list of query methods used to retrieve the public key. Each query method is of the form "type[/options]", where the syntax and semantics of the options depend on the type and specified options. If there are multiple query mechanisms listed, the choice of query mechanism MUST NOT change the interpretation of the signature. Implementations MUST use the recognized query mechanisms in the order presented. Unrecognized query mechanisms MUST be ignored.

Currently, the only valid value is "dns/txt", which defines the DNS TXT resource record (RR) lookup algorithm described elsewhere in this document. The only option defined for the "dns" query type is "txt", which MUST be included. Verifiers and Signers MUST support "dns/txt".

ABNF:

sig-q-tag = %x71 [FWS] "=" [FWS] sig-q-tag-method 
            *([FWS] ":" [FWS] sig-q-tag-method)
sig-q-tag-method = "dns/txt" / x-sig-q-tag-type ["/" x-sig-q-tag-args]
x-sig-q-tag-type = hyphenated-word  ; for future extension
x-sig-q-tag-args = qp-hdr-value

s= Selector

Type: plain-text; REQUIRED

The selector subdividing the namespace for the "d=" (domain) tag.

Internationalized selector names MUST be encoded as A-labels, as described in Section 2.3 of [RFC5890].

ABNF:

sig-s-tag = %x73 [FWS] "=" [FWS] selector

t= Signature Timestamp

Type: plain-text unsigned decimal integer; RECOMMENDED (default is an unknown creation time)

The time that this signature was created. The format is the number of seconds since 00:00:00 on January 1, 1970 in the UTC time zone. The value is expressed as an unsigned integer in decimal ASCII. This value is not constrained to fit into a 31- or 32-bit integer. Implementations SHOULD be prepared to handle values up to at least 10^12 (until approximately AD 200,000; this fits into 40 bits). To avoid denial-of-service attacks, implementations MAY consider any value longer than 12 digits to be infinite. Leap seconds are not counted. Implementations MAY ignore signatures that have a timestamp in the future.

ABNF:

sig-t-tag = %x74 [FWS] "=" [FWS] 1*12DIGIT

x= Signature Expiration

Type: plain-text unsigned decimal integer; RECOMMENDED (default is no expiration)

The format is the same as in the "t=" tag, represented as an absolute date, not as a time delta from the signing timestamp. The value is expressed as an unsigned integer in decimal ASCII, with the same constraints on the value in the "t=" tag. Signatures MAY be considered invalid if the verification time at the Verifier is past the expiration date. The verification time should be the time that the message was first received at the administrative domain of the Verifier if that time is reliably available; otherwise, the current time should be used. The value of the "x=" tag MUST be greater than the value of the "t=" tag if both are present.

INFORMATIVE NOTE: The "x=" tag is not intended as an anti-replay defense.

INFORMATIVE NOTE: Due to clock drift, the receiver's notion of when to consider the signature expired may not exactly match what the sender is expecting. Receivers MAY add a "fudge factor" to allow for such possible drift.

ABNF:

sig-x-tag = %x78 [FWS] "=" [FWS] 1*12DIGIT

z= Copied Header Fields

Type: dkim-quoted-printable; OPTIONAL (default is null)

A vertical-bar-separated list of selected header fields present when the message was signed, including both the field name and value. It is not required to include all header fields present at the time of signing. This field need not contain the same header fields listed in the "h=" tag. The header field text itself must encode the vertical bar ("|", %x7C) character (i.e., vertical bars in the "z=" text are meta-characters, and any actual vertical bar characters in a copied header field must be encoded). Note that all whitespace must be encoded, including whitespace between the colon and the header field value. After encoding, FWS MAY be added at arbitrary locations in order to avoid excessively long lines; such whitespace is NOT part of the value of the header field and MUST be removed before decoding.

The header fields referenced by the "h=" tag refer to the fields in the [RFC5322] header of the message, not to any copied fields in the "z=" tag. Copied header field values are for diagnostic use.

ABNF:

sig-z-tag = %x7A [FWS] "=" [FWS] sig-z-tag-copy *( "|" [FWS] sig-z-tag-copy )
sig-z-tag-copy = hdr-name [FWS] ":" qp-hdr-value

Example DKIM-Signature Header Field

INFORMATIVE EXAMPLE of a signature header field spread across multiple continuation lines:

DKIM-Signature: v=1; a=rsa-sha256; d=example.net; s=brisbane;
    c=simple; q=dns/txt; [email protected];
    t=1117574938; x=1118006938;
    h=from:to:subject:date;
    z=From:[email protected]|To:[email protected]|
      Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700;
    bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=;
    b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ
      VoG4ZHRNiYzR