tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6376

 
 
 

DomainKeys Identified Mail (DKIM) Signatures

Part 2 of 4, p. 10 to 34
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 10 
3.  Protocol Elements

   Protocol Elements are conceptual parts of the protocol that are not
   specific to either Signers or Verifiers.  The protocol descriptions
   for Signers and Verifiers are described in later sections ("Signer
   Actions" (Section 5) and "Verifier Actions" (Section 6)).  NOTE: This
   section must be read in the context of those sections.

3.1.  Selectors

   To support multiple concurrent public keys per signing domain, the
   key namespace is subdivided using "selectors".  For example,
   selectors might indicate the names of office locations (e.g.,
   "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date
   (e.g., "january2005", "february2005", etc.), or even an individual
   user.

   Selectors are needed to support some important use cases.  For
   example:

   o  Domains that want to delegate signing capability for a specific
      address for a given duration to a partner, such as an advertising
      provider or other outsourced function.

   o  Domains that want to allow frequent travelers to send messages
      locally without the need to connect with a particular MSA.

Top      Up      ToC       Page 11 
   o  "Affinity" domains (e.g., college alumni associations) that
      provide forwarding of incoming mail, but that do not operate a
      mail submission agent for outgoing mail.

   Periods are allowed in selectors and are component separators.  When
   keys are retrieved from the DNS, periods in selectors define DNS
   label boundaries in a manner similar to the conventional use in
   domain names.  Selector components might be used to combine dates
   with locations, for example, "march2005.reykjavik".  In a DNS
   implementation, this can be used to allow delegation of a portion of
   the selector namespace.

   ABNF:

   selector =   sub-domain *( "." sub-domain )

   The number of public keys and corresponding selectors for each domain
   is determined by the domain owner.  Many domain owners will be
   satisfied with just one selector, whereas administratively
   distributed organizations can choose to manage disparate selectors
   and key pairs in different regions or on different email servers.

   Beyond administrative convenience, selectors make it possible to
   seamlessly replace public keys on a routine basis.  If a domain
   wishes to change from using a public key associated with selector
   "january2005" to a public key associated with selector
   "february2005", it merely makes sure that both public keys are
   advertised in the public-key repository concurrently for the
   transition period during which email may be in transit prior to
   verification.  At the start of the transition period, the outbound
   email servers are configured to sign with the "february2005" private
   key.  At the end of the transition period, the "january2005" public
   key is removed from the public-key repository.

      INFORMATIVE NOTE: A key may also be revoked as described below.
      The distinction between revoking and removing a key selector
      record is subtle.  When phasing out keys as described above, a
      signing domain would probably simply remove the key record after
      the transition period.  However, a signing domain could elect to
      revoke the key (but maintain the key record) for a further period.
      There is no defined semantic difference between a revoked key and
      a removed key.

   While some domains may wish to make selector values well-known,
   others will want to take care not to allocate selector names in a way
   that allows harvesting of data by outside parties.  For example, if
   per-user keys are issued, the domain owner will need to decide

Top      Up      ToC       Page 12 
   whether to associate this selector directly with the name of a
   registered end user or make it some unassociated random value, such
   as a fingerprint of the public key.

      INFORMATIVE OPERATIONS NOTE: Reusing a selector with a new key
      (for example, changing the key associated with a user's name)
      makes it impossible to tell the difference between a message that
      didn't verify because the key is no longer valid and a message
      that is actually forged.  For this reason, Signers are ill-advised
      to reuse selectors for new keys.  A better strategy is to assign
      new keys to new selectors.

3.2.  Tag=Value Lists

   DKIM uses a simple "tag=value" syntax in several contexts, including
   in messages and domain signature records.

   Values are a series of strings containing either plain text, "base64"
   text (as defined in [RFC2045], Section 6.8), "qp-section" (ibid,
   Section 6.7), or "dkim-quoted-printable" (as defined in
   Section 2.11).  The name of the tag will determine the encoding of
   each value.  Unencoded semicolon (";") characters MUST NOT occur in
   the tag value, since that separates tag-specs.

      INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined
      below (as "tag-value") only includes 7-bit characters, an
      implementation that wished to anticipate future standards would be
      advised not to preclude the use of UTF-8-encoded ([RFC3629]) text
      in tag=value lists.

   Formally, the ABNF syntax rules are as follows:

   tag-list  =  tag-spec *( ";" tag-spec ) [ ";" ]
   tag-spec  =  [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS]
   tag-name  =  ALPHA *ALNUMPUNC
   tag-value =  [ tval *( 1*(WSP / FWS) tval ) ]
                     ; Prohibits WSP and FWS at beginning and end
   tval      =  1*VALCHAR
   VALCHAR   =  %x21-3A / %x3C-7E
                     ; EXCLAMATION to TILDE except SEMICOLON
   ALNUMPUNC =  ALPHA / DIGIT / "_"

   Note that WSP is allowed anywhere around tags.  In particular, any
   WSP after the "=" and any WSP before the terminating ";" is not part
   of the value; however, WSP inside the value is significant.

Top      Up      ToC       Page 13 
   Tags MUST be interpreted in a case-sensitive manner.  Values MUST be
   processed as case sensitive unless the specific tag description of
   semantics specifies case insensitivity.

   Tags with duplicate names MUST NOT occur within a single tag-list; if
   a tag name does occur more than once, the entire tag-list is invalid.

   Whitespace within a value MUST be retained unless explicitly excluded
   by the specific tag description.

   Tag=value pairs that represent the default value MAY be included to
   aid legibility.

   Unrecognized tags MUST be ignored.

   Tags that have an empty value are not the same as omitted tags.  An
   omitted tag is treated as having the default value; a tag with an
   empty value explicitly designates the empty string as the value.

3.3.  Signing and Verification Algorithms

   DKIM supports multiple digital signature algorithms.  Two algorithms
   are defined by this specification at this time: rsa-sha1 and rsa-
   sha256.  Signers MUST implement and SHOULD sign using rsa-sha256.
   Verifiers MUST implement both rsa-sha1 and rsa-sha256.

      INFORMATIVE NOTE: Although rsa-sha256 is strongly encouraged, some
      senders might prefer to use rsa-sha1 when balancing security
      strength against performance, complexity, or other needs.  In
      general, however, rsa-sha256 should always be used whenever
      possible.

3.3.1.  The rsa-sha1 Signing Algorithm

   The rsa-sha1 Signing Algorithm computes a message hash as described
   in Section 3.7 using SHA-1 [FIPS-180-3-2008] as the hash-alg.  That
   hash is then signed by the Signer using the RSA algorithm (defined in
   Public-Key Cryptography Standards (PKCS) #1 version 1.5 [RFC3447]) as
   the crypt-alg and the Signer's private key.  The hash MUST NOT be
   truncated or converted into any form other than the native binary
   form before being signed.  The signing algorithm SHOULD use a public
   exponent of 65537.

3.3.2.  The rsa-sha256 Signing Algorithm

   The rsa-sha256 Signing Algorithm computes a message hash as described
   in Section 3.7 using SHA-256 [FIPS-180-3-2008] as the hash-alg.  That
   hash is then signed by the Signer using the RSA algorithm (defined in

Top      Up      ToC       Page 14 
   PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the Signer's
   private key.  The hash MUST NOT be truncated or converted into any
   form other than the native binary form before being signed.  The
   signing algorithm SHOULD use a public exponent of 65537.

3.3.3.  Key Sizes

   Selecting appropriate key sizes is a trade-off between cost,
   performance, and risk.  Since short RSA keys more easily succumb to
   off-line attacks, Signers MUST use RSA keys of at least 1024 bits for
   long-lived keys.  Verifiers MUST be able to validate signatures with
   keys ranging from 512 bits to 2048 bits, and they MAY be able to
   validate signatures with larger keys.  Verifier policies may use the
   length of the signing key as one metric for determining whether a
   signature is acceptable.

   Factors that should influence the key size choice include the
   following:

   o  The practical constraint that large (e.g., 4096-bit) keys might
      not fit within a 512-byte DNS UDP response packet

   o  The security constraint that keys smaller than 1024 bits are
      subject to off-line attacks

   o  Larger keys impose higher CPU costs to verify and sign email

   o  Keys can be replaced on a regular basis; thus, their lifetime can
      be relatively short

   o  The security goals of this specification are modest compared to
      typical goals of other systems that employ digital signatures

   See [RFC3766] for further discussion on selecting key sizes.

3.3.4.  Other Algorithms

   Other algorithms MAY be defined in the future.  Verifiers MUST ignore
   any signatures using algorithms that they do not implement.

3.4.  Canonicalization

   Some mail systems modify email in transit, potentially invalidating a
   signature.  For most Signers, mild modification of email is
   immaterial to validation of the DKIM domain name's use.  For such
   Signers, a canonicalization algorithm that survives modest in-transit
   modification is preferred.

Top      Up      ToC       Page 15 
   Other Signers demand that any modification of the email, however
   minor, result in a signature verification failure.  These Signers
   prefer a canonicalization algorithm that does not tolerate in-transit
   modification of the signed email.

   Some Signers may be willing to accept modifications to header fields
   that are within the bounds of email standards such as [RFC5322], but
   are unwilling to accept any modification to the body of messages.

   To satisfy all requirements, two canonicalization algorithms are
   defined for each of the header and the body: a "simple" algorithm
   that tolerates almost no modification and a "relaxed" algorithm that
   tolerates common modifications such as whitespace replacement and
   header field line rewrapping.  A Signer MAY specify either algorithm
   for header or body when signing an email.  If no canonicalization
   algorithm is specified by the Signer, the "simple" algorithm defaults
   for both header and body.  Verifiers MUST implement both
   canonicalization algorithms.  Note that the header and body may use
   different canonicalization algorithms.  Further canonicalization
   algorithms MAY be defined in the future; Verifiers MUST ignore any
   signatures that use unrecognized canonicalization algorithms.

   Canonicalization simply prepares the email for presentation to the
   signing or verification algorithm.  It MUST NOT change the
   transmitted data in any way.  Canonicalization of header fields and
   body are described below.

   NOTE: This section assumes that the message is already in "network
   normal" format (text is ASCII encoded, lines are separated with CRLF
   characters, etc.).  See also Section 5.3 for information about
   normalizing the message.

3.4.1.  The "simple" Header Canonicalization Algorithm

   The "simple" header canonicalization algorithm does not change header
   fields in any way.  Header fields MUST be presented to the signing or
   verification algorithm exactly as they are in the message being
   signed or verified.  In particular, header field names MUST NOT be
   case folded and whitespace MUST NOT be changed.

3.4.2.  The "relaxed" Header Canonicalization Algorithm

   The "relaxed" header canonicalization algorithm MUST apply the
   following steps in order:

   o  Convert all header field names (not the header field values) to
      lowercase.  For example, convert "SUBJect: AbC" to "subject: AbC".

Top      Up      ToC       Page 16 
   o  Unfold all header field continuation lines as described in
      [RFC5322]; in particular, lines with terminators embedded in
      continued header field values (that is, CRLF sequences followed by
      WSP) MUST be interpreted without the CRLF.  Implementations MUST
      NOT remove the CRLF at the end of the header field value.

   o  Convert all sequences of one or more WSP characters to a single SP
      character.  WSP characters here include those before and after a
      line folding boundary.

   o  Delete all WSP characters at the end of each unfolded header field
      value.

   o  Delete any WSP characters remaining before and after the colon
      separating the header field name from the header field value.  The
      colon separator MUST be retained.

3.4.3.  The "simple" Body Canonicalization Algorithm

   The "simple" body canonicalization algorithm ignores all empty lines
   at the end of the message body.  An empty line is a line of zero
   length after removal of the line terminator.  If there is no body or
   no trailing CRLF on the message body, a CRLF is added.  It makes no
   other changes to the message body.  In more formal terms, the
   "simple" body canonicalization algorithm converts "*CRLF" at the end
   of the body to a single "CRLF".

   Note that a completely empty or missing body is canonicalized as a
   single "CRLF"; that is, the canonicalized length will be 2 octets.

   The SHA-1 value (in base64) for an empty body (canonicalized to a
   "CRLF") is:

   uoq1oCgLlTqpdDX/iUbLy7J1Wic=

   The SHA-256 value is:

   frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN/XKdLCPjaYaY=

3.4.4.  The "relaxed" Body Canonicalization Algorithm

   The "relaxed" body canonicalization algorithm MUST apply the
   following steps (a) and (b) in order:

   a.  Reduce whitespace:

       *  Ignore all whitespace at the end of lines.  Implementations
          MUST NOT remove the CRLF at the end of the line.

Top      Up      ToC       Page 17 
       *  Reduce all sequences of WSP within a line to a single SP
          character.

   b.  Ignore all empty lines at the end of the message body.  "Empty
       line" is defined in Section 3.4.3.  If the body is non-empty but
       does not end with a CRLF, a CRLF is added.  (For email, this is
       only possible when using extensions to SMTP or non-SMTP transport
       mechanisms.)

   The SHA-1 value (in base64) for an empty body (canonicalized to a
   null input) is:

   2jmj7l5rSw0yVb/vlWAYkK/YBwk=

   The SHA-256 value is:

   47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

3.4.5.  Canonicalization Examples (INFORMATIVE)

   In the following examples, actual whitespace is used only for
   clarity.  The actual input and output text is designated using
   bracketed descriptors: "<SP>" for a space character, "<HTAB>" for a
   tab character, and "<CRLF>" for a carriage-return/line-feed sequence.
   For example, "X <SP> Y" and "X<SP>Y" represent the same three
   characters.

   Example 1: A message reading:

   A: <SP> X <CRLF>
   B <SP> : <SP> Y <HTAB><CRLF>
                   <HTAB> Z <SP><SP><CRLF>
   <CRLF>
   <SP> C <SP><CRLF>
   D <SP><HTAB><SP> E <CRLF>
   <CRLF>
   <CRLF>

   when canonicalized using relaxed canonicalization for both header and
   body results in a header reading:

   a:X <CRLF>
   b:Y <SP> Z <CRLF>

   and a body reading:

   <SP> C <CRLF>
   D <SP> E <CRLF>

Top      Up      ToC       Page 18 
   Example 2: The same message canonicalized using simple
   canonicalization for both header and body results in a header
   reading:

   A: <SP> X <CRLF>
   B <SP> : <SP> Y <HTAB><CRLF>
          <HTAB> Z <SP><SP><CRLF>

   and a body reading:

   <SP> C <SP><CRLF>
   D <SP><HTAB><SP> E <CRLF>

   Example 3: When processed using relaxed header canonicalization and
   simple body canonicalization, the canonicalized version has a header
   of:

   a:X <CRLF>
   b:Y <SP> Z <CRLF>

   and a body reading:

   <SP> C <SP><CRLF>
   D <SP><HTAB><SP> E <CRLF>

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.

Top      Up      ToC       Page 19 
   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.

   v= Version (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= The algorithm used to generate the signature (plain-text;
      REQUIRED).  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= The signature data (base64; REQUIRED).  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.

Top      Up      ToC       Page 20 
      ABNF:

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

   bh=  The hash of the canonicalized body part of the message as
      limited by the "l=" tag (base64; REQUIRED).  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= Message canonicalization (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= The SDID claiming responsibility for an introduction of a message
      into the mail stream (plain-text; REQUIRED).  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].

Top      Up      ToC       Page 21 
      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 (plain-text, but see description; 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= The Agent or User Identifier (AUID) on behalf of which the SDID is
      taking responsibility (dkim-quoted-printable; OPTIONAL, default is
      an empty local-part followed by an "@" followed by the domain from
      the "d=" tag).

Top      Up      ToC       Page 22 
      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.

         INFORMATIVE DISCUSSION: This specification does not require the
         value of the "i=" tag to match the identity in any message
         header fields.  This is considered to be a Verifier policy
         issue.  Constraints between the value of the "i=" tag and other
         identities in other header fields seek to apply basic
         authentication into the semantics of trust associated with a
         role such as content author.  Trust is a broad and complex
         topic, and trust mechanisms are subject to highly creative
         attacks.  The real-world efficacy of any but the most basic
         bindings between the "i=" value and other identities is not
         well established, nor is its vulnerability to subversion by an
         attacker.  Hence, reliance on the use of these options should

Top      Up      ToC       Page 23 
         be strictly limited.  In particular, it is not at all clear to
         what extent a typical end-user recipient can rely on any
         assurances that might be made by successful use of the "i="
         options.

   l= Body length count (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.  Implementers may need to limit the actual
         value expressed to a value smaller than 10^76, e.g., to allow a
         message to fit within the available storage space.

      ABNF:

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

   q= A colon-separated list of query methods used to retrieve the
      public key (plain-text; OPTIONAL, default is "dns/txt").  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)

Top      Up      ToC       Page 24 
      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= The selector subdividing the namespace for the "d=" (domain) tag
      (plain-text; REQUIRED).

      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 (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 (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.

Top      Up      ToC       Page 25 
         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 (dkim-quoted-printable, but see description;
      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

         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; i=@eng.example.net;
      t=1117574938; x=1118006938;
      h=from:to:subject:date;
      z=From:foo@eng.example.net|To:joe@example.com|
       Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700;
      bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=;
      b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZVoG4ZHRNiYzR

Top      Up      ToC       Page 26 
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

Top      Up      ToC       Page 27 
   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

Top      Up      ToC       Page 28 
         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.

Top      Up      ToC       Page 29 
      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.

3.7.  Computing the Message Hashes

   Both signing and verifying message signatures start with a step of
   computing two cryptographic hashes over the message.  Signers will
   choose the parameters of the signature as described in "Signer
   Actions" (Section 5); Verifiers will use the parameters specified in
   the DKIM-Signature header field being verified.  In the following
   discussion, the names of the tags in the DKIM-Signature header field
   that either exists (when verifying) or will be created (when signing)

Top      Up      ToC       Page 30 
   are used.  Note that canonicalization (Section 3.4) is only used to
   prepare the email for signing or verifying; it does not affect the
   transmitted email in any way.

   The Signer/Verifier MUST compute two hashes: one over the body of the
   message and one over the selected header fields of the message.

   Signers MUST compute them in the order shown.  Verifiers MAY compute
   them in any order convenient to the Verifier, provided that the
   result is semantically identical to the semantics that would be the
   case had they been computed in this order.

   In hash step 1, the Signer/Verifier MUST hash the message body,
   canonicalized using the body canonicalization algorithm specified in
   the "c=" tag and then truncated to the length specified in the "l="
   tag.  That hash value is then converted to base64 form and inserted
   into (Signers) or compared to (Verifiers) the "bh=" tag of the DKIM-
   Signature header field.

   In hash step 2, the Signer/Verifier MUST pass the following to the
   hash algorithm in the indicated order.

   1.  The header fields specified by the "h=" tag, in the order
       specified in that tag, and canonicalized using the header
       canonicalization algorithm specified in the "c=" tag.  Each
       header field MUST be terminated with a single CRLF.

   2.  The DKIM-Signature header field that exists (verifying) or will
       be inserted (signing) in the message, with the value of the "b="
       tag (including all surrounding whitespace) deleted (i.e., treated
       as the empty string), canonicalized using the header
       canonicalization algorithm specified in the "c=" tag, and without
       a trailing CRLF.

   All tags and their values in the DKIM-Signature header field are
   included in the cryptographic hash with the sole exception of the
   value portion of the "b=" (signature) tag, which MUST be treated as
   the null string.  All tags MUST be included even if they might not be
   understood by the Verifier.  The header field MUST be presented to
   the hash algorithm after the body of the message rather than with the
   rest of the header fields and MUST be canonicalized as specified in
   the "c=" (canonicalization) tag.  The DKIM-Signature header field
   MUST NOT be included in its own "h=" tag, although other DKIM-
   Signature header fields MAY be signed (see Section 4).

   When calculating the hash on messages that will be transmitted using
   base64 or quoted-printable encoding, Signers MUST compute the hash
   after the encoding.  Likewise, the Verifier MUST incorporate the

Top      Up      ToC       Page 31 
   values into the hash before decoding the base64 or quoted-printable
   text.  However, the hash MUST be computed before transport-level
   encodings such as SMTP "dot-stuffing" (the modification of lines
   beginning with a "." to avoid confusion with the SMTP end-of-message
   marker, as specified in [RFC5321]).

   With the exception of the canonicalization procedure described in
   Section 3.4, the DKIM signing process treats the body of messages as
   simply a string of octets.  DKIM messages MAY be either in plain-text
   or in MIME format; no special treatment is afforded to MIME content.
   Message attachments in MIME format MUST be included in the content
   that is signed.

   More formally, pseudo-code for the signature algorithm is:

   body-hash    =  hash-alg (canon-body, l-param)
   data-hash    =  hash-alg (h-headers, D-SIG, body-hash)
   signature    =  sig-alg (d-domain, selector, data-hash)

   where:

   body-hash:  is the output from hashing the body, using hash-alg.

   hash-alg:   is the hashing algorithm specified in the "a" parameter.

   canon-body: is a canonicalized representation of the body, produced
               using the body algorithm specified in the "c" parameter,
               as defined in Section 3.4 and excluding the
               DKIM-Signature field.

   l-param:    is the length-of-body value of the "l" parameter.

   data-hash:  is the output from using the hash-alg algorithm, to hash
               the header including the DKIM-Signature header, and the
               body hash.

   h-headers:  is the list of headers to be signed, as specified in the
               "h" parameter.

   D-SIG:      is the canonicalized DKIM-Signature field itself without
               the signature value portion of the parameter, that is, an
               empty parameter value.

   signature:  is the signature value produced by the signing algorithm.

   sig-alg:    is the signature algorithm specified by the "a"
               parameter.

Top      Up      ToC       Page 32 
   d-domain:   is the domain name specified in the "d" parameter.

   selector:   is the selector value specified in the "s" parameter.

      NOTE: Many digital signature APIs provide both hashing and
      application of the RSA private key using a single "sign()"
      primitive.  When using such an API, the last two steps in the
      algorithm would probably be combined into a single call that would
      perform both the "a-hash-alg" and the "sig-alg".

3.8.  Input Requirements

   A message that is not compliant with [RFC5322], [RFC2045], and
   [RFC2047] can be subject to attempts by intermediaries to correct or
   interpret such content.  See Section 8 of [RFC4409] for examples of
   changes that are commonly made.  Such "corrections" may invalidate
   DKIM signatures or have other undesirable effects, including some
   that involve changes to the way a message is presented to an end
   user.

   Accordingly, DKIM's design is predicated on valid input.  Therefore,
   Signers and Verifiers SHOULD take reasonable steps to ensure that the
   messages they are processing are valid according to [RFC5322],
   [RFC2045], and any other relevant message format standards.

   See Section 8.15 for additional discussion.

3.9.  Output Requirements

   The evaluation of each signature ends in one of three states, which
   this document refers to as follows:

   SUCCESS:  a successful verification

   PERMFAIL:  a permanent, non-recoverable error such as a signature
      verification failure

   TEMPFAIL:  a temporary, recoverable error such as a DNS query timeout

   For each signature that verifies successfully or produces a TEMPFAIL
   result, output of the DKIM algorithm MUST include the set of:

   o  The domain name, taken from the "d=" signature tag; and

   o  The result of the verification attempt for that signature.

Top      Up      ToC       Page 33 
   The output MAY include other signature properties or result meta-
   data, including PERMFAILed or otherwise ignored signatures, for use
   by modules that consume those results.

   See Section 6.1 for discussion of signature validation result codes.

3.10.  Signing by Parent Domains

   In some circumstances, it is desirable for a domain to apply a
   signature on behalf of any of its subdomains without the need to
   maintain separate selectors (key records) in each subdomain.  By
   default, private keys corresponding to key records can be used to
   sign messages for any subdomain of the domain in which they reside;
   for example, a key record for the domain example.com can be used to
   verify messages where the AUID ("i=" tag of the signature) is
   sub.example.com, or even sub1.sub2.example.com.  In order to limit
   the capability of such keys when this is not intended, the "s" flag
   MAY be set in the "t=" tag of the key record, to constrain the
   validity of the domain of the AUID.  If the referenced key record
   contains the "s" flag as part of the "t=" tag, the domain of the AUID
   ("i=" flag) MUST be the same as that of the SDID (d=) domain.  If
   this flag is absent, the domain of the AUID MUST be the same as, or a
   subdomain of, the SDID.

3.11.  Relationship between SDID and AUID

   DKIM's primary task is to communicate from the Signer to a recipient-
   side Identity Assessor a single Signing Domain Identifier (SDID) that
   refers to a responsible identity.  DKIM MAY optionally provide a
   single responsible Agent or User Identifier (AUID).

   Hence, DKIM's mandatory output to a receive-side Identity Assessor is
   a single domain name.  Within the scope of its use as DKIM output,
   the name has only basic domain name semantics; any possible owner-
   specific semantics are outside the scope of DKIM.  That is, within
   its role as a DKIM identifier, additional semantics cannot be assumed
   by an Identity Assessor.

   Upon successfully verifying the signature, a receive-side DKIM
   Verifier MUST communicate the Signing Domain Identifier (d=) to a
   consuming Identity Assessor module and MAY communicate the Agent or
   User Identifier (i=) if present.

   To the extent that a receiver attempts to intuit any structured
   semantics for either of the identifiers, this is a heuristic function
   that is outside the scope of DKIM's specification and semantics.

Top      Up      ToC       Page 34 
   Hence, it is relegated to a higher-level service, such as a delivery-
   handling filter that integrates a variety of inputs and performs
   heuristic analysis of them.

      INFORMATIVE DISCUSSION: This document does not require the value
      of the SDID or AUID to match an identifier in any other message
      header field.  This requirement is, instead, an Assessor policy
      issue.  The purpose of such a linkage would be to authenticate the
      value in that other header field.  This, in turn, is the basis for
      applying a trust assessment based on the identifier value.  Trust
      is a broad and complex topic, and trust mechanisms are subject to
      highly creative attacks.  The real-world efficacy of any but the
      most basic bindings between the SDID or AUID and other identities
      is not well established, nor is its vulnerability to subversion by
      an attacker.  Hence, reliance on the use of such bindings should
      be strictly limited.  In particular, it is not at all clear to
      what extent a typical end-user recipient can rely on any
      assurances that might be made by successful use of the SDID or
      AUID.



(page 34 continued on part 3)

Next RFC Part