idnits 2.17.1 draft-richter-cbor-error-tag-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 30, 2019) is 1911 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCthis' is mentioned on line 164, but not defined == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-06 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Richter 3 Internet-Draft pdv Financial Software GmbH 4 Intended status: Informational C. Bormann 5 Expires: August 3, 2019 Universitaet Bremen TZI 6 January 30, 2019 8 Concise Binary Object Representation (CBOR) Tag for Error Indications 9 draft-richter-cbor-error-tag-01 11 Abstract 13 The Concise Binary Object Representation (CBOR, RFC 7049) is a data 14 format whose design goals include the possibility of extremely small 15 code size, fairly small message size, and extensibility without the 16 need for version negotiation. 18 In CBOR, one point of extensibility is the definition of CBOR tags. 19 While CBOR defines representations for null values and for an 20 undefined value, there is no convention for expressing errors or 21 exceptions in data structures, where the actual value desired could 22 not be calculated due to an error. The present specification defines 23 a tag for such error indications, enabling the addition of varying 24 levels of detail. 26 Note to Readers 28 Please discuss this draft on the mailing list cbor@ietf.org - 29 subscribe at https://www.ietf.org/mailman/listinfo/cbor to follow the 30 discussions. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on August 3, 2019. 49 Copyright Notice 51 Copyright (c) 2019 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 67 2. Error Format . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 5 69 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 71 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 73 6.2. Informative References . . . . . . . . . . . . . . . . . 6 74 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 6 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 77 1. Introduction 79 The Concise Binary Object Representation (CBOR, [RFC7049]) provides 80 for the interchange of structured data without a requirement for a 81 pre-agreed schema. RFC 7049 defines a basic set of data types, as 82 well as a tagging mechanism that enables extending the set of data 83 types supported via an IANA registry. 85 In CBOR, one point of extensibility is the definition of CBOR tags. 86 While CBOR defines representations for null values and for an 87 undefine value, there is no convention for expressing errors or 88 exceptions in data structures. The present specification defines a 89 tag for such error indications, enabling varying levels of detail. 91 2. Error Format 93 An error value is indicated by CBOR tag TBD101, which tags a data 94 item that may contain additional information about the error value: 96 o If no further information is provided, the data item is the CBOR 97 value null. 99 o If a diagnostic text string is provided, the data item is that 100 text string. 102 o If more detailed information is provided, the data item is a map 103 (CBOR major type 5), with text string or integer keys and values 104 as defined by the application. 106 This specification does not further define what keys and values 107 should be used in a map that is used as the tagged item for this tag. 108 However, to maximize interoperability, the following keys and values 109 are suggested for use whenever they are appropriate for an 110 application (the keys are text strings, suggested value types are 111 indicated in the table with CDDL names): 113 +---------+--------------------------------------------------+------+ 114 | key | value | type | 115 +---------+--------------------------------------------------+------+ 116 | name | a formal name for the kind of error amenable to | text | 117 | | program processing, maybe a class name or a URI | | 118 | code | a number assigned for the kind of error, e.g. an | int | 119 | | HTTP-style error code such as 404 | | 120 | message | human-readable description; what would be in the | text | 121 | | diagnostic text string if only that were | | 122 | | provided | | 123 | file | indicating location of error in program: file | text | 124 | | name | | 125 | line | indicating location of error in program: line | uint | 126 | | number | | 127 | column | indicating location of error in program: column | uint | 128 | | number | | 129 +---------+--------------------------------------------------+------+ 131 Note that these suggestions have been somewhat inspired by the 132 JavaScript "Error" object (Section 19.5 of [ECMA262])), except that 133 two-word forms of keys have been shortened to single words. There is 134 no intention that the details of the JavaScript "Error" object are 135 normative for the present specification. More generally, there is no 136 intention to limit the use of the Tag defined here to those 137 applications that would employ the JavaScript "Error" object. 139 (Discussion: changing lineNumber into line sounds like a good idea. 140 Changing fileName into file is suboptimal, but reallu the problem is 141 that neither says "source file". I was thinking about using "source" 142 in place of "file".) 144 3. CDDL typenames 146 For the use with the CBOR Data Definition Language, CDDL 147 [I-D.ietf-cbor-cddl], the type names defined in Figure 1 are 148 recommended: 150 error = error-of<(null / text / {* (int/text) => any})> 151 error-of = #6.101(T) 153 Figure 1: Recommended type names for CDDL 155 4. IANA Considerations 157 In the registry [IANA.cbor-tags], IANA is requested to allocate the 158 tag in Table 1 from the FCFS space, with the present document as the 159 specification reference. 161 +--------+-----------------+----------------------------+ 162 | Tag | Data Item | Semantics | 163 +--------+-----------------+----------------------------+ 164 | TBD101 | null, text, map | [RFCthis] error indication | 165 +--------+-----------------+----------------------------+ 167 Table 1: Values for Tags 169 5. Security Considerations 171 The security considerations of RFC 7049 apply. 173 Error/diagnostic information provided by a system can disclose 174 internals of that to an attacker; care should be taken with the tag 175 introduced here that its use does not facilitate attacks in this way. 177 6. References 179 6.1. Normative References 181 [I-D.ietf-cbor-cddl] 182 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 183 definition language (CDDL): a notational convention to 184 express CBOR and JSON data structures", draft-ietf-cbor- 185 cddl-06 (work in progress), November 2018. 187 [IANA.cbor-tags] 188 IANA, "Concise Binary Object Representation (CBOR) Tags", 189 . 191 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 192 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 193 October 2013, . 195 6.2. Informative References 197 [ECMA262] Ecma International, "ECMAScript 2018 Language 198 Specification", ECMA Standard ECMA-262, 9th Edition, June 199 2018, . 203 Acknowledgements 205 Authors' Addresses 207 Joerg Richter 208 pdv Financial Software GmbH 209 Dorotheenstr. 64 210 Hamburg D-22301 211 Germany 213 Email: joerg.richter@pdv-fs.de 215 Carsten Bormann 216 Universitaet Bremen TZI 217 Postfach 330440 218 Bremen D-28359 219 Germany 221 Phone: +49-421-218-63921 222 Email: cabo@tzi.org