idnits 2.17.1 draft-crocker-doseta-base-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2700 has weird spacing: '... email elec...' -- The document date (July 12, 2011) is 4666 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC EDITOR' is mentioned on line 194, but not defined == Missing Reference: 'TEMPLATE' is mentioned on line 1215, but not defined == Unused Reference: 'ITU-X660-1997' is defined on line 2213, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4234 (ref. 'RFC5234') (Obsoleted by RFC 5234) -- Obsolete informational reference (is this intentional?): RFC 4871 (ref. 'DKIMSign') (Obsoleted by RFC 6376) -- Obsolete informational reference (is this intentional?): RFC 4409 (Obsoleted by RFC 6409) -- Obsolete informational reference (is this intentional?): RFC 4870 (Obsoleted by RFC 4871) -- Obsolete informational reference (is this intentional?): RFC 5451 (Obsoleted by RFC 7001) -- Obsolete informational reference (is this intentional?): RFC 5672 (Obsoleted by RFC 6376) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Crocker 3 Internet-Draft Brandenburg InternetWorking 4 Intended status: Informational M. Kucherawy 5 Expires: January 13, 2012 Cloudmark 6 July 12, 2011 8 DomainKeys Security Tagging (DOSETA) 9 draft-crocker-doseta-base-03 11 Abstract 13 DomainKeys Security Tagging (DOSETA) is a component mechanism that 14 enables easy development of security-related services, such as for 15 authentication or encryption. It uses self-certifying keys based on 16 domain names. The domain name owner can be any actor involved in the 17 handling of the data, such as the author's organization, a server 18 operator or one of their agents. The DOSETA Library provides a 19 collection of common capabilities, including canonicalization, 20 parameter tagging and key retrieval. The DOSETA Signing Template 21 creates common framework for a signature of data that are in a 22 "header/content" form. Defining the meaning of a signature is the 23 responsibility of the service that incorporates DOSETA. Data 24 security is enforced through the use of cryptographic algorithms. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 13, 2012. 43 Copyright Notice 45 Copyright (c) 2011 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Comments and Issues . . . . . . . . . . . . . . . . . . . 5 59 2. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 2.1. DOSETA Architecture . . . . . . . . . . . . . . . . . . . 5 61 2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 62 2.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 3. DOSETA Library . . . . . . . . . . . . . . . . . . . . . . . . 11 64 3.1. Normalization for Transport Robustness . . . . . . . . . . 11 65 3.2. Canonicalization . . . . . . . . . . . . . . . . . . . . . 12 66 3.3. Tag=Value Parameters . . . . . . . . . . . . . . . . . . . 16 67 3.4. Key Management . . . . . . . . . . . . . . . . . . . . . . 17 68 3.5. Selectors for Keys . . . . . . . . . . . . . . . . . . . . 18 69 3.6. DNS Binding for Key Retrieval . . . . . . . . . . . . . . 20 70 3.7. Stored Key Data . . . . . . . . . . . . . . . . . . . . . 21 71 4. DOSETA H/C Signing Template . . . . . . . . . . . . . . . . . 23 72 4.1. Cryptographic Algorithms . . . . . . . . . . . . . . . . . 23 73 4.2. Signature Data Structure . . . . . . . . . . . . . . . . . 25 74 4.3. Additional Tags . . . . . . . . . . . . . . . . . . . . . 31 75 4.4. Signature Calculations . . . . . . . . . . . . . . . . . . 31 76 4.5. Signer Actions . . . . . . . . . . . . . . . . . . . . . . 35 77 4.6. Verifier Actions . . . . . . . . . . . . . . . . . . . . . 38 78 4.7. Requirements for Tailoring the Signing Service . . . . . . 45 79 5. Semantics of Multiple Signatures . . . . . . . . . . . . . . . 46 80 5.1. Example Scenarios . . . . . . . . . . . . . . . . . . . . 46 81 5.2. Interpretation . . . . . . . . . . . . . . . . . . . . . . 47 82 6. DOSETA Claims Registry Definition . . . . . . . . . . . . . . 48 83 7. Considerations . . . . . . . . . . . . . . . . . . . . . . . . 49 84 7.1. IANA Considerations . . . . . . . . . . . . . . . . . . . 49 85 7.2. Security Considerations . . . . . . . . . . . . . . . . . 49 86 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 50 87 8.1. Normative References . . . . . . . . . . . . . . . . . . . 50 88 8.2. Informative References . . . . . . . . . . . . . . . . . . 51 89 Appendix A. Creating a Public Key . . . . . . . . . . . . . . . . 52 90 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 53 91 Appendix C. Example -- DKIM Using DOSETA . . . . . . . . . . . . 53 92 C.1. Signing and Verification Protocol . . . . . . . . . . . . 53 93 C.2. Extensions to DOSETA Template . . . . . . . . . . . . . . 54 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 62 96 1. Introduction 98 DomainKeys Security Tagging (DOSETA) is a component mechanism 99 enabling development of security-related services, such as for 100 authentication or encryption; it uses self-certifying keys based on 101 domain names [RFC1034]. The domain name owner can be any actor 102 involved in the handling of the data, such as the author's 103 organization, a server operator or one of their agents. The DOSETA 104 Library provides a collection of common capabilities, including 105 canonicalization, parameter tagging and key retrieval. The DOSETA 106 Signing Template creates common framework for signing data that are 107 in a "header/content" form. Defining the intended meaning of a 108 signature is the responsibility of the service that incorporates 109 DOSETA. Data security is enforced through the use of cryptographic 110 algorithms. 112 The approach taken by DOSETA differs from previous approaches to data 113 signing -- such as, Secure/Multipurpose Internet Mail Extensions 114 (S/MIME) [RFC1847], OpenPGP [RFC4880] -- in that: 116 o The message signature can be packaged independently of the data it 117 is signing, so that neither human viewers of the data nor existing 118 data handling software is confused by security-related content 119 appearing in the Content. 121 o There is no dependency on having public and private key pairs 122 being issued by well-known, trusted certificate authorities. 124 o There is no dependency on the deployment of any new Internet 125 protocols or services for public key distribution or revocation. 127 o Specific security services can be limited to those needed by the 128 service using them. 130 DOSETA: 132 o enables compatibility with the existing data handling 133 infrastructure and is transparent to the fullest extent possible 135 o requires minimal new infrastructure 137 o can support a variety of implementation configurations, in order 138 to reduce deployment time 140 o can be deployed incrementally 142 o allows delegation of signing to third parties 143 DOSETA derives from Domain Keys Identified Mail (DKIM) [RFC5672] and 144 has extracted the core portions of the its signing specification 145 [DKIMSign], so that they can be applied to other security-related 146 services. For example, the core could support a DKIM-like signing 147 service for web pages, and it could support a data ion mechanism 148 using the same DNS-based, self-certified key service as DKIM. 150 DOSETA features include: 152 Identity: DOSETA distinguishes the identity of the DOSETA 153 signature's producer from that of any other identifier 154 associated with the data, such as the data's purported author. 155 In particular, the DOSETA header field includes the DOSETA 156 Domain Identifier (DDI), per Section 2.2.1. DOSETA consumers 157 can use the DDI to decide how they want to process the data. 158 The DDI can be directly included in the attributes of the data 159 or can be recorded elsewhere. 161 NOTE: DOSETA does not, itself, specify that the identity it 162 uses is required to match any other associated identifier. 163 Those other identifiers already carry their own semantics 164 which might conflict with the use of the identifier needed 165 by DOSETA. However a particular DOSETA-based security 166 service might choose to add constraints on the choice of 167 identifier, such as having it match another identifier that 168 is associated with the data. 170 Scalability: DOSETA is designed to easily support the extreme 171 scaling requirements that characterize Internet data 172 identification. 174 Key Management: DOSETA differs from traditional hierarchical 175 public-key systems in that no Certificate Authority 176 infrastructure is required; the verifier requests the public 177 key from a repository under the domain name associated with the 178 use of DOSETA directly, rather than requiring consultation of a 179 certificate authority. That is, DOSETA provides self- 180 certifying keys. 182 The DNS is the initial mechanism for DOSETA public keys. Thus, 183 DOSETA currently depends on DNS administration and the security 184 of the DNS system. DOSETA is designed to be extensible to 185 other key fetching services as they become available. 187 Data Integrity: When DOSETA is used to sign data -- independent 188 of the semantics of that signature -- there is a computed hash 189 of some or all of the data that ensures detection of changes to 190 that data, between the times of signing and verifying. 192 1.1. Comments and Issues 194 [RFC EDITOR] Remove this sub-section prior to publication. 196 Possible applications: 198 o JSON structure 200 o XMPP message 202 o XML object 204 o vCard 206 o vCal 208 o Web page signing? 210 o Web ad authentication 212 o Handle System 214 Discussion Venue: Discussion of this draft should take place on the 215 doseta-discuss mailing list. It is located at: 217 http://www.trusteddomain.org/mailman/listinfo/doseta-discuss 219 2. Framework 221 This section provides the technical background for the remainder of 222 the document. 224 2.1. DOSETA Architecture 226 As component technology, DOSETA is meant to be incorporated into a 227 service. This specification provides an underlying set of common 228 features and a template for using them to provide a signing service, 229 such as for authenticating an identifier. Hence, the pieces can be 230 depicted as follows, with DKIM being shown as a specific service that 231 incorporates DOSETA: 233 +--------+ +----------+ +-----------------+ 234 | DKIM | | MIMEAUTH | | Message Privacy | 235 +---+----+ +-----+----+ +--------+--------+ 236 | | | 237 ++=====V==================V========++ | 238 || || | 239 || Header/Content Signing Template || | 240 || || | 241 ++================+================++ | 242 | | 243 ++=================V=================================V============++ 244 || || 245 || D O S E T A L I B R A R Y || 246 || +------------------+ +------------+ +-------------+ +--------+ || 247 || | | | Key | | Parameter | | Tags | || 248 || | Canonicalization | | Management | | Format | | Header | || 249 || | | | (DNS) | | (tag=value) | | Field | || 250 || +------------------+ +------------+ +-------------+ +--------+ || 251 || || 252 ++================================================================++ 254 DKIM is as specified in [DKIMSign]. MIMEAUTH is an exemplar use of 255 DOSETA, specified in [mimeauth]. Message Privacy is a generic term, 256 indicating any service that provides encryption; it is expected that 257 such a service can use the DOSETA core library, but not take 258 advantage of the DOSETA signing template. 260 The library comprises: 262 Canonicalization: This ensures common data representation and 263 robustness against some forms of data modification during transit. 264 It is discussed in Section 3.2 and Section 3.1. 266 Key Management: This covers the mechanisms for discovering and 267 obtaining signature key information by a verifier. It is 268 discussed in Section 3.4, Section 3.5, and Section 3.6. 270 Format: This describes a simple syntax for encoding parametric 271 information and is discussed in Section 3.3. 273 Tags: These are common parameters for the stored public key record, 274 defined in Section 3.7 and the common parameters for the signature 275 record that is associated with the signed data, defined in 276 Section 4.2. 278 2.2. Terminology 280 Within the specification, the label "[TEMPLATE]" is used to indicate 281 actions that are required for tailoring the use of DOSETA into a 282 specific service. 284 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 285 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 286 document are to be interpreted as described in [RFC2119]. 288 Additional terms for this document are divided among Identity and 289 Actors. 291 2.2.1. Identity 293 Identity: A person, role, or organization. In the context of 294 DOSETA, examples include author, author's organization, an ISP 295 along the handling path, an independent trust assessment service, 296 and a data processing intermediary operator. 298 Identifier: A label that refers to an identity. The primary 299 example is a domain name. 301 DOSETA Domain Identifier (DDI): A single domain name that serves as 302 an identifier, referring to the DOSETA key owner's identity. The 303 DDI is specified in Section 4.2. Within this specification, the 304 name has only basic domain name semantics; any possible owner- 305 specific semantics MUST be provided in the specification that 306 incorporates DOSETA. 308 Identity Assessor: A module that consumes DOSETA's payload output. 309 The module is dedicated to the assessment of the delivered 310 identifier. Optionally, other DOSETA (and non-DOSETA) values can 311 also be delivered to this module as well as to a more general 312 message evaluation filtering engine. However, this additional 313 activity is outside the scope of the DOSETA specification. 315 2.2.2. Actors 317 Producer: An element in the data handling system that produces a 318 cryptographic encoding, on behalf of a domain, is referred to as a 319 Producer. For example, a signer is a type of producer. 321 Consumer: An element in the data handling system that processes an 322 existing cryptographic encoding, on behalf of a domain, is 323 referred to as a consumer. For example, a verifier is a type of 324 consumer. 326 Signer: An element in the data handling system that creates a 327 digital signature, on behalf of a domain, is referred to as a 328 signer. This element specifies an actor that is a type of DOSETA 329 producer. The actor might operate through a client, server or 330 other agent such as a reputation service. The core requirement is 331 that the data MUST be signed before it leaves the control of the 332 signer's administrative domain. 334 Verifier: An element in the data handling system that verifies 335 signatures is referred to as a verifier. This element is a 336 consumer of a signing service. It might be a client, server, or 337 other agent, such as a reputation service. In most cases it is 338 expected that a verifier will be close to an end user of the data 339 or some consuming agent such as a data processing intermediary. 341 2.3. Syntax 343 This section specifies foundational syntactic constructs used in the 344 remainder of the document. 346 Syntax descriptions use Augmented BNF (ABNF) [RFC5234]. 348 2.3.1. Whitespace 350 There are three forms of whitespace: 352 WSP: represents simple whitespace, that is, a space or a tab 353 character (formally defined in [RFC5234]). 355 LWSP: is linear whitespace, defined as WSP plus CRLF (formally 356 defined in [RFC5234]). 358 FWS: is folding whitespace. It allows multiple lines to be 359 joined with each a separated by a sequence having CRLF followed 360 by at least one whitespace. 362 The formal syntax for these are (WSP and LWSP are given for 363 information only): 365 ABNF: 366 WSP = SP / HTAB 367 LWSP = *(WSP / CRLF WSP) 368 FWS = [*WSP CRLF] 1*WSP 369 The definition of FWS is identical to that in [RFC5322] except for 370 the exclusion of obs-FWS. 372 2.3.2. Common ABNF Tokens 374 The following tokens are used in this document: 376 ABNF: 377 hyphenated-word = ALPHA 378 [ *(ALPHA / DIGIT / "-") 379 (ALPHA / DIGIT) ] 380 ALPHADIGITPS = (ALPHA / DIGIT / "+" / "/") 381 base64string = ALPHADIGITPS *([FWS] ALPHADIGITPS) 382 [ [FWS] "=" [ [FWS] "=" ] ] 383 hdr-name = field-name 384 qp-hdr-value = D-quoted-printable 385 ; with "|" encoded 387 2.3.3. Imported ABNF Tokens 389 The following tokens are imported from other RFCs as noted. Those 390 RFCs SHOULD be considered definitive. 392 From [RFC5321]: 394 Implementation Warning: This permits quoted 395 strings) 397 399 From [RFC5322]: 401 (name of a header field) 403 From [RFC2045]: 405 a single line of quoted-printable-encoded text 406 a quoted-printable encoded octet) 408 NOTE: Be aware that the ABNF in [RFC2045] does not obey the rules 409 of [RFC5234] and MUST be interpreted accordingly, particularly as 410 regards case folding. 412 Other tokens not defined herein are imported from [RFC5234]. These 413 are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF, 414 etc. 416 2.3.4. D-Quoted-Printable 418 The D-Quoted-Printable encoding syntax resembles that described in 419 Quoted-Printable [RFC2045], Section 6.7: 421 o Any character MAY be encoded as an "=" followed by two hexadecimal 422 digits from the alphabet "0123456789ABCDEF" (no lowercase 423 characters permitted) representing the hexadecimal-encoded integer 424 value of that character. 426 o All control characters (those with values < %x20), 8-bit 427 characters (values > %x7F), and the characters DEL (%x7F), SPACE 428 (%x20), and semicolon (";", %x3B) MUST be encoded. 430 o All whitespace, including SPACE, CR, and LF characters, MUST be 431 encoded. 433 o After encoding, FWS MAY be added at arbitrary locations in order 434 to avoid excessively long lines; such whitespace is NOT part of 435 the value, and MUST be removed before decoding. 437 The formal syntax for D-Quoted-Printable is: 439 ABNF: 440 D-quoted-printable = *(FWS / hex-octet / D-safe-char) 441 ; hex-octet is from RFC2045 442 D-safe-char = %x21-3A / %x3C / %x3E-7E 443 ; '!' - ':', '<', '>' - '~' 444 ; Characters not listed as "mail-safe" 445 ; in [RFC2049] are also not 446 ; recommended. 448 D-Quoted-Printable differs from Quoted-Printable as defined in 449 [RFC2045] in several important ways: 451 1. Whitespace in the input text, including CR and LF, MUST be 452 encoded. [RFC2045] does not require such encoding, and does not 453 permit encoding of CR or LF characters that are part of a CRLF 454 line break. 456 2. Whitespace in the encoded text is ignored. This is to allow tags 457 encoded using D-Quoted-Printable to be wrapped as needed. In 458 particular, [RFC2045] requires that line breaks in the input be 459 represented as physical line breaks; that is not the case here. 461 3. The "soft line break" syntax ("=" as the last non-whitespace 462 character on the line) does not apply. 464 4. D-Quoted-Printable does not require that encoded lines be no more 465 than 76 characters long (although there might be other 466 requirements depending on the context in which the encoded text 467 is being used). 469 3. DOSETA Library 471 DOSETA's library of functional components is distinguished by a DNS- 472 based, self-certifying public key mechanism, common data 473 normalization and canonicalization algorithms, and a common parameter 474 encoding mechanism. 476 3.1. Normalization for Transport Robustness 478 Some messages, particularly those using 8-bit characters, are subject 479 to modification during transit, notably from conversion to 7-bit 480 form. Such conversions will break DOSETA signatures. Similarly, 481 data that is not compliant with its associated standard, might be 482 subject to corrective efforts intermediaries. See Section 8 of 483 [RFC4409] for examples of changes that are commonly made to email. 484 Such "corrections" might break DOSETA signatures or have other 485 undesirable effects. 487 In order to minimize the chances of such breakage, signers convert 488 the data to a suitable encoding, such as quoted-printable or base64, 489 as described in [RFC2045] before signing. Specification and use of 490 such conversions is outside the scope of DOSETA. 492 If the data is submitted to a DOSETA process with any local encoding 493 that will be modified before transmission, that modification to a 494 canonical form MUST be done before DOSETA processing. For Text data 495 in particular, bare CR or LF characters (used by some systems as a 496 local line separator convention) MUST be converted to the CRLF 497 sequences before the data is signed. Any conversion of this sort 498 SHOULD be applied to the data actually sent to the recipient(s), not 499 just to the version presented to the signing algorithm. 501 More generally, a DOSETA producer MUST use the data as it is expected 502 to be received by the DOSETA consumer rather than in some local or 503 internal form. 505 3.2. Canonicalization 507 Some data handling systems modify the original data during transit, 508 potentially invalidating a cryptographic function. In some cases, 509 mild modification of data can be immaterial to the validity of a 510 DOSETA-based service. In these cases, a canonicalization algorithm 511 that survives modest handling modification is preferred. 513 In other cases, preservation of the exact, original bits is required; 514 even minor modifications need to result in a failure. Hence a 515 canonicalization algorithm is needed that does not tolerate any in- 516 transit modification of the data. 518 To satisfy basic requirements, two canonicalization algorithms are 519 defined: a "simple" algorithm that tolerates almost no modification 520 and a "relaxed" algorithm that tolerates common modifications such as 521 whitespace replacement and data line rewrapping. 523 Data presented for canonicalization MUST already be in "network 524 normal" format -- text is ASCII encoded, lines are separated with 525 CRLF characters, etc.) See Section 3.1 for information about 526 normalizing data. 528 Data handling systems sometimes treat different portions of text 529 differentially and might be subject to more or less likelihood of 530 breaking a signature. DOSETA currently covers two types of data: 532 Header: Attribute:value sets, in the style of Internet Mail 533 header fields or MIME header fields 535 Content: Lines of ASCII text 537 Some DOSETA producers might be willing to accept modifications to 538 some portions of the data, but not other portions. For DOSETA, a 539 producer MAY specify one algorithm for the header and another for the 540 content. 542 If no canonicalization algorithm is specified, the "simple" algorithm 543 defaults for each part. DOSETA producers MUST implement both of the 544 base canonicalization algorithms. Because additional 545 canonicalization algorithms might be defined in the future, producers 546 MUST ignore any unrecognized canonicalization algorithms. 548 Canonicalization simply prepares the data for presentation to the 549 DOSETA processing algorithm. 551 NOTE: Canonicalization operates on a copy of the data; it MUST NOT 552 change the transmitted data in any way. Canonicalization of 553 distinct data portions is described below. 555 3.2.1. Header Canonicalization Algorithms 557 This section describes basic entries for the Header Canonicalization 558 IANA registry defined in [DKIMSign], , which also applies to DOSETA 559 header canonicalization. 561 simple: The "simple" header canonicalization algorithm is for a set 562 of "attribute:value" textual data structures, such as email header 563 fields [RFC5322]. It does not change the original Header fields 564 in any way. Header fields MUST be presented to the processing 565 algorithm exactly as they are in the data being processed. In 566 particular, header field names MUST NOT be case folded and 567 whitespace MUST NOT be changed. 569 relaxed: The "relaxed" header canonicalization algorithm is for a 570 set of "attribute:value" textual data structures, such as email 571 header fields [RFC5322]. It does not change the original Header 572 fields in any way. The following steps MUST be applied in order: 574 * Convert all header field names (not the header field values) to 575 lowercase. For example, convert "SUBJect: AbC" to "subject: 576 AbC". 578 * Unfold all header field continuation lines as described in 579 [RFC5322]; in particular, lines with terminators embedded in 580 continued header field values (that is, CRLF sequences followed 581 by WSP) MUST be interpreted without the CRLF. Implementations 582 MUST NOT remove the CRLF at the end of the header field value. 584 * Convert all sequences of one or more WSP characters to a single 585 SP character. WSP characters here include those before and 586 after a line folding boundary. 588 * Delete all WSP characters at the end of each unfolded header 589 field value. 591 * Delete any WSP characters remaining before and after the colon 592 separating the header field name from the header field value. 593 The colon separator MUST be retained. 595 3.2.2. Content Canonicalization Algorithms 597 This section describes basic entries for the Message Canonicalization 598 IANA registry defined in [DKIMSign], which also applies to DOSETA 599 Content. 601 simple: The "simple" Content canonicalization algorithm is for 602 lines of ASCII text, such as occur in the body of email [RFC5322]. 603 It ignores all empty lines at the end of the Content. An empty 604 line is a line of zero length after removal of the line 605 terminator. If there is no Content or no trailing CRLF on the 606 Content, a CRLF is added. It makes no other changes to the 607 Content. In more formal terms, the "simple" Content 608 canonicalization algorithm converts "0*CRLF" at the end of the 609 Content to a single "CRLF". 611 Note that a completely empty or missing Content is canonicalized 612 as a single "CRLF"; that is, the canonicalized length will be 2 613 octets. 615 The sha1 value (in base64) for an empty Content (canonicalized to 616 a "CRLF") is: 617 uoq1oCgLlTqpdDX/iUbLy7J1Wic= 618 The sha256 value is: 619 frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN/XKdLCPjaYaY= 621 relaxed: The "relaxed" Content canonicalization algorithm is for 622 lines of ASCII text, such as occur in the body of email [RFC5322]. 623 It MUST apply the following steps (a) and (b) in order: 625 A. Reduce whitespace: 627 + Ignore all whitespace at the end of lines. Implementations 628 MUST NOT remove the CRLF at the end of the line. 630 + Reduce all sequences of WSP within a line to a single SP 631 character. 633 B. Ignore all empty lines at the end of the Content. "Empty 634 line" is defined in Section 3.2.2. If the Content is non- 635 empty, but does not end with a CRLF, a CRLF is added. (For 636 email, this is only possible when using extensions to SMTP or 637 non-SMTP transport mechanisms.) 639 The sha1 value (in base64) for an empty Content (canonicalized to 640 a null input) is: 641 2jmj7l5rSw0yVb/vlWAYkK/YBwk= 642 The sha256 value is: 643 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 645 NOTE: The relaxed Content canonicalization algorithm can enable 646 certain types of extremely crude "ASCII Art" attacks in which a 647 message can be conveyed, by adjusting the spacing between 648 words. If this is a concern, the "simple" Content 649 canonicalization algorithm is more appropriate for use. 651 3.2.3. Canonicalization Examples 653 In the following examples, actual whitespace is used only for 654 clarity. The actual input and output text is designated using 655 bracketed descriptors: "" for a space character, "" for a 656 tab character, and "" for a carriage-return/line-feed sequence. 657 For example, "X Y" and "XY" represent the same three 658 characters. 660 Example 1: An email message reading: 661 A: X 662 B : Y 663 Z 664 665 C 666 D E 667 668 670 when canonicalized using relaxed canonicalization for both Header and 671 Content results in a Header reading: 672 a:X 673 b:Y Z 675 and a Content reading: 676 C 677 D E 679 Example 2: The same message canonicalized using simple 680 canonicalization for both Header and Content results in a header 681 reading: 682 A: X 683 B : Y 684 Z 686 and a Content reading: 687 C 688 D E 690 Example 3: When processed using relaxed Header canonicalization and 691 simple Content canonicalization, the canonicalized version has a 692 header of: 693 a:X 694 b:Y Z 696 and a Content reading: 697 C 698 D E 700 3.3. Tag=Value Parameters 702 DOSETA uses a simple "tag=value" parameter syntax in several 703 contexts, such as when representing associated cryptographic data and 704 domain key records. 706 Values are a series of strings containing either plain text, "base64" 707 text (as defined in [RFC2045], Section 6.8), "qp-section" (ibid, 708 Section 6.7), or "D-quoted-printable" (as defined in Section 2.6). 709 The definition of a tag will determine the specific encoding for its 710 associated value. Unencoded semicolon (";") characters MUST NOT 711 occur in the tag value, since that separates tag-specs. 713 NOTE: The "plain text" defined below, as "tag-value", only supports 714 use of 7-bit characters. However, it is likely that support of 715 UTF-8 Unicode [UTF8] data will eventually be deemed important. 717 Formally the syntax rules are as follows: 719 ABNF: 720 tag-list = tag-spec 0*( ";" tag-spec ) [ ";" ] 721 tag-spec = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS] 722 tag-name = ALPHA 0*ALNUMPUNC 723 tag-value = [ tval 0*( 1*(WSP / FWS) tval ) ] 724 ; WSP and FWS prohibited at beginning and end 725 tval = 1*VALCHAR 726 VALCHAR = %x21-3A / %x3C-7E 727 ; EXCLAMATION to TILDE except SEMICOLON 728 ALNUMPUNC = ALPHA / DIGIT / "_" 729 NOTE: WSP is allowed anywhere around tags. In particular, any WSP 730 after the "=" and any WSP before the terminating ";" is not part 731 of the value. However, WSP inside the value is significant. 733 Tags MUST interpret a VALCHAR as case-sensitive, unless the specific 734 tag description of semantics specifies case insensitivity. 736 Tags MUST be unique; duplicate names MUST NOT occur within a single 737 tag-list. If a tag name does occur more than once, the entire tag- 738 list is invalid. 740 Whitespace within a value MUST be retained unless explicitly excluded 741 by the specific tag description. 743 Tag=value pairs that represent the default value MAY be included to 744 aid legibility. 746 Unrecognized tags MUST be ignored. 748 Tags that have an empty value are not the same as omitted tags. An 749 omitted tag is treated as having the default value; a tag with an 750 empty value explicitly designates the empty string as the value. 752 3.4. Key Management 754 Applications require some level of assurance that a producer is 755 authorized to use a cited public. Many applications achieve this by 756 using public key certificates issued by a trusted authority. For 757 applications with modest certification requirements, DOSETA achieves 758 a sufficient level of security, with excellent scaling properties, by 759 simply having the consumer query the purported producer's DNS entry 760 (or a supported equivalent) in order to retrieve the public key. The 761 safety of this model is increased by the use of DNSSEC [RFC4033] for 762 the key records in the DNS. 764 DOSETA keys might be stored in multiple types of key servers and in 765 multiple formats. As long as the key-related information is the same 766 and as long as the security properties of key storage and retrieval 767 are the same, DOSETA's operation is unaffected by the actual source 768 of a key. 770 The abstract key lookup algorithm is: 771 public-key = D-find-key(q-val, d-val, s-val) 772 where: 774 q-val: The type of the lookup, as specified in the "q" parameter 775 (Section 4.2) 777 d-val: The domain of the signature, as specified in the "d" 778 parameter (Section 4.2) 780 s-val: The selector of the lookup as specified in the "s" 781 parameter (Section 4.2) 783 D-find-key: A function that uses q-val to determine the specific 784 details for accessing the desired stored Key record. 786 This document defines a single binding between the abstract lookup 787 algorithm and a physical instance, using DNS TXT records, per 788 Section 3.6. Other bindings can be defined. 790 3.5. Selectors for Keys 792 It can be extremely helpful to support multiple DOSETA keys for the 793 same domain name. For example: 795 * Rolling over from one key to another is a common security 796 administration requirement; for an operational service this is 797 made far easier when the old and new keys are supported 798 simultaneously. 800 * Domains that want to delegate signing capability for a specific 801 address for a given duration to a partner, such as an 802 advertising provider or other outsourced function. 804 * Domains that want to allow frequent travelers to generate 805 signed data locally without the need to connect to a particular 806 server. 808 * "Affinity" domains (such as, college alumni associations) that 809 provide data forwarding, but that do not operate a data 810 origination agent for outgoing data. 812 To these ends, DOSETA includes a mechanism that supports multiple 813 concurrent public keys per signing domain. The key namespace is 814 subdivided using "selectors". For example, selectors might indicate 815 the names of office locations (for example, "sanfrancisco", 816 "coolumbeach", and "reykjavik"), the signing date (for example, 817 "january2005", "february2005", etc.), or even an individual user. 819 For further administrative convenience, sub-division of selectors is 820 allowed, distinguished as dotted sub-components of the selector name. 821 When keys are retrieved from the DNS, periods in selectors define DNS 822 label boundaries in a manner similar to the conventional use in 823 domain names. Selector components might be used to combine dates 824 with locations, for example, "march2005.reykjavik". In a DNS 825 implementation, this can be used to allow delegation of a portion of 826 the selector namespace. 828 ABNF: 829 selector = sub-domain *( "." sub-domain ) 831 The number of public keys and the corresponding selectors for each 832 domain are determined by the domain owner. Many domain owners will 833 be satisfied with just one selector, whereas administratively 834 distributed organizations might choose to manage disparate selectors 835 and key pairs in different regions or on different servers. 837 As noted, selectors make it possible to seamlessly replace public 838 keys on a routine basis. If a domain wishes to change from using a 839 public key associated with selector "january2005" to a public key 840 associated with selector "february2005", it merely makes sure that 841 both public keys are advertised in the public-key repository 842 concurrently for the transition period during which data might be in 843 transit prior to verification. At the start of the transition 844 period, the outbound servers are configured to sign with the 845 "february2005" private key. At the end of the transition period, the 846 "january2005" public key is removed from the public-key repository. 848 NOTE: A key can also be revoked as described below. The 849 distinction between revoking and removing a key selector record 850 is subtle. When phasing out keys as described above, a signing 851 domain would probably simply remove the key record after the 852 transition period. However, a signing domain could elect to 853 revoke the key (but maintain the key record) for a further 854 period. There is no defined semantic difference between a 855 revoked key and a removed key. 857 While some domains might wish to make selector values well known, 858 others will want to take care not to allocate selector names in a way 859 that allows harvesting of data by outside parties. For example, if 860 per-user keys are issued, the domain owner will need to make the 861 decision as to whether to associate this selector directly with the 862 name of a registered end-user, or make it some unassociated random 863 value, such as a fingerprint of the public key. 865 NOTE: The ability to reuse a selector with a new key (for 866 example, changing the key associated with a user's name) makes 867 it impossible to tell the difference between data that didn't 868 verify because the key is no longer valid versus a data that is 869 actually forged. For this reason, reuse of selectors with 870 different keys is ill-advised. A better strategy is to assign 871 new keys to new selectors. 873 3.6. DNS Binding for Key Retrieval 875 This section defines a binding using DNS TXT records as a key 876 service. All implementations MUST support this binding. 878 3.6.1. Namespace 880 A DOSETA key is stored in a subdomain named: 882 ABNF: 883 dns-record = s "._domainkey." d 884 where: 886 s: is the selector of the lookup as specified in the "s" 887 parameter (Section 4.2); use of selectors is discussed in 888 Section 3.5 890 d: is the domain of the signature, as specified in the "d" 891 parameter (Section 4.2) 893 NOTE: The string constant "_domainkey" is used to mark a sub-tree 894 that contains unified DOSETA key information. This string is a 895 constant, rather than being a different string for different key- 896 based services, with the view that keys are agnostic about the 897 service they are used for. That is, there is no semantic or 898 security benefit in having a different constant string for 899 different key services. That said, a new service is certainly 900 free to define a new constant and maintain and entirely 901 independent set of keys. 903 Given a DOSETA-Signature field with a "d" parameter of "example.com" 904 and an "s" parameter of "foo.bar", the DNS query will be for: 905 foo.bar._domainkey.example.com 907 Wildcard DNS records (for example, *.bar._domainkey.example.com) do 908 not make sense in the context of DOSETA and their presence can be 909 problematic. Hence DNS wildcards with DOSETA SHOULD NOT be used. 910 Note also that wildcards within domains (for example, 911 s._domainkey.*.example.com) are not supported by the DNS. 913 3.6.2. Resource Record Types for Key Storage 915 The DNS Resource Record type used is specified by an option to the 916 query-type ("q") parameter. The only option defined in this base 917 specification is "txt", indicating the use of a DNS TXT Resource 918 Record (RR), as defined in Section 3.7. A later extension of this 919 standard might define another RR type. 921 Strings in a TXT RR MUST be concatenated together before use, with no 922 intervening whitespace. TXT RRs MUST be unique for a particular 923 selector name; that is, if there are multiple records in an RRset, 924 the results are undefined. 926 3.7. Stored Key Data 928 This section defines a syntax for encoding stored key data within an 929 unstructured environment such as the simple text environment of a DNS 930 TXT record. 932 [TEMPLATE] (Key Retrieval) A service that incorporates DOSETA 933 MAY define the specific mechanism by which consumers can obtain 934 associated public keys. This might be as easy as referencing 935 an existing key management system or it might require a new set 936 of conventions. 938 Absent an explicit specification for key retrieval, the default 939 mechanism is specified in Section 3.6. Use of this means 940 sharing the set of public keys with DKIM and other DOSETA-based 941 services. 943 The overall syntax is a tag-list as described in Section 3.3. The 944 base set of valid tags is described below. Other tags MAY be present 945 and MUST be ignored by any implementation that does not understand 946 them. 948 k= Key type (MAY be include; default is "rsa"). Signers and 949 verifiers MUST support the "rsa" key type. The "rsa" key type 950 indicates that an ASN.1 DER-encoded [ITU-X660-1997] 951 RSAPublicKey [RFC3447] (see Sections Section 3.5 and A.1.1) is 952 being used in the "p" parameter. (Note: the "p" parameter 953 further encodes the value using the base64 algorithm.) 954 Unrecognized key types MUST be ignored. 956 ABNF: 957 key-k-tag = %x76 [FWS] "=" [FWS] key-k-tag-type 958 key-k-tag-type = "rsa" / x-key-k-tag-type 959 x-key-k-tag-type = hyphenated-word ; for future extension 961 n= Notes that might be of interest to a human (MAY be included; 962 default is empty). No interpretation is made by any program. 963 This tag should be used sparingly in any key server mechanism 964 that has space limitations (notably DNS). This is intended for 965 use by administrators, not end users. 967 ABNF: 968 key-n-tag = %x6e [FWS] "=" [FWS] qp-section 970 p= Public-key data (MUST be included). An empty value means 971 that this public key has been revoked. The syntax and 972 semantics of this tag value before being encoded in base64 are 973 defined by the "k" parameter. 975 ABNF: 976 key-p-tag = %x70 [FWS] "=" [ [FWS] base64string] 978 NOTE: If a private key has been compromised or otherwise 979 disabled (for example, an outsourcing contract has been 980 terminated), a signer might want to explicitly state that it 981 knows about the selector, but also have all queries using 982 that selector result in a failed verification. Verifiers 983 SHOULD ignore any DOSETA-Signature header fields with a 984 selector referencing a revoked key. 986 NOTE: A base64string is permitted to include white space 987 (FWS) at arbitrary places; however, any CRLFs MUST be 988 followed by at least one WSP character. Implementors and 989 administrators are cautioned to ensure that selector TXT 990 records conform to this specification. 992 4. DOSETA H/C Signing Template 994 This section specifies the basic components of a signing mechanism; 995 it is similar to the one defined for DKIM. This template for a 996 signing service can be mapped to a two-part -- header/content -- data 997 model. As for DKIM this separates specification of the signer's 998 identity from any other identifiers that might be associated with 999 that data. 1001 NOTE: The use of hashing and signing algorithms by DOSETA 1002 inherently provides a degree of data integrity protection, 1003 between the signing and verifying steps. However it does not 1004 necessarily "authenticate" the data that is signed. For 1005 example, it does not inherently validate the accuracy of the 1006 data or declare that the signer is the author or owner of the 1007 data. To the extent that authentication is meant by the 1008 presence of a signature, that needs to be specified as part of 1009 the semantics for the service based upon this template. 1011 [TEMPLATE] (Header/Content Mapping) The service incorporating 1012 this mechanism MUST define the precise mappings onto the 1013 template provided in this section. (Data lacking a header 1014 component might still be possible to cast in a header/content 1015 form, where the header comprises on the DOSETA Signature 1016 information.) 1018 The service also MUST define the precise meaning of a 1019 signature. 1021 4.1. Cryptographic Algorithms 1023 DOSETA supports multiple digital signature algorithms: 1025 rsa-sha1: The rsa-sha1 Signing Algorithm computes a message hash 1026 as described in Section 4.4 below using SHA-1 [FIPS-180-2-2002] 1027 as a hashing algorithm. That hash is then signed by the signer 1028 using the RSA algorithm (defined in PKCS#1 version 1.5 1029 [RFC3447]) as the crypt-alg and the signer's private key. The 1030 hash MUST NOT be truncated or converted into any form other 1031 than the native binary form before being signed. The signing 1032 algorithm SHOULD use a public exponent of 65537. 1034 rsa-sha256: The rsa-sha256 Signing Algorithm computes a message 1035 hash as described in [RFC5451] below using SHA-256 1036 [FIPS-180-2-2002] as the hash-alg. That hash is then signed by 1037 the signer using the RSA algorithm (defined in PKCS#1 version 1038 1.5 [RFC3447]) as the crypt-alg and the signer's private key. 1039 The hash MUST NOT be truncated or converted into any form other 1040 than the native binary form before being signed. 1042 Other: Other algorithms MAY be defined in the future. Verifiers 1043 MUST ignore any signatures using algorithms that they do not 1044 implement. 1046 Signers MUST implement and SHOULD sign using rsa-sha256. Verifiers 1047 MUST implement rsa-sha256. 1049 NOTE: Although sha256 is strongly encouraged, some senders of low- 1050 security messages (such as routine newsletters) might prefer to 1051 use sha1 because of reduced CPU requirements to compute a sha1 1052 hash. In general, sha256 is always preferred, whenever possible. 1054 Selecting appropriate key sizes is a trade-off between cost, 1055 performance, and risk. Since short RSA keys more easily succumb to 1056 off-line attacks, signers MUST use RSA keys of at least 1024 bits for 1057 long-lived keys. Verifiers MUST be able to validate signatures with 1058 keys ranging from 512 bits to 2048 bits, and they MAY be able to 1059 validate signatures with larger keys. Verifier policies might use 1060 the length of the signing key as one metric for determining whether a 1061 signature is acceptable. 1063 Factors that ought to influence the key size choice include the 1064 following: 1066 * The practical constraint that large (for example, 4096 bit) 1067 keys might not fit within a 512-byte DNS UDP response packet 1069 * The security constraint that keys smaller than 1024 bits are 1070 subject to off-line attacks 1072 * Larger keys impose higher CPU costs to verify and sign data 1074 * Keys can be replaced on a regular basis, thus their lifetime 1075 can be relatively short 1077 * The security goals of this specification are modest compared to 1078 typical goals of other systems that employ digital signatures 1080 See [RFC3766] for further discussion on selecting key sizes. 1082 4.2. Signature Data Structure 1084 A signature of data is stored into an data structure associated with 1085 the signed data. This structure contains all of the signature- and 1086 key-fetching data. This DOSETA-Signature structure is a tag-list as 1087 defined in Section 3.3. 1089 [TEMPLATE] (Signature Association) A service that incorporates 1090 DOSETA MUST define the exact means by which the Signature 1091 structure is associated with the data. 1093 When the DOSETA-Signature structure is part of a sequence of 1094 structures -- such as being added to an email header -- it SHOULD NOT 1095 be reordered and SHOULD be pre-pended to the message. (This is the 1096 same handling as is given to email trace Header fields, defined in 1097 Section 3.6 of [RFC5322].) 1099 The tags are specified below. Tags described as are 1100 encoded as described in Section 6.7 of MIME Part One [RFC2045], with 1101 the additional conversion of semicolon characters to "=3B"; 1102 intuitively, this is one line of quoted-printable encoded text. The 1103 D-quoted-printable syntax is defined in Section 2.3.4. 1105 Tags on the DOSETA-Signature structure along with their type and 1106 requirement status are shown below. Unrecognized tags MUST be 1107 ignored. 1109 v= Version (MUST be included). This tag defines the version of 1110 this specification that applies to the signature record. It 1111 MUST have the value "1". Note that verifiers MUST do an exact 1112 string comparison on this value; for example, "1" is not the 1113 same as "1.0". 1115 ABNF: 1116 sig-v-tag = %x76 [FWS] "=" [FWS] "1" 1117 NOTE: DOSETA-Signature version numbers are expected to 1118 increase arithmetically as new versions of this 1119 specification are released. 1121 a= The algorithm used to generate the signature (MUST be 1122 included). Verifiers MUST support "rsa-sha1" and "rsa-sha256"; 1123 signers SHOULD sign using "rsa-sha256". See Section 4.1 for a 1124 description of algorithms. 1126 ABNF: 1128 sig-a-tag = %x61 [FWS] "=" [FWS] sig-a-tag-alg 1129 sig-a-tag-alg = sig-a-tag-k "-" sig-a-tag-h 1130 sig-a-tag-k = "rsa" / x-sig-a-tag-k 1131 sig-a-tag-h = "sha1" / "sha256" / x-sig-a-tag-h 1132 x-sig-a-tag-k = ALPHA *(ALPHA / DIGIT) 1133 ; for later extension 1134 x-sig-a-tag-h = ALPHA *(ALPHA / DIGIT) 1135 ; for later extension 1137 b= The signature data (MUST be included). Whitespace is 1138 ignored in this value and MUST be ignored when reassembling the 1139 original signature. In particular, the signing process can 1140 safely insert FWS in this value in arbitrary places to conform 1141 to line-length limits. See Signer Actions (Section 4.5) for 1142 how the signature is computed. 1144 ABNF: 1145 sig-b-tag = %x62 [FWS] "=" [FWS] sig-b-tag-data 1146 sig-b-tag-data = base64string 1148 bh= The hash of the canonicalized Content (body), as limited by 1149 the "l" parameter (MUST be included). Whitespace is ignored in 1150 this value and MUST be ignored when reassembling the original 1151 signature. In particular, the signing process can safely 1152 insert FWS in this value in arbitrary places to conform to 1153 line-length limits. See Section 4.4 for how the Content hash 1154 is computed. 1156 ABNF: 1157 sig-bh-tag = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data 1158 sig-bh-tag-data = base64string 1160 c= Data canonicalization (MAY be included; default is "simple/ 1161 simple"). This tag informs the verifier of the type of 1162 canonicalization used to prepare the message for signing. It 1163 consists of two names separated by a "slash" (%d47) character, 1164 corresponding to the header and Content canonicalization 1165 algorithms respectively: 1167 ABNF: 1168 sig-bh-tag = %x63 [FWS] "=" [FWS] sig-c-header "/" sig-c-content 1169 where: 1171 sig-c-header: A value from Header Canonicalization IANA 1172 registry defined in [DKIMSign] 1174 sig-c-content: A value from Message Canonicalization IANA 1175 registry defined in [DKIMSign] 1177 These algorithms are described in Section 3.2. If only one 1178 algorithm is named, that algorithm is used for the header and 1179 "simple" is used for the Content. For example, "c=relaxed" is 1180 treated the same as "c=relaxed/simple". 1182 ABNF: 1183 sig-c-tag = %x63 [FWS] "=" [FWS] sig-c-tag-alg 1184 ["/" sig-c-tag-alg] 1185 sig-c-tag-alg = "simple" / "relaxed" / x-sig-c-tag-alg 1186 x-sig-c-tag-alg = hyphenated-word ; for later extension 1188 cl= A list of semantic claims, asserting the set of "meanings" 1189 intended by the signer, such as author validity or content 1190 validity (SHOULD be included; default is "handled"}. The list 1191 of supported claims comprises values from the DOSETA Claims 1192 IANA registry, defined in Section 6 using values listed in 1193 Section 7.1.2. 1195 ABNF: 1196 sig-cl-tag = %x63 %x6C [FWS] "=" [FWS] 1197 sig-cl-tag-claim 1198 ["/" sig-c-tag-claim] 1199 sig-c-tag-claim = hyphenated-word 1200 ; per DOSETA Claims Registry 1202 d= The DDI doing the signing (MUST be included). Hence, the 1203 DDI value is used to form the query for the public key. The 1204 DDI MUST correspond to a valid DNS name under which the DOSETA 1205 key record is published. The conventions and semantics used by 1206 a signer to create and use a specific DDI are outside the scope 1207 of the DOSETA Signing specification, as is any use of those 1208 conventions and semantics. When presented with a signature 1209 that does not meet these requirements, verifiers MUST consider 1210 the signature invalid. 1212 Internationalized domain names MUST be encoded as described in 1213 [RFC5890]. 1215 [TEMPLATE] (Semantics) The service incorporating DOSETA 1216 MUST define the semantics of a signature. 1218 ABNF: 1220 sig-d-tag = %x64 [FWS] "=" [FWS] domain-name 1221 domain-name = sub-domain 1*("." sub-domain) 1222 ; from RFC 5321 Domain, 1223 ; but excluding address-literal 1225 h= Signed Header fields (MUST be included). A colon-separated 1226 list of header field names that identify the Header fields 1227 presented to the signing algorithm. The field MUST contain the 1228 complete list of Header fields in the order presented to the 1229 signing algorithm. The field MAY contain names of Header 1230 fields that do not exist when signed; nonexistent Header fields 1231 do not contribute to the signature computation (that is, they 1232 are treated as the null input, including the header field name, 1233 the separating colon, the header field value, and any CRLF 1234 terminator). The field MUST NOT include the DOSETA Signature 1235 header field that is being created or verified, but might 1236 include others. Folding whitespace (FWS) MAY be included on 1237 either side of the colon separator. Header field names MUST be 1238 compared against actual header field names in a case- 1239 insensitive manner. This list MUST NOT be empty. See 1240 Section 4.5.3 for a discussion of choosing Header fields to 1241 sign. 1243 ABNF: 1244 sig-h-tag = %x68 [FWS] "=" [FWS] hdr-name 1245 0*( [FWS] ":" [FWS] hdr-name ) 1247 By "signing" Header fields that do not actually exist, a signer 1248 can prevent insertion of those Header fields before 1249 verification. However, since a signer cannot possibly know all 1250 possible Header fields that might be created in the future, the 1251 security of this solution is not total. 1253 The exclusion of the header field name and colon as well as the 1254 header field value for non-existent Header fields prevents an 1255 attacker from inserting an actual header field with a null 1256 value. 1258 q= A colon-separated list of query methods used to retrieve the 1259 public key (MAY be included; default is "dns/txt"). Each query 1260 method is of the form "type[/options]", where the syntax and 1261 semantics of the options depend on the type and specified 1262 options. If there are multiple query mechanisms listed, the 1263 choice of query mechanism MUST NOT change the interpretation of 1264 the signature. Implementations MUST use the recognized query 1265 mechanisms in the order presented. Unrecognized query 1266 mechanisms MUST be ignored. 1268 Currently, the only valid value is "dns/txt", which defines the 1269 DNS TXT record lookup algorithm described elsewhere in this 1270 document. The only option defined for the "dns" query type is 1271 "txt", which MUST be included. Verifiers and signers MUST 1272 support "dns/txt". 1274 ABNF: 1275 sig-q-tag = %x71 [FWS] "=" [FWS] sig-q-tag-method 1276 *([FWS] ":" [FWS] sig-q-tag-method) 1277 sig-q-tag-method = "dns/txt" / x-sig-q-tag-type 1278 ["/" x-sig-q-tag-args] 1279 x-sig-q-tag-type = hyphenated-word ; for future extension 1280 x-sig-q-tag-args = qp-hdr-value 1282 s= The selector subdividing the namespace for the "d=" (domain) 1283 tag (MUST be included). 1285 ABNF: 1286 sig-s-tag = %x73 [FWS] "=" [FWS] selector 1288 t= Signature Timestamp (SHOULD be included; default is an 1289 unknown creation time). The time that this signature was 1290 created. The format is the number of seconds since 00:00:00 on 1291 January 1, 1970 in the UTC time zone. The value is expressed 1292 as an unsigned integer in decimal ASCII. This value is not 1293 constrained to fit into a 31- or 32-bit integer. 1294 Implementations SHOULD be prepared to handle values up to at 1295 least 10^12 (until approximately AD 200,000; this fits into 40 1296 bits). To avoid denial-of-service attacks, implementations MAY 1297 consider any value longer than 12 digits to be infinite. Leap 1298 seconds are not counted. Implementations MAY ignore signatures 1299 that have a timestamp in the future. 1301 ABNF: 1302 sig-t-tag = %x74 [FWS] "=" [FWS] 1*12DIGIT 1304 x= Signature Expiration (SHOULD be included; default is no 1305 expiration). The format is the same as in the "t" parameter, 1306 represented as an absolute date, not as a time delta from the 1307 signing timestamp. The value is expressed as an unsigned 1308 integer in decimal ASCII, with the same constraints on the 1309 value in the "t=" tag. Signatures MAY be considered invalid if 1310 the verification time at the verifier is past the expiration 1311 date. Ideally verification time is when a message is first 1312 received at the administrative domain of the verifier; 1313 otherwise the current time SHOULD be used. The value of the 1314 "x" parameter MUST be greater than the value of the "t" 1315 parameter if both are present. 1317 NOTE: The "x" parameter is not intended as an anti-replay 1318 defense. 1320 NOTE: Due to clock drift, the receiver's notion of when to 1321 consider the signature expired might not match exactly when 1322 the sender is expecting. Receivers MAY add a 'fudge factor' 1323 to allow for such possible drift. 1325 ABNF: 1326 sig-x-tag = %x78 [FWS] "=" [FWS] 1327 1*12DIGIT 1329 4.3. Additional Tags 1331 Some applications can benefit from additional, common functional 1332 enhancements. These are defined here, as options to the core 1333 mechanism. 1335 id= The local identifier, restricting the scope of the DDI, 1336 such as to a specific user. This value is combined with the 1337 DDI, to specify the identifier to be used for assessment. 1338 Administrative choices for selectors can provide different keys 1339 for different local identifiers. See Section 3.5 1341 ABNF: 1342 key-id-tag = %x69 %64 [FWS] "=" [FWS] hyphenated-word 1344 4.4. Signature Calculations 1346 Hashing and cryptographic signature algorithms are combined into a 1347 procedure for computing a digital signature. Producers will choose 1348 appropriate parameters for the signing process. Consumers will use 1349 the tags that are then passed as an associated DOSETA-Signature 1350 header field. Section 4.2. In the following discussion, the names 1351 of the tags are parameters in that field. 1353 The basic operations for producing a signature are canonicalization, 1354 hashing and signing. Canonicalization removes irrelevant variations. 1355 Hashing produces a very short representation for the data and signing 1356 produces a unique, protected string to be exchanged. 1358 NOTE: Canonicalization (see Section 3.2) prepares a separate 1359 representation of the data for additional processing; it does 1360 not affect the original, transmitted data in any way. 1362 Producers MUST compute hashes in the order defined. Consumers MAY 1363 compute them in any order convenient to the producer, provided that 1364 the result is semantically identical to the semantics that would 1365 occur, had they been computed in this order. 1367 The combined hashing and signing algorithms are: 1369 Content Hash: 1371 1. Truncate the content to the length specified in the "l" 1372 parameter. 1374 2. Canonicalize the truncated content, using the algorithm 1375 specified in the "c" parameter. 1377 3. Hash the canonicalized content, using the hashing algorithm 1378 specified in the "a" parameter. 1380 4. Convert the resulting hash to base64 form. 1382 5. Signers then insert the base64 result into the "bh" 1383 parameter of the DOSETA-Signature field; verifiers compare 1384 their hash with the value in the "bh" parameter. 1386 Header Hash: 1388 1. Select the header fields specified by the "h" parameter. 1390 2. Ensure that each field is terminated by a single CRLF. 1392 3. Canonicalize each of these fields, using the header 1393 canonicalization algorithm specified in the "c" parameter. 1395 4. Select the DOSETA-Signature field that exists (verifying), 1396 or will be inserted (signing), in the header. 1398 5. From that field, delete the value portion of the "b" 1399 parameter, including all surrounding whitespace; that is, 1400 treat the "b" parameter as containing an empty string. 1402 6. Canonicalize the resulting field, using the Header 1403 canonicalization algorithm specified in the "c" parameter, 1404 but remove the trailing CRLF, if present. 1406 7. Using the hashing algorithm specified in the "a" parameter, 1407 hash the sequence: 1409 1. the canonicalized header fields, in the order specified 1410 by the "h" parameter, 1412 2. the output from the content hash, and 1414 3. the canonicalized DOSETA-Signature field. 1416 Signature: 1418 1. Obtain the relevant key associated with the relevant domain 1419 and selector; for signing this is a private key; for 1420 verifying this is a public key. 1422 2. Obtain the header hash produced by the previous 1423 calculation. 1425 3. Using the signing algorithm specified in the "a" parameter, 1426 and the relevant key, process the hash. 1428 All tags cited in the "h" parameter MUST be included even if they are 1429 not understood by the verifier. Note that the DOSETA-Signature field 1430 is presented to the hash algorithm after the content hash is 1431 processed, rather than with the rest of the header fields that are 1432 processed before the content hash. The DOSETA-Signature header 1433 structure MUST NOT be cited in its own h= tag. If present, other 1434 DOSETA-Signature header fields MAY be cited and included in the 1435 signature process (see Section 5). 1437 When calculating the hash on data that will be transmitted using 1438 additional encoding, such as base64 or quoted-printable, signers MUST 1439 compute the hash after the encoding. Likewise, the verifier MUST 1440 incorporate the values into the hash before decoding the base64 or 1441 quoted-printable text. However, the hash MUST be computed before 1442 transport level encodings such as SMTP "dot-stuffing" (the 1443 modification of lines beginning with a "." to avoid confusion with 1444 the SMTP end-of-message marker, as specified in [RFC5321]). 1446 With the exception of the canonicalization procedure described in 1447 Section 3.2, the DOSETA signing process treats the content as a 1448 simple string of octets. DOSETA content MAY be either simple lines 1449 of plain-text or as a MIME object; no special treatment is afforded 1450 to MIME content. 1452 Formally, the algorithm for the signature is as follows: 1454 ABNF: 1455 content-hash = hash-alg (canon-content, l-param) 1456 data-hash = hash-alg (h-headers, D-SIG, content-hash) 1457 signature = sig-alg (d-domain, selector, data-hash) 1459 where: 1461 content-hash: is the output from hashing the content, using 1462 hash-alg. 1464 hash-alg: is the hashing algorithm specified in the "a" 1465 parameter. 1467 canon-content: is a canonicalized representation of the content. 1469 l-param: is the length-of-content value of the "l" parameter. 1471 data-hash: is the output from using the hash-alg algorithm, to 1472 hash the header including the DKIM-Signature header, and the 1473 content hash. 1475 h-headers: is the list of headers to be signed, as specified in 1476 the "h" parameter. 1478 D-SIG: is the canonicalized DOSETA-Signature field without the 1479 signature value portion of the parameter, itself; that is, an 1480 empty parameter value. 1482 canon-content: is the canonicalized data content (respectively) 1483 as defined in Section 3.2 (excluding the DOSETA-Signature 1484 field). 1486 signature: is the signature value produced by the signing 1487 algorithm. 1489 sig-alg: is the signature algorithm specified by the "a" 1490 parameter. 1492 d-domain: is the domain name specified in the "d" parameter. 1494 selector: is the selector value specified in the "s" parameter. 1496 NOTE: Many digital signature APIs provide both hashing and 1497 application of the RSA private key using a single "sign()" 1498 primitive. When using such an API, the last two steps in the 1499 algorithm would probably be combined into a single call that would 1500 simultaneously perform both "a-hash-alg" and the "sig-alg". 1502 4.5. Signer Actions 1504 The following steps are performed in order by signers. 1506 4.5.1. Determine Whether the Data Should Be Signed and by Whom 1508 A signer can obviously only sign data using domains for which it has 1509 a private key and the necessary knowledge of the corresponding public 1510 key and selector information. However, there are a number of other 1511 reasons beyond the lack of a private key why a signer could choose 1512 not to sign the data. 1514 NOTE: Signing modules can be incorporated into any portion of a 1515 service, as deemed appropriate, including end-systems, servers and 1516 intermediaries. Wherever implemented, signers need to beware of 1517 the semantics of signing data. An example of how this can be 1518 problematic is that within a trusted enclave the signing address 1519 might be derived from the data according to local policy; the 1520 derivation is based on local trust rather than explicit 1521 validation. 1523 If the data cannot be signed for some reason, the disposition of that 1524 data is a local policy decision. 1526 4.5.2. Select a Private Key and Corresponding Selector Information 1528 This specification does not define the basis by which a signer ought 1529 to choose which private key and selector information to use. 1530 Currently, all selectors are equal, with respect to this 1531 specification. So the choices ought to largely be a matter of 1532 administrative convenience. Distribution and management of private 1533 keys is also outside the scope of this document. 1535 NOTE: A signer SHOULD use a private key with an associated selector 1536 record that is expected to still be valid by time the verifier is 1537 likely to have an opportunity to validate the signature. The 1538 signer SHOULD anticipate that verifiers can choose to defer 1539 validation, perhaps until the message is actually read by the 1540 final recipient. In particular, when rotating to a new key pair, 1541 signing SHOULD immediately commence with the new private key, but 1542 the old public key SHOULD be retained for a reasonable validation 1543 interval before being removed from the key server. 1545 4.5.3. Determine the Header Fields to Sign 1547 Signers SHOULD NOT sign an existing header field that is likely to be 1548 legitimately modified or removed in transit. Signers MAY include any 1549 other Header fields present at the time of signing at the discretion 1550 of the signer. 1552 NOTE: The choice of which Header fields to sign is non-obvious. 1553 One strategy is to sign all existing, non-repeatable Header 1554 fields. An alternative strategy is to sign only Header fields 1555 that are likely to be displayed to or otherwise be likely to 1556 affect the processing of the Content at the receiver. A third 1557 strategy is to sign only "well known" headers. Note that 1558 verifiers might treat unsigned Header fields with extreme 1559 skepticism, including refusing to display them to the end user or 1560 even ignoring the signature if it does not cover certain Header 1561 fields. 1563 The DOSETA-Signature header field is always implicitly signed and 1564 MUST NOT be included in the "h" parameter except to indicate that 1565 other preexisting signatures are also signed. 1567 Signers MAY claim to have signed Header fields that do not exist 1568 (that is, signers MAY include the header field name in the "h" 1569 parameter even if that header field does not exist in the message). 1570 When computing the signature, the non-existing header field MUST be 1571 treated as the null string (including the header field name, header 1572 field value, all punctuation, and the trailing CRLF). 1574 NOTE: This allows signers to explicitly assert the absence of a 1575 header field; if that header field is added later the signature 1576 will fail. 1578 NOTE: A header field name need only be listed once more than the 1579 actual number of that header field in a message at the time of 1580 signing in order to prevent any further additions. For example, 1581 if there is a single Comments header field at the time of signing, 1582 listing Comments twice in the "h" parameter is sufficient to 1583 prevent any number of Comments Header fields from being appended; 1584 it is not necessary (but is legal) to list Comments three or more 1585 times in the "h" parameter. 1587 Signers choosing to sign an existing header field that occurs more 1588 than once in the message (such as Received) MUST sign the physically 1589 last instance of that header field in the header block. Signers 1590 wishing to sign multiple instances of such a header field MUST 1591 include the header field name multiple times in the h= tag of the 1592 DOSETA-Signature header field, and MUST sign such Header fields in 1593 order from the bottom of the header field block to the top. The 1594 signer MAY include more instances of a header field name in h= than 1595 there are actual corresponding Header fields to indicate that 1596 additional Header fields of that name SHOULD NOT be added. 1598 EXAMPLE: 1600 If the signer wishes to sign two existing Received Header fields, 1601 and the existing header contains: 1602 Received: 1603 Received: 1604 Received: 1606 then the resulting DOSETA-Signature header field ought to read: 1608 DKIM-Signature: ... h=Received : Received :... 1609 and Received Header fields and will be signed in that 1610 order. 1612 Signers need to be careful of signing Header fields that might have 1613 additional instances added later in the delivery process, since such 1614 Header fields might be inserted after the signed instance or 1615 otherwise reordered. Trace Header fields (such as Received) and 1616 Resent-* blocks are the only fields prohibited by [RFC5322] from 1617 being reordered. In particular, since DOSETA-Signature Header fields 1618 might be reordered by some intermediate MTAs, signing existing 1619 DOSETA-Signature Header fields is error-prone. 1621 NOTE: Despite the fact that [RFC5322] permits Header fields to be 1622 reordered (with the exception of Received Header fields), 1623 reordering of signed Header fields with multiple instances by 1624 intermediate MTAs will cause DOSETA signatures to be broken; such 1625 anti-social behavior ought to be avoided. 1627 NOTE: Although not required by this specification, all end-user 1628 visible Header fields SHOULD be signed to avoid possible "indirect 1629 spamming". For example, if the Subject header field is not 1630 signed, a spammer can resend a previously signed mail, replacing 1631 the legitimate subject with a one-line spam. 1633 4.5.4. Compute the Message Signature 1635 The signer MUST compute the message hash as described in Section 4.4 1636 and then sign it using the selected public-key algorithm. This will 1637 result in a DOSETA-Signature header field that will include the 1638 Content hash and a signature of the header hash, where that header 1639 includes the DOSETA-Signature header field itself. 1641 Entities such as mailing list managers that implement DOSETA and that 1642 modify the message or a header field (for example, inserting 1643 unsubscribe information) before retransmitting the message SHOULD 1644 check any existing signature on input and MUST make such 1645 modifications before re-signing the message. 1647 The signer MAY elect to limit the number of bytes of the Content that 1648 will be included in the hash and hence signed. The length actually 1649 hashed SHOULD be inserted in the "l=" tag of the DOSETA-Signature 1650 header field. 1652 4.5.5. Insert the DOSETA-Signature Header Field 1654 Finally, the signer MUST insert the DOSETA-Signature header field 1655 created in the previous step prior to transmitting the data. The 1656 DOSETA-Signature header field MUST be the same as used to compute the 1657 hash as described above, except that the value of the "b" parameter 1658 MUST be the appropriately signed hash computed in the previous step, 1659 signed using the algorithm specified in the "a" parameter of the 1660 DOSETA-Signature header field and using the private key corresponding 1661 to the selector given in the "s=" tag of the DOSETA-Signature header 1662 field, as chosen above in Section 4.5.2 1664 The DOSETA-Signature header field MUST be inserted before any other 1665 DOSETA-Signature fields in the header block. 1667 NOTE: The easiest way to achieve this is to insert the 1668 DOSETA-Signature header field at the beginning of the header 1669 block. In particular, it might be placed before any existing 1670 Received Header fields. This is consistent with treating 1671 DOSETA-Signature as a trace header field. 1673 4.6. Verifier Actions 1675 Since a signer MAY remove or revoke a public key at any time, it is 1676 recommended that verification occur in a timely manner. In many 1677 configurations, the most timely place is during acceptance by the 1678 border MTA or shortly thereafter. In particular, deferring 1679 verification until the message is accessed by the end user is 1680 discouraged. 1682 A border or intermediate server MAY verify the data signature(s). An 1683 server that has performed verification MAY communicate the result of 1684 that verification by adding a verification header field to incoming 1685 data. 1687 A verifying server MAY implement a policy with respect to 1688 unverifiable data, regardless of whether or not it applies the 1689 verification header field to signed messages. 1691 Verifiers MUST produce a result that is semantically equivalent to 1692 applying the following steps in the order listed. In practice, 1693 several of these steps can be performed in parallel in order to 1694 improve performance. 1696 4.6.1. Extract Signatures from the Message 1698 The order in which verifiers try DOSETA-Signature Header fields is 1699 not defined; verifiers MAY try signatures in any order they like. 1700 For example, one implementation might try the signatures in textual 1701 order, whereas another might try signatures by identities that match 1702 the contents of the From header field before trying other signatures. 1703 Verifiers MUST NOT attribute ultimate meaning to the order of 1704 multiple DOSETA-Signature Header fields. In particular, there is 1705 reason to believe that some relays will reorder the Header fields in 1706 potentially arbitrary ways. 1708 NOTE: Verifiers might use the order as a clue to signing order in 1709 the absence of any other information. However, other clues as to 1710 the semantics of multiple signatures (such as correlating the 1711 signing host with Received Header fields) might also be 1712 considered. 1714 A verifier SHOULD NOT treat a message that has one or more bad 1715 signatures and no good signatures differently from a message with no 1716 signature at all; such treatment is a matter of local policy and is 1717 beyond the scope of this document. 1719 When a signature successfully verifies, a verifier will either stop 1720 processing or attempt to verify any other signatures, at the 1721 discretion of the implementation. A verifier MAY limit the number of 1722 signatures it tries to avoid denial-of-service attacks. 1724 NOTE: An attacker could send messages with large numbers of faulty 1725 signatures, each of which would require a DNS lookup and 1726 corresponding CPU time to verify the message. This could be an 1727 attack on the domain that receives the message, by slowing down 1728 the verifier by requiring it to do a large number of DNS lookups 1729 and/or signature verifications. It could also be an attack 1730 against the domains listed in the signatures, essentially by 1731 enlisting innocent verifiers in launching an attack against the 1732 DNS servers of the actual victim. 1734 In the following description, text reading "return status 1735 (explanation)" (where "status" is one of "PERMFAIL" or "TEMPFAIL") 1736 means that the verifier MUST immediately cease processing that 1737 signature. The verifier SHOULD proceed to the next signature, if any 1738 is present, and completely ignore the bad signature. If the status 1739 is "PERMFAIL", the signature failed and SHOULD NOT be reconsidered. 1740 If the status is "TEMPFAIL", the signature could not be verified at 1741 this time but might be tried again later. A verifier MAY either 1742 defer the message for later processing, perhaps by queueing it 1743 locally or issuing a 451/4.7.5 SMTP reply, or try another signature; 1744 if no good signature is found and any of the signatures resulted in a 1745 TEMPFAIL status, the verifier MAY save the message for later 1746 processing. The "(explanation)" is not normative text; it is 1747 provided solely for clarification. 1749 Verifiers SHOULD ignore any DOSETA-Signature Header fields where the 1750 signature does not validate. Verifiers that are prepared to validate 1751 multiple signature Header fields SHOULD proceed to the next signature 1752 header field, if it exists. However, verifiers MAY make note of the 1753 fact that an invalid signature was present for consideration at a 1754 later step. 1756 NOTE: The rationale of this requirement is to permit messages that 1757 have invalid signatures but also a valid signature to work. For 1758 example, a mailing list exploder might opt to leave the original 1759 submitter signature in place even though the exploder knows that 1760 it is modifying the message in some way that will break that 1761 signature, and the exploder inserts its own signature. In this 1762 case, the message ought to succeed even in the presence of the 1763 known-broken signature. 1765 For each signature to be validated, the following steps need to be 1766 performed in such a manner as to produce a result that is 1767 semantically equivalent to performing them in the indicated order. 1769 4.6.2. Validate the Signature Header Field 1771 Implementers MUST meticulously validate the format and values in the 1772 DOSETA-Signature header field; any inconsistency or unexpected values 1773 MUST cause the header field to be completely ignored and the verifier 1774 to return PERMFAIL (signature syntax error). Being "liberal in what 1775 you accept" is definitely a bad strategy in this security context. 1776 Note however that this does not include the existence of unknown tags 1777 in a DOSETA-Signature header field, which are explicitly permitted. 1779 If any tag listed as "required" in Section 4.2 is omitted from the 1780 DOSETA-Signature header field, the verifier MUST ignore the 1781 DOSETA-Signature header field and return PERMFAIL (signature missing 1782 required tag). 1784 NOTE: The tags listed as required in Section 4.2 are "v=", "a=", 1785 "b=", "bh=", "d=", "h=", and "s=". Should there be a conflict 1786 between this note and Section 4.2, is normative. 1788 If the DOSETA-Signature header field does not contain the "i" 1789 parameter, the verifier MUST behave as though the value of that tag 1790 were "@d", where "d" is the value from the "d=" tag. 1792 Verifiers MUST confirm that the domain specified in the "d=" tag is 1793 the same as or a parent domain of the domain part of the "i" 1794 parameter. If not, the DOSETA-Signature header field MUST be ignored 1795 and the verifier SHOULD return PERMFAIL (domain mismatch). 1797 If the "h" parameter does not include the From header field, the 1798 verifier MUST ignore the DOSETA-Signature header field and return 1799 PERMFAIL (From field not signed). 1801 Verifiers MAY ignore the DOSETA-Signature header field and return 1802 PERMFAIL (signature expired) if it contains an "x" parameter and the 1803 signature has expired. 1805 Verifiers MAY ignore the DOSETA-Signature header field if the domain 1806 used by the signer in the "d" parameter is not associated with a 1807 valid signing entity. For example, signatures with "d=" values such 1808 as "com" and "co.uk" might be ignored. The list of unacceptable 1809 domains SHOULD be configurable. 1811 Verifiers MAY ignore the DOSETA-Signature header field and return 1812 PERMFAIL (unacceptable signature header) for any other reason, for 1813 example, if the signature does not sign Header fields that the 1814 verifier views to be essential. As a case in point, if MIME Header 1815 fields are not signed, certain attacks might be possible that the 1816 verifier would prefer to avoid. 1818 4.6.3. Get the Public Key 1820 The public key for a signature is needed to complete the verification 1821 process. The process of retrieving the public key depends on the 1822 query type as defined by the "q" parameter in the DOSETA-Signature 1823 header field. Obviously, a public key need only be retrieved if the 1824 process of extracting the signature information is completely 1825 successful. Details of key management and representation are 1826 described in Section 3.4. The verifier MUST validate the key record 1827 and MUST ignore any public key records that are malformed. 1829 NOTE: The use of wildcard TXT records in the DNS will produce a 1830 response to a DOSETA query that is unlikely to be valid DOSETA key 1831 record. This problem applies to many other types of queries, and 1832 client software that processes DNS responses needs to take this 1833 problem into account. 1835 When validating a message, a verifier MUST perform the following 1836 steps in a manner that is semantically the same as performing them in 1837 the following order -- in some cases the implementation might 1838 parallelize or reorder these steps, as long as the semantics remain 1839 unchanged: 1841 1. Retrieve the public key as described in Section 3.4 using the 1842 algorithm in the "q=" tag, the domain from the "d" parameter, and 1843 the selector from the "s" parameter. 1845 2. If the query for the public key fails to respond, the verifier 1846 MAY defer acceptance of this data and return TEMPFAIL - key 1847 unavailable. (If verification is occurring during the incoming 1848 SMTP session, this MAY be achieved with a 451/4.7.5 SMTP reply 1849 code.) Alternatively, the verifier MAY store the message in the 1850 local queue for later trial or ignore the signature. Note that 1851 storing a message in the local queue is subject to denial-of- 1852 service attacks. 1854 3. If the query for the public key fails because the corresponding 1855 key record does not exist, the verifier MUST immediately return 1856 PERMFAIL (no key for signature). 1858 4. If the query for the public key returns multiple key records, the 1859 verifier might choose one of the key records or might cycle 1860 through the key records performing the remainder of these steps 1861 on each record at the discretion of the implementer. The order 1862 of the key records is unspecified. If the verifier chooses to 1863 cycle through the key records, then the "return ..." wording in 1864 the remainder of this section means "try the next key record, if 1865 any; if none, return to try another signature in the usual way". 1867 5. If the result returned from the query does not adhere to the 1868 format defined in this specification, the verifier MUST ignore 1869 the key record and return PERMFAIL (key syntax error). Verifiers 1870 are urged to validate the syntax of key records carefully to 1871 avoid attempted attacks. 1873 6. If the "h" parameter exists in the public key record and the hash 1874 algorithm implied by the a= tag in the DOSETA-Signature header 1875 field is not included in the contents of the "h" parameter, the 1876 verifier MUST ignore the key record and return PERMFAIL 1877 (inappropriate hash algorithm). 1879 7. If the public key data (the "p" parameter) is empty, then this 1880 key has been revoked and the verifier MUST treat this as a failed 1881 signature check and return PERMFAIL (key revoked). There is no 1882 defined semantic difference between a key that has been revoked 1883 and a key record that has been removed. 1885 8. If the public key data is not suitable for use with the algorithm 1886 and key types defined by the "a=" and "k" parameters in the 1887 DOSETA-Signature header field, the verifier MUST immediately 1888 return PERMFAIL (inappropriate key algorithm). 1890 4.6.4. Compute the Verification 1892 Given a signer and a public key, verifying a signature consists of 1893 actions semantically equivalent to the following steps. 1895 1. Based on the algorithm defined in the "c" parameter, the Content 1896 length specified in the "l" parameter, and the header field names 1897 in the "h" parameter, prepare a canonicalized version of the 1898 Content as is described in Section 4.4 (note that this version 1899 does not actually need to be instantiated). When matching header 1900 field names in the "h" parameter against the actual message 1901 header field, comparisons MUST be case-insensitive. 1903 2. Based on the algorithm indicated in the "a" parameter, compute 1904 the message hashes from the canonical copy as described in 1905 Section 4.4 1907 3. Verify that the hash of the canonicalized Content computed in the 1908 previous step matches the hash value conveyed in the "bh" 1909 parameter. If the hash does not match, the verifier SHOULD 1910 ignore the signature and return PERMFAIL (Content hash did not 1911 verify). 1913 4. Using the signature conveyed in the "b" parameter, verify the 1914 signature against the header hash using the mechanism appropriate 1915 for the public key algorithm described in the "a" parameter. If 1916 the signature does not validate, the verifier SHOULD ignore the 1917 signature and return PERMFAIL (signature did not verify). 1919 5. Otherwise, the signature has correctly verified. 1921 NOTE: Implementations might wish to initiate the public-key query 1922 in parallel with calculating the hash as the public key is not 1923 needed until the final decryption is calculated. Implementations 1924 might also verify the signature on the message header before 1925 validating that the message hash listed in the "bh" parameter in 1926 the DOSETA-Signature header field matches that of the actual 1927 Content; however, if the Content hash does not match, the entire 1928 signature MUST be considered to have failed. 1930 4.6.5. Communicate Verification Results 1932 Verifiers wishing to communicate the results of verification to other 1933 parts of the data handling system can do so in whatever manner they 1934 see fit. For example, implementations might choose to add a Header 1935 field to the data before passing it on. Any such header field SHOULD 1936 be inserted before any existing DOSETA-Signature or preexisting 1937 verification status Header fields in the header field block. The 1938 Authentication-Results: header field ([RFC5451]) MAY be used for this 1939 purpose. 1941 Patterns intended to search for results Header fields to visibly 1942 mark authenticated data for end users SHOULD verify that the 1943 header field was added by the appropriate verifying domain In 1944 particular, filters SHOULD NOT be influenced by bogus results 1945 header fields added by attackers. To circumvent this attack, 1946 verifiers SHOULD delete existing results Header fields after 1947 verification and before adding a new header field. 1949 4.6.6. Interpret Results/Apply Local Policy 1951 It is beyond the scope of this specification to describe what actions 1952 an Assessment phase will take, but data with a verified DOSETA 1953 signature presents an opportunity to an Assessor that unsigned data 1954 does not. Specifically, signed data creates a predictable identifier 1955 by which other decisions can reliably be managed, such as trust and 1956 reputation. Conversely, unsigned data typically lacks a reliable 1957 identifier that can be used to assign trust and reputation. It is 1958 usually reasonable to treat unsigned data as lacking any trust and 1959 having no positive reputation. 1961 In general, verifiers SHOULD NOT reject data solely on the basis of a 1962 lack of signature or an unverifiable signature; such rejection would 1963 cause severe interoperability problems. However, if the verifier 1964 does opt to reject such data 1966 Temporary failures such as inability to access the key server or 1967 other external service are the only conditions that SHOULD use a 1968 temporary failure code. In particular, cryptographic signature 1969 verification failures MUST NOT return temporary failure replies. 1971 Once the signature has been verified, that information MUST be 1972 conveyed to the Assessor (such as an explicit allow/whitelist and 1973 reputation system) and/or to the end user. If the DDI is not the 1974 same as the address in the From: header field, the data system SHOULD 1975 take pains to ensure that the actual DDI is clear to the reader. 1977 The verifier MAY treat unsigned Header fields with extreme 1978 skepticism, including marking them as untrusted or even deleting 1979 them. 1981 While the symptoms of a failed verification are obvious -- the 1982 signature doesn't verify -- establishing the exact cause can be more 1983 difficult. If a selector cannot be found, is that because the 1984 selector has been removed, or was the value changed somehow in 1985 transit? If the signature line is missing, is that because it was 1986 never there, or was it removed by an overzealous filter? For 1987 diagnostic purposes, the exact nature of a verification failure 1988 SHOULD be made available to the policy module and possibly recorded 1989 in the system logs. If the data cannot be verified, then it SHOULD 1990 be rendered the same as all unverified data regardless of whether or 1991 not it looks like it was signed. 1993 4.7. Requirements for Tailoring the Signing Service 1995 This generic template requires additional details, to define a 1996 specific service: 1998 Association: Specify the means by which the signature field is 1999 associated with the data it signs. This identifies the 2000 specific signing service and the mechanics of attaching the 2001 signature. For example, DKIM uses the DKIM-Signature email 2002 header field. If the header field is encoded differently than 2003 defined for the DOSETA generic service, such as in XML or JSON, 2004 then that also needs to be specified, including the algorithm 2005 for mapping between the common encoding provided here and the 2006 new encoding. 2008 Semantics: Define the meaning(s) of a signature that is intended 2009 by the signer. Note that exactly the same algorithms might be 2010 used for very different semantics. One might merely affix an 2011 identifier to some data, in a verifiable fashion, while the 2012 same set of mechanisms might separately be defined as 2013 authenticating the validity of that data. A single service can 2014 support multiple semantics for a signature. These SHOULD be 2015 specified using the "cl=" claims mechanism defined in 2016 Section 4.2 and Section 6 with values listed in Section 7.1.2 2018 Structural Mapping: The mappings between the template's generic 2019 service and data of a particular service needs to be defined. 2020 For example, with DKIM the DOSETA Header maps to the email 2021 header and DOSETA Content maps to the email body. 2023 Required Fields: Specify the header fields that MUST, SHOULD or 2024 MAY be included in the signature calculation. 2026 Required Algorithms: Specify the hashing and signing algorithms 2027 that MUST, SHOULD or MAY be supported by participants in the 2028 service. 2030 5. Semantics of Multiple Signatures 2032 5.1. Example Scenarios 2034 There are many reasons why a message might have multiple signatures. 2035 For example, a given signer might sign multiple times, perhaps with 2036 different hashing or signing algorithms during a transition phase. 2038 EXAMPLE: Suppose SHA-256 is in the future found to be 2039 insufficiently strong, and DOSETA usage transitions to SHA-1024. 2040 A signer might immediately sign using the newer algorithm, but 2041 continue to sign using the older algorithm for interoperability 2042 with verifiers that had not yet upgraded. The signer would do 2043 this by adding two DOSETA-Signature Header fields, one using each 2044 algorithm. Older verifiers that did not recognize SHA-1024 as an 2045 acceptable algorithm would skip that signature and use the older 2046 algorithm; newer verifiers could use either signature at their 2047 option, and all other things being equal might not even attempt to 2048 verify the other signature. 2050 Similarly, a signer might sign a message including all headers and no 2051 "l" parameter (to satisfy strict verifiers) and a second time with a 2052 limited set of headers and an "l" parameter (in anticipation of 2053 possible message modifications in route to other verifiers). 2054 Verifiers could then choose which signature they preferred. 2056 EXAMPLE: A verifier might receive data with two signatures, one 2057 covering more of the data than the other. If the signature 2058 covering more of the data verified, then the verifier could make 2059 one set of policy decisions; if that signature failed but the 2060 signature covering less of the data verified, the verifier might 2061 make a different set of policy decisions. 2063 Of course, a message might also have multiple signatures because it 2064 passed through multiple signers. A common case is expected to be 2065 that of a signed message that passes through a mailing list that also 2066 signs all messages. Assuming both of those signatures verify, a 2067 recipient might choose to accept the message if either of those 2068 signatures were known to come from trusted sources. 2070 EXAMPLE: Recipients might choose to whitelist mailing lists to 2071 which they have subscribed and that have acceptable anti- abuse 2072 policies so as to accept messages sent to that list even from 2073 unknown authors. They might also subscribe to less trusted 2074 mailing lists (for example, those without anti-abuse protection) 2075 and be willing to accept all messages from specific authors, but 2076 insist on doing additional abuse scanning for other messages. 2078 Another related example of multiple signers might be forwarding 2079 services, such as those commonly associated with academic alumni 2080 sites. 2082 EXAMPLE: A recipient might have an address at members.example.org, 2083 a site that has anti-abuse protection that is somewhat less 2084 effective than the recipient would prefer. Such a recipient might 2085 have specific authors whose messages would be trusted absolutely, 2086 but messages from unknown authors that had passed the forwarder's 2087 scrutiny would have only medium trust. 2089 5.2. Interpretation 2091 A signer that is adding a signature to a message merely creates a new 2092 DOSETA-Signature header, using the usual semantics of the h= option. 2093 A signer MAY sign previously existing DOSETA-Signature Header fields 2094 using the method described in Section 4.5.3 to sign trace Header 2095 fields. 2097 NOTE: Signers need to be cognizant that signing DOSETA-Signature 2098 Header fields might result in verification failures due to 2099 modifications by intermediaries, such as their reordering 2100 DOSETA-Signature header fields. For this reason, signing existing 2101 DOSETA-Signature Header fields is unadvised, albeit legal. 2103 NOTE: If a header field with multiple instances is signed, those 2104 header fields are always signed from the "bottom" up (from last to 2105 first). Thus, it is not possible to sign only specific instances 2106 of header fields. For example, if the message being signed 2107 already contains three DOSETA-Signature header fields (from the 2108 bottom, up) A, B, and C, it is possible to sign all of them, A and 2109 B only, or A only, but not C only, B only, B and C only, or A and 2110 C only. 2112 A signer MAY add more than one DOSETA-Signature header field using 2113 different parameters. For example, during a transition period a 2114 signer might want to produce signatures using two different hash 2115 algorithms. 2117 Signers SHOULD NOT remove any DOSETA-Signature Header fields from 2118 messages they are signing, even if they know that the signatures 2119 cannot be verified. 2121 When evaluating a message with multiple signatures, a verifier SHOULD 2122 evaluate signatures independently and on their own merits. For 2123 example, a verifier that by policy chooses not to accept signatures 2124 with deprecated cryptographic algorithms would consider such 2125 signatures invalid. Verifiers MAY process signatures in any order of 2126 their choice; for example, some verifiers might choose to process 2127 signatures corresponding to the From field in the message header 2128 before other signatures. See Section 4.6.1 for more information 2129 about signature choices. 2131 NOTE: Verifier attempts to correlate valid signatures with invalid 2132 signatures in an attempt to guess why a signature failed are ill- 2133 advised. In particular, there is no general way that a verifier 2134 can determine that an invalid signature was ever valid. 2136 Verifiers SHOULD ignore failed signatures as though they were not 2137 present in the message. Verifiers SHOULD continue to check 2138 signatures until a signature successfully verifies to the 2139 satisfaction of the verifier. To limit potential denial-of-service 2140 attacks, verifiers MAY limit the total number of signatures they will 2141 attempt to verify. 2143 6. DOSETA Claims Registry Definition 2145 A registry entry MUST contain: 2147 Label: Specifies a textual name for claim, to be used in the 2148 "cl=" tag. 2150 Description: Explains the semantics of the claim being asserted. 2152 The registry entries are contained in the IANA DOSETA Claims 2153 Registry, defined in Section 7.1.2 2155 7. Considerations 2157 7.1. IANA Considerations 2159 7.1.1. DKIM Registries 2161 DOSETA relies on IANA registration data bases specified by DKIM 2162 [DKIMSign]. Services that incorporate DOSETA might need to define 2163 new registries or add to existing ones. 2165 7.1.2. Claims Registry 2167 Per [RFC2434], IANA is requested to establish a DOSETA Claims 2168 Registry, for assertions (claims) that are meant by the presence of 2169 the DOSETA-based signature that contains the claims. See Section 6 2170 for the definition of the columns in the registry table. 2172 +-------------+-----------------------------------------------------+ 2173 | LABEL | CLAIM DESCRIPTION | 2174 +-------------+-----------------------------------------------------+ 2175 | handled | The signer claims they have had a role in | 2176 | | processing the object. (This claim is | 2177 | | approximately equivalent to the semantics of DKIM.) | 2178 | validauth | If there is a standardized field listing the | 2179 | | purported author of the data, the signer claims | 2180 | | that the value in that field is valid. | 2181 | validdata | The signer claims that all of the data in the | 2182 | | object valid. | 2183 | validfields | The signer claims that the portions of the object | 2184 | | that are covered by the signature hash are valid. | 2185 +-------------+-----------------------------------------------------+ 2187 Table 1: DOSETA Claim Registry (with initial values) 2189 7.2. Security Considerations 2191 Any mechanism that attempts to prevent or detect abuse is subject to 2192 intensive attack. DOSETA needs to be carefully scrutinized to 2193 identify potential attack vectors and the vulnerability to each. See 2194 also [RFC4686]. 2196 DOSETA core technology derives from DKIM [DKIMSign]. The Security 2197 Considerations of that specification applies equally to DOSETA. 2199 The DOSETA "cl=" claims list provides a list of claimed meanings for 2200 a DOSETA signature. An opportunity for security problems comes from 2201 failing to distinguish between a signer "claim" and claim validity. 2202 Whether to trust claims made by a signer requires a level of 2203 assessment beyond DOSETA. 2205 8. References 2207 8.1. Normative References 2209 [FIPS-180-2-2002] 2210 U.S. Department of Commerce, "Secure Hash Standard", FIPS 2211 PUB 180-2, August 2002. 2213 [ITU-X660-1997] 2214 "Information Technology - ASN.1 encoding rules: 2215 Specification of Basic Encoding Rules (BER), Canonical 2216 Encoding Rules (CER) and Distinguished Encoding Rules 2217 (DER)", 1997. 2219 [RFC1034] Mockapetris, P., "DOMAIN NAMES - CONCEPTS AND FACILITIES", 2220 RFC 1034, November 1987. 2222 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2223 Extensions (MIME) Part One: Format of Internet Message 2224 Bodies", RFC 2045, November 1996. 2226 [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2227 Extensions (MIME) Part Five: Conformance Criteria and 2228 Examples", RFC 2049, November 1996. 2230 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2231 Requirement Levels", BCP 14, RFC 2119, March 1997. 2233 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2234 IANA Considerations Section in RFCs", RFC 2434, 2235 October 1998. 2237 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2238 Standards (PKCS) #1: RSA Cryptography Specifications 2239 Version 2.1", RFC 3447, February 2003. 2241 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2242 Specifications: ABNF", RFC 4234, January 2008. 2244 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 2245 October 2008. 2247 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 2248 October 2008. 2250 [RFC5890] Klensin, J., "Internationalizing Domain Names in 2251 Applications (IDNA): Definitions and Document Framework", 2252 RFC 5890, August 2010. 2254 8.2. Informative References 2256 [DKIMSign] 2257 Allman, E., Callas, J., Delany, M., Libbey, M., Fenton, 2258 J., and M. Thomas, "DomainKeys Identified Mail (DKIM) 2259 Signatures", RFC 4871, May 2007. 2261 [RFC1847] Galvin, J., Murphy, S., Crocker, S., and N. Freed, 2262 "Security Multiparts for MIME: Multipart/Signed and 2263 Multipart/Encrypted", RFC 1847, October 1995. 2265 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 2266 Part Three: Message Header Extensions for Non-ASCII 2267 Content", RFC 2047, November 1996. 2269 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 2270 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 2271 RFC 3766, April 2004. 2273 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2274 Rose, "DNS Security Introduction and Requirements", 2275 RFC 4033, March 2005. 2277 [RFC4409] Gellens, R. and J. Klensin, "Message Submission for Mail", 2278 RFC 4409, April 2006. 2280 [RFC4686] Fenton, J., "Analysis of Threats Motivating DomainKeys 2281 Identified Mail (DKIM)", RFC 4686, September 2006. 2283 [RFC4870] Delany, M., "Domain-Based Email Authentication Using 2284 Public Keys Advertised in the DNS (DomainKeys)", RFC 4870, 2285 May 2007. 2287 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., and R. Thayer, 2288 "OpenPGP Message Format", RFC 4880, November 2007. 2290 [RFC5451] Kucherawy, M., "Message Header Field for Indicating 2291 Message Authentication Status", RFC 5451, April 2009. 2293 [RFC5672] Crocker, D., Ed., "RFC 4871 DomainKeys Identified Mail 2294 (DKIM) Signatures: Update", RFC 5672, August 2009. 2296 [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO 2297 10646", RFC 3629, November 2003. 2299 [mimeauth] 2300 Crocker, D. and M. Kucherawy, "MIME Content Authentication 2301 using DOSETA (MIMEAUTH)", 2302 I-D draft-crocker-doseta-mimeauth, 2011. 2304 Appendix A. Creating a Public Key 2306 The default signature is an RSA signed SHA256 digest of the complete 2307 email. For ease of explanation, the openssl command is used to 2308 describe the mechanism by which keys and signatures are managed. One 2309 way to generate a 1024-bit, unencrypted private key suitable for 2310 DOSETA is to use openssl like this: 2311 $ openssl genrsa -out rsa.private 1024 2312 For increased security, the "-passin" parameter can also be added to 2313 encrypt the private key. Use of this parameter will require entering 2314 a password for several of the following steps. Servers might prefer 2315 to use hardware cryptographic support. 2317 The "genrsa" step results in the file rsa.private containing the key 2318 information similar to this: 2319 -----BEGIN RSA PRIVATE KEY----- 2320 MIICXwIBAAKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFC 2321 jxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gb 2322 to/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB 2323 AoGBALmn+XwWk7akvkUlqb+dOxyLB9i5VBVfje89Teolwc9YJT36BGN/l4e0l6QX 2324 /1//6DWUTB3KI6wFcm7TWJcxbS0tcKZX7FsJvUz1SbQnkS54DJck1EZO/BLa5ckJ 2325 gAYIaqlA9C0ZwM6i58lLlPadX/rtHb7pWzeNcZHjKrjM461ZAkEA+itss2nRlmyO 2326 n1/5yDyCluST4dQfO8kAB3toSEVc7DeFeDhnC1mZdjASZNvdHS4gbLIA1hUGEF9m 2327 3hKsGUMMPwJBAPW5v/U+AWTADFCS22t72NUurgzeAbzb1HWMqO4y4+9Hpjk5wvL/ 2328 eVYizyuce3/fGke7aRYw/ADKygMJdW8H/OcCQQDz5OQb4j2QDpPZc0Nc4QlbvMsj 2329 7p7otWRO5xRa6SzXqqV3+F0VpqvDmshEBkoCydaYwc2o6WQ5EBmExeV8124XAkEA 2330 qZzGsIxVP+sEVRWZmW6KNFSdVUpk3qzK0Tz/WjQMe5z0UunY9Ax9/4PVhp/j61bf 2331 eAYXunajbBSOLlx4D+TunwJBANkPI5S9iylsbLs6NkaMHV6k5ioHBBmgCak95JGX 2332 GMot/L2x0IYyMLAz6oLWh2hm7zwtb0CgOrPo1ke44hFYnfc= 2333 -----END RSA PRIVATE KEY----- 2334 To extract the public-key component from the private key, use openssl 2335 like this: 2336 $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM 2338 This results in the file rsa.public containing the key information 2339 similar to this: 2340 -----BEGIN PUBLIC KEY----- 2341 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkM 2342 oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R 2343 tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI 2344 MmPSPDdQPNUYckcQ2QIDAQAB 2345 -----END PUBLIC KEY----- 2347 This public-key data (without the BEGIN and END tags) is placed in 2348 the DNS: 2350 brisbane IN TXT 2351 ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ" 2352 "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt" 2353 "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v" 2354 "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi" 2355 "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB") 2357 Appendix B. Acknowledgements 2359 DOSETA is derived from DKIM [DKIMSign]. DKIM is an evolution of 2360 DomainKeys [RFC4870], which was developed by Mark Delany, then of 2361 Yahoo!. In particular, the key management service, based on the DNS, 2362 and the user-INvisible tagging scheme was developed by him. 2364 Appendix C. Example -- DKIM Using DOSETA 2366 This example re-specifies DKIM in terms of DOSETA, while retaining 2367 bit-level compatibility with the existing DKIM specification 2368 [DKIMSign]. 2370 NOTE: This section is merely an example. Any use of normative 2371 language in this section is strictly for completness of the 2372 example and has no normative effect on the DOSETA specification. 2374 C.1. Signing and Verification Protocol 2376 The DOSETA template specifies TEMPLATE information that is required 2377 to tailor the signing service: 2379 Association: The DOSETA-Signature data are stored in a 2380 DKIM-Signature header field that is part of the header of the 2381 message being signed. This contains all of the signature and 2382 key-fetching data, per Section 4.2. 2384 Semantics: A DKIM signature means that the owner of the signing 2385 domain is taking "some" responsibility for the message. Hence, 2386 the payload, or output, of DKIM is: 2388 + A validated domain name, specifically the d= parameter in 2389 the DKIM-Signature header field 2391 + An indication that its use has been validated 2393 The nature and extent of a DKIM signer's responsibility can 2394 vary widely and is beyond the scope of this specification. 2396 Structural Mapping: DKIM maps the DOSETA Header processing to an 2397 email header and the DOSETA Content to an email body, per 2398 [RFC5322] 2400 Required Support 2402 Field Hash: The basic rule for choosing fields to include is 2403 to select those fields that constitute the "core" of the 2404 message content. Hence, any replay attack will have to 2405 include these in order to have the signature succeed; but 2406 with these included, the core of the message is valid, even 2407 if sent on to new recipients. 2409 Common examples of fields with addresses and fields with 2410 textual content related to the body are: From (MUST be 2411 included), Reply-To, Subject, Date, To, Cc, Resent-Date, 2412 Resent-From, Resent-To, Resent-Cc, In-Reply-To, References, 2413 List-Id, List-Help, List-Unsubscribe, List-Subscribe, List- 2414 Post, List-Owner, List-Archive. 2416 Required Algorithms: Use DOSETA defaults. 2418 C.2. Extensions to DOSETA Template 2420 This section contains specifications that are added to the basic 2421 DOSETA H/C Signing Template. 2423 C.2.1. Signature Data Structure 2425 These are DKIM-specific tags: 2427 i= The Agent or User Identifier (AUID) on behalf of which the 2428 SDID is taking responsibility (DOSETA-quoted-printable; 2429 OPTIONAL, default is an empty followed by an "@" 2430 followed by the domain from the "d=" tag). 2432 The syntax is a standard email address where the 2433 MAY be omitted. The domain part of the address MUST be the 2434 same as, or a subdomain of, the value of the "d=" tag. 2436 Internationalized domain names MUST be converted using the 2437 steps listed in Section 4 of [RFC5890] using the "ToASCII" 2438 function. 2440 ABNF: 2441 sig-i-tag = %x69 [FWS] "=" [FWS] 2442 [ local-part ] "@" domain-name 2444 The AUID is specified as having the same syntax as an email 2445 address, but is not required to have the same semantics. 2446 Notably, the domain name is not required to be registered in 2447 the DNS -- so it might not resolve in a query -- and the 2448 MAY be drawn from a namespace unrelated to any 2449 mailbox. The details of the structure and semantics for the 2450 namespace are determined by the Signer. Any knowledge or use 2451 of those details by verifiers or assessors is outside the scope 2452 of the DOSETA Signing specification. The Signer MAY choose to 2453 use the same namespace for its AUIDs as its users' email 2454 addresses or MAY choose other means of representing its users. 2455 However, the signer SHOULD use the same AUID for each message 2456 intended to be evaluated as being within the same sphere of 2457 responsibility, if it wishes to offer receivers the option of 2458 using the AUID as a stable identifier that is finer grained 2459 than the SDID. 2461 NOTE: The of the "i=" tag is optional because in 2462 some cases a signer might not be able to establish a 2463 verified individual identity. In such cases, the signer 2464 might wish to assert that although it is willing to go as 2465 far as signing for the domain, it is unable or unwilling to 2466 commit to an individual user name within their domain. It 2467 can do so by including the domain part but not the of the identity. 2470 NOTE: Absent public standards for the semantics of an AUID, 2471 an assessment based on AUID requires a non-standardized 2472 basis. 2474 NOTE: This specification does not require the value of the 2475 "i=" tag to match the identity in any Header field. This is 2476 considered to be an assessment-time policy issue. 2477 Constraints between the value of the "i=" tag and other 2478 identities in other Header fields might seek to apply basic 2479 authentication into the semantics of trust associated with a 2480 role such as content author. Trust is a broad and complex 2481 topic and trust mechanisms are subject to highly creative 2482 attacks. The real-world efficacy of any but the most basic 2483 bindings between the "i=" value and other identities is not 2484 well established, nor is its vulnerability to subversion by 2485 an attacker. Hence reliance on the use of these options 2486 needs to be strictly limited. In particular, it is not at 2487 all clear to what extent a typical end-user recipient can 2488 rely on any assurances that might be made by successful use 2489 of the "i=" options. 2491 l= Content length count (plain-text unsigned decimal integer; 2492 OPTIONAL, default is entire Content). This tag informs the 2493 verifier of the number of octets in the Content of the data 2494 after canonicalization included in the cryptographic hash, 2495 starting from 0 immediately following the CRLF preceding the 2496 Content. This value MUST NOT be larger than the actual number 2497 of octets in the canonicalized Content. 2499 ABNF: 2500 sig-l-tag = %x6c [FWS] "=" [FWS] 2501 1*76DIGIT 2503 NOTE: Use of the "l=" tag might allow display of fraudulent 2504 content without appropriate warning to end users. The "l=" 2505 tag is intended for increasing signature robustness when 2506 sending to intermediaries that append data to Content, such 2507 as mailing lists that both modify their content and do not 2508 sign their messages. However, using the "l=" tag enables 2509 attacks in which an intermediary with malicious intent 2510 modifies a message to include content that solely benefits 2511 the attacker. It is possible for the appended content to 2512 completely replace the original content in the end 2513 recipient's eyes and to defeat duplicate message detection 2514 algorithms. Examples are described in Security 2515 Considerations Section 7.2. To avoid this attack, signers 2516 need be extremely wary of using this tag, and verifiers 2517 might wish to ignore the tag or remove text that appears 2518 after the specified content length. 2520 NOTE: The value of the "l=" tag is constrained to 76 decimal 2521 digits. This constraint is not intended to predict the size 2522 of future data or to require implementations to use an 2523 integer representation large enough to represent the maximum 2524 possible value, but is intended to remind the implementer to 2525 check the length of this and all other tags during 2526 verification and to test for integer overflow when decoding 2527 the value. Implementers might need to limit the actual 2528 value expressed to a value smaller than 10^76, for example, 2529 to allow a message to fit within the available storage 2530 space. 2532 z= Copied Header fields (DOSETA-quoted-printable, but see 2533 description; OPTIONAL, default is null). A vertical-bar- 2534 separated list of selected Header fields present when the 2535 message was signed, including both the field name and value. 2536 It is not required to include all Header fields present at the 2537 time of signing. This field need not contain the same Header 2538 fields listed in the "h=" tag. The Header field text itself 2539 MUST encode the vertical bar ("|", %x7C) character. That is, 2540 vertical bars in the "z=" text are meta-characters, and any 2541 actual vertical bar characters in a copied header field MUST be 2542 encoded. Note that all whitespace MUST be encoded, including 2543 whitespace between the colon and the header field value. After 2544 encoding, FWS MAY be added at arbitrary locations in order to 2545 avoid excessively long lines; such whitespace is NOT part of 2546 the value of the header field, and MUST be removed before 2547 decoding. 2549 The Header fields referenced by the "h=" tag refer to the 2550 fields in the [RFC5322] Header, not to any copied fields in the 2551 "z=" tag. Copied header field values are for diagnostic use. 2553 Header fields with characters requiring conversion (perhaps 2554 from legacy MTAs that are not [RFC5322] compliant) SHOULD be 2555 converted as described in MIME Part Three [RFC2047]. 2557 ABNF: 2559 sig-z-tag = %x7A [FWS] "=" [FWS] 2560 sig-z-tag-copy 2561 *( "|" [FWS] sig-z-tag-copy ) 2562 sig-z-tag-copy = hdr-name [FWS] ":" 2563 qp-hdr-value 2565 EXAMPLE of a signature header field spread across multiple 2566 continuation lines: 2567 DKIM-Signature: v=1; a=rsa-sha256; d=example.net; 2568 s=brisbane; c=simple; q=dns/txt; i=@eng.example.net; 2569 t=1117574938; x=1118006938; 2570 h=from:to:subject:date; 2571 z=From:foo@eng.example.net|To:joe@example.com| 2572 Subject:demo=20run| 2573 Date:July=205,=202005=203:44:08=20PM=20-0700; 2574 bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=; 2575 b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZVoG4ZHRNiYzR 2577 C.2.1.1. Content Length Limits 2579 A text length count MAY be specified to limit the signature 2580 calculation to an initial prefix of an ASCII text data portion, 2581 measured in octets. If the Content length count is not specified, 2582 the entire Content is signed. 2584 This capability is provided because it is very common for 2585 intermediate data handling services to add trailers to text (for 2586 example, instructions how to get off a mailing list). Until such 2587 data is signed by the intermediate handler, the text length count can 2588 be a useful tool for the verifier since it can, as a matter of 2589 policy, accept messages having valid signatures that do not cover the 2590 additional data. 2592 NOTE: Using text length limits enables an attack in which an 2593 attacker modifies a message to include content that solely 2594 benefits the attacker. It is possible for the appended content to 2595 completely replace the original content in the end recipient's 2596 eyes and to defeat duplicate message detection algorithms. To 2597 avoid this attack, signers need to be wary of using this tag, and 2598 verifiers might wish to ignore the tag or remove text that appears 2599 after the specified content length, perhaps based on other 2600 criteria. 2602 The text length count allows the signer of text to permit data to be 2603 appended to the end of the text of a signed message. The text length 2604 count MUST be calculated following the canonicalization algorithm; 2605 for example, any whitespace ignored by a canonicalization algorithm 2606 is not included as part of the Content length count. Signers of MIME 2607 messages that include a Content length count SHOULD be sure that the 2608 length extends to the closing MIME boundary string. 2610 NOTE: A creator wishing to ensure that the only acceptable 2611 modifications are to add to a MIME postlude would use a text 2612 length count encompassing the entire final MIME boundary string, 2613 including the final "--CRLF". A signer wishing to allow 2614 additional MIME parts but not modification of existing parts would 2615 use a Content length count extending through the final MIME 2616 boundary string, omitting the final "--CRLF". Note that this only 2617 works for some MIME types, such as, multipart/mixed but not 2618 multipart/signed. 2620 A text length count of zero means that the text is completely 2621 unsigned. 2623 Creators wishing to ensure that no modification of any sort can occur 2624 will specify the "simple" canonicalization algorithm for all data 2625 portions and will and omit the text length counts. 2627 C.2.1.2. Signature Verification 2629 A Content length specified in the "l=" tag of the signature limits 2630 the number of bytes of the Content passed to the verification 2631 algorithm. All data beyond that limit is not validated by DOSETA. 2632 Hence, verifiers might treat a message that contains bytes beyond the 2633 indicated Content length with suspicion, such as by truncating the 2634 message at the indicated Content length, declaring the signature 2635 invalid (for example, by returning PERMFAIL (unsigned content)), or 2636 conveying the partial verification to the policy module. 2638 NOTE: Verifiers that truncate the Content at the indicated Content 2639 length might pass on a malformed MIME message if the signer used 2640 the "N-4" trick (omitting the final "--CRLF") described in the 2641 informative note in Appendix C.2.1.1. Such verifiers might wish 2642 to check for this case and include a trailing "--CRLF" to avoid 2643 breaking the MIME structure. A simple way to achieve this might 2644 be to append "--CRLF" to any "multipart" message with a Content 2645 length; if the MIME structure is already correctly formed, this 2646 will appear in the postlude and will not be displayed to the end 2647 user. 2649 C.2.2. Stored Key Data 2651 This section defines additions to the DOSETA Library, concerning 2652 stored key data. 2654 g= Granularity of the key (plain-text; OPTIONAL, default is 2655 "*"). This value MUST match the Local-part of the "i=" tag of 2656 the DKIM- Signature header field (or its default value of the 2657 empty string if "i=" is not specified), with a single, optional 2658 "*" character matching a sequence of zero or more arbitrary 2659 characters ("wildcarding"). An email with a signing address 2660 that does not match the value of this tag constitutes a failed 2661 verification. The intent of this tag is to constrain which 2662 signing address can legitimately use this selector, for 2663 example, when delegating a key to a third party that should 2664 only be used for special purposes. Wildcarding allows matching 2665 for addresses such as "user+*" or "*-offer". An empty "g=" 2666 value never matches any addresses. 2668 ABNF: 2669 key-g-tag = %x67 [FWS] "=" [FWS] key-g-tag-lpart 2670 key-g-tag-lpart = [dot-atom-text] 2671 ["*" [dot-atom-text] ] 2673 h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults 2674 to allowing all algorithms). A colon-separated list of hash 2675 algorithms that might be used. Signers and Verifiers MUST 2676 support the "sha256" hash algorithm. Verifiers MUST also 2677 support the "sha1" hash algorithm. Unrecognized hash 2678 algorithms MUST be ignored. 2680 ABNF: 2682 key-h-tag = %x68 [FWS] "=" [FWS] 2683 key-h-tag-alg 2684 0*( [FWS] ":" [FWS] 2685 key-h-tag-alg ) 2686 key-h-tag-alg = "sha1" / "sha256" / 2687 x-key-h-tag-alg 2688 x-key-h-tag-alg = hyphenated-word 2689 ; for future extension 2691 s= Service Type (plain-text; OPTIONAL; default is "*"). A 2692 colon-separated list of service types to which this record 2693 applies. Verifiers for a given service type MUST ignore this 2694 record if the appropriate type is not listed. Unrecognized 2695 service types MUST be ignored. Currently defined service types 2696 are as follows: 2698 * matches all service types 2700 email electronic mail (not necessarily limited to SMTP) 2702 This tag is intended to constrain the use of keys for other 2703 purposes, if use of DOSETA is defined by other services in the 2704 future. 2706 ABNF: 2708 key-s-tag = %x73 [FWS] "=" [FWS] 2709 key-s-tag-type 2710 0*( [FWS] ":" [FWS] 2711 key-s-tag-type ) 2712 key-s-tag-type = "email" / "*" / 2713 x-key-s-tag-type 2714 x-key-s-tag-type = hyphenated-word 2715 ; for future extension 2717 t= Flags, represented as a colon-separated list of names 2718 (plain-text; OPTIONAL, default is no flags set). Unrecognized 2719 flags MUST be ignored. The defined flags are as follows: 2721 y This domain is testing DOSETA. Verifiers MUST NOT treat 2722 data from signers in testing mode differently from unsigned 2723 data, even if the signature fails to verify. Verifiers MAY 2724 wish to track testing mode results to assist the signer. 2726 s Any DOSETA-Signature Header fields using the "i=" tag MUST 2727 have the same domain value on the right-hand side of the "@" 2728 in the "i=" tag and the value of the "d=" tag. That is, the 2729 "i=" domain MUST NOT be a subdomain of "d=". Use of this 2730 flag is RECOMMENDED unless subdomaining is required. 2732 ABNF: 2733 key-t-tag = %x74 [FWS] "=" [FWS] 2734 key-t-tag-flag 2735 0*( [FWS] ":" [FWS] 2736 key-t-tag-flag ) 2737 key-t-tag-flag = "y" / "s" / 2738 x-key-t-tag-flag 2739 x-key-t-tag-flag = hyphenated-word 2740 ; for future extension 2742 Authors' Addresses 2744 D. Crocker 2745 Brandenburg InternetWorking 2746 675 Spruce Dr. 2747 Sunnyvale 2748 USA 2750 Phone: +1.408.246.8253 2751 Email: dcrocker@bbiw.net 2752 URI: http://bbiw.net 2754 M. Kucherawy 2755 Cloudmark 2756 128 King St., 2nd Floor 2757 San Francisco, CA 94107 2758 USA 2760 Email: msk@cloudmark.com