From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc9054.txt | 498 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 498 insertions(+) create mode 100644 doc/rfc/rfc9054.txt (limited to 'doc/rfc/rfc9054.txt') diff --git a/doc/rfc/rfc9054.txt b/doc/rfc/rfc9054.txt new file mode 100644 index 0000000..ba80383 --- /dev/null +++ b/doc/rfc/rfc9054.txt @@ -0,0 +1,498 @@ + + + + +Internet Engineering Task Force (IETF) J. Schaad +Request for Comments: 9054 August Cellars +Category: Informational August 2022 +ISSN: 2070-1721 + + + CBOR Object Signing and Encryption (COSE): Hash Algorithms + +Abstract + + The CBOR Object Signing and Encryption (COSE) syntax (see RFC 9052) + does not define any direct methods for using hash algorithms. There + are, however, circumstances where hash algorithms are used, such as + indirect signatures, where the hash of one or more contents are + signed, and identification of an X.509 certificate or other object by + the use of a fingerprint. This document defines hash algorithms that + are identified by COSE algorithm identifiers. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Not all documents + approved by the IESG are candidates for any level of Internet + Standard; see Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9054. + +Copyright Notice + + Copyright (c) 2022 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) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Requirements Terminology + 2. Hash Algorithm Usage + 2.1. Example CBOR Hash Structure + 3. Hash Algorithm Identifiers + 3.1. SHA-1 Hash Algorithm + 3.2. SHA-2 Hash Algorithms + 3.3. SHAKE Algorithms + 4. IANA Considerations + 4.1. COSE Algorithm Registry + 5. Security Considerations + 6. References + 6.1. Normative References + 6.2. Informative References + Author's Address + +1. Introduction + + The CBOR Object Signing and Encryption (COSE) syntax [RFC9052] does + not define any direct methods for the use of hash algorithms. It + also does not define a structure syntax that is used to encode a + digested object structure along the lines of the DigestedData ASN.1 + structure in [CMS]. This omission was intentional, as a structure + consisting of just a digest identifier, the content, and a digest + value does not, by itself, provide any strong security service. + Additionally, an application is going to be better off defining this + type of structure so that it can include any additional data that + needs to be hashed, as well as methods of obtaining the data. + + While the above is true, there are some cases where having some + standard hash algorithms defined for COSE with a common identifier + makes a great deal of sense. Two of the cases where these are going + to be used are: + + * Indirect signing of content, and + + * Object identification. + + Indirect signing of content is a paradigm where the content is not + directly signed, but instead a hash of the content is computed, and + that hash value -- along with an identifier for the hash algorithm -- + is included in the content that will be signed. Indirect signing + allows for a signature to be validated without first downloading all + of the content associated with the signature. Rather, the signature + can be validated on all of the hash values and pointers to the + associated contents; those associated parts can then be downloaded, + then the hash value of that part can be computed and compared to the + hash value in the signed content. This capability can be of even + greater importance in a constrained environment, as not all of the + content signed may be needed by the device. An example of how this + is used can be found in Section 5.4 of [SUIT-MANIFEST]. + + The use of hashes to identify objects is something that has been very + common. One of the primary things that has been identified by a hash + function in a secure message is a certificate. Two examples of this + can be found in [ESS] and the COSE equivalents in [COSE-x509]. + +1.1. Requirements Terminology + + 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 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +2. Hash Algorithm Usage + + As noted in the previous section, hash functions can be used for a + variety of purposes. Some of these purposes require that a hash + function be cryptographically strong. These include direct and + indirect signatures -- that is, using the hash as part of the + signature or using the hash as part of the body to be signed. Other + uses of hash functions may not require the same level of strength. + + This document contains some hash functions that are not designed to + be used for cryptographic operations. An application that is using a + hash function needs to carefully evaluate exactly what hash + properties are needed and which hash functions are going to provide + them. Applications should also make sure that the ability to change + hash functions is part of the base design, as cryptographic advances + are sure to reduce the strength of any given hash function [BCP201]. + + A hash function is a map from one, normally large, bit string to a + second, usually smaller, bit string. As the number of possible input + values is far greater than the number of possible output values, it + is inevitable that there are going to be collisions. The trick is to + make sure that it is difficult to find two values that are going to + map to the same output value. A "Collision Attack" is one where an + attacker can find two different messages that have the same hash + value. A hash function that is susceptible to practical collision + attacks SHOULD NOT be used for a cryptographic purpose. The + discovery of theoretical collision attacks against a given hash + function SHOULD trigger protocol maintainers and users to review the + continued suitability of the algorithm if alternatives are available + and migration is viable. The only reason such a hash function is + used is when there is absolutely no other choice (e.g., a Hardware + Security Module (HSM) that cannot be replaced), and only after + looking at the possible security issues. Cryptographic purposes + would include the creation of signatures or the use of hashes for + indirect signatures. These functions may still be usable for + noncryptographic purposes. + + An example of a noncryptographic use of a hash is filtering from a + collection of values to find a set of possible candidates; the + candidates can then be checked to see if they can successfully be + used. A simple example of this is the classic fingerprint of a + certificate. If the fingerprint is used to verify that it is the + correct certificate, then that usage is a cryptographic one and is + subject to the warning above about collision attack. If, however, + the fingerprint is used to sort through a collection of certificates + to find those that might be used for the purpose of verifying a + signature, a simple filter capability is sufficient. In this case, + one still needs to confirm that the public key validates the + signature (and that the certificate is trusted), and all certificates + that don't contain a key that validates the signature can be + discarded as false positives. + + To distinguish between these two cases, a new value in the + Recommended column of the "COSE Algorithms" registry has been added. + "Filter Only" indicates that the only purpose of a hash function + should be to filter results; it is not intended for applications that + require a cryptographically strong algorithm. + +2.1. Example CBOR Hash Structure + + [COSE] did not provide a default structure for holding a hash value + both because no separate hash algorithms were defined and because the + way the structure is set up is frequently application specific. + There are four fields that are often included as part of a hash + structure: + + * The hash algorithm identifier. + + * The hash value. + + * A pointer to the value that was hashed. This could be a pointer + to a file, an object that can be obtained from the network, a + pointer to someplace in the message, or something very application + specific. + + * Additional data. This can be something as simple as a random + value (i.e., salt) to make finding hash collisions slightly harder + (because the payload handed to the application could have been + selected to have a collision), or as complicated as a set of + processing instructions that is used with the object that is + pointed to. The additional data can be dealt with in a number of + ways, prepending or appending to the content, but it is strongly + suggested that either it be a fixed known size, or the lengths of + the pieces being hashed be included so that the resulting byte + string has a unique interpretation as the additional data. + (Encoding as a CBOR array accomplishes this requirement.) + + An example of a structure that permits all of the above fields to + exist would look like the following: + + COSE_Hash_V = ( + 1 : int / tstr, # Algorithm identifier + 2 : bstr, # Hash value + ? 3 : tstr, # Location of object that was hashed + ? 4 : any # object containing other details and things + ) + + Below is an alternative structure that could be used in situations + where one is searching a group of objects for a matching hash value. + In this case, the location would not be needed, and adding extra data + to the hash would be counterproductive. This results in a structure + that looks like this: + + COSE_Hash_Find = [ + hashAlg : int / tstr, + hashValue : bstr + ] + +3. Hash Algorithm Identifiers + +3.1. SHA-1 Hash Algorithm + + The SHA-1 hash algorithm [RFC3174] was designed by the United States + National Security Agency and published in 1995. Since that time, a + large amount of cryptographic analysis has been applied to this + algorithm, and a successful collision attack has been created + [SHA-1-collision]. The IETF formally started discouraging the use of + SHA-1 in [RFC6194]. + + Despite these facts, there are still times where SHA-1 needs to be + used; therefore, it makes sense to assign a code point for the use of + this hash algorithm. Some of these situations involve historic HSMs + where only SHA-1 is implemented; in other situations, the SHA-1 value + is used for the purpose of filtering; thus, the collision-resistance + property is not needed. + + Because of the known issues for SHA-1 and the fact that it should no + longer be used, the algorithm will be registered with the + recommendation of "Filter Only". This provides guidance about when + the algorithm is safe for use, while discouraging usage where it is + not safe. + + The COSE capabilities for this algorithm is an empty array. + + +=====+======+=============+==============+===========+=============+ + |Name |Value | Description | Capabilities | Reference | Recommended | + +=====+======+=============+==============+===========+=============+ + |SHA-1|-14 | SHA-1 Hash | [] | RFC 9054 | Filter Only | + +-----+------+-------------+--------------+-----------+-------------+ + + Table 1: SHA-1 Hash Algorithm + +3.2. SHA-2 Hash Algorithms + + The family of SHA-2 hash algorithms [FIPS-180-4] was designed by the + United States National Security Agency and published in 2001. Since + that time, some additional algorithms have been added to the original + set to deal with length-extension attacks and some performance + issues. While the SHA-3 hash algorithms have been published since + that time, the SHA-2 algorithms are still broadly used. + + There are a number of different parameters for the SHA-2 hash + functions. The set of hash functions that has been chosen for + inclusion in this document is based on those different parameters and + some of the trade-offs involved. + + * *SHA-256/64* provides a truncated hash. The length of the + truncation is designed to allow for smaller transmission size. + The trade-off is that the odds that a collision will occur + increase proportionally. Use of this hash function requires + analysis of the potential problems that could result from a + collision, or it must be limited to where the purpose of the hash + is noncryptographic. + + The latter is the case for some of the scenarios identified in + [COSE-x509], specifically, for the cases when the hash value is + used to select among possible certificates: if there are multiple + choices remaining, then each choice can be tested by using the + public key. + + * *SHA-256* is probably the most common hash function used + currently. SHA-256 is an efficient hash algorithm for 32-bit + hardware. + + * *SHA-384* and *SHA-512* hash functions are efficient for 64-bit + hardware. + + * *SHA-512/256* provides a hash function that runs more efficiently + on 64-bit hardware but offers the same security level as SHA-256. + + | NOTE: SHA-256/64 is a simple truncation of SHA-256 to 64 bits + | defined in this specification. SHA-512/256 is a modified + | variant of SHA-512 truncated to 256 bits, as defined in + | [FIPS-180-4]. + + The COSE capabilities array for these algorithms is empty. + + +===========+=====+===========+==============+=========+============+ + |Name |Value|Description| Capabilities |Reference|Recommended | + +===========+=====+===========+==============+=========+============+ + |SHA-256/64 |-15 |SHA-2 | [] |RFC 9054 |Filter Only | + | | |256-bit | | | | + | | |Hash | | | | + | | |truncated | | | | + | | |to 64-bits | | | | + +-----------+-----+-----------+--------------+---------+------------+ + |SHA-256 |-16 |SHA-2 | [] |RFC 9054 |Yes | + | | |256-bit | | | | + | | |Hash | | | | + +-----------+-----+-----------+--------------+---------+------------+ + |SHA-384 |-43 |SHA-2 | [] |RFC 9054 |Yes | + | | |384-bit | | | | + | | |Hash | | | | + +-----------+-----+-----------+--------------+---------+------------+ + |SHA-512 |-44 |SHA-2 | [] |RFC 9054 |Yes | + | | |512-bit | | | | + | | |Hash | | | | + +-----------+-----+-----------+--------------+---------+------------+ + |SHA-512/256|-17 |SHA-2 | [] |RFC 9054 |Yes | + | | |512-bit | | | | + | | |Hash | | | | + | | |truncated | | | | + | | |to 256-bits| | | | + +-----------+-----+-----------+--------------+---------+------------+ + + Table 2: SHA-2 Hash Algorithms + +3.3. SHAKE Algorithms + + The family of SHA-3 hash algorithms [FIPS-202] was the result of a + competition run by NIST. The pair of algorithms known as SHAKE-128 + and SHAKE-256 are the instances of SHA-3 that are currently being + standardized in the IETF. This is the reason for including these + algorithms in this document. + + The SHA-3 hash algorithms have a significantly different structure + than the SHA-2 hash algorithms. + + Unlike the SHA-2 hash functions, no algorithm identifier is created + for shorter lengths. The length of the hash value stored is 256 bits + for SHAKE-128 and 512 bits for SHAKE-256. + + The COSE capabilities array for these algorithms is empty. + + +========+=====+=============+==============+=========+=============+ + |Name |Value|Description | Capabilities |Reference| Recommended | + +========+=====+=============+==============+=========+=============+ + |SHAKE128|-18 |SHAKE-128 | [] |RFC 9054 | Yes | + | | |256-bit Hash | | | | + | | |Value | | | | + +--------+-----+-------------+--------------+---------+-------------+ + |SHAKE256|-45 |SHAKE-256 | [] |RFC 9054 | Yes | + | | |512-bit Hash | | | | + | | |Value | | | | + +--------+-----+-------------+--------------+---------+-------------+ + + Table 3: SHAKE Hash Functions + +4. IANA Considerations + +4.1. COSE Algorithm Registry + + IANA has registered the following algorithms in the "COSE Algorithms" + registry (https://www.iana.org/assignments/cose/). + + * The SHA-1 hash function found in Table 1. + + * The set of SHA-2 hash functions found in Table 2. + + * The set of SHAKE hash functions found in Table 3. + + Many of the hash values produced are relatively long; as such, use of + a two-byte algorithm identifier seems reasonable. SHA-1 is tagged as + "Filter Only", so a longer algorithm identifier is appropriate even + though it is a shorter hash value. + + IANA has added the value of "Filter Only" to the set of legal values + for the Recommended column. This value is only to be used for hash + functions and indicates that it is not to be used for purposes that + require collision resistance. As a result of this addition, IANA has + added this document as a reference for the "COSE Algorithms" + registry. + +5. Security Considerations + + Protocols need to perform a careful analysis of the properties of a + hash function that are needed and how they map onto the possible + attacks. In particular, one needs to distinguish between those uses + that need the cryptographic properties, such as collision resistance, + and uses that only need properties that correspond to possible object + identification. The different attacks correspond to who or what is + being protected: is it the originator that is the attacker or a third + party? This is the difference between collision resistance and + second pre-image resistance. As a general rule, longer hash values + are "better" than short ones, but trade-offs of transmission size, + timeliness, and security all need to be included as part of this + analysis. In many cases, the value being hashed is a public value + and, as such, (first) pre-image resistance is not part of this + analysis. + + Algorithm agility needs to be considered a requirement for any use of + hash functions [BCP201]. As with any cryptographic function, hash + functions are under constant attack, and the cryptographic strength + of hash algorithms will be reduced over time. + +6. References + +6.1. Normative References + + [FIPS-180-4] + NIST, "Secure Hash Standard", FIPS PUB 180-4, + DOI 10.6028/NIST.FIPS.180-4, August 2015, + . + + [FIPS-202] Dworkin, M.J., "SHA-3 Standard: Permutation-Based Hash and + Extendable-Output Functions", FIPS PUB 202, + DOI 10.6028/NIST.FIPS.202, August 2015, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 + (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Structures and Process", STD 96, RFC 9052, + DOI 10.17487/RFC9052, August 2022, + . + +6.2. Informative References + + [BCP201] Housley, R., "Guidelines for Cryptographic Algorithm + Agility and Selecting Mandatory-to-Implement Algorithms", + BCP 201, RFC 7696, November 2015, + . + + [CMS] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, + RFC 5652, DOI 10.17487/RFC5652, September 2009, + . + + [COSE] Schaad, J., "CBOR Object Signing and Encryption (COSE)", + RFC 8152, DOI 10.17487/RFC8152, July 2017, + . + + [COSE-x509] + Schaad, J., "CBOR Object Signing and Encryption (COSE): + Header parameters for carrying and referencing X.509 + certificates", Work in Progress, Internet-Draft, draft- + ietf-cose-x509-08, 14 December 2020, + . + + [ESS] Hoffman, P., Ed., "Enhanced Security Services for S/MIME", + RFC 2634, DOI 10.17487/RFC2634, June 1999, + . + + [RFC6194] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security + Considerations for the SHA-0 and SHA-1 Message-Digest + Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, + . + + [SHA-1-collision] + Stevens, M., Bursztein, E., Karpman, P., Albertini, A., + and Y. Markov, "The first collision for full SHA-1", + February 2017, + . + + [SUIT-MANIFEST] + Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, + "A Concise Binary Object Representation (CBOR)-based + Serialization Format for the Software Updates for Internet + of Things (SUIT) Manifest", Work in Progress, Internet- + Draft, draft-ietf-suit-manifest-19, 9 August 2022, + . + +Author's Address + + Jim Schaad + August Cellars -- cgit v1.2.3