idnits 2.17.1 draft-ietf-sacm-coswid-11.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: +-------+-----------+-----------------------------------------------+ | Index | Ownership | Definition | | | Type | | +-------+-----------+-----------------------------------------------+ | 1 | abandon | If the software component referenced by the | | | | CoSWID tag is uninstalled, then the | | | | referenced software SHOULD not be uninstalled | | | | | | 2 | private | If the software component referenced by the | | | | CoSWID tag is uninstalled, then the | | | | referenced software SHOULD be uninstalled as | | | | well. | | | | | | 3 | shared | If the software component referenced by the | | | | CoSWID tag is uninstalled, then the | | | | referenced software SHOULD be uninstalled if | | | | no other components sharing the software. | +-------+-----------+-----------------------------------------------+ -- The document date (June 27, 2019) is 1765 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Link' is mentioned on line 1902, but not defined == Missing Reference: 'RFC-AAAA' is mentioned on line 2470, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Possible downref: Non-RFC (?) normative reference: ref. 'SAM' -- Possible downref: Non-RFC (?) normative reference: ref. 'SEMVER' -- Possible downref: Non-RFC (?) normative reference: ref. 'SWID' == Outdated reference: A later version (-07) exists of draft-birkholz-rats-tuda-00 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SACM Working Group H. Birkholz 3 Internet-Draft Fraunhofer SIT 4 Intended status: Standards Track J. Fitzgerald-McKay 5 Expires: December 29, 2019 Department of Defense 6 C. Schmidt 7 The MITRE Corporation 8 D. Waltermire 9 NIST 10 June 27, 2019 12 Concise Software Identification Tags 13 draft-ietf-sacm-coswid-11 15 Abstract 17 ISO/IEC 19770-2:2015 Software Identification (SWID) tags provide an 18 extensible XML-based structure to identify and describe individual 19 software components, patches, and installation bundles. SWID tag 20 representations can be too large for devices with network and storage 21 constraints. This document defines a concise representation of SWID 22 tags: Concise SWID (CoSWID) tags. CoSWID supports the same features 23 as SWID tags, as well as additional semantics that allow CoSWIDs to 24 describe additional types of information, all in a more memory 25 efficient format. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on December 29, 2019. 44 Copyright Notice 46 Copyright (c) 2019 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. The SWID and CoSWID Tag Lifecycle . . . . . . . . . . . . 4 63 1.2. Concise SWID Format . . . . . . . . . . . . . . . . . . . 6 64 1.3. Requirements Notation . . . . . . . . . . . . . . . . . . 7 65 2. Concise SWID Data Definition . . . . . . . . . . . . . . . . 7 66 2.1. Concise SWID Extensions . . . . . . . . . . . . . . . . . 8 67 2.2. The concise-swid-tag Group . . . . . . . . . . . . . . . 10 68 2.3. concise-swid-tag Co-constraints . . . . . . . . . . . . . 14 69 2.4. The global-attributes Group . . . . . . . . . . . . . . . 15 70 2.5. The entity-entry Group . . . . . . . . . . . . . . . . . 16 71 2.6. The link-entry Map . . . . . . . . . . . . . . . . . . . 18 72 2.7. The software-meta-entry Map . . . . . . . . . . . . . . . 22 73 2.8. The Resource Collection Definition . . . . . . . . . . . 25 74 2.8.1. The hash-entry Array . . . . . . . . . . . . . . . . 25 75 2.8.2. The resource-collection Group . . . . . . . . . . . . 25 76 2.8.3. The payload-entry Group . . . . . . . . . . . . . . . 29 77 2.8.4. The evidence-entry Group . . . . . . . . . . . . . . 29 78 2.9. Full CDDL Definition . . . . . . . . . . . . . . . . . . 30 79 3. Determining the Type of CoSWID . . . . . . . . . . . . . . . 35 80 4. CoSWID Indexed Label Values . . . . . . . . . . . . . . . . . 36 81 4.1. Version Scheme . . . . . . . . . . . . . . . . . . . . . 36 82 4.2. Entity Role Values . . . . . . . . . . . . . . . . . . . 37 83 4.3. Link Ownership Values . . . . . . . . . . . . . . . . . . 38 84 4.4. Link Rel Values . . . . . . . . . . . . . . . . . . . . . 39 85 4.5. Link Use Values . . . . . . . . . . . . . . . . . . . . . 41 86 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 87 5.1. CoSWID Items Registry . . . . . . . . . . . . . . . . . . 42 88 5.2. SWID/CoSWID Value Registries . . . . . . . . . . . . . . 45 89 5.2.1. SWID/CoSWID Version Scheme Value Registry . . . . . . 45 90 5.2.2. SWID/CoSWID Entity Role Value Registry . . . . . . . 46 91 5.2.3. SWID/CoSWID Link Ownership Value Registry . . . . . . 48 92 5.2.4. SWID/CoSWID Link Relationship Value Registry . . . . 49 93 5.2.5. SWID/CoSWID Link Use Value Registry . . . . . . . . . 52 94 5.3. swid+cbor Media Type Registration . . . . . . . . . . . . 53 95 5.4. CoAP Content-Format Registration . . . . . . . . . . . . 54 96 5.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . . 54 98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 55 99 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 56 100 8. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 56 101 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 60 102 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 103 10.1. Normative References . . . . . . . . . . . . . . . . . . 60 104 10.2. Informative References . . . . . . . . . . . . . . . . . 62 105 Appendix A. Signed Concise SWID Tags using COSE . . . . . . . . 63 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 108 1. Introduction 110 SWID tags, as defined in ISO-19770-2:2015 [SWID], provide a 111 standardized XML-based record format that identifies and describes a 112 specific release of software, a patch, or an installation bundle, 113 which are referred to as software components in this document. 114 Different software components, and even different releases of a 115 particular software component, each have a different SWID tag record 116 associated with them. SWID tags are meant to be flexible and able to 117 express a broad set of metadata about a software component. 119 SWID tags are used to support a number of processes including but not 120 limited to: 122 o Software Inventory Management, a part of a Software Asset 123 Management [SAM] process, which requires an accurate list of 124 discernible deployed software components. 126 o Vulnerability Assessment, which requires a semantic link between 127 standardized vulnerability descriptions and software components 128 installed on IT-assets [X.1520]. 130 o Remote Attestation, which requires a link between reference 131 integrity measurements (RIM) and security logs of measured 132 software components [I-D.birkholz-rats-tuda]. 134 While there are very few required fields in SWID tags, there are many 135 optional fields that support different uses. A SWID tag consisting 136 of only required fields might be a few hundred bytes in size; 137 however, a tag containing many of the optional fields can be many 138 orders of magnitude larger. Thus, real-world instances of SWID tags 139 can be fairly large, and the communication of SWID tags in usage 140 scenarios, such as those described earlier, can cause a large amount 141 of data to be transported. This can be larger than acceptable for 142 constrained devices and networks. Concise SWID (CoSWID) tags 143 significantly reduce the amount of data transported as compared to a 144 typical SWID tag. This reduction is enabled through the use of CBOR, 145 which maps the human-readable labels of SWID data items to more 146 concise integer labels (indices). The use of CBOR to express SWID 147 information in CoSWID tags allows both CoSWID and SWID tags to be 148 part of an enterprise security solution for a wider range of 149 endpoints and environments. 151 1.1. The SWID and CoSWID Tag Lifecycle 153 In addition to defining the format of a SWID tag record, ISO/IEC 154 19770-2:2015 defines requirements concerning the SWID tag lifecycle. 155 Specifically, when a software component is installed on an endpoint, 156 that software component's SWID tag is also installed. Likewise, when 157 the software component is uninstalled or replaced, the SWID tag is 158 deleted or replaced, as appropriate. As a result, ISO/IEC 159 19770-2:2015 describes a system wherein there is a correspondence 160 between the set of installed software components on an endpoint, and 161 the presence of the corresponding SWID tags for these components on 162 that endpoint. CoSWIDs share the same lifecycle requirements as a 163 SWID tag. 165 The SWID specification and supporting guidance provided in NIST 166 Internal Report (NISTIR) 8060: Guidelines for the Creation of 167 Interoperable SWID Tags [SWID-GUIDANCE] defines four types of SWID 168 tags: primary, patch, corpus, and supplemental. The following text 169 is paraphrased from these sources. 171 1. Primary Tag - A SWID or CoSWID tag that identifies and describes 172 an installed software component on an endpoint. A primary tag is 173 intended to be installed on an endpoint along with the 174 corresponding software component. 176 2. Patch Tag - A SWID or CoSWID tag that identifies and describes an 177 installed patch that has made incremental changes to a software 178 component installed on an endpoint. A patch tag is intended to 179 be installed on an endpoint along with the corresponding software 180 component patch. 182 3. Corpus Tag - A SWID or CoSWID tag that identifies and describes 183 an installable software component in its pre-installation state. 184 A corpus tag can be used to represent metadata about an 185 installation package or installer for a software component, a 186 software update, or a patch. 188 4. Supplemental Tag - A SWID or CoSWID tag that allows additional 189 information to be associated with a referenced SWID tag. This 190 allows tools and users to record their own metadata about a 191 software component without modifying SWID primary or patch tags 192 created by a software provider. 194 The type of a tag is determined by specific data elements, which are 195 discussed in Section 3. 197 Corpus, primary, and patch tags have similar functions in that 198 they describe the existence and/or presence of different types of 199 software components (e.g., software installers, software 200 installations, software patches), and, potentially, different 201 states of these software components. Supplemental tags have the 202 same structure as other tags, but are used to provide information 203 not contained in the referenced corpus, primary, and patch tags. 204 All four tag types come into play at various points in the 205 software lifecycle and support software management processes that 206 depend on the ability to accurately determine where each software 207 component is in its lifecycle. 209 +------------+ 210 v | 211 Software Software Software Software Software 212 Deployment -> Installation -> Patching -> Upgrading -> Removal 214 Corpus Primary Primary xPrimary xPrimary 215 Supplemental Supplemental Supplemental xSupplemental xSuplemental 216 Patch xPatch 217 Primary 218 Supplemental 220 Figure 1: Use of Tag Types in the Software Lifecycle 222 Figure 1 illustrates the steps in the software lifecycle and the 223 relationships among those lifecycle events supported by the four 224 types of SWID and CoSWID tags, as follows: 226 * Software Deployment. Before the software component is 227 installed (i.e., pre-installation), and while the product is 228 being deployed, a corpus tag provides information about the 229 installation files and distribution media (e.g., CD/DVD, 230 distribution package). 232 * Software Installation. A primary tag will be installed with 233 the software component (or subsequently created) to uniquely 234 identify and describe the software component. Supplemental 235 tags are created to augment primary tags with additional site- 236 specific or extended information. While not illustrated in the 237 figure, patch tags can also be installed during software 238 installation to provide information about software fixes 239 deployed along with the base software installation. 241 * Software Patching. When a new patch is applied to the software 242 component a new patch tag is provided, supplying details about 243 the patch and its dependencies. While not illustrated in the 244 figure, a corpus tag can also provide information about the 245 patch installer and patching dependencies that need to be 246 installed before the patch. 248 * Software Upgrading. As a software component is upgraded to a 249 new version, new primary and supplemental tags replace existing 250 tags, enabling timely and accurate tracking of updates to 251 software inventory. While not illustrated in the figure, a 252 corpus tag can also provide information about the upgrade 253 installer and dependencies that need to be installed before the 254 upgrade. 256 * Software Removal. Upon removal of the software component, 257 relevant SWID tags are removed. This removal event can trigger 258 timely updates to software inventory reflecting the removal of 259 the product and any associated patch or supplemental tags. 261 As illustrated in the figure, supplemental tags can be associated 262 with any corpus, primary, or patch tag to provide additional metadata 263 about an installer, installed software, or installed patch 264 respectively. 266 Understanding the use of CoSWIDs in the software lifecycle provides a 267 basis for understanding the information provided in a CoSWID and the 268 associated semantics of this information. Each of the different SWID 269 and CoSWID tag types provide different sets of information. For 270 example, a "corpus tag" is used to describe a software component's 271 installation image on an installation media, while a "patch tag" is 272 meant to describe a patch that modifies some other software 273 component. 275 1.2. Concise SWID Format 277 This document defines the CoSWID tag format, which is based on the 278 Concise Binary Object Representation (CBOR) [RFC7049]. CBOR-based 279 CoSWID tags offer a more concise representation of SWID information 280 as compared to the XML-based SWID tag representation in ISO- 281 19770-2:2015. The structure of a CoSWID is described via the Concise 282 Data Definition Language (CDDL) [RFC8610]. The resulting CoSWID data 283 definition is aligned to the information able to be expressed with 284 the XML schema definition of ISO-19770-2:2015 [SWID]. This alignment 285 allows both SWID and CoSWID tags to represent a common set of 286 software component information and allows CoSWID tags to support the 287 same uses as a SWID tag. To achieve this end, the CDDL 288 representation includes every SWID tag field and attribute. 290 The vocabulary, i.e., the CDDL names of the types and members used in 291 the CoSWID data definition, are mapped to more concise labels 292 represented as small integer values. The names used in the CDDL data 293 definition and the mapping to the CBOR representation using integer 294 labels is based on the vocabulary of the XML attribute and element 295 names defined in ISO/IEC 19770-2:2015. 297 1.3. Requirements Notation 299 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 300 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 301 "OPTIONAL" in this document are to be interpreted as described in 302 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 303 capitals, as shown here. 305 2. Concise SWID Data Definition 307 The following describes the general rules and processes for encoding 308 data using CDDL representation. Prior familiarity with CBOR and CDDL 309 concepts will be helpful in understanding this CoSWID data 310 definition. 312 This section describes the rules by which SWID tag XML is represented 313 in the CoSWID CDDL structure. The CamelCase [CamelCase] notation 314 used in the XML schema definition is changed to a hyphen-separated 315 notation [KebabCase] (e.g. ResourceCollection is named resource- 316 collection) in the CoSWID data definition. This deviation from the 317 original notation used in the XML representation reduces ambiguity 318 when referencing certain attributes in corresponding textual 319 descriptions. An attribute referred to by its name in CamelCase 320 notation explicitly relates to XML SWID tags; an attribute referred 321 to by its name in KebabCase notation explicitly relates to CBOR 322 CoSWID tags. This approach simplifies the composition of further 323 work that reference both XML SWID and CBOR CoSWID documents. 325 Note that sometimes CoSWID CDDL attribute names show greater 326 variation than the described notation change relative to their 327 corresponding SWID XML Schema attributes. This is done when the 328 change improves clarity in the specification. For example the "name" 329 and "version" SWID fields corresponds to the "software-name" and 330 "software-version" CoSWID fields, respectively. As such, it is not 331 always possible to mechanically translate between corresponding 332 attribute names in the two formats. 334 The 57 human-readable text labels of the CDDL-based CoSWID vocabulary 335 are mapped to integer indices via a block of rules at the bottom of 336 the definition. This allows a more concise integer-based form to be 337 stored or transported, as compared to the less efficient text-based 338 form of the original vocabulary. 340 In CBOR, an array is encoded using bytes that identify the array, and 341 the array's length or stop point (see [RFC7049]). To make items that 342 support 1 or more values, the following CDDL notion is used. 344 _name_ = (_label_: _data_ / [ 2* _data_ ]) 346 The CDDL rule above allows either a single data item or an array of 2 347 or more data values to be provided. When a singleton data value is 348 provided, the CBOR markers for the array, array length, and stop 349 point are not needed saving bytes. When two or more data values are 350 provided, these values are encoded as an array. This modeling 351 pattern is used frequently in the CoSWID CDDL data definition to 352 allow for more efficient encoding of singleton values. 354 The following subsections describe the different parts of the CoSWID 355 model. 357 2.1. Concise SWID Extensions 359 The CoSWID data definition contains two features that are not 360 included in the SWID data definition on which it is based. These 361 features are: 363 o The explicit definition of types for attributes that are typically 364 stored in the "any attribute" of an ISO-19770-2:2015 in XML 365 representation. These are covered in Section 2.4. 367 o The inclusion of extension points in the CoSWID data definition 368 using CDDL sockets (see [RFC8610] section 3.9). The use of CDDL 369 sockets allow for well-formed extensions to be defined in 370 supplementary CDDL descriptions that support additional uses of 371 CoSWID tags that go beyond the original scope of ISO-19770-2:2015 372 tags. This extension mechanism can also be used to update the 373 CoSWID format as revisions to ISO-19770-2 are published. 375 The following CDDL sockets (extension points) are defined in this 376 document, which allow the addition of new information structures to 377 their respective CDDL groups. 379 +---------------------+-----------------------+---------------+ 380 | Map Name | CDDL Socket | Defined in | 381 +---------------------+-----------------------+---------------+ 382 | concise-swid-tag | $$coswid-extension | Section 2.2 | 383 | | | | 384 | entity-entry | $$entity-extension | Section 2.5 | 385 | | | | 386 | link-entry | $$link-extension | Section 2.6 | 387 | | | | 388 | software-meta-entry | $$meta-extension | Section 2.7 | 389 | | | | 390 | file-entry | $$file-extension | Section 2.8.2 | 391 | | | | 392 | directory-entry | $$directory-extension | Section 2.8.2 | 393 | | | | 394 | process-entry | $$process-extension | Section 2.8.2 | 395 | | | | 396 | resource-entry | $$resource-extension | Section 2.8.2 | 397 | | | | 398 | payload-entry | $$payload-extension | Section 2.8.3 | 399 | | | | 400 | evidence-entry | $$evidence-extension | Section 2.8.4 | 401 +---------------------+-----------------------+---------------+ 403 Table 1: CoSWID CDDL Group Extension Points 405 The CoSWID Items Registry defined in Section 5.1 provides a 406 registration mechanism allowing new items, and their associated index 407 values, to be added to the CoSWID model through the use of the CDDL 408 sockets described in the table above. This registration mechanism 409 provides for well-known index values for data items in CoSWID 410 extensions, allowing these index values to be recognized by 411 implementations supporting a given extension. 413 The following additional CDDL sockets are defined in this document to 414 allow for adding new values to corresponding type-choices (i.e. to 415 represent enumerations) via custom CDDL data definitions. 417 +------------------+-----------------+-------------+ 418 | Enumeration Name | CDDL Socket | Defined in | 419 +------------------+-----------------+-------------+ 420 | version-scheme | $version-scheme | Section 4.1 | 421 | | | | 422 | role | $role | Section 4.2 | 423 | | | | 424 | ownership | $ownership | Section 4.3 | 425 | | | | 426 | rel | $rel | Section 4.4 | 427 | | | | 428 | use | $use | Section 4.5 | 429 +------------------+-----------------+-------------+ 431 Table 2: CoSWID CDDL Enumeration Extension Points 433 A number of SWID/CoSWID value registries are also defined in 434 Section 5.2 that allow new values to be registered with IANA for the 435 enumerations above. This registration mechanism supports the 436 definition of new well-known index values and names for new 437 enumeration values used by both SWID and CoSWID. This registration 438 mechanism allows new standardized enumerated values to be shared 439 between both specifications (and implementations) over time, and 440 references to the IANA registries will be added to the next revision 441 of [SWID]. 443 2.2. The concise-swid-tag Group 445 The CDDL data definition for the root concise-swid-tag map is as 446 follows and this rule and its constraints MUST be followed when 447 creating or validating a CoSWID tag: 449 concise-swid-tag = { 450 global-attributes, 451 tag-id => text, 452 tag-version => integer, 453 ? corpus => bool, 454 ? patch => bool, 455 ? supplemental => bool, 456 software-name => text, 457 ? software-version => text, 458 ? version-scheme => $version-scheme, 459 ? media => text, 460 ? software-meta => software-meta-entry / [ 2* software-meta-entry ], 461 entity => entity-entry / [ 2* entity-entry ], 462 ? link => link-entry / [ 2* link-entry ], 463 ? (( payload => payload-entry ) // ( evidence => evidence-entry )), 464 * $$coswid-extension 465 } 467 tag-id = 0 468 software-name = 1 469 entity = 2 470 evidence = 3 471 link = 4 472 software-meta = 5 473 payload = 6 474 corpus = 8 475 patch = 9 476 media = 10 477 supplemental = 11 478 tag-version = 12 479 software-version = 13 480 version-scheme = 14 482 $version-scheme /= multipartnumeric 483 $version-scheme /= multipartnumeric-suffix 484 $version-scheme /= alphanumeric 485 $version-scheme /= decimal 486 $version-scheme /= semver 487 $version-scheme /= uint / text 488 multipartnumeric = 1 489 multipartnumeric-suffix = 2 490 alphanumeric = 3 491 decimal = 4 492 semver = 16384 494 The following describes each member of the concise-swid-tag root map. 496 o global-attributes: A list of items including an optional language 497 definition to support the processing of text-string values and an 498 unbounded set of any-attribute items. Described in Section 2.4. 500 o tag-id (index 0): A textual identifier uniquely referencing a 501 software component. The tag identifier MUST be globally unique. 502 There are no strict guidelines on how this identifier is 503 structured, but examples include a 16 byte GUID (e.g. class 4 504 UUID) [RFC4122], or a text string appended to a DNS domain name to 505 ensure uniqueness across organizations. 507 o tag-version (index 12): An integer value that indicate the 508 specific release revision of the tag. Typically, the initial 509 value of this field is set to 0 and the value is monotonically 510 increased for subsequent tags produced for the same software 511 component release. This value allows a CoSWID tag producer to 512 correct an incorrect tag previously released without indicating a 513 change to the underlying software component the tag represents. 514 For example, the tag version could be changed to add new metadata, 515 to correct a broken link, to add a missing payload entry, etc. 516 When producing a revised tag, the new tag-version value MUST be 517 greater than the old tag-version value. 519 o corpus (index 8): A boolean value that indicates if the tag 520 identifies and describes an installable software component in its 521 pre-installation state. Installable software includes a 522 installation package or installer for a software component, a 523 software update, or a patch. If the CoSWID tag represents 524 installable software, the corpus item MUST be set to "true". If 525 not provided, the default value MUST be considered "false". 527 o patch (index 9): A boolean value that indicates if the tag 528 identifies and describes an installed patch that has made 529 incremental changes to a software component installed on an 530 endpoint. Typically, an installed patch has made a set of file 531 modifications to pre-installed software and does not alter the 532 version number or the descriptive metadata of an installed 533 software component. If a CoSWID tag is for a patch, the patch 534 item MUST be set to "true". If not provided, the default value 535 MUST be considered "false". 537 Note: If the software component's version number is modified, then 538 the correct course of action would be to replace the previous 539 primary tag for the component with a new primary tag that 540 reflected this new version. In such a case, the new tag would 541 have a patch item value of "false" or would omit this item 542 completely. 544 o supplemental (index 11): A boolean value that indicates if the tag 545 is providing additional information to be associated with another 546 referenced SWID or CoSWID tag. This allows tools and users to 547 record their own metadata about a software component without 548 modifying SWID primary or patch tags created by a software 549 provider. If a CoSWID tag is a supplemental tag, the supplemental 550 item MUST be set to "true". If not provided, the default value 551 MUST be considered "false". 553 o software-name (index 1): This textual item provides the software 554 component's name. This name is likely the same name that would 555 appear in a package management tool. 557 o software-version (index 13): A textual value representing the 558 specific release or development version of the software component. 560 o version-scheme (index 14): An 8-bit integer or textual value 561 representing the versioning scheme used for the software-version 562 item. If an integer value is used it MUST be a value from the 563 SWID/CoSWID Version Scheme Value Registry (see section 564 Section 5.2.1 or a value in the private use range: 32768-65535. 566 An initial set of version-scheme index and text values are defined in 567 Section 4.1, and are based on the version-scheme values defined in 568 [SWID]. These pre-defined version-scheme values are registered with 569 IANA in the "SWID/CoSWID Version Scheme Value" registry 570 Section 5.2.1. The values in this registry will likely be expanded 571 in the future. 573 The value of an version-scheme item MUST be one of the following: 575 o The index (preferred) or string value of a role from the IANA in 576 the "SWID/CoSWID Version Scheme Value" registry. 578 o An index value in the range 32768 through 65535, to indicate that 579 a private use index value is used. 581 o A string value prefixed with "x_", to indicate that a private use 582 string value is used. 584 o media (index 10): This text value is a hint to the tag consumer to 585 understand what target platform this tag applies to. This item 586 represents a query as defined by the W3C Media Queries 587 Recommendation (see [W3C.REC-css3-mediaqueries-20120619]). 589 o software-meta (index 5): An open-ended map of key/value data 590 pairs. A number of predefined keys can be used within this item 591 providing for common usage and semantics across the industry. Use 592 of this map allows any additional attribute to be included in the 593 tag. It is expected that industry groups will use a common set of 594 attribute names to allow for interoperability within their 595 communities. Described in Section 2.7. 597 o entity (index 2): Provides information about one or more 598 organizations responsible for producing the CoSWID tag, and 599 producing or releasing the software component referenced by this 600 CoSWID tag. Described in Section 2.5. 602 o link (index 4): Provides a means to establish relationship arcs 603 between the tag and another items. A given link can be used to 604 establish the relationship between tags or to reference another 605 resource that is related to the CoSWID tag, e.g. vulnerability 606 database association, ROLIE feed [RFC8322], MUD resource 607 [RFC8520], software download location, etc). This is modeled 608 after the HTML "link" element. Described in Section 2.6. 610 o payload (index 6): This item represents a collection of software 611 artifacts (described by child items) that compose the target 612 software. For example, these artifacts could be the files 613 included with an installer for a corpus tag or installed on an 614 endpoint when the software component is installed for a primary or 615 patch tag. The artifacts listed in a payload may be a superset of 616 the software artifacts that are actually installed. Based on user 617 selections at install time, an installation might not include 618 every artifact that could be created or executed on the endpoint 619 when the software component is installed or run. Described in 620 Section 2.8.3. 622 o evidence-entry (index 3): This item can be used to record the 623 results of a software discovery process used to identify untagged 624 software on an endpoint or to represent indicators for why 625 software is believed to be installed on the endpoint. In either 626 case, a CoSWID tag can be created by the tool performing an 627 analysis of the software components installed on the endpoint. 628 Described in Section 2.8.4. 630 o $$coswid-extension: This CDDL socket is used to add new 631 information structures to the concise-swid-tag root map. See 632 Section 2.1. 634 2.3. concise-swid-tag Co-constraints 636 The following co-constraints apply to the information provided in the 637 concise-swid-tag group. 639 o The patch and supplemental items MUST NOT both be set to "true". 641 o If the patch item is set to "true", the tag SHOULD contain at 642 least one link item with both the rel(ation) item value of 643 "patches" and an href item specifying an association with the 644 software that was patched. 646 o If the supplemental item is set to "true", the tag SHOULD contain 647 at least one link item with both the rel(ation) item value of 648 "supplements" and an href item specifying an association with the 649 software that is supplemented. 651 o If all of the corpus, patch, and supplemental items are "false", 652 or if the corpus item is set to "true", then a software-version 653 item MUST be included with a value set to the version of the 654 software component. This ensures that primary and corpus tags 655 have an identifiable software version. 657 2.4. The global-attributes Group 659 The global-attributes group provides a list of items, including an 660 optional language definition to support the processing of text-string 661 values, and an unbounded set of any-attribute items allowing for 662 additional items to be provided as a general point of extension in 663 the model. 665 The CDDL for the global-attributes follows: 667 global-attributes = ( 668 ? lang, 669 * any-attribute, 670 ) 672 any-attribute = ( 673 label => text / int / [ 2* text ] / [ 2* int ] 674 ) 676 label = text / int 678 The following describes each child item of this group. 680 o lang (index 15): A textual language tag that conforms with IANA 681 "Language Subtag Registry" [RFC5646]. The context of the 682 specified language applies to all sibling and descendant textual 683 values, unless a descendant object has defined a different 684 language tag. Thus, a new context is established when a 685 descendant object redefines a new language tag. All textual 686 values within a given context MUST be considered expressed in the 687 specified language. 689 o any-attribute: This sub-group provides a means to include 690 arbitrary information via label ("key") value pairs. Labels can 691 be either a single integer or text string. Values can be a single 692 integer, a text string, or an array of integers or text strings. 694 2.5. The entity-entry Group 696 The CDDL for the entity-entry group follows: 698 entity-entry = { 699 global-attributes, 700 entity-name => text, 701 ? reg-id => any-uri, 702 role => $role / [ 2* $role ], 703 ? thumbprint => hash-entry, 704 * $$entity-extension, 705 } 706 entity-name = 31 707 reg-id = 32 708 role = 33 709 thumbprint = 34 711 $role /= tag-creator 712 $role /= software-creator 713 $role /= aggregator 714 $role /= distributor 715 $role /= licensor 716 $role /= uint / text 717 tag-creator=1 718 software-creator=2 719 aggregator=3 720 distributor=4 721 licensor=5 723 The following describes each child item of this group. 725 o global-attributes: The global-attributes group described in 726 Section 2.4. 728 o entity-name (index 32): The textual name of the organizational 729 entity claiming the roles specified by the role item for the 730 CoSWID tag. 732 o reg-id (index 32): The registration id value is intended to 733 uniquely identify a naming authority in a given scope (e.g. 734 global, organization, vendor, customer, administrative domain, 735 etc.) for the referenced entity. The value of an registration ID 736 MUST be a RFC 3986 URI. The scope SHOULD be the scope of an 737 organization. In a given scope, the registration id MUST be used 738 consistently for CoSWID tag production. 740 o role (index 33): The relationship(s) between the entity, and this 741 tag or the referenced software component. Use of index values 742 instead of text for these pre-defined roles allows a CoSWID to be 743 more concise. 745 An initial set of role index and text values are defined in 746 Section 4.2, and are based on the roles defined in [SWID]. These 747 pre-defined roles are registered with IANA in the "SWID/CoSWID 748 Entity Role Value" registry Section 5.2.2. The values in this 749 registry will likely be expanded in the future. 751 The value of a role item MUST be one of the following: 753 * The index (preferred) or string value of a role from the IANA 754 in the "SWID/CoSWID Entity Role Value" registry. 756 * An index value in the range 128 through 255, to indicate that a 757 private use index value is used. 759 * A string value prefixed with "x_", to indicate that a private 760 use string value is used. 762 The following additional requirements exist for the use of the 763 "role" item: 765 * An entity item MUST be provided with the role of "tag-creator" 766 for every CoSWID tag. This indicates the organization that 767 created the CoSWID tag. 769 * An entity item SHOULD be provided with the role of "software- 770 creator" for every CoSWID tag, if this information is known to 771 the tag creator. This indicates the organization that created 772 the referenced software component. 774 o thumbprint (index 34): The value of the thumbprint item provides 775 an integer-based hash algorithm identifier (hash-alg-id) and a 776 byte string value (hash-value) that contains the corresponding 777 hash value (i.e. the thumbprint) of the signing entity's public 778 key certificate. This provides an indicator of which entity 779 signed the CoSWID tag, which will typically be the tag creator. 780 If the hash-alg-id is not known, then the integer value "0" MUST 781 be used. This ensures parity between the SWID tag specification 782 [SWID], which does not allow an algorithm to be identified for 783 this field. See Section 2.8.1 for more details on the use of the 784 hash-entry data structure. 786 o $$entity-extension: This CDDL socket can be used to extend the 787 entity-entry group model. See Section 2.1. 789 2.6. The link-entry Map 791 The CDDL for the link-entry map follows: 793 link-entry = { 794 global-attributes, 795 ? artifact => text, 796 href => any-uri, 797 ? media => text, 798 ? ownership => $ownership, 799 rel => $rel, 800 ? media-type => text, 801 ? use => $use, 802 * $$link-extension, 803 } 804 media = 10 805 artifact = 37 806 href = 38 807 ownership = 39 808 rel = 40 809 media-type = 41 810 use = 42 812 $ownership /= shared 813 $ownership /= private 814 $ownership /= abandon 815 $ownership /= uint / text 816 shared=1 817 private=2 818 abandon=3 820 $rel /= ancestor 821 $rel /= component 822 $rel /= feature 823 $rel /= installationmedia 824 $rel /= packageinstaller 825 $rel /= parent 826 $rel /= patches 827 $rel /= requires 828 $rel /= see-also 829 $rel /= supersedes 830 $rel /= supplemental 831 $rel /= uint / text 832 ancestor=1 833 component=2 834 feature=3 835 installationmedia=4 836 packageinstaller=5 837 parent=6 838 patches=7 839 requires=8 840 see-also=9 841 supersedes=10 842 supplemental=11 844 $use /= optional 845 $use /= required 846 $use /= recommended 847 $use /= uint / text 848 optional=1 849 required=2 850 recommended=3 852 The following describes each member of this map. 854 o global-attributes: The global-attributes group described in 855 Section 2.4. 857 o artifact (index: 37): To be used with rel="installation-media", 858 this item's value provides the path to the installer executable or 859 script that can be run to launch the referenced installation. 860 Links with the same artifact name MUST be considered mirrors of 861 each other, allowing the installation media to be acquired from 862 any of the described sources. 864 o href (index 38): A URI for the referenced resource. The "href" 865 item's value can be, but is not limited to, the following (which 866 is a slightly modified excerpt from [SWID]): 868 * If no URI scheme is provided, then the URI is to be interpreted 869 as being relative to the URI of the CoSWID tag. For example, 870 "./folder/supplemental.coswid". 872 * a physical resource location with any acceptable URI scheme 873 (e.g., file:// http:// https:// ftp://) 875 * a URI with "swid:" as the scheme, which refers to another SWID 876 or CoSWID by tag-id. This URI would need to be resolved in the 877 context of the endpoint by software that can lookup other SWID 878 or CoSWID tags. For example, "swid:2df9de35-0aff- 879 4a86-ace6-f7dddd1ade4c" references the tag with the tag-id 880 value "2df9de35-0aff-4a86-ace6-f7dddd1ade4c". 882 * a URI with "swidpath:" as the scheme, which refers to another 883 CoSIWD via an XPATH query. This URI would need to be resolved 884 in the context of the system entity via software components 885 that can lookup other CoSWID tags and select the appropriate 886 tag based on an XPATH query [W3C.REC-xpath20-20101214]. 888 Examples include: 890 + swidpath://SoftwareIdentity[Entity/@regid='http://contoso.co 891 m'] would retrieve all SWID or CoSWID tags that include an 892 entity where the regid is "Contoso" 894 + swidpath://SoftwareIdentity[Meta/@persistentId='b0c55172-38e 895 9-4e36-be86-92206ad8eddb'] would match all SWID or CoSWID 896 tags with the persistent-id value 897 "b0c55172-38e9-4e36-be86-92206ad8eddb" 899 o media (index 10): A hint to the consumer of the link to what 900 target platform the link is applicable to. This item represents a 901 query as defined by the W3C Media Queries Recommendation (see 902 [W3C.REC-css3-mediaqueries-20120619]). See also media defined in 903 Section 2.2. 905 o ownership (index 39): Used when the "href" item references another 906 software component to indicate the degree of ownership between the 907 software component referenced by the COSWID tag and the software 908 component referenced by the link. 910 An initial set of ownership index and text values are defined in 911 Section 4.3, and are based on the ownership values defined in 912 [SWID]. These pre-defined ownership values are registered with 913 IANA in the "SWID/CoSWID Link Ownership Value" registry 914 Section 5.2.3. The values in this registry will likely be 915 expanded in the future. 917 The value of an ownership item MUST be one of the following: 919 * The index (preferred) or string value of a role from the IANA 920 in the "SWID/CoSWID Link Ownership Value" registry. 922 * An index value in the range 128 through 255, to indicate that a 923 private use index value is used. 925 * A string value prefixed with "x_", to indicate that a private 926 use string value is used. 928 o rel (index 40): Identifies the relationship between this CoSWID 929 and the target resource indicated by the "href" item. 931 An initial set of rel index and text values are defined in 932 Section 4.4, and are based on the rel values defined in [SWID]. 933 These pre-defined rel values are registered with IANA in the 934 "SWID/CoSWID Link Relationship Value" registry Section 5.2.4. The 935 values in this registry will likely be expanded in the future. 937 The value of a rel item MUST be one of the following: 939 * The index (preferred) or string value of a role from the IANA 940 in the "SWID/CoSWID Link Relationship Value" registry. 942 * An index value in the range 128 through 255, to indicate that a 943 private use index value is used. 945 * A string value prefixed with "x_", to indicate that a private 946 use string value is used. 948 * A string value, as defined by [RFC8288], corresponding to a 949 "Relation Name" from the IANA "Link Relation Types" registry: 950 https://www.iana.org/assignments/link-relations/link- 951 relations.xhtml. When a string value defined in the IANA 952 "SWID/CoSWID Link Relationship Value" registry matches a 953 Relation Name defined in the IANA "Link Relation Types" 954 registry, the value in the IANA "SWID/CoSWID Link Relationship 955 Value" registry MUST be used instead, as this relationship has 956 a specialized meaning in the context of a SWID/CoSWID tag. 958 o media-type (index 41): A link can point to arbitrary resources on 959 the endpoint, local network, or Internet using the href item. Use 960 of this item supplies the resource consumer with a hint of what 961 type of resource to expect. Media types are identified by 962 referencing a "Name" from the IANA "Media Types" registry: 963 http://www.iana.org/assignments/media-types/media-types.xhtml. 965 o use (index 42): Determines if the referenced software component 966 has to be installed before installing the software component 967 identified by the tag. 969 An initial set of use index and text values are defined in 970 Section 4.5, and are based on the use values defined in [SWID]. 971 These pre-defined use values are registered with IANA in the 972 "SWID/CoSWID Link Use Value" registry Section 5.2.5. The values 973 in this registry will likely be expanded in the future. 975 The value of an ownership item MUST be one of the following: 977 * The index (preferred) or string value of a role from the IANA 978 in the "SWID/CoSWID Link Use Value" registry. 980 * An index value in the range 128 through 255, to indicate that a 981 private use index value is used. 983 * A string value prefixed with "x_", to indicate that a private 984 use string value is used. 986 o $$link-extension: This CDDL socket can be used to extend the link- 987 entry map model. See Section 2.1. 989 2.7. The software-meta-entry Map 991 The CDDL for the software-meta-entry map follows: 993 software-meta-entry = { 994 global-attributes, 995 ? activation-status => text, 996 ? channel-type => text, 997 ? colloquial-version => text, 998 ? description => text, 999 ? edition => text, 1000 ? entitlement-data-required => bool, 1001 ? entitlement-key => text, 1002 ? generator => text, 1003 ? persistent-id => text, 1004 ? product => text, 1005 ? product-family => text, 1006 ? revision => text, 1007 ? summary => text, 1008 ? unspsc-code => text, 1009 ? unspsc-version => text, 1010 * $$meta-extension, 1011 } 1012 activation-status = 43 1013 channel-type = 44 1014 colloquial-version = 45 1015 description = 46 1016 edition = 47 1017 entitlement-data-required = 48 1018 entitlement-key = 49 1019 generator = 50 1020 persistent-id = 51 1021 product = 52 1022 product-family = 53 1023 revision = 54 1024 summary = 55 1025 unspsc-code = 56 1026 unspsc-version = 57 1027 The following describes each child item of this group. 1029 o global-attributes: The global-attributes group described in 1030 Section 2.4. 1032 o activation-status (index 43): A textual value that identifies how 1033 the software component has been activated, which might relate to 1034 specific terms and conditions for its use (e.g. Trial, 1035 Serialized, Licensed, Unlicensed, etc) and relate to an 1036 entitlement. This attribute is typically used in supplemental 1037 tags as it contains information that might be selected during a 1038 specific install. 1040 o channel-type (index 44): A textual value that identfies which 1041 sales, licensing, or marketing channel the software component has 1042 been targeted for (e.g. Volume, Retail, OEM, Academic, etc). 1043 This attribute is typically used in supplemental tags as it 1044 contains information that might be selected during a specific 1045 install. 1047 o colloquial-version (index 45): A textual value for the software 1048 component's informal or colloquial version. Examples may include 1049 a year value, a major version number, or similar value that are 1050 used to identify a group of specific software component releases 1051 that are part of the same release/support cycle. This version can 1052 be the same through multiple releases of a software component, 1053 while the software-version specified in the concise-swid-tag group 1054 is much more specific and will change for each software component 1055 release. This version is intended to be used for string 1056 comparison only and is not intended to be used to determine if a 1057 specific value is earlier or later in a sequence. 1059 o description (index 46): A textual value that provides a detailed 1060 description of the software component. This value MAY be multiple 1061 sentences. 1063 o edition (index 47): A textual value indicating that the software 1064 component represents a functional variation of the code base used 1065 to support multiple software components. For examplem, this item 1066 can be used to differentiate enterprise, standard, or professional 1067 variants of a software component. 1069 o entitlement-data-required (index 48): A boolean value that can be 1070 used to determine if accompanying proof of entitlement is needed 1071 when a software license reconciliation process is performed. 1073 o entitlement-key (index 49): A vendor-specific textual key that can 1074 be used to identify and establish a relationship to an 1075 entitlement. Examples of an entitlement-key might include a 1076 serial number, product key, or license key. For values that 1077 relate to a given software component install (i.e., license key), 1078 a supplemental tag will typically contain this information. In 1079 other cases, where a general-purpose key can be provided that 1080 applies to all possible installs of the software component on 1081 different endpoints, a primary tag will typically contain this 1082 information. 1084 o generator (index 50): The name (or tag-id) of the software 1085 component that created the CoSWID tag. If the generating software 1086 component has a SWID or CoSWID tag, then the tag-id for the 1087 generating software component SHOULD be provided. 1089 o persistent-id (index 51): A globally unique identifier used to 1090 identify a set of software components that are related. Software 1091 components sharing the same persistent-id can be different 1092 versions. This item can be used to relate software components, 1093 released at different points in time or through different release 1094 channels, that may not be able to be related through use of the 1095 link item. 1097 o product (index 52): A basic name for the software component that 1098 can be common across multiple tagged software components (e.g., 1099 Apache HTTPD). 1101 o product-family (index 53): A textual value indicating the software 1102 components overall product family. This should be used when 1103 multiple related software components form a larger capability that 1104 is installed on multiple different endpoints. For example, some 1105 software families may consist of server, client, and shared 1106 service components that are part of a larger capability. Email 1107 systems, enterprise applications, backup services, web 1108 conferencing, and similar capabilities are examples of families. 1109 Use of this item is not intended to represent groups of software 1110 that are bundled or installed together. The persistent-id or link 1111 items SHOULD be used to relate bundled software components. 1113 o revision (index 54): A string value indicating an informal or 1114 colloquial release version of the software. This value can 1115 provide a different version value as compared to the software- 1116 version specified in the concise-swid-tag group. This is useful 1117 when one or more releases need to have an informal version label 1118 that differs from the specific exact version value specified by 1119 software-version. Examples can include SP1, RC1, Beta, etc. 1121 o summary (index 55): A short description of the software component. 1122 This MUST be a single sentence suitable for display in a user 1123 interface. 1125 o unspsc-code (index 56): An 8 digit UNSPSC classification code for 1126 the software component. For more information see, 1127 http://www.unspsc.org/. 1129 o unspsc-version (index 57): The version of UNSPSC used to define 1130 the unspsc-code value. 1132 o $$meta-extension: This CDDL socket can be used to extend the 1133 software-meta-entry group model. See Section 2.1. 1135 2.8. The Resource Collection Definition 1137 2.8.1. The hash-entry Array 1139 CoSWID adds explicit support for the representation of hash entries 1140 using algorithms that are registered in the IANA "Named Information 1141 Hash Algorithm Registry" using the hash-entry member (label 58). 1143 hash-entry = [ hash-alg-id: int, hash-value: bytes ] 1145 The number used as a value for hash-alg-id MUST refer an ID in the 1146 "Named Information Hash Algorithm Registry" (see 1147 https://www.iana.org/assignments/named-information/named- 1148 information.xhtml); other hash algorithms MUST NOT be used. The 1149 hash-value MUST represent the raw hash value of the hashed resource 1150 generated using the hash algorithm indicated by the hash-alg-id. 1152 2.8.2. The resource-collection Group 1154 A list of items both used in evidence (created by a software 1155 discovery process) and payload (installed in an endpoint) content of 1156 a CoSWID tag document to structure and differentiate the content of 1157 specific CoSWID tag types. Potential content includes directories, 1158 files, processes, or resources. 1160 The CDDL for the resource-collection group follows: 1162 resource-collection = ( 1163 ? directory => directory-entry, 1164 ? file => file-entry, 1165 ? process => process-entry, 1166 ? resource => resource-entry, 1167 ) 1168 filesystem-item = ( 1169 global-attributes, 1170 ? key => bool, 1171 ? location => text, 1172 fs-name => text, 1173 ? root => text, 1174 ) 1176 path-elements-entry = [ [ * file-entry ], 1177 [ * directory-entry ], 1178 ] 1180 file-entry = { 1181 filesystem-item, 1182 ? size => integer, 1183 ? file-version => text, 1184 ? hash => hash-entry, 1185 * $$file-extension 1186 } 1188 directory-entry = { 1189 filesystem-item, 1190 path-elements => path-elements-entry, 1191 * $$directory-extension 1192 } 1194 process-entry = { 1195 global-attributes, 1196 process-name => text, 1197 ? pid => integer, 1198 * $$process-extension 1199 } 1201 resource-entry = { 1202 global-attributes, 1203 type => text, 1204 * $$resource-extension 1205 } 1207 directory = 16 1208 file = 17 1209 process = 18 1210 resource = 19 1211 size = 20 1212 file-version = 21 1213 key = 22 1214 location = 23 1215 fs-name = 24 1216 root = 25 1217 path-elements = 26 1218 process-name = 27 1219 pid = 28 1220 type = 29 1222 The following describes each member of the groups and maps 1223 illustrated above. 1225 o filesystem-item: A list of common items used for representing the 1226 filesystem root, relative location, name, and significance of a 1227 file or directory item. 1229 o global-attributes: The global-attributes group described in 1230 Section 2.4. 1232 o directory (index 16): A directory item allows child directory and 1233 file items to be defined within a directory hierarchy for the 1234 software component. 1236 o file (index 17): A file item allows details about a file to be 1237 provided for the software component. 1239 o process (index 18): A process item allows details to be provided 1240 about the runtime behavior of the software component, such as 1241 information that will appear in a process listing on an endpoint. 1243 o resource (index 19): A resource item can be used to provide 1244 details about an artifact or capability expected to be found on an 1245 endpoint or evidence collected related to the software component. 1246 This can be used to represent concepts not addressed directly by 1247 the directory, file, or process items. Examples include: registry 1248 keys, bound ports, etc. The equivalent construct in [SWID] is 1249 currently under specified. As a result, this item might be 1250 further defined through extension in the future. 1252 o size (index 20): The file's size in bytes. 1254 o file-version (index 21): The file's version as reported by 1255 querying information on the file from the operating system. 1257 o key (index 22): A boolean value indicating if a file or directory 1258 is significant or required for the software component to execute 1259 or function properly. These are files or directories that can be 1260 used to affirmatively determine if the software component is 1261 installed on an endpoint. 1263 o location (index 23): The filesystem path where a file is expected 1264 to be located when installed or copied. The location MUST be 1265 either relative to the location of the parent directory item 1266 (preferred) or relative to the location of the CoSWID tag if no 1267 parent is defined. The location MUST NOT include a file's name, 1268 which is provided by the fs-name item. 1270 o fs-name (index 24): The name of the directory or file without any 1271 path information. 1273 o root (index 25): A filesystem-specific name for the root of the 1274 filesystem. The location item is considered relative to this 1275 location if specified. If not provided, the value provided by the 1276 location item is expected to be relative to its parent or the 1277 location of the CoSWID tag if no parent is provided. 1279 o path-elements (index 26): This group allows a heirarchy of 1280 directory and file items to be defined in payload or evidence 1281 items. 1283 o process-name (index 27): The software component's process name as 1284 it will appear in an endpoint's process list. 1286 o pid (index 28): The process ID identified for a running instance 1287 of the software component in the endpoint's process list. This is 1288 used as part of the evidence item. 1290 o type (index 29): A string indicating the type of resource. 1292 o $$resource-collection-extension: This CDDL socket can be used to 1293 extend the resource-collection group model. This can be used to 1294 add new specialized types of resources. See Section 2.1. 1296 o $$file-extension: This CDDL socket can be used to extend the file- 1297 entry group model. See Section 2.1. 1299 o $$directory-extension: This CDDL socket can be used to extend the 1300 directory-entry group model. See Section 2.1. 1302 o $$process-extension: This CDDL socket can be used to extend the 1303 process-entry group model. See Section 2.1. 1305 o $$resource-extension: This CDDL socket can be used to extend the 1306 group model. See Section 2.1. 1308 o $$-extension: This CDDL socket can be used to extend the resource- 1309 entry group model. See Section 2.1. 1311 2.8.3. The payload-entry Group 1313 The CDDL for the payload-entry group follows: 1315 payload-entry = { 1316 global-attributes, 1317 resource-collection, 1318 * $$payload-extension 1319 } 1321 The following describes each child item of this group. 1323 o global-attributes: The global-attributes group described in 1324 Section 2.4. 1326 o resource-collection: The resource-collection group described in 1327 Section 2.8.2. 1329 o $$payload-extension: This CDDL socket can be used to extend the 1330 payload-entry group model. See Section 2.1. 1332 2.8.4. The evidence-entry Group 1334 The CDDL for the evidence-entry group follows: 1336 evidence-entry = { 1337 global-attributes, 1338 resource-collection, 1339 ? date => time, 1340 ? device-id => text, 1341 * $$evidence-extension 1342 } 1343 date = 35 1344 device-id = 36 1346 The following describes each child item of this group. 1348 o global-attributes: The global-attributes group described in 1349 Section 2.4. 1351 o resource-collection: The resource-collection group described in 1352 Section 2.8.2. 1354 o date (index 35): The date and time the information was collected 1355 pertaining to the evidence item. 1357 o device-id (index 36): The endpoint's string identifier from which 1358 the evidence was collected. 1360 o $$evidence-extension: This CDDL socket can be used to extend the 1361 evidence-entry group model. See Section 2.1. 1363 2.9. Full CDDL Definition 1365 In order to create a valid CoSWID document the structure of the 1366 corresponding CBOR message MUST adhere to the following CDDL data 1367 definition. 1369 concise-swid-tag = { 1370 global-attributes, 1371 tag-id => text, 1372 tag-version => integer, 1373 ? corpus => bool, 1374 ? patch => bool, 1375 ? supplemental => bool, 1376 software-name => text, 1377 ? software-version => text, 1378 ? version-scheme => $version-scheme, 1379 ? media => text, 1380 ? software-meta => software-meta-entry / [ 2* software-meta-entry ], 1381 entity => entity-entry / [ 2* entity-entry ], 1382 ? link => link-entry / [ 2* link-entry ], 1383 ? (( payload => payload-entry ) // ( evidence => evidence-entry )), 1384 * $$coswid-extension 1385 } 1387 any-uri = text 1388 label = text / int 1390 $version-scheme /= multipartnumeric 1391 $version-scheme /= multipartnumeric-suffix 1392 $version-scheme /= alphanumeric 1393 $version-scheme /= decimal 1394 $version-scheme /= semver 1395 $version-scheme /= uint / text 1397 any-attribute = ( 1398 label => text / int / [ 2* text ] / [ 2* int ] 1399 ) 1401 global-attributes = ( 1402 ? lang => text, 1403 * any-attribute, 1404 ) 1406 hash-entry = [ hash-alg-id: int, 1407 hash-value: bytes ] 1409 entity-entry = { 1410 global-attributes, 1411 entity-name => text, 1412 ? reg-id => any-uri, 1413 role => $role / [ 2* $role ], 1414 ? thumbprint => hash-entry, 1415 * $$entity-extension, 1416 } 1418 $role /= tag-creator 1419 $role /= software-creator 1420 $role /= aggregator 1421 $role /= distributor 1422 $role /= licensor 1423 $role /= uint / text 1425 link-entry = { 1426 global-attributes, 1427 ? artifact => text, 1428 href => any-uri, 1429 ? media => text, 1430 ? ownership => $ownership, 1431 rel => $rel, 1432 ? media-type => text, 1433 ? use => $use, 1434 * $$link-extension 1435 } 1437 $ownership /= shared 1438 $ownership /= private 1439 $ownership /= abandon 1440 $ownership /= uint / text 1442 $rel /= ancestor 1443 $rel /= component 1444 $rel /= feature 1445 $rel /= installationmedia 1446 $rel /= packageinstaller 1447 $rel /= parent 1448 $rel /= patches 1449 $rel /= requires 1450 $rel /= see-also 1451 $rel /= supersedes 1452 $rel /= supplemental 1453 $rel /= uint / text 1455 $use /= optional 1456 $use /= required 1457 $use /= recommended 1458 $use /= uint / text 1460 software-meta-entry = { 1461 global-attributes, 1462 ? activation-status => text, 1463 ? channel-type => text, 1464 ? colloquial-version => text, 1465 ? description => text, 1466 ? edition => text, 1467 ? entitlement-data-required => bool, 1468 ? entitlement-key => text, 1469 ? generator => text, 1470 ? persistent-id => text, 1471 ? product => text, 1472 ? product-family => text, 1473 ? revision => text, 1474 ? summary => text, 1475 ? unspsc-code => text, 1476 ? unspsc-version => text, 1477 * $$meta-extension, 1478 } 1480 resource-collection = ( 1481 ? directory => directory-entry, 1482 ? file => file-entry, 1483 ? process => process-entry, 1484 ? resource => resource-entry, 1485 * $$resource-collection-extension 1486 ) 1488 file-entry = { 1489 filesystem-item, 1490 ? size => integer, 1491 ? file-version => text, 1492 ? hash => hash-entry, 1493 * $$file-extension 1494 } 1496 path-elements-entry = [ [ * file-entry ], 1497 [ * directory-entry ], 1498 ] 1500 directory-entry = { 1501 filesystem-item, 1502 path-elements => path-elements-entry, 1503 * $$directory-extension 1504 } 1505 process-entry = { 1506 global-attributes, 1507 process-name => text, 1508 ? pid => integer, 1509 * $$process-extension 1510 } 1512 resource-entry = { 1513 global-attributes, 1514 type => text, 1515 * $$resource-extension 1516 } 1518 filesystem-item = ( 1519 global-attributes, 1520 ? key => bool, 1521 ? location => text, 1522 fs-name => text, 1523 ? root => text, 1524 ) 1526 payload-entry = { 1527 global-attributes, 1528 resource-collection, 1529 * $$payload-extension 1530 } 1532 evidence-entry = { 1533 global-attributes, 1534 resource-collection, 1535 ? date => time, 1536 ? device-id => text, 1537 * $$evidence-extension 1538 } 1540 ; "global map member" integer indexes 1541 tag-id = 0 1542 software-name = 1 1543 entity = 2 1544 evidence = 3 1545 link = 4 1546 software-meta = 5 1547 payload = 6 1548 hash = 7 1549 corpus = 8 1550 patch = 9 1551 media = 10 1552 supplemental = 11 1553 tag-version = 12 1554 software-version = 13 1555 version-scheme = 14 1556 lang = 15 1557 directory = 16 1558 file = 17 1559 process = 18 1560 resource = 19 1561 size = 20 1562 file-version = 21 1563 key = 22 1564 location = 23 1565 fs-name = 24 1566 root = 25 1567 path-elements = 26 1568 process-name = 27 1569 pid = 28 1570 type = 29 1571 entity-name = 31 1572 reg-id = 32 1573 role = 33 1574 thumbprint = 34 1575 date = 35 1576 device-id = 36 1577 artifact = 37 1578 href = 38 1579 ownership = 39 1580 rel = 40 1581 media-type = 41 1582 use = 42 1583 activation-status = 43 1584 channel-type = 44 1585 colloquial-version = 45 1586 description = 46 1587 edition = 47 1588 entitlement-data-required = 48 1589 entitlement-key = 49 1590 generator = 50 1591 persistent-id = 51 1592 product = 52 1593 product-family = 53 1594 revision = 54 1595 summary = 55 1596 unspsc-code = 56 1597 unspsc-version = 57 1599 ; "version-scheme" integer indexes 1600 multipartnumeric = 1 1601 multipartnumeric-suffix = 2 1602 alphanumeric = 3 1603 decimal = 4 1604 semver = 16384 1606 ; "role" integer indexes 1607 tag-creator=1 1608 software-creator=2 1609 aggregator=3 1610 distributor=4 1611 licensor=5 1613 ; ownership integer indexes 1614 shared=1 1615 private=2 1616 abandon=3 1618 ; "rel" integer indexes 1619 ancestor=1 1620 component=2 1621 feature=3 1622 installationmedia=4 1623 packageinstaller=5 1624 parent=6 1625 patches=7 1626 requires=8 1627 see-also=9 1628 supersedes=10 1629 supplemental=11 1631 ; "use" integer indexes 1632 optional=1 1633 required=2 1634 recommended=3 1636 3. Determining the Type of CoSWID 1638 The operational model for SWID and CoSWID tags was introduced in 1639 Section 1.1, which described four different CoSWID tag types. The 1640 following additional rules apply to the use of CoSWID tags to ensure 1641 that created tags properly identify the tag type. 1643 The first matching rule MUST determine the type of the CoSWID tag. 1645 1. Primary Tag: A CoSWID tag MUST be considered a primary tag if the 1646 corpus, patch, and supplemental items are "false". 1648 2. Supplemental Tag: A CoSWID tag MUST be considered a supplemental 1649 tag if the supplemental item is set to "true". 1651 3. Corpus Tag: A CoSWID tag MUST be considered a corpus tag if the 1652 corpus item is "true". 1654 4. Patch Tag: A CoSWID tag MUST be considered a patch tag if the 1655 patch item is "true". 1657 Note: Multiple of the corpus, patch, and supplemental items can have 1658 values set as "true". The rules above provide a means to determine 1659 the tag's type in such a case. For example, a SWID or CoSWID tag for 1660 a patch installer might have both corpus and patch items set to 1661 "true". In such a case, the tag is a "Corpus Tag". The tag 1662 installed by this installer would have only the patch item set to 1663 "true", making the installed tag type a "Patch Tag". 1665 4. CoSWID Indexed Label Values 1667 4.1. Version Scheme 1669 The following table contains a set of values for use in the concise- 1670 swid-tag group's version-scheme item. These values match the version 1671 schemes defined in the ISO/IEC 19770-2:2015 [SWID] specification. 1672 Index value indicates the value to use as the version-scheme item's 1673 value. The Version Scheme Name provides human-readable text for the 1674 value. The Definition describes the syntax of allowed values for 1675 each entry. 1677 +-------+-------------------------+---------------------------------+ 1678 | Index | Version Scheme Name | Definition | 1679 +-------+-------------------------+---------------------------------+ 1680 | 1 | multipartnumeric | Numbers separated by dots, | 1681 | | | where the numbers are | 1682 | | | interpreted as integers | 1683 | | | (e.g.,1.2.3, 1.4.5, | 1684 | | | 1.2.3.4.5.6.7) | 1685 | | | | 1686 | 2 | multipartnumeric+suffix | Numbers separated by dots, | 1687 | | | where the numbers are | 1688 | | | interpreted as integers with an | 1689 | | | additional textual suffix | 1690 | | | (e.g., 1.2.3a) | 1691 | | | | 1692 | 3 | alphanumeric | Strictly a string, sorting is | 1693 | | | done alphanumerically | 1694 | | | | 1695 | 4 | decimal | A floating point number (e.g., | 1696 | | | 1.25 is less than 1.3) | 1697 | | | | 1698 | 16384 | semver | Follows the [SEMVER] | 1699 | | | specification | 1700 +-------+-------------------------+---------------------------------+ 1702 Table 3: Version Scheme Values 1704 The values above are registered in the IANA "SWID/CoSWID Version 1705 Scheme Value" registry defined in section Section 5.2.1. Additional 1706 values will likely be registered over time in this registry. 1707 Additionally, the index values 32768 through 65535 and the name 1708 prefix "x_" have been reserved for private use. 1710 4.2. Entity Role Values 1712 The following table indicates the index value to use for the entity- 1713 entry group's role item (see Section 2.5). These values match the 1714 entity roles defined in the ISO/IEC 19770-2:2015 [SWID] 1715 specification. The "Index" value indicates the value to use as the 1716 role item's value. The "Role Name" provides human-readable text for 1717 the value. The "Definition" describes the semantic meaning of each 1718 entry. 1720 +-------+-----------------+-----------------------------------------+ 1721 | Index | Role Name | Definition | 1722 +-------+-----------------+-----------------------------------------+ 1723 | 1 | tagCreator | The person or organization that created | 1724 | | | the containing SWID or CoSWID tag | 1725 | | | | 1726 | 2 | softwareCreator | The person or organization entity that | 1727 | | | created the software component. | 1728 | | | | 1729 | 3 | aggregator | From [SWID], "An organization or system | 1730 | | | that encapsulates software from their | 1731 | | | own and/or other organizations into a | 1732 | | | different distribution process (as in | 1733 | | | the case of virtualization), or as a | 1734 | | | completed system to accomplish a | 1735 | | | specific task (as in the case of a | 1736 | | | value added reseller)." | 1737 | | | | 1738 | 4 | distributor | From [SWID], "An entity that furthers | 1739 | | | the marketing, selling and/or | 1740 | | | distribution of software from the | 1741 | | | original place of manufacture to the | 1742 | | | ultimate user without modifying the | 1743 | | | software, its packaging or its | 1744 | | | labelling." | 1745 | | | | 1746 | 5 | licensor | From [SAM] as "software licensor", a | 1747 | | | "person or organization who owns or | 1748 | | | holds the rights to issue a software | 1749 | | | license for a specific software | 1750 | | | [component]" | 1751 +-------+-----------------+-----------------------------------------+ 1753 Table 4: Entity Role Values 1755 The values above are registered in the IANA "SWID/CoSWID Entity Role 1756 Value" registry defined in section Section 5.2.2. Additional values 1757 will likely be registered over time. Additionally, the index values 1758 128 through 255 and the name prefix "x_" have been reserved for 1759 private use. 1761 4.3. Link Ownership Values 1763 The following table indicates the index value to use for the link- 1764 entry group's ownership item (see Section 2.6). These values match 1765 the link ownership values defined in the ISO/IEC 19770-2:2015 [SWID] 1766 specification. The "Index" value indicates the value to use as the 1767 link-entry group ownership item's value. The "Ownership Type" 1768 provides human-readable text for the value. The "Definition" 1769 describes the semantic meaning of each entry. 1771 +-------+-----------+-----------------------------------------------+ 1772 | Index | Ownership | Definition | 1773 | | Type | | 1774 +-------+-----------+-----------------------------------------------+ 1775 | 1 | abandon | If the software component referenced by the | 1776 | | | CoSWID tag is uninstalled, then the | 1777 | | | referenced software SHOULD not be uninstalled | 1778 | | | | 1779 | 2 | private | If the software component referenced by the | 1780 | | | CoSWID tag is uninstalled, then the | 1781 | | | referenced software SHOULD be uninstalled as | 1782 | | | well. | 1783 | | | | 1784 | 3 | shared | If the software component referenced by the | 1785 | | | CoSWID tag is uninstalled, then the | 1786 | | | referenced software SHOULD be uninstalled if | 1787 | | | no other components sharing the software. | 1788 +-------+-----------+-----------------------------------------------+ 1790 Table 5: Link Ownership Values 1792 The values above are registered in the IANA "SWID/CoSWID Link 1793 Ownership Value" registry defined in section Section 5.2.3. 1794 Additional values will likely be registered over time. Additionally, 1795 the index values 128 through 255 and the name prefix "x_" have been 1796 reserved for private use. 1798 4.4. Link Rel Values 1800 The following table indicates the index value to use for the link- 1801 entry group's rel item (see Section 2.6). These values match the 1802 link rel values defined in the ISO/IEC 19770-2:2015 [SWID] 1803 specification. The "Index" value indicates the value to use as the 1804 link-entry group ownership item's value. The "Relationship Type" 1805 provides human-readable text for the value. The "Definition" 1806 describes the semantic meaning of each entry. 1808 +-------+-------------------+---------------------------------------+ 1809 | Index | Relationship Type | Definition | 1810 +-------+-------------------+---------------------------------------+ 1811 | 1 | ancestor | The link references a SWID/CoSWID tag | 1812 | | | for a previous release of this | 1813 | | | software. This can be useful to | 1814 | | | define an upgrade path. | 1815 | | | | 1816 | 2 | component | The link references a SWID/CoSWID tag | 1817 | | | for a separate component of this | 1818 | | | software. | 1819 | | | | 1820 | 3 | feature | The link references a configurable | 1821 | | | feature of this software that can be | 1822 | | | enabled or disabled without changing | 1823 | | | the installed files. | 1824 | | | | 1825 | 4 | installationmedia | The link references the installation | 1826 | | | package that can be used to install | 1827 | | | this software. | 1828 | | | | 1829 | 5 | packageinstaller | The link references the installation | 1830 | | | software needed to install this | 1831 | | | software. | 1832 | | | | 1833 | 6 | parent | The link references a SWID/CoSWID tag | 1834 | | | that is the parent of this | 1835 | | | SWID/CoSWID tag. This relationship | 1836 | | | can be used when multiple software | 1837 | | | components are part of a software | 1838 | | | bundle, where the "parent" is the | 1839 | | | SWID/CoSWID tag for the bundle, and | 1840 | | | each child is a "component". In such | 1841 | | | a case, each child component can | 1842 | | | provide a "parent" link relationship | 1843 | | | to the bundle's SWID/CoSWID tag, and | 1844 | | | the bundle can provide a "component" | 1845 | | | link relationship to each child | 1846 | | | software component. | 1847 | | | | 1848 | 7 | patches | The link references a SWID/CoSWID tag | 1849 | | | that this software patches. Typically | 1850 | | | only used for patch SWID/CoSWID tags | 1851 | | | (see Section 1.1). | 1852 | | | | 1853 | 8 | requires | The link references a prerequisite | 1854 | | | for installing this software. A patch | 1855 | | | SWID/CoSWID tag (see Section 1.1) can | 1856 | | | use this to represent base software | 1857 | | | or another patch that needs to be | 1858 | | | installed first. | 1859 | | | | 1860 | 9 | see-also | The link references other software | 1861 | | | that may be of interest that relates | 1862 | | | to this software. | 1863 | | | | 1864 | 10 | supersedes | The link references another software | 1865 | | | that this software replaces. A patch | 1866 | | | SWID/CoSWID tag (see Section 1.1) can | 1867 | | | use this to represent another patch | 1868 | | | that this patch incorporates or | 1869 | | | replaces. | 1870 | | | | 1871 | 11 | supplemental | The link references a SWID/CoSWID tag | 1872 | | | that this tag supplements. Used on | 1873 | | | supplemental SWID/CoSWID tags (see | 1874 | | | Section 1.1). | 1875 +-------+-------------------+---------------------------------------+ 1877 Table 6: Link Relationship Values 1879 The values above are registered in the IANA "SWID/CoSWID Link 1880 Relationship Value" registry defined in section Section 5.2.4. 1881 Additional values will likely be registered over time. Additionally, 1882 the index values 32768 through 65535 and the name prefix "x_" have 1883 been reserved for private use. 1885 4.5. Link Use Values 1887 The following table indicates the index value to use for the link- 1888 entry group's use item (see Section 2.6). These values match the 1889 link use values defined in the ISO/IEC 19770-2:2015 [SWID] 1890 specification. The "Index" value indicates the value to use as the 1891 link-entry group use item's value. The "Use Type" provides human- 1892 readable text for the value. The "Definition" describes the semantic 1893 meaning of each entry. 1895 +-------+-------------+---------------------------------------------+ 1896 | Index | Use Type | Definition | 1897 +-------+-------------+---------------------------------------------+ 1898 | 1 | optional | From [SWID], "Not absolutely required; the | 1899 | | | [Link]'d software is installed only when | 1900 | | | specified." | 1901 | | | | 1902 | 2 | required | From [SWID], "The [Link]'d software is | 1903 | | | absolutely required for an operation | 1904 | | | software installation." | 1905 | | | | 1906 | 3 | recommended | From [SWID], "Not absolutely required; the | 1907 | | | [Link]'d software is installed unless | 1908 | | | specified otherwise." | 1909 +-------+-------------+---------------------------------------------+ 1911 Table 7: Link Use Values 1913 The values above are registered in the IANA "SWID/CoSWID Link Use 1914 Value" registry defined in section Section 5.2.5. Additional values 1915 will likely be registered over time. Additionally, the index values 1916 128 through 255 and the name prefix "x_" have been reserved for 1917 private use. 1919 5. IANA Considerations 1921 This document has a number of IANA considerations, as described in 1922 the following subsections. 1924 5.1. CoSWID Items Registry 1926 This document uses integer values as index values in CBOR maps. 1928 This document defines a new a new registry titled "CoSWID Items". 1929 Future registrations for this registry are to be made based on 1930 [RFC8126] as follows: 1932 +------------------+-------------------------+ 1933 | Range | Registration Procedures | 1934 +------------------+-------------------------+ 1935 | 0-32767 | Standards Action | 1936 | | | 1937 | 32768-4294967295 | Specification Required | 1938 +------------------+-------------------------+ 1940 Table 8: CoSWID Items Registration Proceedures 1942 All negative values are reserved for Private Use. 1944 Initial registrations for the "CoSWID Items" registry are provided 1945 below. Assignments consist of an integer index value, the item name, 1946 and a reference to the defining specification. 1948 +---------------+---------------------------+---------------+ 1949 | Index | Item Name | Specification | 1950 +---------------+---------------------------+---------------+ 1951 | 0 | tag-id | RFC-AAAA | 1952 | | | | 1953 | 1 | software-name | RFC-AAAA | 1954 | | | | 1955 | 2 | entity | RFC-AAAA | 1956 | | | | 1957 | 3 | evidence | RFC-AAAA | 1958 | | | | 1959 | 4 | link | RFC-AAAA | 1960 | | | | 1961 | 5 | software-meta | RFC-AAAA | 1962 | | | | 1963 | 6 | payload | RFC-AAAA | 1964 | | | | 1965 | 7 | hash | RFC-AAAA | 1966 | | | | 1967 | 8 | corpus | RFC-AAAA | 1968 | | | | 1969 | 9 | patch | RFC-AAAA | 1970 | | | | 1971 | 10 | media | RFC-AAAA | 1972 | | | | 1973 | 11 | supplemental | RFC-AAAA | 1974 | | | | 1975 | 12 | tag-version | RFC-AAAA | 1976 | | | | 1977 | 13 | software-version | RFC-AAAA | 1978 | | | | 1979 | 14 | version-scheme | RFC-AAAA | 1980 | | | | 1981 | 15 | lang | RFC-AAAA | 1982 | | | | 1983 | 16 | directory | RFC-AAAA | 1984 | | | | 1985 | 17 | file | RFC-AAAA | 1986 | | | | 1987 | 18 | process | RFC-AAAA | 1988 | | | | 1989 | 19 | resource | RFC-AAAA | 1990 | | | | 1991 | 20 | size | RFC-AAAA | 1992 | | | | 1993 | 21 | file-version | RFC-AAAA | 1994 | | | | 1995 | 22 | key | RFC-AAAA | 1996 | | | | 1997 | 23 | location | RFC-AAAA | 1998 | | | | 1999 | 24 | fs-name | RFC-AAAA | 2000 | | | | 2001 | 25 | root | RFC-AAAA | 2002 | | | | 2003 | 26 | path-elements | RFC-AAAA | 2004 | | | | 2005 | 27 | process-name | RFC-AAAA | 2006 | | | | 2007 | 28 | pid | RFC-AAAA | 2008 | | | | 2009 | 29 | type | RFC-AAAA | 2010 | | | | 2011 | 31 | entity-name | RFC-AAAA | 2012 | | | | 2013 | 32 | reg-id | RFC-AAAA | 2014 | | | | 2015 | 33 | role | RFC-AAAA | 2016 | | | | 2017 | 34 | thumbprint | RFC-AAAA | 2018 | | | | 2019 | 35 | date | RFC-AAAA | 2020 | | | | 2021 | 36 | device-id | RFC-AAAA | 2022 | | | | 2023 | 37 | artifact | RFC-AAAA | 2024 | | | | 2025 | 38 | href | RFC-AAAA | 2026 | | | | 2027 | 39 | ownership | RFC-AAAA | 2028 | | | | 2029 | 40 | rel | RFC-AAAA | 2030 | | | | 2031 | 41 | media-type | RFC-AAAA | 2032 | | | | 2033 | 42 | use | RFC-AAAA | 2034 | | | | 2035 | 43 | activation-status | RFC-AAAA | 2036 | | | | 2037 | 44 | channel-type | RFC-AAAA | 2038 | | | | 2039 | 45 | colloquial-version | RFC-AAAA | 2040 | | | | 2041 | 46 | description | RFC-AAAA | 2042 | | | | 2043 | 47 | edition | RFC-AAAA | 2044 | | | | 2045 | 48 | entitlement-data-required | RFC-AAAA | 2046 | | | | 2047 | 49 | entitlement-key | RFC-AAAA | 2048 | | | | 2049 | 50 | generator | RFC-AAAA | 2050 | | | | 2051 | 51 | persistent-id | RFC-AAAA | 2052 | | | | 2053 | 52 | product | RFC-AAAA | 2054 | | | | 2055 | 53 | product-family | RFC-AAAA | 2056 | | | | 2057 | 54 | revision | RFC-AAAA | 2058 | | | | 2059 | 55 | summary | RFC-AAAA | 2060 | | | | 2061 | 56 | unspsc-code | RFC-AAAA | 2062 | | | | 2063 | 57 | unspsc-version | RFC-AAAA | 2064 | | | | 2065 | 58-4294967295 | Unassigned | | 2066 +---------------+---------------------------+---------------+ 2068 Table 9: CoSWID Items Inital Registrations 2070 5.2. SWID/CoSWID Value Registries 2072 The following IANA registries provide a mechanism for new values to 2073 be added over time to common enumerations used by SWID and CoSWID. 2075 5.2.1. SWID/CoSWID Version Scheme Value Registry 2077 This document uses unsigned 16-bit index values to represent version- 2078 scheme item values. The initial set of version-scheme values are 2079 derived from the textual version scheme names defined in the ISO/IEC 2080 19770-2:2015 specification [SWID]. 2082 This document defines a new a new registry titled "SWID/CoSWID 2083 Version Scheme Values". Future registrations for this registry are 2084 to be made based on [RFC8126] as follows: 2086 [TO BE REMOVED: This registration should take place at the following 2087 location: https://www.iana.org/assignments/swid] 2089 +-------------+--------------------------+ 2090 | Range | Registration Procedures | 2091 +-------------+--------------------------+ 2092 | 0-16383 | Standards Action | 2093 | | | 2094 | 16384-32767 | Specification Required | 2095 | | | 2096 | 32768-65535 | Reserved for Private Use | 2097 +-------------+--------------------------+ 2099 Table 10: CoSWID Version Scheme Registration Proceedures 2101 Initial registrations for the "SWID/CoSWID Version Scheme Value" 2102 registry are provided below. Assignments consist of an integer Index 2103 value, the Version Scheme Name, and a reference to the defining 2104 specification. 2106 +-------------+--------------------------+-----------------+ 2107 | Index | Version Scheme Name | Specification | 2108 +-------------+--------------------------+-----------------+ 2109 | 0 | Reserved | | 2110 | | | | 2111 | 1 | multipartnumeric | See Section 4.1 | 2112 | | | | 2113 | 2 | multipartnumeric+suffix | See Section 4.1 | 2114 | | | | 2115 | 3 | alphanumeric | See Section 4.1 | 2116 | | | | 2117 | 4 | decimal | See Section 4.1 | 2118 | | | | 2119 | 5-16383 | Unassigned | | 2120 | | | | 2121 | 16384 | semver | [SEMVER] | 2122 | | | | 2123 | 16385-32767 | Unassigned | | 2124 | | | | 2125 | 32768-65535 | Reserved for Private Use | | 2126 +-------------+--------------------------+-----------------+ 2128 Table 11: CoSWID Version Scheme Inital Registrations 2130 Additional syntax requirements for registrations: 2132 o All registered names MUST be valid according to the XML Schema 2133 NMTOKEN data type (see [W3C.REC-xmlschema-2-20041028] section 2134 3.3.4). 2136 o The name prefix "x_" has been reserved for private use and NUST 2137 NOT be used in a registered name. 2139 5.2.2. SWID/CoSWID Entity Role Value Registry 2141 This document uses unsigned 8-bit index values to represent entity- 2142 entry role item values. The initial set of Entity roles are derived 2143 from the textual role names defined in the ISO/IEC 19770-2:2015 2144 specification [SWID]. 2146 This document defines a new a new registry titled "SWID/CoSWID Entity 2147 Role Values". Future registrations for this registry are to be made 2148 based on [RFC8126] as follows: 2150 [TO BE REMOVED: This registration should take place at the following 2151 location: https://www.iana.org/assignments/swid] 2152 +---------+--------------------------+ 2153 | Range | Registration Procedures | 2154 +---------+--------------------------+ 2155 | 0-31 | Standards Action | 2156 | | | 2157 | 32-127 | Specification Required | 2158 | | | 2159 | 128-255 | Reserved for Private Use | 2160 +---------+--------------------------+ 2162 Table 12: CoSWID Entity Role Registration Proceedures 2164 Initial registrations for the "SWID/CoSWID Entity Role Value" 2165 registry are provided below. Assignments consist of an integer Index 2166 value, a Role Name, and a reference to the defining specification. 2168 +---------+--------------------------+-----------------+ 2169 | Index | Role Name | Specification | 2170 +---------+--------------------------+-----------------+ 2171 | 0 | Reserved | | 2172 | | | | 2173 | 1 | tagCreator | See Section 4.2 | 2174 | | | | 2175 | 2 | softwareCreator | See Section 4.2 | 2176 | | | | 2177 | 3 | aggregator | See Section 4.2 | 2178 | | | | 2179 | 4 | distributor | See Section 4.2 | 2180 | | | | 2181 | 5 | licensor | See Section 4.2 | 2182 | | | | 2183 | 6-127 | Unassigned | | 2184 | | | | 2185 | 128-255 | Reserved for Private Use | | 2186 +---------+--------------------------+-----------------+ 2188 Table 13: CoSWID Entity Role Inital Registrations 2190 Additional syntax requirements for registrations: 2192 o All registered names MUST be valid according to the XML Schema 2193 NMTOKEN data type (see [W3C.REC-xmlschema-2-20041028] section 2194 3.3.4). 2196 o The name prefix "x_" has been reserved for private use and NUST 2197 NOT be used in a registered name. 2199 5.2.3. SWID/CoSWID Link Ownership Value Registry 2201 This document uses unsigned 8-bit index values to represent link- 2202 entry ownership item values. The initial set of Link ownership 2203 values are derived from the textual ownership names defined in the 2204 ISO/IEC 19770-2:2015 specification [SWID]. 2206 This document defines a new a new registry titled "SWID/CoSWID Link 2207 Ownership Values". Future registrations for this registry are to be 2208 made based on [RFC8126] as follows: 2210 [TO BE REMOVED: This registration should take place at the following 2211 location: https://www.iana.org/assignments/swid] 2213 +---------+--------------------------+ 2214 | Range | Registration Procedures | 2215 +---------+--------------------------+ 2216 | 0-31 | Standards Action | 2217 | | | 2218 | 32-127 | Specification Required | 2219 | | | 2220 | 128-255 | Reserved for Private Use | 2221 +---------+--------------------------+ 2223 Table 14: CoSWID Link Ownership Registration Proceedures 2225 Initial registrations for the "SWID/CoSWID Link Ownership Value" 2226 registry are provided below. Assignments consist of an integer Index 2227 value, an Ownership Type Name, and a reference to the defining 2228 specification. 2230 +-------------+--------------------------+-----------------+ 2231 | Index | Ownership Type Name | Definition | 2232 +-------------+--------------------------+-----------------+ 2233 | 0 | Reserved | | 2234 | | | | 2235 | 1 | abandon | See Section 4.3 | 2236 | | | | 2237 | 2 | private | See Section 4.3 | 2238 | | | | 2239 | 3 | shared | See Section 4.3 | 2240 | | | | 2241 | 4-16384 | Unassigned | | 2242 | | | | 2243 | 16385-32767 | Unassigned | | 2244 | | | | 2245 | 32768-65535 | Reserved for Private Use | | 2246 +-------------+--------------------------+-----------------+ 2248 Table 15: CoSWID Link Ownership Inital Registrations 2250 Additional syntax requirements for registrations: 2252 o All registered names MUST be valid according to the XML Schema 2253 NMTOKEN data type (see [W3C.REC-xmlschema-2-20041028] section 2254 3.3.4). 2256 o The name prefix "x_" has been reserved for private use and NUST 2257 NOT be used in a registered name. 2259 5.2.4. SWID/CoSWID Link Relationship Value Registry 2261 This document uses unsigned 16-bit index values to represent link- 2262 entry rel item values. The initial set of rel values are derived 2263 from the textual rel names defined in the ISO/IEC 19770-2:2015 2264 specification [SWID]. 2266 This document defines a new a new registry titled "SWID/CoSWID Link 2267 Relationship Values". Future registrations for this registry are to 2268 be made based on [RFC8126] as follows: 2270 [TO BE REMOVED: This registration should take place at the following 2271 location: https://www.iana.org/assignments/swid] 2272 +-------------+--------------------------+ 2273 | Range | Registration Procedures | 2274 +-------------+--------------------------+ 2275 | 0-16383 | Standards Action | 2276 | | | 2277 | 16384-32767 | Specification Required | 2278 | | | 2279 | 32768-65535 | Reserved for Private Use | 2280 +-------------+--------------------------+ 2282 Table 16: CoSWID Link Relationship Registration Proceedures 2284 Initial registrations for the "SWID/CoSWID Link Relationship Value" 2285 registry are provided below. Assignments consist of an integer Index 2286 value, the Relationship Type Name, and a reference to the defining 2287 specification. 2289 +-------------+--------------------------+-----------------+ 2290 | Index | Relationship Type Name | Specification | 2291 +-------------+--------------------------+-----------------+ 2292 | 0 | Reserved | | 2293 | | | | 2294 | 1 | ancestor | See Section 4.4 | 2295 | | | | 2296 | 2 | component | See Section 4.4 | 2297 | | | | 2298 | 3 | feature | See Section 4.4 | 2299 | | | | 2300 | 4 | installationmedia | See Section 4.4 | 2301 | | | | 2302 | 5 | packageinstaller | See Section 4.4 | 2303 | | | | 2304 | 6 | parent | See Section 4.4 | 2305 | | | | 2306 | 7 | patches | See Section 4.4 | 2307 | | | | 2308 | 8 | requires | See Section 4.4 | 2309 | | | | 2310 | 9 | see-also | See Section 4.4 | 2311 | | | | 2312 | 10 | supersedes | See Section 4.4 | 2313 | | | | 2314 | 11 | supplemental | See Section 4.4 | 2315 | | | | 2316 | 12-16384 | Unassigned | | 2317 | | | | 2318 | 16385-32767 | Unassigned | | 2319 | | | | 2320 | 32768-65535 | Reserved for Private Use | | 2321 +-------------+--------------------------+-----------------+ 2323 Table 17: CoSWID Link Relationship Inital Registrations 2325 Additional syntax requirements for registrations: 2327 o All registered names MUST be valid according to the XML Schema 2328 NMTOKEN data type (see [W3C.REC-xmlschema-2-20041028] section 2329 3.3.4). 2331 o The name prefix "x_" has been reserved for private use and NUST 2332 NOT be used in a registered name. 2334 5.2.5. SWID/CoSWID Link Use Value Registry 2336 This document uses unsigned 8-bit index values to represent link- 2337 entry use item values. The initial set of Link use values are 2338 derived from the textual names defined in the ISO/IEC 19770-2:2015 2339 specification [SWID]. 2341 This document defines a new a new registry titled "SWID/CoSWID Link 2342 Use Values". Future registrations for this registry are to be made 2343 based on [RFC8126] as follows: 2345 [TO BE REMOVED: This registration should take place at the following 2346 location: https://www.iana.org/assignments/swid] 2348 +---------+--------------------------+ 2349 | Range | Registration Procedures | 2350 +---------+--------------------------+ 2351 | 0-31 | Standards Action | 2352 | | | 2353 | 32-127 | Specification Required | 2354 | | | 2355 | 128-255 | Reserved for Private Use | 2356 +---------+--------------------------+ 2358 Table 18: CoSWID Link Use Registration Proceedures 2360 Initial registrations for the "SWID/CoSWID Entity Role Value" 2361 registry are provided below. Assignments consist of an integer Index 2362 value, the Link Use Type Name, and a reference to the defining 2363 specification. 2365 +---------+--------------------------+-----------------+ 2366 | Index | Link Use Type Name | Specification | 2367 +---------+--------------------------+-----------------+ 2368 | 0 | Reserved | | 2369 | | | | 2370 | 1 | optional | See Section 4.5 | 2371 | | | | 2372 | 2 | required | See Section 4.5 | 2373 | | | | 2374 | 3 | recommended | See Section 4.5 | 2375 | | | | 2376 | 4-127 | Unassigned | | 2377 | | | | 2378 | 128-255 | Reserved for Private Use | | 2379 +---------+--------------------------+-----------------+ 2381 Table 19: CoSWID Link Use Inital Registrations 2383 Additional syntax requirements for registrations: 2385 o All registered names MUST be valid according to the XML Schema 2386 NMTOKEN data type (see [W3C.REC-xmlschema-2-20041028] section 2387 3.3.4). 2389 o The name prefix "x_" has been reserved for private use and NUST 2390 NOT be used in a registered name. 2392 5.3. swid+cbor Media Type Registration 2394 IANA is requested to add the following to the IANA "Media Types" 2395 registry. 2397 Type name: application 2399 Subtype name: swid+cbor 2401 Required parameters: none 2403 Optional parameters: none 2405 Encoding considerations: Must be encoded as using [RFC7049]. See 2406 RFC-AAAA for details. 2408 Security considerations: See Section 6 of RFC-AAAA. 2410 Interoperability considerations: Applications MAY ignore any key 2411 value pairs that they do not understand. This allows backwards 2412 compatible extensions to this specification. 2414 Published specification: RFC-AAAA 2416 Applications that use this media type: The type is used by software 2417 asset management systems, vulnerability assessment systems, and in 2418 applications that use remote integrity verification. 2420 Fragment identifier considerations: Fragment identification for 2421 application/swid+cbor is supported by using fragment identifiers as 2422 specified by RFC-7049 section 7.5. 2424 Additional information: 2426 Magic number(s): first five bytes in hex: da 53 57 49 44 2428 File extension(s): coswid 2430 Macintosh file type code(s): none 2431 Macintosh Universal Type Identifier code: org.ietf.coswid conforms to 2432 public.data 2434 Person & email address to contact for further information: Henk 2435 Birkholz 2437 Intended usage: COMMON 2439 Restrictions on usage: None 2441 Author: Henk Birkholz 2443 Change controller: IESG 2445 5.4. CoAP Content-Format Registration 2447 IANA is requested to assign a CoAP Content-Format ID for the CoSWID 2448 media type in the "CoAP Content-Formats" sub-registry, from the "IETF 2449 Review or IESG Approval" space (256..999), within the "CoRE 2450 Parameters" registry [RFC7252]: 2452 +-----------------------+----------+------+-----------+ 2453 | Media type | Encoding | ID | Reference | 2454 +-----------------------+----------+------+-----------+ 2455 | application/swid+cbor | - | TBD1 | RFC-AAAA | 2456 +-----------------------+----------+------+-----------+ 2458 Table 20: CoAP Content-Format IDs 2460 5.5. CBOR Tag Registration 2462 IANA is requested to allocate a tag in the "CBOR Tags" registry, 2463 preferably with the specific value requested: 2465 +------------+----------+-------------------------------------------+ 2466 | Tag | Data | Semantics | 2467 | | Item | | 2468 +------------+----------+-------------------------------------------+ 2469 | 1398229316 | map | Concise Software Identifier (CoSWID) | 2470 | | | [RFC-AAAA] | 2471 +------------+----------+-------------------------------------------+ 2473 Table 21: CoSWID CBOR Tag 2475 6. Security Considerations 2477 SWID and CoSWID tags contain public information about software 2478 components and, as such, do not need to be protected against 2479 disclosure on an endpoint. Similarly, SWID/CoSWID tags are intended 2480 to be easily discoverable by applications and users on an endpoint in 2481 order to make it easy to identify and collect all of an endpoint's 2482 SWID tags. As such, any security considerations regarding SWID/ 2483 CoSWID tags focus on the application of SWID/CoSWID tags to address 2484 security challenges, and the possible disclosure of the results of 2485 those applications. 2487 A signed SWID/CoSWID tag whose signature has been validated can be 2488 relied upon to be unchanged since it was signed. If the SWID/CoSWID 2489 tag was created by the software provider, is signed, and the software 2490 provider can be authenticated as the originator of the signature, 2491 then the tag can be considered authoritative. In this way, an 2492 authoritative SWID/CoSWID tag contains information about a software 2493 component provided by the maintainer of the software component, who 2494 is expected to be an expert in their own software. Thus, 2495 authoritative SWID/CoSWID tags can be trusted to represent 2496 authoritative information about the software component. Having an 2497 authoritative SWID/CoSWID tag can be useful when the information in 2498 the tag needs to be trusted, such as when the tag is being used to 2499 convey reference integrity measurements for software components. By 2500 contrast, the data contained in unsigned tags cannot be trusted to be 2501 unmodified. 2503 SWID/CoSWID tags are designed to be easily added and removed from an 2504 endpoint along with the installation or removal of software 2505 components. On endpoints where addition or removal of software 2506 components is tightly controlled, the addition or removal of SWID 2507 tags can be similarly controlled. On more open systems, where many 2508 users can manage the software inventory, SWID/CoSWID tags can be 2509 easier to add or remove. On such systems, it can be possible to add 2510 or remove SWID/CoSWID tags in a way that does not reflect the actual 2511 presence or absence of corresponding software components. Similarly, 2512 not all software products automatically install SWID/CoSWID tags, so 2513 products can be present on an endpoint without providing a 2514 corresponding SWID tag. As such, any collection of SWID/CoSWID tags 2515 cannot automatically be assumed to represent either a complete or 2516 fully accurate representation of the software inventory of the 2517 endpoint. However, especially on endpoint devices that more strictly 2518 control the ability to add or remove applications, SWID/CoSWID tags 2519 are an easy way to provide an preliminary understanding of that 2520 endpoint's software inventory. 2522 Any report of an endpoint's SWID/CoSWID tag collection provides 2523 information about the software inventory of that endpoint. If such a 2524 report is exposed to an attacker, this can tell them which software 2525 products and versions thereof are present on the endpoint. By 2526 examining this list, the attacker might learn of the presence of 2527 applications that are vulnerable to certain types of attacks. As 2528 noted earlier, SWID/CoSWID tags are designed to be easily 2529 discoverable by an endpoint, but this does not present a significant 2530 risk since an attacker would already need to have access to the 2531 endpoint to view that information. However, when the endpoint 2532 transmits its software inventory to another party, or that inventory 2533 is stored on a server for later analysis, this can potentially expose 2534 this information to attackers who do not yet have access to the 2535 endpoint. For this reason, it is important to protect the 2536 confidentiality of SWID/CoSWID tag information that has been 2537 collected from an endpoint, not because those tags individually 2538 contain sensitive information, but because the collection of SWID/ 2539 CoSWID tags and their association with an endpoint reveals 2540 information about that endpoint's attack surface. 2542 Finally, both the ISO-19770-2:2015 XML schema SWID definition and the 2543 CoSWID data definition allow for the construction of "infinite" tags 2544 with link item loops or tags that contain malicious content with the 2545 intent of creating non-deterministic states during validation or 2546 processing of those tags. While software providers are unlikely to 2547 do this, SWID/CoSWID tags can be created by any party and the SWID/ 2548 CoSWID tags collected from an endpoint could contain a mixture of 2549 vendor and non-vendor created tags. For this reason, tools that 2550 consume SWID/CoSWID tags ought to treat the tag contents as 2551 potentially malicious and employ input sanitizing and loop detection 2552 on the tags they ingest. 2554 7. Acknowledgments 2556 TBD 2558 8. Change Log 2560 Changes from version 03 to version 11: 2562 o Reduced representation complexity of the media-entry type and 2563 removed the section describing the older data structure. 2565 o Added more signature schemes from COSE 2567 o Included a minimal required set of normative language 2568 o Reordering of attribute name to integer label by priority 2569 according to semantics. 2571 o Added an IANA registry for CoSWID items supporting future 2572 extension. 2574 o Cleaned up IANA registrations, fixing some inconsistencies in the 2575 table labels. 2577 o Added additional CDDL sockets for resource collection entries 2578 providing for additional extension points to address future SWID/ 2579 CoSWID extensions. 2581 o Updated section on extension points to address new CDDL sockets 2582 and to reference the new IANA registry for items. 2584 o Removed unused references and added new references to address 2585 placeholder comments. 2587 o Added table with semantics for the link ownership item. 2589 o Clarified language, made term use more consistent, fixed 2590 references, and replacing lowercase RFC2119 keywords. 2592 Changes from version 02 to version 03: 2594 o Updated core CDDL including the CDDL design pattern according to 2595 RFC 8428. 2597 Changes from version 01 to version 02: 2599 o Enforced a more strict separation between the core CoSWID 2600 definition and additional usage by moving content to corresponding 2601 appendices. 2603 o Removed artifacts inherited from the reference schema provided by 2604 ISO (e.g. NMTOKEN(S)) 2606 o Simplified the core data definition by removing group and type 2607 choices where possible 2609 o Minor reordering of map members 2611 o Added a first extension point to address requested flexibility for 2612 extensions beyond the any-element 2614 Changes from version 00 to version 01: 2616 o Ambiguity between evidence and payload eliminated by introducing 2617 explicit members (while still 2619 o allowing for "empty" SWID tags) 2621 o Added a relatively restrictive COSE envelope using cose_sign1 to 2622 define signed CoSWID (single signer only, at the moment) 2624 o Added a definition how to encode hashes that can be stored in the 2625 any-member using existing IANA tables to reference hash-algorithms 2627 Changes since adopted as a WG I-D -00: 2629 o Removed redundant any-attributes originating from the ISO- 2630 19770-2:2015 XML schema definition 2632 o Fixed broken multi-map members 2634 o Introduced a more restrictive item (any-element-map) to represent 2635 custom maps, increased restriction on types for the any-attribute, 2636 accordingly 2638 o Fixed X.1520 reference 2640 o Minor type changes of some attributes (e.g. NMTOKENS) 2642 o Added semantic differentiation of various name types (e,g. fs- 2643 name) 2645 Changes from version 06 to version 07: 2647 o Added type choices/enumerations based on textual definitions in 2648 19770-2:2015 2650 o Added value registry request 2652 o Added media type registration request 2654 o Added content format registration request 2656 o Added CBOR tag registration request 2658 o Removed RIM appedix to be addressed in complementary draft 2660 o Removed CWT appendix 2662 o Flagged firmware resource colletion appendix for revision 2663 o Made use of terminology more consistent 2665 o Better defined use of extension points in the CDDL 2667 o Added definitions for indexed values 2669 o Added IANA registry for Link use indexed values 2671 Changes from version 05 to version 06: 2673 o Improved quantities 2675 o Included proposals for implicet enumerations that were NMTOKENS 2677 o Added extension points 2679 o Improved exemplary firmware-resource extension 2681 Changes from version 04 to version 05: 2683 o Clarified language around SWID and CoSWID to make more consistent 2684 use of these terms. 2686 o Added language describing CBOR optimizations for single vs. arrays 2687 in the model front matter. 2689 o Fixed a number of grammatical, spelling, and wording issues. 2691 o Documented extension points that use CDDL sockets. 2693 o Converted IANA registration tables to markdown tables, reserving 2694 the 0 value for use when a value is not known. 2696 o Updated a number of references to their current versions. 2698 Changes from version 03 to version 04: 2700 o Re-index label values in the CDDL. 2702 o Added a section describing the CoSWID model in detail. 2704 o Created IANA registries for entity-role and version-scheme 2706 Changes from version 02 to version 03: 2708 o Updated CDDL to allow for a choice between a payload or evidence 2710 o Re-index label values in the CDDL. 2712 o Added item definitions 2714 o Updated references for COSE, CBOR Web Token, and CDDL. 2716 Changes from version 01 to version 02: 2718 o Added extensions for Firmware and CoSWID use as Reference 2719 Integrity Measurements (CoSWID RIM) 2721 o Changes meta handling in CDDL from use of an explicit use of items 2722 to a more flexible unconstrained collection of items. 2724 o Added sections discussing use of COSE Signatures and CBOR Web 2725 Tokens 2727 Changes from version 00 to version 01: 2729 o Added CWT usage for absolute SWID paths on a device 2731 o Fixed cardinality of type-choices including arrays 2733 o Included first iteration of firmware resource-collection 2735 9. Contributors 2737 10. References 2739 10.1. Normative References 2741 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2742 Requirement Levels", BCP 14, RFC 2119, 2743 DOI 10.17487/RFC2119, March 1997, 2744 . 2746 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2747 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2748 September 2009, . 2750 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2751 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2752 October 2013, . 2754 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2755 Application Protocol (CoAP)", RFC 7252, 2756 DOI 10.17487/RFC7252, June 2014, 2757 . 2759 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2760 Writing an IANA Considerations Section in RFCs", BCP 26, 2761 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2762 . 2764 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2765 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2766 . 2768 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2769 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2770 May 2017, . 2772 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2773 DOI 10.17487/RFC8288, October 2017, 2774 . 2776 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2777 Definition Language (CDDL): A Notational Convention to 2778 Express Concise Binary Object Representation (CBOR) and 2779 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2780 June 2019, . 2782 [SAM] "Information technology - Software asset management - Part 2783 5: Overview and vocabulary", ISO/IEC 19770-5:2015, 2784 November 2013. 2786 [SEMVER] Preston-Werner, T., "Semantic Versioning 2.0.0", n.d., 2787 . 2789 [SWID] "Information technology - Software asset management - Part 2790 2: Software identification tag", ISO/IEC 19770-2:2015, 2791 October 2015. 2793 [W3C.REC-css3-mediaqueries-20120619] 2794 Rivoal, F., "Media Queries", World Wide Web Consortium 2795 Recommendation REC-css3-mediaqueries-20120619, June 2012, 2796 . 2799 [W3C.REC-xmlschema-2-20041028] 2800 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 2801 Second Edition", World Wide Web Consortium Recommendation 2802 REC-xmlschema-2-20041028, October 2004, 2803 . 2805 [W3C.REC-xpath20-20101214] 2806 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 2807 Kay, M., Robie, J., and J. Simeon, "XML Path Language 2808 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 2809 Recommendation REC-xpath20-20101214, December 2010, 2810 . 2812 [X.1520] "Recommendation ITU-T X.1520 (2014), Common 2813 vulnerabilities and exposures", April 2011. 2815 10.2. Informative References 2817 [CamelCase] 2818 "UpperCamelCase", August 2014, 2819 . 2821 [I-D.birkholz-rats-tuda] 2822 Fuchs, A., Birkholz, H., McDonald, I., and C. Bormann, 2823 "Time-Based Uni-Directional Attestation", draft-birkholz- 2824 rats-tuda-00 (work in progress), March 2019. 2826 [KebabCase] 2827 "KebabCase", December 2014, 2828 . 2830 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2831 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2832 DOI 10.17487/RFC4122, July 2005, 2833 . 2835 [RFC8322] Field, J., Banghart, S., and D. Waltermire, "Resource- 2836 Oriented Lightweight Information Exchange (ROLIE)", 2837 RFC 8322, DOI 10.17487/RFC8322, February 2018, 2838 . 2840 [RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage 2841 Description Specification", RFC 8520, 2842 DOI 10.17487/RFC8520, March 2019, 2843 . 2845 [SWID-GUIDANCE] 2846 Waltermire, D., Cheikes, B., Feldman, L., and G. Witte, 2847 "Guidelines for the Creation of Interoperable Software 2848 Identification (SWID) Tags", NISTIR 8060, April 2016, 2849 . 2851 Appendix A. Signed Concise SWID Tags using COSE 2853 SWID tags, as defined in the ISO-19770-2:2015 XML schema, can include 2854 cryptographic signatures to protect the integrity of the SWID tag. 2855 In general, tags are signed by the tag creator (typically, although 2856 not exclusively, the vendor of the software component that the SWID 2857 tag identifies). Cryptographic signatures can make any modification 2858 of the tag detectable, which is especially important if the integrity 2859 of the tag is important, such as when the tag is providing reference 2860 integrity measurements for files. 2862 The ISO-19770-2:2015 XML schema uses XML DSIG to support 2863 cryptographic signatures. CoSWID tags require a different signature 2864 scheme than this. COSE (CBOR Object Signing and Encryption) provides 2865 the required mechanism [RFC8152]. Concise SWID can be wrapped in a 2866 COSE Single Signer Data Object (COSE_Sign1) that contains a single 2867 signature. The following CDDL defines a more restrictive subset of 2868 header attributes allowed by COSE tailored to suit the requirements 2869 of Concise SWID tags. 2871 2872 signed-coswid = #6.18(COSE-Sign1-coswid) 2874 cose-label = int / tstr 2875 cose-values = any 2877 protected-signed-coswid-header = { 2878 1 => int, ; algorithm identifier 2879 3 => "application/swid+cbor", 2880 * cose-label => cose-values, 2881 } 2883 unprotected-signed-coswid-header = { 2884 4 => bstr, ; key identifier 2885 * cose-label => cose-values, 2886 } 2888 COSE-Sign1-coswid = [ 2889 protected: bstr .cbor protected-signed-coswid-header, 2890 unprotected: unprotected-signed-coswid-header, 2891 payload: bstr .cbor concise-swid-tag, 2892 signature: bstr, 2893 ] 2894 2896 Optionally, the COSE_Sign structure that allows for more than one 2897 signature to be applied to a CoSWID tag MAY be used. The 2898 corresponding usage scenarios are domain-specific and require well- 2899 defined application guidance. Representation of the corresponding 2900 guidance is out-of-scope of this document. 2902 Additionally, the COSE Header counter signature MAY be used as an 2903 attribute in the unprotected header map of the COSE envelope of a 2904 CoSWID. The application of counter signing enables second parties to 2905 provide a signature on a signature allowing for a proof that a 2906 signature existed at a given time (i.e., a timestamp). 2908 Authors' Addresses 2910 Henk Birkholz 2911 Fraunhofer SIT 2912 Rheinstrasse 75 2913 Darmstadt 64295 2914 Germany 2916 Email: henk.birkholz@sit.fraunhofer.de 2918 Jessica Fitzgerald-McKay 2919 Department of Defense 2920 9800 Savage Road 2921 Ft. Meade, Maryland 2922 USA 2924 Email: jmfitz2@nsa.gov 2926 Charles Schmidt 2927 The MITRE Corporation 2928 202 Burlington Road 2929 Bedford, Maryland 01730 2930 USA 2932 Email: cmschmidt@mitre.org 2934 David Waltermire 2935 National Institute of Standards and Technology 2936 100 Bureau Drive 2937 Gaithersburg, Maryland 20877 2938 USA 2940 Email: david.waltermire@nist.gov