Calendaring Extensions R. Tse Internet-Draft P. Tam Updates: 5545,6321,6350,6351 (if Ribose approved) April 18, 2018 Intended status: Standards Track Expires: October 20, 2018 Integrity Protection for vObject, vCard and iCalendar draft-calconnect-vobject-integrity-00 Abstract This document specifies an integrity checking mechanism and related properties for: o vObject [I-D.calconnect-vobject-vformat] o vCard version 4 (vCard v4) [RFC6350]; and o iCalendar (Internet Calendaring and Scheduling Core Object Specification) [RFC5545] This work is produced by the CalConnect TC-VCARD and TC-CALENDAR committees. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 20, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. Tse & Tam Expires October 20, 2018 [Page 1] Internet-Draft vObject and vFormat April 2018 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. TODOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Terms and Definitions . . . . . . . . . . . . . . . . . . . . 7 4. Symbols And Abbreviations . . . . . . . . . . . . . . . . . . 7 4.1. Functions . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1.1. SORT . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1.2. UPCASE . . . . . . . . . . . . . . . . . . . . . . . 7 4.1.3. LIST-TO-TEXT . . . . . . . . . . . . . . . . . . . . 8 4.1.4. NORMALIZE-PROPERTY-PARAMETER-KEY . . . . . . . . . . 8 4.1.5. NORMALIZE-PROPERTY-PARAMETER-VALUES . . . . . . . . . 8 4.1.6. NORMALIZE-PROPERTY-PARAMETER . . . . . . . . . . . . 9 4.1.7. NORMALIZE-PROPERTY-PARAMETERS . . . . . . . . . . . . 9 4.1.8. NORMALIZE-PROPERTY-KEY . . . . . . . . . . . . . . . 9 4.1.9. NORMALIZE-PROPERTY-VALUE-HASHA . . . . . . . . . . . 10 4.1.10. NORMALIZE-PROPERTY-VALUES . . . . . . . . . . . . . . 10 4.1.11. NORMALIZE-PROPERTY . . . . . . . . . . . . . . . . . 10 4.1.12. HASH-PROPERTY . . . . . . . . . . . . . . . . . . . . 11 4.1.13. HASH-AND-NORMALIZE-PROPERTIES . . . . . . . . . . . . 11 4.1.14. NORMALIZE-COMPONENT-NAME . . . . . . . . . . . . . . 11 4.1.15. NORMALIZE-COMPONENT . . . . . . . . . . . . . . . . . 12 4.1.16. HASH-COMPONENT . . . . . . . . . . . . . . . . . . . 12 4.1.17. HASH . . . . . . . . . . . . . . . . . . . . . . . . 12 5. Properties . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.1. CHECKSUM . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1.1. Namespace . . . . . . . . . . . . . . . . . . . . . . 13 5.1.2. Property name . . . . . . . . . . . . . . . . . . . . 13 5.1.3. Purpose . . . . . . . . . . . . . . . . . . . . . . . 13 5.1.4. Value type . . . . . . . . . . . . . . . . . . . . . 13 5.1.5. Cardinality . . . . . . . . . . . . . . . . . . . . . 13 5.1.6. Property parameters . . . . . . . . . . . . . . . . . 13 5.1.7. Value . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1.8. Description . . . . . . . . . . . . . . . . . . . . . 13 5.1.9. Format definition . . . . . . . . . . . . . . . . . . 14 5.1.10. Examples . . . . . . . . . . . . . . . . . . . . . . 14 6. Property Parameters . . . . . . . . . . . . . . . . . . . . . 14 6.1. PREF Property Parameter . . . . . . . . . . . . . . . . . 14 Tse & Tam Expires October 20, 2018 [Page 2] Internet-Draft vObject and vFormat April 2018 6.2. HASHA Property Parameter . . . . . . . . . . . . . . . . 14 6.2.1. Namespace . . . . . . . . . . . . . . . . . . . . . . 14 6.2.2. Parameter name . . . . . . . . . . . . . . . . . . . 15 6.2.3. Purpose . . . . . . . . . . . . . . . . . . . . . . . 15 6.2.4. Description . . . . . . . . . . . . . . . . . . . . . 15 6.2.5. Format definition . . . . . . . . . . . . . . . . . . 15 6.2.6. Examples: . . . . . . . . . . . . . . . . . . . . . . 15 6.3. HASHP Property Parameter . . . . . . . . . . . . . . . . 15 6.3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . 16 6.3.2. Parameter name . . . . . . . . . . . . . . . . . . . 16 6.3.3. Purpose . . . . . . . . . . . . . . . . . . . . . . . 16 6.3.4. Description . . . . . . . . . . . . . . . . . . . . . 16 6.3.5. Format definition . . . . . . . . . . . . . . . . . . 17 7. Integrity Validation . . . . . . . . . . . . . . . . . . . . 17 7.1. Integrity In The vObject Life Cycle . . . . . . . . . . . 17 7.2. vObject Validity States . . . . . . . . . . . . . . . . . 18 7.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 18 7.4. Integrity Validity When Presented With A Single CHECKSUM Property . . . . . . . . . . . . . . . . . . . . . . . . 18 7.5. Integrity Validity When Presented With Multiple CHECKSUM Properties . . . . . . . . . . . . . . . . . . . . . . . 19 8. Method of CHECKSUM Value Calculation . . . . . . . . . . . . 19 9. Cryptographic Hash Functions . . . . . . . . . . . . . . . . 21 9.1. Supported Hash Functions . . . . . . . . . . . . . . . . 21 9.1.1. Hash Function Specifiers . . . . . . . . . . . . . . 22 9.1.1.1. Example . . . . . . . . . . . . . . . . . . . . . 25 9.1.2. The SHA-2 Hash Functions . . . . . . . . . . . . . . 25 9.1.3. The WHIRLPOOL Hash Function . . . . . . . . . . . . . 25 9.1.4. The SM3 Hash Function . . . . . . . . . . . . . . . . 26 9.1.5. The SHA-3 Hash Functions . . . . . . . . . . . . . . 26 9.1.6. The STREEBOG Hash Functions . . . . . . . . . . . . . 27 9.1.7. The BLAKE2 Hash Functions . . . . . . . . . . . . . . 27 9.1.8. The SHA-3 Extension Hash Functions . . . . . . . . . 27 9.2. Selection Considerations . . . . . . . . . . . . . . . . 28 9.2.1. Collision Resistance of Hash Function Families . . . 28 9.2.2. Guidelines for Hash Function Selection . . . . . . . 28 9.2.3. Hash Functions Considered Unsuitable . . . . . . . . 28 10. Using CHECKSUM With Server Support . . . . . . . . . . . . . 29 10.1. Usage of CHECKSUM in vCards on CardDAV servers . . . . . 29 10.1.1. Creating And Updating Address Object Resources . . . 29 10.1.1.1. Client Implementations Should Transmit With CHECKSUM . . . . . . . . . . . . . . . . . . . . 29 10.1.2. Additional Server Semantics for PUT, COPY and MOVE . 29 10.1.2.1. Only Admit Valid vCard Data From Client . . . . 30 10.1.2.2. Additional Precondition . . . . . . . . . . . . 30 10.1.2.3. Resolve Discrepancy Between Server And Client vCard Data . . . . . . . . . . . . . . . . . . . 30 10.1.2.4. Additional Postcondition . . . . . . . . . . . . 30 Tse & Tam Expires October 20, 2018 [Page 3] Internet-Draft vObject and vFormat April 2018 10.2. Usage of CHECKSUM with CalDAV . . . . . . . . . . . . . 31 10.2.1. Creating Calendar Resources . . . . . . . . . . . . 31 10.3. Usage of CHECKSUM with iTIP . . . . . . . . . . . . . . 31 11. Alternative vObject Representations . . . . . . . . . . . . . 31 11.1. xCard . . . . . . . . . . . . . . . . . . . . . . . . . 31 11.2. jCard . . . . . . . . . . . . . . . . . . . . . . . . . 32 12. Implementation Notes . . . . . . . . . . . . . . . . . . . . 32 12.1. vCard REV Update Guidelines For The CHECKSUM Property . 32 12.2. Calculating CHECKSUM From An xCard . . . . . . . . . . . 32 12.3. Backwards Compatibility Concerns . . . . . . . . . . . . 32 12.4. Unsupported Property Parameters . . . . . . . . . . . . 32 12.5. Recommendations for Client User Applications . . . . . . 33 12.5.1. User Experience . . . . . . . . . . . . . . . . . . 33 12.5.2. Ongoing Improvements . . . . . . . . . . . . . . . . 33 13. Security Considerations . . . . . . . . . . . . . . . . . . . 33 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 14.1. Common vObject Registries . . . . . . . . . . . . . . . 34 14.2. Registering New Hash Functions And Hash Function Specifiers . . . . . . . . . . . . . . . . . . . . . . . 34 14.2.1. Registration Procedure . . . . . . . . . . . . . . . 34 14.2.2. Registration Template for vObject Hash Functions . . 34 14.2.3. Registration Template for vObject Hash Function Specifiers . . . . . . . . . . . . . . . . . . . . . 35 14.2.4. vObject Hash Functions Registry . . . . . . . . . . 35 14.2.5. vObject Hash Function Specifier Registry . . . . . . 36 14.3. Property Registrations . . . . . . . . . . . . . . . . . 38 14.4. Parameter Registrations . . . . . . . . . . . . . . . . 38 14.4.1. Parameter Value Registrations . . . . . . . . . . . 38 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 15.1. Normative References . . . . . . . . . . . . . . . . . . 39 15.2. Informative References . . . . . . . . . . . . . . . . . 40 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 44 A.1. vCard CHECKSUM . . . . . . . . . . . . . . . . . . . . . 44 A.1.1. Original vCard . . . . . . . . . . . . . . . . . . . 44 A.1.2. Setup . . . . . . . . . . . . . . . . . . . . . . . . 44 A.1.3. Normalization: Properties . . . . . . . . . . . . . . 45 A.1.4. Cryptographic Hashing: Properties . . . . . . . . . . 45 A.1.5. Normalization: Component . . . . . . . . . . . . . . 45 A.1.6. Cryptographic Hashing: Component . . . . . . . . . . 46 A.1.7. Final Checksum . . . . . . . . . . . . . . . . . . . 46 A.2. Hash Functions Registry Examples . . . . . . . . . . . . 47 A.2.1. SHA-2 SHA-224 . . . . . . . . . . . . . . . . . . . . 47 A.2.2. SHA-2 SHA-256 . . . . . . . . . . . . . . . . . . . . 47 A.2.3. SHA-2 SHA-384 . . . . . . . . . . . . . . . . . . . . 47 A.2.4. SHA-2 SHA-512 . . . . . . . . . . . . . . . . . . . . 47 A.2.5. SHA-2 SHA-512/224 . . . . . . . . . . . . . . . . . . 47 A.2.6. SHA-2 SHA-512/256 . . . . . . . . . . . . . . . . . . 47 A.2.7. WHIRLPOOL (512-bit) . . . . . . . . . . . . . . . . . 47 Tse & Tam Expires October 20, 2018 [Page 4] Internet-Draft vObject and vFormat April 2018 A.2.8. STREEBOG-256 . . . . . . . . . . . . . . . . . . . . 48 A.2.9. STREEBOG-512 . . . . . . . . . . . . . . . . . . . . 48 A.2.10. SHA-3-224 . . . . . . . . . . . . . . . . . . . . . . 48 A.2.11. SHA-3-256 . . . . . . . . . . . . . . . . . . . . . . 48 A.2.12. SHA-3-384 . . . . . . . . . . . . . . . . . . . . . . 48 A.2.13. SHA-3-512 . . . . . . . . . . . . . . . . . . . . . . 48 A.2.14. SM3 (256-bits) . . . . . . . . . . . . . . . . . . . 48 A.2.15. BLAKE2b-256 . . . . . . . . . . . . . . . . . . . . . 48 A.2.15.1. BLAKE2b-384 . . . . . . . . . . . . . . . . . . 49 A.2.16. BLAKE2b-512 . . . . . . . . . . . . . . . . . . . . . 49 A.2.17. BLAKE2s-224 . . . . . . . . . . . . . . . . . . . . . 49 A.2.18. BLAKE2s-256 . . . . . . . . . . . . . . . . . . . . . 49 A.2.19. SHAKE-128 . . . . . . . . . . . . . . . . . . . . . . 49 A.2.20. SHAKE-256 . . . . . . . . . . . . . . . . . . . . . . 49 A.2.21. cSHAKE-128 . . . . . . . . . . . . . . . . . . . . . 49 A.2.22. cSHAKE-256 . . . . . . . . . . . . . . . . . . . . . 49 A.2.23. ParallelHash128 . . . . . . . . . . . . . . . . . . . 49 A.2.24. ParallelHash256 . . . . . . . . . . . . . . . . . . . 49 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 49 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 1. TODOs o Add CalDAV mechanisms and recommendations o Fill in missing example hashes o Fully replace normalization process with the vObject one, remove normalization process here 2. Introduction The ubiquitous vCard and iCalendar standards, also known together as the "vObject" family of standards [I-D.calconnect-vobject-vformat], powers digital contact exchanges, calendaring and scheduling on billions of devices today. Integrity 2.1.2 [RFC3552] is a key property of "information security" defined as the "preservation of confidentiality, integrity and availability of information" 2.33 [ISO-IEC-27000]. When provided with a vObject, however, there is no inherent method to detect its own data integrity. In reality, people are known to exchange vCard and iCalendar data through unreliable means, which could affect data integrity during transport, such as Internet mail [RFC5322] and QR Codes [ISO-IEC-18004]. On the other hand, there are implementations that Tse & Tam Expires October 20, 2018 [Page 5] Internet-Draft vObject and vFormat April 2018 store vCard and/or iCalendar content on disk, which could be subject to silent corruption. Previous standards were created in a time where integrity concerns were less widespread, and relied solely on data transport, application and storage integrity without considering on whether the content transmitted, processed or retrieved was as intended without corruption. This document specifically deals with information integrity in face of the following risks: o vObjects on storage may face silent corruption; o vObjects transmitted over networks or other channels may face network corruption that may go undetected by the underlying transport mechanism. The standards subject to such risks include: o vCard version 2.1 [vCard21]; o vCard version 3 [RFC2425], [RFC2426]; o vCard version 4 [RFC6350]; and o iCalendar [RFC5545]. This document provides: o a stable mechanism to calculate vObject equivalence using cryptographic hash functions, valid across alternative representations, such as xCard/jCard and xCal/jCal; o introduces a new property CHECKSUM to vObjects; o usage of the CHECKSUM property on CardDAV [RFC6352] and CalDAV [RFC4791] systems; o alternative representations of the CHECKSUM property for xCard [RFC6351], jCard [RFC7095], xCal [RFC6321] and jCal [RFC7265] representations of this property; and o guidance to implementers on dealing with integrity concerns and the proper usage of CHECKSUM. Tse & Tam Expires October 20, 2018 [Page 6] Internet-Draft vObject and vFormat April 2018 Organizations that implement information security management systems, such as [ISO-IEC-27001], *MAY* find this document applicable to their own processes. The decision to update the existing vCard version 4 [RFC6350] and iCalendar [RFC5545] standards were chosen to maintain maximum backwards compatibility. This work is produced by the CalConnect TC-VCARD [CALCONNECT-VCARD] and TC-CALENDAR [CALCONNECT-CALENDAR] committees. 3. Terms and Definitions 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. The definitions from [I-D.calconnect-vobject-vformat] are inherited in this document unless explicitly overriden. 4. Symbols And Abbreviations 4.1. Functions These functions are *REQUIRED* and *MUST* be implemented for compliance to this document. 4.1.1. SORT Sorts an list according to alphabetical order (A-Z). 4.1.2. UPCASE This function makes all alphabets in the input string uppercase. The input is expected to be encoded in US-ASCII. UPCASE(s) = upcase(char(s, 1)) + upcase(char(s, 2)) + ... where: o + indicates concatenation; o "char(s, i)" is the i-th character of string "s", o "upcase(c)" outputs the "uppercase" equivalent of character "c". Tse & Tam Expires October 20, 2018 [Page 7] Internet-Draft vObject and vFormat April 2018 4.1.3. LIST-TO-TEXT This function returns a Unicode string (7 [RFC8259]) containing a string representation of a list of string values, each followed by a selected delimiter character. LIST-TO-TEXT(list, delimiter) = value(list, 1) + delimiter + value(list, 2) + delimiter + ... value(list, last-element-position(list)) where: * "+" indicates concatenation; * "value(l, i)" is the i-th value in the list "l" in string representation; * "last-element- position(a)" returns the last element position of list "l". 4.1.4. NORMALIZE-PROPERTY-PARAMETER-KEY This function returns a Unicode string (7 [RFC8259]) representation of the normalized property parameter key. NORMALIZE-PROPERTY-PARAMETER-KEY(parameter) = UPCASE(key(parameter)) where: * "+" indicates concatenation; * "key(parameter)" is the property parameter key. 4.1.5. NORMALIZE-PROPERTY-PARAMETER-VALUES This function returns a Unicode string (7 [RFC8259]) representation of the normalized property parameter values. NORMALIZE-PROPERTY-PARAMETER-VALUES(parameter) = LIST-TO-TEXT( SORT( values(parameter, 1), values(parameter, 2), ... ), ";" ) where: * "+" indicates concatenation; * "values(parameter, i)" is the i-th property parameter value in "parameter". Tse & Tam Expires October 20, 2018 [Page 8] Internet-Draft vObject and vFormat April 2018 4.1.6. NORMALIZE-PROPERTY-PARAMETER Converts a property parameter into a string, with its key and values. This function returns a Unicode string (7 [RFC8259]) containing a sequence of zero or more list values in string format, each followed by a ';' character. NORMALIZE-PROPERTY-PARAMETER(parameter) = "{" + NORMALIZE-PROPERTY-PARAMETER-KEY(property) + ":" + NORMALIZE-PROPERTY-PARAMETER-VALUES(property) + "}" where: * + indicates concatenation. 4.1.7. NORMALIZE-PROPERTY-PARAMETERS This function returns a Unicode string (7 [RFC8259]) representation of a set of property parameters. We exclude the "VALUE" property parameter in this calculation (such as "VALUE=TEXT") as this information is represented in NORMALIZE- PROPERTY-VALUE-HASHA. NORMALIZE-PROPERTY-PARAMETERS(property) = "#" + LIST-TO-TEXT( SORT([ NORMALIZE-PROPERTY-PARAMETER(parameter(property, 1)), NORMALIZE-PROPERTY-PARAMETER(parameter(property, 2)), ... ]), ";" ) where: * + indicates concatenation; * parameters(property, i) is the i-th parameter of "property". 4.1.8. NORMALIZE-PROPERTY-KEY This function returns a Unicode string (7 [RFC8259]) representation of the normalized property key. NORMALIZE-PROPERTY-KEY(property) = UPCASE(key(property)) Tse & Tam Expires October 20, 2018 [Page 9] Internet-Draft vObject and vFormat April 2018 where: * + indicates concatenation; * key(property) is the property key; * UPCASE(s) is function that makes all alphabets in the string s uppercase. 4.1.9. NORMALIZE-PROPERTY-VALUE-HASHA This function returns a Unicode string (7 [RFC8259]) representation of the normalized property value type. Since the property value type is represented here, we exclude the "VALUE" property parameter in NORMALIZE-PROPERTY-PARAMETERS (such as "VALUE=TEXT") NORMALIZE-PROPERTY-VALUE-HASHA(property) = UPCASE(type(property)) where: * + indicates concatenation; * type(property) is the property value type, if not explicitly provided, it should be filled in according to [RFC6350]; * UPCASE(s) is function that makes all alphabets in the string s uppercase. 4.1.10. NORMALIZE-PROPERTY-VALUES This function returns a Unicode string (7 [RFC8259]) representation of the normalized property values. Certain content types allow storing multiple values (as a list) in the same property line. For example, in the ADR and N properties, values are separated by the ";" delimiter, while in NICKNAME and CATEGORIES they are separated by the "," delimiter 3.3 [RFC6350]. NORMALIZE-PROPERTY-VALUES(property) = LIST-TO-TEXT( SORT( values(property, 1), values(property, 2), ... ), ";" ) where: * + indicates concatenation; * values(property, i) is the i-th property value in "property". 4.1.11. NORMALIZE-PROPERTY This function returns a Unicode string (7 [RFC8259]) representation of a single property. Tse & Tam Expires October 20, 2018 [Page 10] Internet-Draft vObject and vFormat April 2018 NORMALIZE-PROPERTY(property) = NORMALIZE-PROPERTY-KEY(property) + ":" + NORMALIZE-PROPERTY-VALUE-HASHA(property) + "/" + NORMALIZE-PROPERTY-VALUES(property) + "?" + NORMALIZE-PROPERTY-PARAMETERS(property) where: * + indicates concatenation 4.1.12. HASH-PROPERTY This function returns a Unicode string (7 [RFC8259]) representation of a single property. HASH-PROPERTY-TO-TEXT(property) = NORMALIZE-PROPERTY-KEY(property) + ":" + HASH(NORMALIZE-PROPERTY(property) where: * + indicates concatenation 4.1.13. HASH-AND-NORMALIZE-PROPERTIES This function returns a Unicode string (7 [RFC8259]) representation of a set of properties. HASH-AND-NORMALIZE-PROPERTIES(properties) = LIST-TO-TEXT( SORT([ HASH-PROPERTY(property(properties, 1)), HASH-PROPERTY(property(properties, 2)), ... ]), CRLF ) where: * + indicates concatenation; * property(properties, i) is the i-th property of "properties"; * HASH(s) is selected cryptographic hash function applied to string "s". 4.1.14. NORMALIZE-COMPONENT-NAME This function returns a Unicode string (7 [RFC8259]) representation of the normalized vObject name. NORMALIZE-COMPONENT-NAME(component) = UPCASE(name(component)) where: * name(c) is the component name of component "c". Tse & Tam Expires October 20, 2018 [Page 11] Internet-Draft vObject and vFormat April 2018 4.1.15. NORMALIZE-COMPONENT This function returns a Unicode string (7 [RFC8259]) representation of a vObject. The similarity of this representation with the vObject structure is intentional for readability purposes. NORMALIZE-COMPONENT(component) = "BEGIN:" + NORMALIZE-COMPONENT-NAME(component) + ":CHECKSUM" + CRLF + HASH-AND-NORMALIZE-PROPERTIES(properties(component)) + CRLF + "END:" + NORMALIZE-COMPONENT-NAME(component) + ":CHECKSUM" where: * + indicates concatenation; * properties(c) returns the properties of the component "c" in an list; 4.1.16. HASH-COMPONENT This function returns a Unicode string (7 [RFC8259]) as the output of a selected cryptographic hash function applied on a vObject. HASH-COMPONENT(component) = HASH(NORMALIZE-COMPONENT(component)) 4.1.17. HASH This function returns the calculated hash of an input string and outputs the hash in string representation. HASH(string) = generate-hash-function( selected-hash-function, selected-hash-parameters )(string) where: * "generate-hash-function(a, p)" creates a new cryptographic hash function that uses the hash algorithm "a" with algorithm parameters "p" which takes a string input and generates the hash using a string output; * "selected-hash-function" is the selected cryptographic hash algorithm selected by the user (and/or CUA); * "selected-hash-parameters" are the selected parameters for the selected cryptographic hash function by the user (and/or CUA), and could be different per algorithm. 5. Properties Property cardinalities are indicated in the same method as provided by [RFC6350] based on ABNF 3.6 [RFC5234]. Tse & Tam Expires October 20, 2018 [Page 12] Internet-Draft vObject and vFormat April 2018 5.1. CHECKSUM These registration details for the CHECKSUM property adhere to rules specified in 10.2.1 [RFC6350]. 5.1.1. Namespace Nil. 5.1.2. Property name CHECKSUM 5.1.3. Purpose Allows content integrity detection and verification against data corruption of a vObject. 5.1.4. Value type A single text value. 5.1.5. Cardinality "*" 5.1.6. Property parameters HASHA, HASHP 5.1.7. Value TEXT 5.1.8. Description CHECKSUM is an *OPTIONAL* property of a vObject. There can be multiple CHECKSUM properties within the same vObject. vObject client implementations are *RECOMMENDED* to implement CHECKSUM for a basic level of integrity guarantee. The CHECKSUM value used to compare the checksum of data should be selected in this way: o the highest PREF value among all CHECKSUM properties; then o the most applicable HASHA algorithm taking into account collision resistance and application support. Tse & Tam Expires October 20, 2018 [Page 13] Internet-Draft vObject and vFormat April 2018 5.1.9. Format definition ABNF: CHECKSUM-param = "VALUE=text" CHECKSUM-param = pid-param / pref-param / altid-param / checksum-param-hasha / checksum-param-hashp / iana-token CHECKSUM-value = TEXT ; Value type and VALUE parameter MUST match. 5.1.10. Examples CHECKSUM: ad58ca4f14b317dea48987f4991bdcd56fdf0f6a95049623f0fe5c4453d157e0 CHECKSUM;PREF=99: 3ac0e03cccda6663ed32052749cc5c607d88e381f9cfcb795317bc39a57909e3 CHECKSUM;HASHA=sha224: 22e92efac9d7b0e63695a9d960376ace1e69eb317e3d42c5c94f1401 6. Property Parameters The CHECKSUM allowed property parameters of "PID", "PREF", "ALTID" have the same meaning as on other properties [RFC6350]. 6.1. PREF Property Parameter The "PREF" property parameter indicates the preference of the vCard author on which CHECKSUM value to put most weight on. Usage of this parameter is further explained in Section 7. 6.2. HASHA Property Parameter Registration details for the HASHA property parameter adhere to rules specified in 10.2.1 [RFC6350] 6.2.1. Namespace Nil. Tse & Tam Expires October 20, 2018 [Page 14] Internet-Draft vObject and vFormat April 2018 6.2.2. Parameter name HASHA 6.2.3. Purpose Specify the hash function used for the property value 6.2.4. Description Possible values are defined in Section 14.2.4. The HASHA Property Parameter *MUST* not be applied on properties other than CHECKSUM unless specified. New HASHA hash functions *MUST* be specified in a Standards Track RFC. 6.2.5. Format definition ABNF: hasha-param = "HASHA=" hasha-value *("," hasha-value) hasha-value = "sha3-256" / iana-token / x-name ; This is further defined in <> 6.2.6. Examples: CHECKSUM;HASHA=sha384: 4055b176af753e251bc269007569c8f9633e6227a5f9727381cfba0bbb44a0c9 25b8d31d72083d9cb4dc1da278f3a4e4 CHECKSUM;HASHA=streebog256: TODO 6.3. HASHP Property Parameter Certain hash functions such as extendable output functions (XOFs) can be customized: o SHAKE-128, SHAKE-256, cSHAKE-128, cSHAKE256, ParallelHash128, ParallelHash256 support customizable hash value length. o cSHAKE-128, cSHAKE-256, support function name customization. o cSHAKE-128, cSHAKE-256, ParallelHash128, ParallelHash256 support customizable bit strings. Tse & Tam Expires October 20, 2018 [Page 15] Internet-Draft vObject and vFormat April 2018 o ParallelHash128, ParallelHash256 support customizable block sizes for parallel hashing. Since each hash function may take different specifiers, each hash function identifier *MAY* specify its own set of HASHP specifiers in a particular order. The parameter value(s) entered *MUST* conform to the hash function's specification in a Standards Track RFC. An implementation *MUST* follow the value type interpretation specified for the hash function. For example, in Section 9.1.1, the cSHAKE-128 algorithm (with the identifier "cshake128") takes "(L, N, S)" as input, where L is an integer to specify the output bit length, N is a text string representing the function name, S is a text string for customization purposes. When given a HASHP parameter value "512,address book,Orange", for the HASHA identifier "cshake128", the implementation *MUST* recognize that L is the integer 512, N is the string "address book", and S is the string "Orange". Registration details for the HASHP property parameter adhere to rules specified in 10.2.1 [RFC6350] 6.3.1. Namespace Nil. 6.3.2. Parameter name HASHP 6.3.3. Purpose Describe hash function specifiers used for the property value. 6.3.4. Description Provide specifiers for the HASHA hash function used to calculate the property value. Possible values are defined in Section 14.2.5. The HASHP Property Parameter *MUST* not be applied on properties other than CHECKSUM unless specified. Tse & Tam Expires October 20, 2018 [Page 16] Internet-Draft vObject and vFormat April 2018 6.3.5. Format definition ABNF: hashp-param = "HASHP=" hashp-value *("," hashp-value) hashp-value = param-value ; This list of values must be specified in the exact order and value type defined in <> Example(s): CHECKSUM;HASHA=shake128;HASHP=512,"Directory Service Identifier": TODO CHECKSUM;HASHA=parallelhash128;HASHP=64,512: TODO 7. Integrity Validation 7.1. Integrity In The vObject Life Cycle Data integrity is important during storage and transmission of a vObject. If an implementation stores vObjects directly on disk or in memory, it is *RECOMMENDED* that: o Immediately prior to saving on target medium, a CHECKSUM is calculated and stored; and o Immediately after retrieval from target medium, the included CHECKSUM is verified to ensure that it has not been corrupted. An implementation that supports CHECKSUM *MUST* adhere to the following rules: o If it supports vObject import (including network import), it *MUST* verify the provided CHECKSUM property value immediately prior to import to ensure the vObject has not been damaged. o If it supports vObject export (including network export), it *MUST* insert at least one CHECKSUM property with corresponding checksum values to the vObject immediately prior to exporting, to ensure the recipient of the vObject can check against data integrity. Tse & Tam Expires October 20, 2018 [Page 17] Internet-Draft vObject and vFormat April 2018 7.2. vObject Validity States There are 3 validity states of a vObject: Valid This vObject is not corrupt. Invalid This vObject is corrupt. Unable to determine This vObject does not provide enough information to make a validity judgement. 7.3. Definitions Implementation Supported Checksum An implementation is considered to "support checksum calculation" if it is able to calculate the checksum without external aid, i.e., it supports the parameters specified to calculate the checksum value. Source Preferred Checksum Value (SPCV) A CHECKSUM property that includes a PREF property parameter. Receiver Preferred Checksum Value (RPCV) The CHECKSUM property that uses the implementation's preferred checksum parameters. 7.4. Integrity Validity When Presented With A Single CHECKSUM Property Given one CHECKSUM property, an implementation that supports the CHECKSUM property *SHOULD* reach the following conclusions about the vObject: o Valid. The vObject is intact. Calculation by the implementation of the vObject's CHECKSUM property value was identical to the provided checksum value. o Invalid. The vObject is corrupted. Calculation by the implementation of the vObject's CHECKSUM resulted in a different value as the provided checksum value. o Unverified. The implementation is unable to determine data integrity of the vObject. * The vObject did not have a CHECKSUM property and therefore its data integrity cannot be verified. Tse & Tam Expires October 20, 2018 [Page 18] Internet-Draft vObject and vFormat April 2018 * The vObject had a CHECKSUM property with a blank value and therefore its data integrity cannot be verified. This also signifies that the originator implementation was not able to calculate a CHECKSUM value. * The vObject had a CHECKSUM property with a value but the current implementation does not support the chosen hash function, therefore its data integrity cannot be verified. 7.5. Integrity Validity When Presented With Multiple CHECKSUM Properties If a vObject has more than one non-empty CHECKSUM property, an implementation should validate according to the rules below. 1. In the order of preference stated (PREF parameter value), validate all supported SPCV until one is verified. * If a vObject can be validated to any SPCV, it is deemed valid. * If all SPCVs are invalid, the vObject fails validation. 2. If a vObject does not have any SPCV, or the implementation does not support any SPCV, but contains a supported CHECKSUM property * If the CHECKSUM property value is valid, the vObject is deemed valid. * Otherwise, the vObject fails validation. 8. Method of CHECKSUM Value Calculation The following method to calculate CHECKSUM is devised for these desired properties: o Stable across alternative representation formats of the vCard and iCalendar, such as xCard/jCard. o Allows comparison of equivalence of content rather than formatting. E.g., addition of new-lines within a vCard and order of listed properties do not affect the resulting checksum value. For implementations that handle CHECKSUM, its calculation *MUST* be performed after all property updates including REV, which is often updated during save. Steps to calculate CHECKSUM: Tse & Tam Expires October 20, 2018 [Page 19] Internet-Draft vObject and vFormat April 2018 1. Calculate the hash value of the vObject A. Determine the need to add a new CHECKSUM property. + If there is no existing CHECKSUM property, add it as the last property of the vObject, with the selected cryptographic hash algorithm type and the selected hash parameters. Its value should be set to "" (empty string). + If there is an existing CHECKSUM property: - If its parameters are identical to the user's current settings (or the CUA's defaults), there is no need to add an extra CHECKSUM property. Set its value to "" (empty string). - Otherwise, add the extra CHECKSUM property as described above. B. Calculate hash of each property individually (including the newly added CHECKSUM property). i. Obtain string representation of a property. A. Obtain string representation of a property parameter. I. Normalize property parameter values. ...... Sort property parameter values alphabetically. ...... Concatenate property parameter values. I. Normalize property parameter key: cast to uppercase. II. Concatenate string form of property parameter key, value type and values. A. Normalize property key: cast to uppercase. B. Normalize property value type: fill in value type if missing, and cast to uppercase. C. Normalize property values. III. Sort property values alphabetically. IV. Concatenate property values. Tse & Tam Expires October 20, 2018 [Page 20] Internet-Draft vObject and vFormat April 2018 A. Concatenate string form of property key, value type and values. i. Calculate hash of a property using the selected cryptographic hash function on the string representation of the property. ii. Convert hash into a normalized string representation. A. Concatenate hashes (in string representation) of the collection of properties. B. Calculate hash of the combined properties using the selected cryptographic hash function on the string representation of the collection of properties. 1. This procedure is repeated to calculate the value for every CHECKSUM property (which may specify different cryptographic hash algorithms and parameters), with all CHECKSUM values set to "" (empty string) for calculation consistency. * If the implementation is unable to calculate the CHECKSUM due to unsupported or unrecognized parameters of a CHECKSUM property, assign the "" (empty string) as its value. 2. Enter the calculated CHECKSUM value for each CHECKSUM property. 3. The checksum calculation procedure is complete. 9. Cryptographic Hash Functions The CHECKSUM value is calculated by a chosen cryptographic hash function specified in the HASHA property parameter. Certain hash functions accept customization specifiers, which can be specified in the HASHP property parameter. 9.1. Supported Hash Functions CHECKSUM supports the following hash algorithms. Tse & Tam Expires October 20, 2018 [Page 21] Internet-Draft vObject and vFormat April 2018 9.1.1. Hash Function Specifiers CHECKSUM supported hash algorithms are listed in the following table. o The CHECKSUM value contains the output of the hash function, which is usually stored in hexadecimal format as the "text" value type. o The identifier from this table should be put as value of the property parameter HASHA. o Algorithms with a "Variable" message digest size mean its length can be specified by a HASHP specifier. Algorithms with no specifiers: +----------------+------------+------------+------------------------+ | Algorithm | Identifier | Message | Description | | | | Digest | | | | | Size | | | | | (bits) | | +----------------+------------+------------+------------------------+ | SHA-2 SHA-224 | sha224 | 224 | [RFC6234]; | | | | | [NIST-FIPS-180-4]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 8 (SHA-224) | | SHA-2 SHA-256 | sha256 | 256 | [RFC6234]; | | | | | [NIST-FIPS-180-4]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 4 (SHA-256) | | SHA-2 SHA-384 | sha384 | 384 | [RFC6234]; | | | | | [NIST-FIPS-180-4]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 6 (SHA-384) | | SHA-2 SHA-512 | sha512 | 512 | [RFC6234]; | | | | | [NIST-FIPS-180-4]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 5 (SHA-512) | | SHA-2 | sha512-224 | 224 | [NIST-FIPS-180-4]; | | SHA-512/224 | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 9 | | | | | (SHA-512/224) | | SHA-2 | sha512-256 | 256 | [NIST-FIPS-180-4]; | | SHA-512/256 | | | [ISO-IEC-10118-3] | Tse & Tam Expires October 20, 2018 [Page 22] Internet-Draft vObject and vFormat April 2018 | | | | Dedicated Hash- | | | | | Function 10 | | | | | (SHA-512/256) | | WHIRLPOOL | whirlpool | 512 | [WHIRLPOOL]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 7 (WHIRLPOOL) | | STREEBOG-256 | streebog25 | 256 | [STREEBOG] GOST R | | | 6 | | 34.11-2012; [RFC6986]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 12 | | | | | (STREEBOG-256) | | STREEBOG-512 | streebog51 | 512 | [STREEBOG] GOST R | | | 2 | | 34.11-2012; [RFC6986]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 11 | | | | | (STREEBOG-512) | | SHA3-224 | sha3-224 | 224 | [NIST-FIPS-202]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 13 (SHA3-224) | | SHA3-256 | sha3-256 | 256 | [NIST-FIPS-202]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 14 (SHA3-256) | | SHA3-384 | sha3-384 | 384 | [NIST-FIPS-202]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 15 (SHA3-384) | | SHA3-512 | sha3-512 | 512 | [NIST-FIPS-202]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 16 (SHA3-512) | | SM3 | sm3 | 512 | <>; [SM3]; | | | | | [ISO-IEC-10118-3] | | | | | Dedicated Hash- | | | | | Function 17 (SM3) | | IANA | iana-token | iana-token | IANA | | registered | | | | | hash algorithm | | | | | Vendor- | x-token | Vendor | Vendor specific | | specific hash | | specific | | | algorithm | | | | +----------------+------------+------------+------------------------+ Tse & Tam Expires October 20, 2018 [Page 23] Internet-Draft vObject and vFormat April 2018 Algorithms with specifiers: +--------------+----------+-----------+------------+----------------+ | Algorithm | Identifi | Message | Specifier( | Description | | | er | Digest | s) | | | | | Size | | | | | | (bits) | | | +--------------+----------+-----------+------------+----------------+ | SHAKE-128 | shake128 | Varys | L: integer | [NIST-FIPS-202 | | | | | (default: | ] | | | | | 256) | | | SHAKE-256 | shake256 | Varys | L: integer | [NIST-FIPS-202 | | | | | (default: | ] | | | | | 512) | | | cSHAKE-128 | cshake12 | Varys | L: integer | [NIST-SP-800-1 | | | 8 | | (default: | 85] | | | | | 256), N: | | | | | | text | | | | | | (default: | | | | | | ""), S: | | | | | | text | | | | | | (default: | | | | | | "") | | | cSHAKE-256 | cshake25 | Varys | L: integer | [NIST-SP-800-1 | | | 6 | | (default: | 85] | | | | | 512), N: | | | | | | text | | | | | | (default: | | | | | | ""), S: | | | | | | text | | | | | | (default: | | | | | | "") | | | ParallelHash | parallel | Varys | B: integer | [NIST-SP-800-1 | | -128 | 128 | | (default: | 85] | | | | | 64), L: | | | | | | integer | | | | | | (default: | | | | | | 256), S: | | | | | | text | | | | | | (default: | | | | | | "") | | | ParallelHash | parallel | Varys | B: integer | [NIST-SP-800-1 | | -256 | 256 | | (default: | 85] | | | | | 64), L: | | | | | | integer | | | | | | (default: | | | | | | 256), S: | | | | | | text | | Tse & Tam Expires October 20, 2018 [Page 24] Internet-Draft vObject and vFormat April 2018 | | | | (default: | | | | | | "") | | | IANA | iana- | iana- | iana-token | IANA | | registered | token | token | | | | hash | | | | | | algorithm | | | | | | Vendor- | x-token | Vendor | Vendor | Vendor | | specific | | specific | specific | specific | | hash | | | | | | algorithm | | | | | +--------------+----------+-----------+------------+----------------+ 9.1.1.1. Example sha3-256('BEGIN:VCARD') = "f1fcbc9bddcd44b1e50db99a277bc868" + "61736eb32cb30ef7e7a2c9ef95c05d50" The default algorithm is "sha3-256". An implementation that supports this document *MUST* support at least the "sha3-256" function. 9.1.2. The SHA-2 Hash Functions Secure Hash Algorithm 2 (SHA-2) is a family of secure hash algorithms defined in [NIST-FIPS-180-4]: SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224 and SHA-512/256. o SHA-256 and SHA-512 are the two core hash functions that differ by process parameters, which produce a hash value of 256 and 512 bits respectively. o SHA-224 is identical to SHA-256, except that different initial hash values are used, and the final hash value is truncated to 224 bits. o SHA-384, SHA-512/224, SHA-512/256 are identical to SHA-512, except that different initial hash values are used, and the final hash value is truncated to 384, 224, 256 bits respectively. In particular, SHA-512/224 and SHA-512/256 use initial hash values generated by the "SHA-512/t IV Generation Function" given in [NIST-FIPS-180-4]. 9.1.3. The WHIRLPOOL Hash Function WHIRLPOOL is a hash function that operates on messages less than 2^256 bits in length, and produces a hash value of 512 bits [WHIRLPOOL]. Tse & Tam Expires October 20, 2018 [Page 25] Internet-Draft vObject and vFormat April 2018 It uses Merkle-Damgard strengthening and the Miyaguchi-Preneel hashing scheme with a dedicated 512-bit block cipher called W [WHIRLPOOL]. 9.1.4. The SM3 Hash Function SM3 is a hash function <> standardized by the Chinese Commercial Cryptography Administration Office [SM3] for the use of electronic authentication service systems. SM3 is an iterated hash function based on a Merkle-Damgard design, processes on 512-bit input message blocks with a 256-bit state, and produces a 256-bit hash value. 9.1.5. The SHA-3 Hash Functions Secure Hash Algorithm-3 (SHA-3) is a family of hash functions defined in [NIST-FIPS-202] consisting of: o four cryptographic hash functions, SHA3-224, SHA3-256, SHA3-384, SHA3-512; and o two extendable-output functions (XOFs), SHAKE128 and SHAKE256. Each SHA-3 function is based on an instance of the KECCAK algorithm [KECCAK] which won the SHA-3 Cryptographic Hash Algorithm Competition [NIST-FIPS-202]. o SHA3-224, SHA3-256, SHA3-384, SHA3-512 produce a hash value output of 224, 256, 384 and 512 bits respectively. o SHAKE128 and SHAKE256 are XOFs that produce output of arbitrary length, which can be specified using the "HASHP" property parameter. Notes concerning SHA-3 based XOFs [NIST-FIPS-202]: o Output of a XOF can be considered as an infinite string, and the "HASHP" property parameter simply determines how many initial bits of the initial string to use. o The SHAKE-256 and -128 functions, as long as at least 2x bits of their output is used, they have generic security strengths of 256 and 128 bits. However, using an excess of 64 or 32 bytes of their output respectively, does not increase their collision-resistance. Tse & Tam Expires October 20, 2018 [Page 26] Internet-Draft vObject and vFormat April 2018 9.1.6. The STREEBOG Hash Functions Streebog (or Stribog) is a family of two separate hash functions defined in the Russian standard GOST R 34.11-2012 [STREEBOG] where the functions differ in their output lengths, which are 256- and 512-bits respectively. Streebog accepts message block sizes of 512-bits, and both functions only differ in the different IVs used other than the output length [STREEBOG]. 9.1.7. The BLAKE2 Hash Functions BLAKE2, described in [BLAKE2] and [RFC7693], is a hash algorithm that comes in two flavors, BLAKE2b and BLAKE2s. It is the successor of BLAKE [BLAKE] which was a NIST SHA-3 competition finalist. o BLAKE2b is optimized for 64-bit platforms and produces hash values of any size between 1 and 64 bytes o BLAKE2s is optimized for 8- to 32-bit platforms and produces hash values of any size between 1 and 32 bytes While BLAKE2 allows customizing parameters, including salt and a customization string, implementations that adhere to this specification should adopt BLAKE2 as defined in [RFC7693]. 9.1.8. The SHA-3 Extension Hash Functions [NIST-SP-800-185] defines a number of additional hash algorithms based on algorithms defined in [NIST-FIPS-202], including: o cSHAKE-128, cSHAKE-256: customizable SHAKE functions, which take extra inputs of hash value length, a function name string, and a customization string; o ParallelHash128, ParallelHash256: supports efficient hashing of very long strings by taking advantage of the parallelism available in modern processors based on SHAKE. These take the extra inputs of block size, hash value length and a customization string. Both cSHAKE and ParallelHash are XOFs that can produce variable length output. The number suffix at their names mean the security strength bits of the algorithm. Tse & Tam Expires October 20, 2018 [Page 27] Internet-Draft vObject and vFormat April 2018 9.2. Selection Considerations 9.2.1. Collision Resistance of Hash Function Families For our purposes we specify the following strength families of hash algorithms. Hash functions placed in the higher bracket are considered "more resistant" in algorithm selection. +----------+--------------------------------------------------------+ | Strength | Hash Function Identifier | +----------+--------------------------------------------------------+ | 1 | sha224, sha256, sha384, sha512, sha512-224, sha512-256 | | 2 | whirlpool, streebog256, streebog512 | | 3 | blake2b256, blake2b384, blake2b512, blake2s224, | | | blake2s256, sm3, shake128, shake256, sha3-224, | | | sha3-256, sha3-384, sha3-512 | +----------+--------------------------------------------------------+ 9.2.2. Guidelines for Hash Function Selection o Collision-resistance: higher bit length digests are generally preferable to lower bit length digests due to lower susceptibility to collisions. o Performance: some hash functions are more computation intensive. Higher bit length digests generally require more computation to generate. o History: a hash algorithm that has withstood cryptanalytic attacks provide better confidence than ones that have not been in widespread use. o Availability and interoperability: certain hash algorithms, such as SHA-2 ([RFC6234]; [NIST-FIPS-180-4]; [ISO-IEC-10118-3] Dedicated Hash-Function 4 (SHA-256)), are more prevalently available on computing platforms. Selection of the hash function should be based on a balance of collision resistance, performance, history and interoperability. 9.2.3. Hash Functions Considered Unsuitable The following hash functions are specifically excluded due to stated reasons: o RIPEMD-160 [ISO-IEC-10118-3] Dedicated Hash-Function 1 and RIPEMD-128 [ISO-IEC-10118-3] Dedicated Hash-Function 2, are specifically excluded as they do no longer provide a sufficient Tse & Tam Expires October 20, 2018 [Page 28] Internet-Draft vObject and vFormat April 2018 level of collision resistance, see 7.1 [ISO-IEC-10118-3] Note 2 8 [ISO-IEC-10118-3] Note 2. The RIPEMD optional extensions RIPEMD-256 and RIPEMD-320 [RIPEMD160] are also excluded as they are of the same security levels as RIPEMD-128 and RIPE-160 respectively. o SHA-1 [RFC3174] [ISO-IEC-10118-3] Dedicated Hash-Function 3 is excluded as it does not provide a sufficient level of collision resistance, see 9.1 [ISO-IEC-10118-3] Note 2. o CRC-32 [ISO-IEC-13239] and in general CRC algorithms are excluded due to weak collision resistance. 10. Using CHECKSUM With Server Support 10.1. Usage of CHECKSUM in vCards on CardDAV servers CardDAV servers are *RECOMMENDED* to calculate and provide an extra CHECKSUM property for al vCard retrieval requests in order to provide a base level of integrity guarantee. The CHECKSUM property and its parameters are fully compatible with the CardDAV mechanism described in [RFC6352]. 10.1.1. Creating And Updating Address Object Resources 6.3.2 [RFC6352] specifies how to create address object resources. An implementation abiding to this specification *MUST* augment this process according to the following. 10.1.1.1. Client Implementations Should Transmit With CHECKSUM o When a client issues a PUT to create an address object resource, a CHECKSUM property *SHOULD* be included in the request. o The CHECKSUM property value *MAY* be empty if the client wishes the server to calculate the value according to the given HASHA and/or HASHP parameters. 10.1.2. Additional Server Semantics for PUT, COPY and MOVE This specification creates an additional precondition and postcondition for the PUT, COPY, and MOVE methods when: o A PUT operation requests an address object resource to be placed into an address book collection; and Tse & Tam Expires October 20, 2018 [Page 29] Internet-Draft vObject and vFormat April 2018 o A COPY or MOVE operation requests an address object resource to be placed into (or out of) an address book collection. 10.1.2.1. Only Admit Valid vCard Data From Client 10.1.2.2. Additional Precondition "(CARDDAV:valid-address-data-checksum)" The address object resource submitted in the PUT request, or targeted by a COPY or MOVE request, contains a CHECKSUM property: o The address object resource's integrity *MUST* be valid as determined by methods of this specification. o If the resource contains an empty CHECKSUM property value, the server *SHOULD* fill in the property value with its own calculation. o The CHECKSUM property value *SHOULD* be stored by the server to enable data integrity verification. o If the resource CHECKSUM is deemed invalid, the server *SHOULD* respond with a "409" (Conflict) status to indicate to the client so, hence the "" condition is not met. In this case, the client may choose to empty the CHECKSUM property value for re-submission. 10.1.2.3. Resolve Discrepancy Between Server And Client vCard Data Certain servers perform silent changes or cleanups of client provided vCard data when stored as address object resources, such as the order of property parameters or scrubbed values. The resulting vCard data stored on the server (and when returned back to the client) may end up different than that of the client without its knowledge. It is therefore necessary for the client to be reported on such modifications. 10.1.2.4. Additional Postcondition "(CARDDAV:resource-not-modified)": The address object resource should not be modified by the server such that its original CHECKSUM value becomes invalid. o After action execution, the server should re-calculate the CHECKSUM property value based on the retrieved address object resource. Tse & Tam Expires October 20, 2018 [Page 30] Internet-Draft vObject and vFormat April 2018 o If the CHECKSUM property value is now different, the server *SHOULD* respond to client with the latest address object resource and the new CHECKSUM so that the client knows the resource has been changed by the server. 10.2. Usage of CHECKSUM with CalDAV The CalDAV [RFC4791] calendar access protocol allows clients and servers to exchange iCalendar data. iCalendar data is typically stored in calendar object resources on a CalDAV server. A CalDAV server is *RECOMMENDED* to return iCalendar data with integrity protection. 10.2.1. Creating Calendar Resources A CalDAV client typically updates the calendar object resource data via an HTTP PUT request, which requires sending the entire iCalendar object in the HTTP request body. 10.3. Usage of CHECKSUM with iTIP iTIP [RFC5546] defines how iCalendar data can be sent between calendar user agents to schedule calendar components between calendar users. This specification is compatible with iTIP transfer of iCalendar data. 11. Alternative vObject Representations 11.1. xCard The XML representation [RFC6351] of the CHECKSUM property follows the example shown below. For this property, the value type *MUST* be set to "text" and parameter "type" *MUST* also be set to "text". sha224 99 22e92efac9d7b0e63695a9d960376ace1e69eb317e3d42c5c94f1401 Tse & Tam Expires October 20, 2018 [Page 31] Internet-Draft vObject and vFormat April 2018 11.2. jCard The JSON representation of the CHECKSUM property follows [RFC7095] as the example shown below. ["checksum", { "hasha": "sha224", "pref": "99" }, "text", "22e92efac9d7b0e63695a9d960376ace1e69eb317e3d42c5c94f1401" ] 12. Implementation Notes 12.1. vCard REV Update Guidelines For The CHECKSUM Property Updating of the CHECKSUM property value should not affect the REV value of a vCard. However, if a CHECKSUM property is newly inserted, or its parameters changed (such as HASHA or HASHP), then the REV value should be updated according to [RFC6350]. 12.2. Calculating CHECKSUM From An xCard Implementers *MUST* ignore individual parameter value types in xCard (6 [RFC6351], Appendix A 4.1) during CHECKSUM value calculation to be compatible with vCard and jCard, as individual parameter value types are implicit (not explicitly represented) in both vCard and jCard properties. 12.3. Backwards Compatibility Concerns If an implementation does not support the CHECKSUM property, it *MUST* ignore the CHECKSUM property entirely without providing it any value. If an incorrect value is provided, the receiving end of this vObject may falsely assume that the vObject is broken. 12.4. Unsupported Property Parameters o If an implementation supports the CHECKSUM property but not certain parameters (e.g., a specified hash function), it *MUST* leave that property value empty as the insertion of the CHECKSUM property indicates the wish of the user to utilize it. o If an implementation supports the CHECKSUM property, it *MUST* calculate the checksum values for every CHECKSUM property in the vObject. Tse & Tam Expires October 20, 2018 [Page 32] Internet-Draft vObject and vFormat April 2018 12.5. Recommendations for Client User Applications 12.5.1. User Experience o The CUA *SHOULD* honestly reflect checksum validation results to the user to allow further action from the user, e.g., to seek retransmission of the vObject. 12.5.2. Ongoing Improvements o Cryptographic hash algorithms can break overtime. There will be a time when best practice designates a better one, CUA *SHOULD* take this in mind and promote best practice to update its security profile. 13. Security Considerations o The function of the CHECKSUM property depends on the collision- free property of cryptographic hash functions. However, as time passes, today's recommended cryptographic hash functions may no longer be considered reliable in the future. Implementers *MUST* take this into account and update its security profile according to the latest best practice on cryptographic hash functions. o The CHECKSUM property is not designed to protect against intentional and unauthorized modification. A malicious party with access to the vObject (such as a man-in-the-middle attack (3.3.5 [RFC3552]; 4 [RFC4949]. Definition for 'man-in-the-middle') could both modify the data and the CHECKSUM property at the same time and prevent detection. o The CHECKSUM property is not designed to address data authenticity (2.8 [ISO-IEC-27000]; 2.1.3 [RFC3552]) concerns. A malicious party may send a vObject posing as another entity. This document does not protect against that situation. o While many vObject properties can be used to transport URIs, the CHECKSUM property specifically does not allow setting a URI as its value due to extra security risks raised during the reference step to a URI (7 [RFC3986]). In any case, it is easy for an attacker to directly modify the CHECKSUM instead of modifying the results at a third-party URI, and therefore would not improve integrity protection of the vObject. o Security considerations around vObject formats in the following documents *MUST* be adhered to: o vCard: [RFC6350] Tse & Tam Expires October 20, 2018 [Page 33] Internet-Draft vObject and vFormat April 2018 o iCalendar: [RFC5545], [RFC5789], [RFC4791] 14. IANA Considerations 14.1. Common vObject Registries The IANA has created and will maintain the following registries for vObject elements with pointers to appropriate reference documents. The registries are grouped together under the heading "Common vObject Elements". 14.2. Registering New Hash Functions And Hash Function Specifiers This section defines the process for registering new or modified hash functions and hash function specifiers with IANA. 14.2.1. Registration Procedure The IETF mailing lists for vCard () and iCalendar () *SHOULD* be used for public discussion of additional hash functions and hash function specifiers for the CHECKSUM property prior to registration. The registration procedure specified in [RFC6350] should be followed to register additional hash functions and hash function specifiers for vObjects. Registration of new vObject hash functions and their specifiers *MUST* be reviewed by the designated expert and published in an RFC. A Standards Track RFC is *REQUIRED* for: o Registration of new hash functions or hash function specifiers. o Modification of hash functions and hash function specifiers previously documented in a Standards Track RFC. 14.2.2. Registration Template for vObject Hash Functions A Hash Function is defined by completing the following template. Identifier The identifier of the hash function. Description A short but clear description of the hash function, with any special notes about it. Tse & Tam Expires October 20, 2018 [Page 34] Internet-Draft vObject and vFormat April 2018 Example(s) One or more examples of input and output of the hash function. 14.2.3. Registration Template for vObject Hash Function Specifiers A Hash Function Specifier is defined by completing the following template. Identifier Identifier of the hash function that this specifier applies to. Description A short but clear description of the hash function specifier. Order In which position in the specifier list should this specifier be found. Value Type The type of specifier value (e.g., text). Example(s) One or more examples of input and output of the hash function. 14.2.4. vObject Hash Functions Registry