RFC 8358
Update to Digital Signatures on Internet-Draft Documents
Update to Digital Signatures on Internet-Draft Documents ✨
Okay bestie, let's start with the basics 🎀 This is RFC 8358, written by R. Housley from Vigil Security and published in March 2018 🌸 It's Informational, which means it's published for information and isn't a Standards Track spec. Its ISSN is 2070-1721, and it updates RFC 5485. The header doesn't list any RFCs it obsoletes, so nothing gets replaced here, just updated 💖
Abstract
Okay so RFC 5485 is the rulebook for signing Internet-Drafts 🔏 It uses the Cryptographic Message Syntax (CMS) to make a detached signature, which just means the signature lives in its own companion file. That's iconic because none of the existing tools break when a signature gets added 🙌
Then the RFC Editor published the first RFC with non-ASCII characters in a plain text file 👀 That followed the conventions in RFC 7997. We're pretty sure non-ASCII characters are about to start showing up in Internet-Drafts too 🌈 So this document updates how digital signatures get handled for Internet-Drafts that have non-ASCII characters in a text file. Main character energy ✨
This document updates RFC 5485.
Status of This Memo
Real talk, this document is not an Internet Standards Track specification 📜 It's published for informational purposes 🦋
It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every IESG-approved doc is a candidate for an Internet Standard, so check Section 2 of RFC 7841 if you want the details 💅
For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc8358 🔗
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved 🌸
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stood on the publication date. Please read these carefully, because they spell out your rights and restrictions for this document 🧐 Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes 💜
Table of Contents ✨
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. ASN.1 . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Detached Signature Files . . . . . . . . . . . . . . . . . . 4
3. Additional Content Types . . . . . . . . . . . . . . . . . . 4
4. Need for Canonicalization . . . . . . . . . . . . . . . . . . 5
4.1. ASCII, UTF-8, and HTML File Canonicalization . . . . . . 6
4.2. XML File Canonicalization . . . . . . . . . . . . . . . . 6
4.3. No Canonicalization of Other File Formats . . . . . . . . 7
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . 7
7. Deployment and Operational Considerations . . . . . . . . . . 7
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
8.1. Normative References . . . . . . . . . . . . . . . . . . 7
8.2. Informative References . . . . . . . . . . . . . . . . . 9
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 91. Introduction 🦋
RFC 5485 [IDSIG] is the rulebook for signing Internet-Drafts 🔏 It uses the Cryptographic Message Syntax (CMS) [CMS] to create a detached signature, stored in a separate companion file, so no existing utilities are impacted by the signature 💖
The RFC Editor recently published the first RFC with non-ASCII characters in a text file. The conventions from RFC 7997 [RFCED] were followed. We expect non-ASCII characters to soon start appearing in Internet-Drafts as well, so this document updates how digital signatures are handled for Internet-Drafts that contain non-ASCII characters in a text file 🌈
This document updates RFC 5485 [IDSIG], which holds the conventions the IETF Secretariat has used to digitally sign Internet-Drafts for the past few years 🎀 The Secretariat generates the digital signature shortly after the Internet-Draft is posted in the repository ⭐
The digital signature lets anyone confirm that the contents of the Internet-Draft have not been altered since the document was signed 🔒 It's meant to be a simple way for anyone to check whether a particular file is the Internet-Draft the IETF Secretariat made available 🧚 The signing-time attached to the signature is the wall clock time when the signature was generated. It is not meant to be a trusted timestamp, so don't treat it like one 🙈
1.1. Terminology 💅
Here's the vocab 📖 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [STDWORDS] [STDWORDS2] when, and only when, they appear in all capitals, as shown here 🫶
1.2. ASN.1 🌸
The CMS uses Abstract Syntax Notation One (ASN.1) [X.680]. ASN.1 is a formal notation for describing data protocols, no matter which programming language the implementation uses 🧠 Encoding rules describe how the values defined in ASN.1 get represented for transmission 📦
The Basic Encoding Rules (BER) [X.690] are the most widely used rule set, but they give you more than one way to represent data structures. For example, definite length encoding and indefinite length encoding are both supported 😵💫 That flexibility is not desirable when digital signatures are involved, so the Distinguished Encoding Rules (DER) [X.690] were invented 👑 DER is a subset of BER that makes sure there's a single way to represent a given value. For example, DER always uses definite length encoding ✨
2. Detached Signature Files 📁
All Internet-Draft file names begin with "draft-" 🍓 The next part depends on where the document came from. For example, documents from IETF working groups usually have "ietf-" followed by the working group abbreviation, and then a string that helps people figure out the subject of the document 🧁
All Internet-Draft file names end with a hyphen, a two digit version number, and a suffix. The suffix tells you the type of file. For example, a text file has a suffix of ".txt". Plain text files are the most common today, but the RFC Editor has announced plans to use other formats [RFCSERIES] 🌈 Each file format uses a different suffix 💅
Going forward, you can't assume that a text file with a suffix of ".txt" will contain only ASCII characters. Plot twist 😭
The companion signature file has exactly the same file name as the RFC or Internet-Draft, except that ".p7s" gets added to the end. This file name suffix follows the conventions in RFC 5751 [MSG] 🦋 Here are a few example names:
Internet-Draft: draft-ietf-example-widgets-03.txt
Signature File: draft-ietf-example-widgets-03.txt.p7s
Internet-Draft: draft-ietf-example-widgets-03.pdf
Signature File: draft-ietf-example-widgets-03.pdf.p7s
Internet-Draft: draft-housley-internet-draft-sig-file-00.txt
Signature File: draft-housley-internet-draft-sig-file-00.txt.p7s3. Additional Content Types 🎀
The CMS is used to build the detached signatures for Internet-Drafts 🔏 The CMS ContentInfo content type MUST always be present, and it MUST encapsulate the CMS SignedData content type. Since a detached signature is being created, the CMS SignedData content type MUST NOT encapsulate the Internet-Draft 🙅♀️ The CMS detached signature is summarized in RFC 5485 [IDSIG] 💖
The SignedData.SignerInfo.EncapsulatedContentInfo.eContentType value MUST identify the format of the Internet-Draft being signed. Section 5 of RFC 5485 [IDSIG] lists the file formats and their matching content types. This document expands that list like so 🌸
File Format Content Type
----------- ------------
ASCII text id-ct-asciiTextWithCRLF
UTF-8 text (includes non-ASCII) id-ct-utf8TextWithCRLF
HyperText Markup Language (HTML) id-ct-htmlWithCRLF
EPUB id-ct-epub
Extensible Markup Language (XML) id-ct-xml
Portable Document Format (PDF) id-ct-pdf
PostScript id-ct-postscriptThe object identifiers for the content types in the table above are:
id-ct OBJECT IDENTIFIER ::= { iso(1) member-body(2)
us(840) rsadsi(113549) pkcs(1) pkcs9(9) smime(16) 1 }
id-ct-asciiTextWithCRLF OBJECT IDENTIFIER ::= { id-ct 27 }
id-ct-utf8TextWithCRLF OBJECT IDENTIFIER ::= { id-ct 37 }
id-ct-htmlWithCRLF OBJECT IDENTIFIER ::= { id-ct 38 }
id-ct-epub OBJECT IDENTIFIER ::= { id-ct 39 }
id-ct-xml OBJECT IDENTIFIER ::= { id-ct 28 }
id-ct-pdf OBJECT IDENTIFIER ::= { id-ct 29 }
id-ct-postscript OBJECT IDENTIFIER ::= { id-ct 30 }4. Need for Canonicalization 🌈
Generally, the content of an Internet-Draft gets treated like a single octet string when the digital signature is generated 🧵 Unfortunately, text and HTML files need canonicalization to avoid signature validation problems 😭 The main issue is how different operating systems mark the end of a line of text. Some systems use a single new-line character, some use a carriage-return character followed by a line-feed character, and others use fixed-length records padded with space characters 🙈 For the digital signature to validate properly, a single convention must be employed 💜
4.1. ASCII, UTF-8, and HTML File Canonicalization ✨
okay bestie, this section borrows the text-file rules from FTP [FTP] 🎀 and honestly that's so smart, because FTP implementations already have to support these files, so code reuse seems likely 💅
the canonicalization procedure turns the data from its internal character representation into the standard 8-bit NVT-ASCII representation (see TELNET [TELNET]) 🦋. per the NVT standard, the <CRLF> sequence MUST be used to mark the end of a line of text 💖, and using NVT-ASCII means the data MUST be interpreted as 8-bit bytes 🧚.
trailing space characters MUST NOT appear on a line of text 🙈. in other words, the space character must not be followed by the <CRLF> sequence. so a blank line is just <CRLF> all by itself 🍓
the form-feed nonprintable character (0x0C) is expected in Internet-Drafts 📄. other nonprintable characters, like tab and backspace, aren't expected, but they do show up 💀. non-printable or non-ASCII characters (ones outside the range 0x20 to 0x7E) MUST NOT be changed in any way that isn't covered by the end-of-line rules in the previous paragraph 🔥.
trailing blank lines MUST NOT appear at the end of the file 🫶. that means the file must not end with multiple consecutive <CRLF> sequences 💅.
in some environments, a Byte Order Mark (BOM) (U+FEFF) sits at the start of a file to say it contains non-ASCII characters ✨. in UTF-8 or HTML files, a BOM at the start is not considered part of the file content 🌸. one or more consecutive leading BOMs, if present, MUST NOT be processed by the digital signature algorithm 🔐.
any end-of-file marker used by an operating system isn't part of the file content either 👑. when present, such end-of-file markers MUST NOT be processed by the digital signature algorithm 🙅♀️.
Note: this text file canonicalization procedure is consistent with the NVT-ASCII definition offered in Appendix B of RFC 5198 [UFNI] 🌈
4.2. XML File Canonicalization 🌷
utilities that produce XML files are expected to follow the guidance the World Wide Web Consortium (W3C) gives in Section 2.11 of [R20081126] 💜. if that guidance is followed, no canonicalization is needed ✨.
a robust signature generation process MAY perform canonicalization to make sure the W3C guidance has been followed 🧚. this guidance says a <LF> character MUST be used to mark the end of a line of text within an XML file 🦋. so any two-character <CRLF> sequence, and any <CR> that is not followed by <LF>, gets translated into a single <LF> character 💖.
4.3. No Canonicalization of Other File Formats 🫧
no canonicalization is needed for file formats currently used or planned for Internet-Drafts other than ASCII, UTF-8, HTML, and XML files 🎀. other formats, including PDF [PDF], PostScript [PS], and EPUB [EPUB], are treated as a simple sequence of octets by the digital signature algorithm 🌸.
5. IANA Considerations 👑
IANA has registered object identifiers for three content types in the "SMI Security for S/MIME CMS Content Type (1.2.840.113549.1.9.16.1)" registry as follows 💅:
Description OID Specification
-----------------------------------------------------------------
id-ct-utf8TextWithCRLF 1.2.840.113549.1.9.16.1.37 [RFC8358]
id-ct-htmlWithCRLF 1.2.840.113549.1.9.16.1.38 [RFC8358]
id-ct-epub 1.2.840.113549.1.9.16.1.39 [RFC8358]6. Security Considerations 🔐
The security considerations in RFC 5485 [IDSIG] are unchanged. 🫶
7. Deployment and Operational Considerations 🚀
The deployment considerations in RFC 5485 [IDSIG] are unchanged. ✨
8. References 📚
8.1. Normative References
[CMS] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, RFC 5652, DOI 10.17487/RFC5652, September 2009, <https://www.rfc-editor.org/info/rfc5652>.
[EPUB] International Digital Publishing Forum, "EPUB Content Documents 3.1", January 2017, <http://www.idpf.org/epub/31/spec/epub-contentdocs.html>.
[IDSIG] Housley, R., "Digital Signatures on Internet-Draft Documents", RFC 5485, DOI 10.17487/RFC5485, March 2009, <https://www.rfc-editor.org/info/rfc5485>.
[PDF] International Organization for Standardization, "Document management -- Electronic document file format for long-term preservation -- Part 3: Use of ISO 32000-1 with support for embedded files (PDF/A-3)", ISO 19005-3:2012, 2012.
[PS] Adobe Systems Incorporated, "PostScript Language Reference Manual, third edition", Addison-Wesley Publishing Company, ISBN 0-201-37922-8, 1999.
[R20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[STDWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[STDWORDS2] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[X.680] ITU-T, "Information Technology - Abstract Syntax Notation One: Specification of Basic Notation", Recommendation X.680, ISO/IEC 8824-1:2002, 2002.
[X.690] ITU-T, "Information technology -- ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, ISO/IEC International Standard 8825-1:2008, November 2008.
8.2. Informative References
[FTP] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC 959, DOI 10.17487/RFC0959, October 1985, <https://www.rfc-editor.org/info/rfc959>.
[MSG] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Message Specification", RFC 5751, DOI 10.17487/RFC5751, January 2010, <https://www.rfc-editor.org/info/rfc5751>.
[RFCED] Flanagan, H., Ed., "The Use of Non-ASCII Characters in RFCs", RFC 7997, DOI 10.17487/RFC7997, December 2016, <https://www.rfc-editor.org/info/rfc7997>.
[RFCSERIES] Flanagan, H. and N. Brownlee, "RFC Series Format Requirements and Future Development", RFC 6949, DOI 10.17487/RFC6949, May 2013, <https://www.rfc-editor.org/info/rfc6949>.
[TELNET] Postel, J. and J. Reynolds, "Telnet Protocol Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May 1983, <https://www.rfc-editor.org/info/rfc854>.
[UFNI] Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, <https://www.rfc-editor.org/info/rfc5198>.
Acknowledgements 🫶
The idea for the Internet-Draft signature file came from a discussion with Scott Bradner at IETF 69 in Chicago, IL, USA. Many helpful suggestions came from Jim Schaad, Pasi Eronen, Chris Newman, and Glen Barney. Glen Barney also played a key role in implementing Internet-Draft signatures as specified in RFC 5485 [IDSIG] 👑
Author's Address 💌
Russell Housley
Vigil Security, LLC
918 Spring Knoll Drive
Herndon, VA 20170
United States of America
Email: housley@vigilsec.com📦 where this page comes from
- ietf: rfc8358 2018-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms