idnits 2.17.1 draft-ietf-sacm-coswid-04.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 4 instances of too long lines in the document, the longest one being 19 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 05, 2018) is 2243 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) == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-12 ** 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'SWID-GUIDANCE' == Outdated reference: A later version (-16) exists of draft-ietf-sacm-terminology-14 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 5 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: September 6, 2018 Department of Defense 6 C. Schmidt 7 The MITRE Corporation 8 D. Waltermire 9 NIST 10 March 05, 2018 12 Concise Software Identifiers 13 draft-ietf-sacm-coswid-04 15 Abstract 17 This document defines a concise representation of ISO/IEC 18 19770-2:2015 Software Identifiers (SWID tags) that is interoperable 19 with the XML schema definition of ISO/IEC 19770-2:2015 and augmented 20 for application in Constrained-Node Networks. Next to the inherent 21 capability of SWID tags to express arbitrary context information, 22 CoSWID support the definition of additional semantics via well- 23 defined data definitions incorporated by extension points. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 6, 2018. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. The SWID Tag Lifecycle . . . . . . . . . . . . . . . . . 3 61 1.2. Concise SWID Extensions . . . . . . . . . . . . . . . . . 6 62 1.3. Requirements Notation . . . . . . . . . . . . . . . . . . 6 63 2. Concise SWID Data Definition . . . . . . . . . . . . . . . . 7 64 2.1. The concise-software-identity Object . . . . . . . . . . 7 65 2.1.1. Determining the tag type . . . . . . . . . . . . . . 11 66 2.1.2. concise-software-identity Co-constraints . . . . . . 12 67 2.2. The global-attributes Group . . . . . . . . . . . . . . . 12 68 2.3. The any-element-entry . . . . . . . . . . . . . . . . . . 13 69 2.4. The entity Object . . . . . . . . . . . . . . . . . . . . 13 70 2.5. The link Object . . . . . . . . . . . . . . . . . . . . . 15 71 2.6. The software-meta Object . . . . . . . . . . . . . . . . 16 72 2.7. The Resource Collection Definition . . . . . . . . . . . 19 73 2.7.1. The hash-entry Array . . . . . . . . . . . . . . . . 19 74 2.7.2. The resource-collection Group . . . . . . . . . . . . 20 75 2.7.3. The payload Object . . . . . . . . . . . . . . . . . 22 76 2.7.4. The evidence Object . . . . . . . . . . . . . . . . . 23 77 2.8. Full CDDL Definition . . . . . . . . . . . . . . . . . . 23 78 3. CoSWID Indexed Label Values . . . . . . . . . . . . . . . . . 28 79 3.1. Version Scheme . . . . . . . . . . . . . . . . . . . . . 28 80 3.2. Entity Role Values . . . . . . . . . . . . . . . . . . . 28 81 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 82 4.1. SWID/CoSWID Version Schema Values Registry . . . . . . . 29 83 4.2. SWID/CoSWID Entity Role Values Registry . . . . . . . . . 30 84 5. Security Considerations . . . . . . . . . . . . . . . . . . . 30 85 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32 86 7. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 32 87 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 34 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 89 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 90 9.2. Informative References . . . . . . . . . . . . . . . . . 35 91 Appendix A. CoSWID Attributes for Firmware (label 60) . . . . . 35 92 Appendix B. Signed Concise SWID Tags using COSE . . . . . . . . 38 93 Appendix C. CoSWID used as Reference Integrity Measurements 94 (CoSWID RIM) . . . . . . . . . . . . . . . . . . . . 39 95 Appendix D. CBOR Web Token for Concise SWID Tags . . . . . . . . 40 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 98 1. Introduction 100 SWID tags have several use-applications including but not limited to: 102 o Software Inventory Management, a part of the Software Asset 103 Management [SAM] process, which requires an accurate list of 104 discernible deployed software components. 106 o Vulnerability Assessment, which requires a semantic link between 107 standardized vulnerability descriptions and IT-assets [X.1520]. 109 o Remote Attestation, which requires a link between reference 110 integrity measurements (RIM) and security logs of measured 111 software components [I-D.birkholz-tuda]. 113 SWID tags, as defined in ISO-19770-2:2015 [SWID], provide a 114 standardized format for a record that identifies and describes a 115 specific release of a software component. Different software 116 components, and even different releases of a particular software 117 component, each have a different SWID tag record associated with 118 them. SWID tags are meant to be flexible and able to express a broad 119 set of metadata about a software component. 121 Real-world instances of SWID tags can be fairly large, and the 122 communication of SWID tags in use-applications such as those 123 described earlier can cause a large amount of data to be transported. 124 This can be larger than acceptable for constrained devices and 125 networks. CoSWID tags significantly reduce the amount of data 126 transported as compared to a typical SWID tag. This reduction is 127 enable through the use of CBOR, which maps human-readable labels of 128 that content to more concise integer labels (indices). This allows 129 SWID tags to be part of an enterprise security solution for a wider 130 range of endpoints and environments. 132 1.1. The SWID Tag Lifecycle 134 In addition to defining the format of these records, ISO/IEC 135 19770-2:2015 defines requirements concerning the SWID tag life-cycle. 136 Specifically, when a software component is installed on an endpoint, 137 that product's SWID tag is also installed. Likewise, when the 138 product is uninstalled or replaced, the SWID tag is deleted or 139 replaced, as appropriate. As a result, ISO/IEC 19770-2:2015 140 describes a system wherein there is a correspondence between the set 141 of installed software products on an endpoint, and the presence on 142 that endpoint of the SWID tags corresponding to those products. 144 The following is an excerpt (with some modifications and reordering) 145 from NIST Interagency Report (NISTIR) 8060: Guidelines for the 146 Creation of Interoperable SWID Tags [SWID-GUIDANCE], which describes 147 the tag types used within the lifecycle defined in ISO-19770-2:2015. 149 The SWID specification defines four types of SWID tags: primary, 150 patch, corpus, and supplemental. 152 1. Primary Tag - A SWID tag that identifies and describes a 153 software component is installed on a computing device. 155 2. Patch Tag - A SWID tag that identifies and describes an 156 installed patch which has made incremental changes to a 157 software component installed on a computing device. 159 3. Corpus Tag - A SWID tag that identifies and describes an 160 installable software component in its pre-installation state. 161 A corpus tag can be used to represent metadata about an 162 installation package or installer for a software component, a 163 software update, or a patch. 165 4. Supplemental Tag - A SWID tag that allows additional 166 information to be associated with a referenced SWID tag. This 167 helps to ensure that SWID Primary and Patch Tags provided by a 168 software provider are not modified by software management 169 tools, while allowing these tools to provide their own 170 software metadata. 172 Corpus, primary, and patch tags have similar functions in that 173 they describe the existence and/or presence of different types of 174 software (e.g., software installers, software installations, 175 software patches), and, potentially, different states of software 176 components. In contrast, supplemental tags furnish additional 177 information not contained in corpus, primary, or patch tags. All 178 four tag types come into play at various points in the software 179 lifecycle, and support software management processes that depend 180 on the ability to accurately determine where each software 181 component is in its lifecycle. 183 Installation Product Product Product Product 184 Media -> Installed -> Patched -> Upgraded -> Removed 185 Deployed 187 Corpus Primary Primary xPrimary xPrimary 188 Supplemental Supplemental xSupplemental xSuplemental 189 Patch xPatch 190 Primary 191 Supplemental 193 The figure above illustrates the steps in the software lifecycle 194 and the relationships among those lifecycle events supported by 195 the four types of SWID tags, as follows: - Software Deployment. 196 Before the software component is installed (i.e., pre- 197 installation), and while the product is being deployed, a corpus 198 tag provides information about the installation files and 199 distribution media (e.g., CD/DVD, distribution package). - 200 Software Installation. A primary tag will be installed with the 201 software component (or subsequently created) to uniquely identify 202 and describe the software component. Supplemental tags are 203 created to augment primary tags with additional site-specific or 204 extended information. While not illustrated in the figure, patch 205 tags may also be installed during software installation to provide 206 information about software fixes deployed along with the base 207 software installation. - Software Patching. When a new patch is 208 applied to the software component, a new patch tag is provided, 209 supplying details about the patch and its dependencies. While not 210 illustrated in the figure, a corpus tag can also provide 211 information about the patch installer, and patching dependencies 212 that need to be installed before the patch. - Software Upgrading. 213 As a software component is upgraded to a new version, new primary 214 and supplemental tags replace existing tags, enabling timely and 215 accurate tracking of updates to software inventory. While not 216 illustrated in the figure, a corpus tag can also provide 217 information about the upgrade installer, and dependencies that 218 need to be installed before the upgrade. - Software Removal. 219 Upon removal of the software component, relevant SWID tags are 220 removed. This removal event can trigger timely updates to 221 software inventory reflecting the removal of the product and any 222 associated patch or supplemental tags. 224 Note: While not fully illustrated in the figure, supplemental tags 225 can be associated with any corpus, primary, or patch tag to provide 226 additional metadata about an installer, installed software, or 227 installed patch respectively. 229 Each of the different SWID tag types of SWID tags provide different 230 types of information. For example, a "corpus tag" is used to 231 describe an application's installation image on an installation 232 media, while a "patch tag" is meant to describe a patch that modifies 233 some other application. While there are very few required fields in 234 SWID tags, there are many optional fields that support different uses 235 of these different types of tags. While a SWID tag that consisted 236 only of required fields could be a few hundred bytes in size, a tag 237 containing many of the optional fields could be many orders of 238 magnitude larger. 240 1.2. Concise SWID Extensions 242 This document defines a more concise representation of SWID tags in 243 the Concise Binary Object Representation (CBOR) [RFC7049]. This is 244 described via the Concise Data Definition Language (CDDL) 245 [I-D.greevenbosch-appsawg-cbor-cddl]. The resulting Concise SWID 246 data definition is interoperable with the XML schema definition of 247 ISO-19770-2:2015 [SWID]. The vocabulary, i.e., the CDDL names of the 248 types and members used in the CoSWID data definition, is mapped to 249 more concise labels represented as small integers. The names used in 250 the CDDL data definition and the mapping to the CBOR representation 251 using integer labels is based on the vocabulary of the XML attribute 252 and element names defined in ISO/IEC 19770-2:2015. 254 This document specifies a standardized equivalent to the ISO- 255 19770-2:2015 standard. The corresponding CoSWID data definition 256 includes two kinds of augmentation. 258 o the explicit definition of types for attributes that are typically 259 stored in the "any attribute" of an ISO-19770-2:2015 in XML 260 representation. These are covered in the main body of this 261 document. 263 o the inclusion of extension points in the CoSWID data definition 264 that allow for additional uses of CoSWID tags that go beyond the 265 original scope of ISO-19770-2:2015 tags. These are covered in 266 appendices to this document. 268 1.3. Requirements Notation 270 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 271 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 272 "OPTIONAL" in this document are to be interpreted as described in RFC 273 2119, BCP 14 [RFC2119]. 275 2. Concise SWID Data Definition 277 The following is a CDDL representation of the ISO/IEC 19770-2:2015 278 [SWID] XML schema definition of SWID tags. This representation 279 includes every SWID tag field and attribute and thus supports all 280 SWID tag use cases. The CamelCase notation used in the XML schema 281 definition is changed to a hyphen-separated notation (e.g. 282 ResourceCollection is named resource-collection in the CoSWID data 283 definition). This deviation from the original notation used in the 284 XML representation reduces ambiguity when referencing certain 285 attributes in corresponding textual descriptions. An attribute 286 referred by its name in CamelCase notation explicitly relates to XML 287 SWID tags, an attribute referred by its name in hyphen-separated 288 notation explicitly relates to CoSWID tags. This approach simplifies 289 the composition of further work that reference both XML SWID and 290 CoSWID documents. 292 Human-readable names of members in the CDDL data definition are 293 mapped to integer indices via a block of rules at the bottom of the 294 definition. The 67 character strings of the SWID vocabulary that 295 would have to be stored or transported in full if using the original 296 vocabulary are replaced. 298 Concise Software Identifiers are tailored to be used in the domain of 299 constrained-node networks. A typical endpoint is capable of storing 300 the CoSWID tag of installed software, a constrained-node might lack 301 that capability. CoSWID address these constraints and the 302 corresponding specification is augmented to retain their usefulness 303 in the thing-2-thing domain. Specific examples include, but are not 304 limited to limiting the scope of hash algorithms to the IANA Named 305 Information tables or including firmware attributes addressing 306 devices that do not necessarily provide a file-system to store a 307 CoSWID tag in. 309 The following subsections describe the different parts of the CoSWID 310 model. 312 2.1. The concise-software-identity Object 314 The CDDL for the main concise-software-identity object is as follows: 316 317 concise-software-identity = { 318 global-attributes, 319 tag-id, 320 tag-version, 321 ? corpus, 322 ? patch, 323 ? supplemental, 324 swid-name, 325 ? software-version, 326 ? version-scheme, 327 ? media, 328 ? software-meta-entry, 329 ? entity-entry, 330 ? link-entry, 331 ? ( payload-entry / evidence-entry ), 332 ? any-element-entry, 333 } 334 tag-id = (0: text) 335 swid-name = (1: text) 336 entity-entry = (2: entity / [ 2* entity ]) 337 evidence-entry = (3: evidence) 338 link-entry = (4: link / [ 2* link ]) 339 software-meta-entry = (5: software-meta / [ 2* software-meta ]) 340 payload-entry = (6: payload) 341 any-element-entry = (7: any-element-map / [ 2* any-element-map ]) 342 corpus = (8: bool) 343 patch = (9: bool) 344 media = (10: text) 345 supplemental = (11: bool) 346 tag-version = (12: integer) 347 software-version = (13: text) 348 version-scheme = (14: text) 349 351 The items are ordered ensure that tag metadata appears first, 352 followed by general software metadata, entity information, link 353 relations, and finally payload or evidence data. This ordering 354 attempts to provide the most significant metadata that a parser may 355 need first, followed by metadata that may support more specific use- 356 applications. The following describes each child item of the 357 concise-software-identity model. 359 o global-attributes: A list of items including an optional language 360 definition to support the processing of text-string values and an 361 unbounded set of any-attribute items. Described in Section 2.2. 363 o tag-id (label 0): An textual identifier uniquely referencing a 364 (composite) software component. The tag identifier is intended to 365 be globally unique. There are no strict guidelines on how this 366 identifier is structured, but examples include a 16 byte GUID 367 (e.g. class 4 UUID). 369 o tag-version (label 12): An integer value that indicates if a 370 specific release of a software component has more than one tag 371 that can represent that specific release. A typical use of this 372 field may be to set an initial value to 0 and to monotonically 373 increase the value for subsequent tags produced for the specific 374 release. A change in the value of this field may be the case if a 375 CoSWID tag producer creates and releases an incorrect tag that 376 they subsequently want to fix, but with no underlying changes to 377 the product the CoSWID tag represents. This could happen if, for 378 example, a patch is distributed that has a link reference that 379 does not cover all the various software releases it can patch. A 380 newer CoSWID tag for that patch can be generated and the tag- 381 version value incremented to indicate that the data is updated. 383 o corpus (label 8): A boolean value that indicates if the tag 384 identifies and describes an installable software component in its 385 pre-installation state. Installable software includes a 386 installation package or installer for a software component, a 387 software update, or a patch. If the Concise SWID tag represents 388 installable software, the corpus item MUST be set to "true". If 389 not provided the default value MUST be considered "false". 391 o patch (label 9): A boolean value that indicates if the tag 392 identifies and describes an installed patch which has made 393 incremental changes to a software component installed on a 394 computing device. Typically, an installed patch has made a set of 395 file modifications to pre-installed software, and does not alter 396 the version number or the descriptive metadata of an installed 397 software product. If a Concise SWID tag is for a patch, it MUST 398 contain the patch item and its value MUST be set to "true". If 399 not provided the default value MUST be considered "false". 401 o supplemental (label 11): A boolean value that indicates if the tag 402 is providing additional information to be associated with another 403 referenced SWID tag. Tags using this item help to ensure that 404 primary and patch tags provided by a software provider are not 405 modified by software management tools, while allowing these tools 406 to provide their own software metadata for a software component. 407 If a Concise SWID tag is a supplemntal tag, it MUST contain the 408 supplemental item and its value MUST be set to "true". If not 409 provided the default value MUST be considered "false". 411 o swid-name (label 1): This textual item provides the software 412 component name as it would typically be referenced. For example, 413 what would be seen in the add/remove software dialog in an 414 operating system, or what is specified as the name of a packaged 415 software component or a patch identifier name. 417 o software-version (label 13): A textual value representing the 418 specific underlying release or development version of the software 419 component. 421 o version-scheme (label 14): An 8-bit integer or textual value 422 representing the versioning scheme used for the software-version 423 item. If an integer value is used it MUST be a value from the 424 registry (see section Section 4.1 or a value in the private use 425 range: 32768-65,535. 427 o media (label 10): This text value is a hint to the tag consumer to 428 understand what this SWID tag applies to. This item can also be 429 included in the link item to represent a attributes defined by the 430 W3C Media Queries Recommendation (see http://www.w3.org/TR/ 431 css3-mediaqueries/). A hint to the consumer of the link to what 432 the target item is applicable for. 434 o software-meta-entry (label 5): An open-ended collection of key/ 435 value data related to this CoSWID. The attributes included in 436 this Element are predefined attributes to ensure common usage 437 across the industry. The schema allows for any additional 438 attribute to be included in a CoSWID tag, though it is recommended 439 that industry norms for new attributes are defined and followed to 440 the degree possible. Described in Section 2.6. 442 o entity-entry (label 2): Specifies the organizations related to the 443 software component referenced by this CoSWID tag. Described in 444 Section 2.4. 446 o link-entry (label 4): A reference to any another item (can include 447 details that are related to the CoSWID tag such as details on 448 where specific resources can be found, e.g. vulnerability 449 database associations, ROLIE feeds, MUD files, etc). This is 450 modeled directly to match the HTML "link" element; it is critical 451 for streamlining software discovery scenarios to ensure their 452 consistency. Described in Section 2.5. 454 o payload-entry (label 6): The items that may be installed on a 455 system entity when the software component is installed. Note that 456 payload may be a superset of the items installed and - depending 457 on optimization mechanisms in respect to that system entity - may 458 or may not include every item that could be created or executed on 459 the corresponding system entitiy when software components are 460 installed. In general, payload will be used to indicate the files 461 that may be installed with a software component. Therefore 462 payload will often be a superset of those files (i.e. if a 463 particular optional sub-component is not installed, the files 464 associated with that software component may be included in 465 payload, but not installed in the system entity). Described in 466 Section 2.7.3. 468 o evidence-entry (label 3): This item is used to provide results 469 from a scan of a system where software that does not have a CoSWID 470 tag is discovered. This information is not provided by the 471 software-creator, and is instead created when a system is being 472 scanned and the evidence for why software is believed to be 473 installed on the device is provided in the evidence item. 474 Described in Section 2.7.4. 476 o any-element-entry (label 7): A default map that can contain 477 arbitrary map members and even nested maps (which would be also 478 any-elements). In essence, the any-element allows items not 479 defined in this CDDL data definition to be included in a Concise 480 Software Identifier. Described in Section 2.3. 482 2.1.1. Determining the tag type 484 o Primary Tag: A CoSWID tag MUST be considered a primary tag if the 485 corpus, patch, and supplemental items are "false". 487 o Patch Tag: A CoSWID tag MUST be considered a patch tag if the 488 patch item is "true". 490 o Corpus Tag: A CoSWID tag MUST be considered a corpus tag if the 491 corpus item is "true". 493 o Supplemental Tag: A CoSWID tag MUST be considered a supplemental 494 tag if the supplemental item is set to "true". 496 If multiple of the corpus, patch, and supplemental items are "true", 497 then the containing tag MUST be considered an unsupported tag type. 499 If the patch does modify the version number or the descriptive 500 metadata of the software, then a new tag representing these details 501 SHOULD be installed, and the old tag SHOULD be removed. 503 2.1.2. concise-software-identity Co-constraints 505 o Only one of the corpus, patch, and supplemental items MUST be set 506 to "true", or all of the corpus, patch, and supplemental items 507 MUST be set to "false" or be omitted. 509 o If the patch item is set to "true", the the tag SHOULD contain at 510 least one link with the rel(ation) item value of "patches" and an 511 href item specifying an association with the software that was 512 patched. 514 o If the supplemental item is set to "true", the the tag SHOULD 515 contain at least one link with the rel(ation) item value of 516 "suplements" and an href item specifying an association with the 517 software that is supplemented. 519 o If all of the corpus, patch, and supplemental items are "false", 520 or if the corpus item is set to "true", then a software-version 521 item MUST be included with a value set to the version of the 522 software component. This ensure that primary and corpus tags have 523 an identifiable software version. 525 2.2. The global-attributes Group 527 The global-attributes group provides a list of items including an 528 optional language definition to support the processing of text-string 529 values and an unbounded set of any-attribute items allowing for 530 additional items to be provided as a general point of extension in 531 the model. 533 The CDDL for the global-attributes is as follows: 535 536 global-attributes = ( 537 ? lang, 538 * any-attribute, 539 ) 541 label = text / int 543 any-attribute = ( 544 label => text / int / [ 2* text ] / [ 2* int ] 545 ) 547 lang = (15: text) 548 550 The following describes each child item of this object. 552 o lang (index 15): A language tag or corresponding IANA index 553 integer that conforms with IANA Language Subtag Registry 554 [RFC5646]. 556 o any-attribute: This sub-group provides a means to include 557 arbitrary information via label (key) item value pairs where both 558 keys and values can be either a single integer or text string, or 559 an array of integers or text strings. 561 2.3. The any-element-entry 563 The CDDL for the any-element-entry object is as follows: 565 566 any-element-map = { 567 global-attributes, 568 * label => any-element-map / [ 2* any-element-map ], 569 } 570 any-element-entry = (7: any-element-map / [ 2* any-element-map ]) 571 573 The following describes each child item of this object. 575 o global-attributes: The global-attributes group described in 576 Section 2.2. 578 o label: a single or multiple 580 2.4. The entity Object 582 The CDDL for the entity object is as follows: 584 585 entity = { 586 global-attributes, 587 entity-name, 588 ? reg-id, 589 role, 590 ? thumbprint, 591 extended-data, 592 } 594 any-uri = text 596 extended-data = (30: any-element-map / [ 2* any-element-map ]) 597 entity-name = (31: text) 598 reg-id = (32: any-uri) 599 role = (33: text / [2* text]) 600 thumbprint = (34: text) 601 603 The following describes each child item of this object. 605 o global-attributes: The global-attributes group described in 606 Section 2.2. 608 o entity-name (index 32): The text-string name of the organization 609 claiming a particular role in the CoSWID tag. 611 o reg-id (index 32): The registration id is intended to uniquely 612 identify a naming authority in a given scope (e.g. global, 613 organization, vendor, customer, administrative domain, etc.) that 614 is implied by the referenced naming authority. The value of an 615 registration ID MUST be a RFC 3986 URI. The scope SHOULD be the 616 scope of an organization. In a given scope, the registration id 617 MUST be used consistently. 619 o role (index 33): The relationship(s) between this organization and 620 this tag. The role of tag creator is required for every CoSWID 621 tag. The role of an entity may include any role value, but the 622 per-defined roles include: "aggregator", "distributor", 623 "licensor", "software-creator", "tag-creator". The enumerations 624 of this will include a request to IANA in order to be reference- 625 able via an integer index. 627 o thumbprint (index 34): This value provides a hexadecimal string 628 that contains a hash (i.e. the thumbprint) of the signing entities 629 certificate(s). . 631 o extended-data (index 30): An open-ended collection of elements 632 that can be used to attach arbitrary metadata to an entity item. 634 2.5. The link Object 636 The CDDL for the link object is as follows: 638 639 link = { 640 global-attributes, 641 ? artifact, 642 href, 643 ? media 644 ? ownership, 645 rel, 646 ? media-type, 647 ? use, 648 } 649 artifact = (37: text) 650 href = (38: any-uri) 651 media = (10: any-uri) 652 ownership = (39: "shared" / "private" / "abandon") 653 rel = (40: text) 654 media-type = (41: text) 655 use = (42: "optional" / "required" / "recommended") 656 658 The following describes each child item of this object. 660 o global-attributes: The global-attributes group described in 661 Section 2.2. 663 o artifact (index: 37): For installation media (rel="installation- 664 media") - dictates the canonical name for the file. Items with 665 the same artifact name should be considered mirrors of each other 666 (so download from wherever works). 668 o href (index 38): The link to the item being referenced. The href 669 can point to several different things, and can be any of the 670 following: 672 * a relative uri (no scheme), which is interpreted depending on 673 context (for example, "./folder/supplemental.coswid") 675 * a physical file location with any system-acceptable URI scheme 676 (e.g., file:// http:// https:// ftp://) 678 * an URI with "coswid:" as the scheme, which refers to another 679 CoSWID by tag-id. This URI would need to be resolved in the 680 context of the system by software that can lookup other CoSWID 681 tags (for example, 683 * "coswid:2df9de35-0aff-4a86-ace6-f7dddd1ade4c"). an URI with 684 "swidpath:" as the scheme, which refers to another CoSIWD via 685 an XPATH query. This URI would need to be resolved in the 686 context of the system entity via dedicated software components 687 that can lookup other CoSWID tags and select the appropriate 688 tag based on an XPATH query. Examples include: 690 * swidpath://SoftwareIdentity[Entity/@regid='http://contoso.com'] 691 would retrieve all CoSWID tags that include an entity where the 692 regid was "Contoso". 694 * swidpath://SoftwareIdentity[Meta/@persistentId='b0c55172-38e9-4 695 e36-be86-92206ad8eddb'] would retrieve CoSWID tags that matched 696 the persistent-id. 698 * See XPATH query standard : http://www.w3.org/TR/xpath20/ 700 o media (index 10): See media defined in Section 2.1. 702 o ownership (index 39): Determines the relative strength of 703 ownership of the software components. Valid enumerations are: 704 abandon, private, shared 706 o rel (index 40): The relationship between this CoSWID and the 707 target file. Relationships can be identified by referencing the 708 IANA registration library: https://www.iana.org/assignments/link- 709 relations/link-relations.xhtml. 711 o media-type (index 41): The IANA MediaType for the target file; 712 this provides the consumer with intelligence of what to expect. 713 See http://www.iana.org/assignments/media-types/media-types.xhtml 714 for more details on link type. 716 o use (index 42): Determines if the target software is a hard 717 requirement or not. Valid enumerations are: required, 718 recommended, optional. 720 2.6. The software-meta Object 722 The CDDL for the software-meta object is as follows: 724 726 software-meta = { 727 global-attributes, 728 ? activation-status, 729 ? channel-type, 730 ? colloquial-version, 731 ? description, 732 ? edition, 733 ? entitlement-data-required, 734 ? entitlement-key, 735 ? generator, 736 ? persistent-id, 737 ? product, 738 ? product-family, 739 ? revision, 740 ? summary, 741 ? unspsc-code, 742 ? unspsc-version, 743 } 744 activation-status = (43: text) 745 channel-type = (44: text) 746 colloquial-version = (45: text) 747 description = (46: text) 748 edition = (47: text) 749 entitlement-data-required = (48: bool) 750 entitlement-key = (49: text) 751 generator = (50: text) 752 persistent-id = (51: text) 753 product = (52: text) 754 product-family = (53: text) 755 revision = (54: text) 756 summary = (55: text) 757 unspsc-code = (56: text) 758 unspsc-version = (57: text) 759 761 The following describes each child item of this object. 763 o global-attributes: The global-attributes group described in 764 Section 2.2. 766 o activation-status (index 43): Identification of the activation 767 status of this software title (e.g. Trial, Serialized, Licensed, 768 Unlicensed, etc). Typically, this is used in supplemental tags. 770 o channel-type (index 44): Provides information on which channel 771 this particular software was targeted for (e.g. Volume, Retail, 772 OEM, Academic, etc). Typically used in supplemental tags. 774 o colloquial-version (index 45): The informal or colloquial version 775 of the product (i.e. 2013). Note that this version may be the 776 same through multiple releases of a software component where the 777 version specified in entity is much more specific and will change 778 for each software release. Note that this representation of 779 version is typically used to identify a group of specific software 780 releases that are part of the same release/support infrastructure 781 (i.e. Fabrikam Office 2013). This version is used for string 782 comparisons only and is not compared to be an earlier or later 783 release (that is done via the entity version). 785 o description (index 46): A longer, detailed description of the 786 software. This description can be multiple sentences 787 (differentiated from summary, which is a very short, one-sentence 788 description). 790 o edition (index 47): The variation of the product (Extended, 791 Enterprise, Professional, Standard etc). 793 o entitlement-data-required (index 48): An indicator to determine if 794 there should be accompanying proof of entitlement when a software 795 license reconciliation is completed. 797 o entitlement-key (index 49): A vendor-specific textual key that can 798 be used to reconcile the validity of an entitlement. (e.g. serial 799 number, product or license key). 801 o generator (index 50): The name of the software tool that created a 802 CoSWID tag. This item is typically used if tags are created on 803 the fly or via a catalog-based analysis for data found on a 804 computing device. 806 o persistent-id (index 51): A GUID used to represent products 807 installed where the product are related, but may be different 808 versions. For example, an "upgradeCode" (see 809 http://msdn.microsoft.com/en-us/library/aa372375(v=vs.85).aspx as 810 an reference for this example). 812 o product (index 52): The base name of the product (e.g. ). 814 o product-family (index 53): The overall product family this 815 software belongs to. Product family is not used to identify that 816 a product is part of a suite, but is instead used when a set of 817 products that are all related may be installed on multiple 818 different devices. For example, an enterprise backup system may 819 consist of a backup services, multiple different backup services 820 that support mail services, databases and ERP systems, as well as 821 individual software components that backup client system entities. 822 In such an usage scenario, all software components that are part 823 of the backup system would have the same product-family name so 824 they can be grouped together in respect to reporting systems. 826 o revision (index 54): The informal or colloquial representation of 827 the sub-version of the given product (ie, SP1, R2, RC1, Beta 2, 828 etc). Note that the version will provide very exact version 829 details, the revision is intended for use in environments where 830 reporting on the informal or colloquial representation of the 831 software is important (for example, if for a certain business 832 process, an organization recognizes that it must have, for example 833 "ServicePack 1" or later of a specific product installed on all 834 devices, they can use the revision data value to quickly identify 835 any devices that do not meet this requirement). Depending on how 836 a software organizations distributes revisions, this value could 837 be specified in a primary (if distributed as an upgrade) or 838 supplemental (if distributed as a patch) CoSWID tag. 840 o summary (index 55): A short (one-sentence) description of the 841 software. 843 o unspsc-code (index 56): An 8 digit code that provides UNSPSC 844 classification of the software component this SWID tag identifies. 845 For more information see, http://www.unspsc.org/. 847 o unspsc-version (index 57): The version of the UNSPSC code used to 848 define the UNSPSC code value. For more information see, 849 http://www.unspsc.org/. 851 2.7. The Resource Collection Definition 853 2.7.1. The hash-entry Array 855 CoSWID add explicit support for the representation of hash entries 856 using algorithms that are registered at the Named Information Hash 857 Algorithm Registry via the hash-entry member (label 58). 859 hash-entry = (58: [ hash-alg-id: int, hash-value: bstr ] ) 861 The number used as a value for hash-alg-id MUST refer the ID in the 862 Named Information Hash Algorithm table; other hash algorithms MUST 863 NOT be used. The hash-value MUST represent the raw hash value of the 864 hashed resource generated using the hash algorithm indicated by the 865 hash-alg-id. 867 2.7.2. The resource-collection Group 869 A list of items both used in evidence (discovered by an inventory 870 process) and payload (installed in a system entity) content of a 871 CoSWID tag document to structure and differentiate the content of 872 specific CoSWID tag types. Potential content includes directories, 873 files, processes, resources or firmwares. 875 The CDDL for the resource-collection group is as follows: 877 878 resource-collection = ( 879 ? directory-entry, 880 ? file-entry, 881 ? process-entry, 882 ? resource-entry 883 ) 885 directory = { 886 filesystem-item, 887 path-elements, 888 } 890 file = { 891 filesystem-item, 892 ? size, 893 ? file-version, 894 ? hash-entry, 895 } 897 process = { 898 global-attributes, 899 process-name, 900 ? pid, 901 } 903 resource = { 904 global-attributes, 905 type, 906 } 908 filesystem-item = ( 909 global-attributes, 910 ? key, 911 ? location, 912 fs-name, 913 ? root, 914 ) 915 directory-entry = (16: directory / [ 2* directory ]) 916 file-entry = (17: file / [ 2* file ]) 917 process-entry = (18: process / [ 2* process ]) 918 resource-entry = (19: resource / [ 2* resource ]) 919 size = (20: integer) 920 file-version = (21: text) 921 key = (22: bool) 922 location = (23: text) 923 fs-name = (24: text) 924 root = (25: text) 925 path-elements = (26: { * file-entry, 926 * directory-entry, 927 } 928 ) 929 process-name = (27: text) 930 pid = (28: integer) 931 type = (29: text) 932 934 The following describes each child item or group for these groups. 936 o filesystem-item: A list of items both used in representing the 937 nodes of a file-system hierarchy, i.e. directory items that allow 938 one or more directories to be defined in the file structure, and 939 file items that allow one or more files to be specified for a 940 given location. 942 o global-attributes: The global-attributes group described in 943 Section 2.2. 945 o directory-entry (index 16): A directory item allows one or more 946 directories to be defined in the file structure. 948 o file-entry (index 17): A file element that allows one or more 949 files to be specified for a given location. 951 o process-entry (index 18): Provides process (software component in 952 execution) information for data that will show up in a devices 953 process table. 955 o resource-entry (index 19): A set of items that can be used to 956 provide arbitrary resource information about an application 957 installed on a system entity, or evidence collected from a system 958 entity. 960 o size (index 20): The file size in bytes of the file. 962 o file-version (index 21): The version of the file. 964 o key (index 22): Files that are considered important or required 965 for the use of a software component. Typical key files would be 966 those which, if not available on a system entity, would cause the 967 software component not to execute or function properly. Key files 968 will typically be used to validate that a software component 969 referenced by the CoSWID tag document is actually installed on a 970 specific system entity. 972 o location (index 23): The directory or location where a file was 973 found or can expected to be located. This text-string is intended 974 to include the filename itself. This SHOULD be the relative path 975 from the location represented by the root item. 977 o fs-name (index 24): The file name or directory name without any 978 path characters. 980 o root (index 25): A system-specific root folder that the location 981 item is an offset from. If this is not specified the assumption 982 is the root is the same folder as the location of the CoSWID tag. 983 The text-string value represents a path expression relative to the 984 CoSWID tag document location in the (composite) file-system 985 hierarchy. 987 o path-elements (index 26): Provides the ability to apply a 988 directory structure to the path expressions for files defined in a 989 payload or evidence item. 991 o process-name (index 27): The process name as it will be found in 992 the system entity's process table. 994 o pid (index 28): The process ID for the process in execution that 995 can be included in the process item as part of an evidence tag. 997 o type (index 29): The type of resource represented via a text- 998 string (typically, registry-key, port or root-uri). 1000 2.7.3. The payload Object 1002 The CDDL for the payload object is as follows: 1004 payload = { 1005 global-attributes, 1006 resource-collection, 1007 * $$payload-extension 1008 } 1009 1011 The following describes each child item of this object. 1013 o global-attributes: The global-attributes group described in 1014 Section 2.2. 1016 o resource-collection: The resource-collection group described in 1017 Section 2.7.2. 1019 o $$payload-extension: 1021 2.7.4. The evidence Object 1023 The CDDL for the evidence object is as follows: 1025 1026 evidence = { 1027 global-attributes, 1028 resource-collection, 1029 ? date, 1030 ? device-id, 1031 * $$evidence-extension 1032 } 1033 date = (35: time) 1034 device-id = (36: text) 1035 1037 The following describes each child item of this object. 1039 o global-attributes: The global-attributes group described in 1040 Section 2.2. 1042 o resource-collection: The resource-collection group described in 1043 Section 2.7.2. 1045 o date (index 35): The date and time evidence represented by an 1046 evidence item was gathered. 1048 o device-id (index 36): A text-string identifier for a device 1049 evidence was gathered from. 1051 o $$evidence-extension: 1053 2.8. Full CDDL Definition 1055 In order to create a valid CoSWID document the structure of the 1056 corresponding CBOR message MUST adhere to the following CDDL data 1057 definition. 1059 1060 concise-software-identity = { 1061 global-attributes, 1062 tag-id, 1063 tag-version, 1064 ? corpus, 1065 ? patch, 1066 ? supplemental, 1067 swid-name, 1068 ? software-version, 1069 ? version-scheme, 1070 ? media, 1071 ? software-meta-entry, 1072 ? entity-entry, 1073 ? link-entry, 1074 ? ( payload-entry / evidence-entry ), 1075 ? any-element-entry, 1076 } 1078 any-uri = text 1079 label = text / int 1081 any-attribute = ( 1082 label => text / int / [ 2* text ] / [ 2* int ] 1083 ) 1085 any-element-map = { 1086 global-attributes, 1087 * label => any-element-map / [ 2* any-element-map ], 1088 } 1090 global-attributes = ( 1091 ? lang, 1092 * any-attribute, 1093 ) 1095 resource-collection = ( 1096 ? directory-entry, 1097 ? file-entry, 1098 ? process-entry, 1099 ? resource-entry 1100 ) 1102 file = { 1103 filesystem-item, 1104 ? size, 1105 ? file-version, 1106 ? hash-entry, 1107 } 1108 filesystem-item = ( 1109 global-attributes, 1110 ? key, 1111 ? location, 1112 fs-name, 1113 ? root, 1114 ) 1116 directory = { 1117 filesystem-item, 1118 path-elements, 1119 } 1121 process = { 1122 global-attributes, 1123 process-name, 1124 ? pid, 1125 } 1127 resource = { 1128 global-attributes, 1129 type, 1130 } 1132 entity = { 1133 global-attributes, 1134 entity-name, 1135 ? reg-id, 1136 role, 1137 ? thumbprint, 1138 extended-data, 1139 } 1141 evidence = { 1142 global-attributes, 1143 resource-collection, 1144 ? date, 1145 ? device-id, 1146 * $$evidence-extension 1147 } 1149 link = { 1150 global-attributes, 1151 ? artifact, 1152 href, 1153 ? media 1154 ? ownership, 1155 rel, 1156 ? media-type, 1157 ? use, 1158 } 1160 software-meta = { 1161 global-attributes, 1162 ? activation-status, 1163 ? channel-type, 1164 ? colloquial-version, 1165 ? description, 1166 ? edition, 1167 ? entitlement-data-required, 1168 ? entitlement-key, 1169 ? generator, 1170 ? persistent-id, 1171 ? product, 1172 ? product-family, 1173 ? revision, 1174 ? summary, 1175 ? unspsc-code, 1176 ? unspsc-version, 1177 } 1179 payload = { 1180 global-attributes, 1181 resource-collection, 1182 * $$payload-extension 1183 } 1185 tag-id = (0: text) 1186 swid-name = (1: text) 1187 entity-entry = (2: entity / [ 2* entity ]) 1188 evidence-entry = (3: evidence) 1189 link-entry = (4: link / [ 2* link ]) 1190 software-meta-entry = (5: software-meta / [ 2* software-meta ]) 1191 payload-entry = (6: payload) 1192 any-element-entry = (7: any-element-map / [ 2* any-element-map ]) 1193 corpus = (8: bool) 1194 patch = (9: bool) 1195 media = (10: text) 1196 supplemental = (11: bool) 1197 tag-version = (12: integer) 1198 software-version = (13: text) 1199 version-scheme = (14: text / int) 1200 lang = (15: text) 1201 directory-entry = (16: directory / [ 2* directory ]) 1202 file-entry = (17: file / [ 2* file ]) 1203 process-entry = (18: process / [ 2* process ]) 1204 resource-entry = (19: resource / [ 2* resource ]) 1205 size = (20: integer) 1206 file-version = (21: text) 1207 key = (22: bool) 1208 location = (23: text) 1209 fs-name = (24: text) 1210 root = (25: text) 1211 path-elements = (26: { * file-entry, 1212 * directory-entry, 1213 } 1214 ) 1215 process-name = (27: text) 1216 pid = (28: integer) 1217 type = (29: text) 1218 extended-data = (30: any-element-map / [ 2* any-element-map ]) 1219 entity-name = (31: text) 1220 reg-id = (32: any-uri) 1221 role = (33: text / [2* text]) 1222 thumbprint = (34: text) 1223 date = (35: time) 1224 device-id = (36: text) 1225 artifact = (37: text) 1226 href = (38: any-uri) 1227 ownership = (39: "shared" / "private" / "abandon") 1228 rel = (40: text) 1229 media-type = (41: text) 1230 use = (42: "optional" / "required" / "recommended") 1231 activation-status = (43: text) 1232 channel-type = (44: text) 1233 colloquial-version = (45: text) 1234 description = (46: text) 1235 edition = (47: text) 1236 entitlement-data-required = (48: bool) 1237 entitlement-key = (49: text) 1238 generator = (50: text) 1239 persistent-id = (51: text) 1240 product = (52: text) 1241 product-family = (53: text) 1242 revision = (54: text) 1243 summary = (55: text) 1244 unspsc-code = (56: text) 1245 unspsc-version = (57: text) 1246 hash-entry = (58: [ hash-alg-id: int, 1247 hash-value: bstr, 1248 ] 1249 ) 1250 1252 3. CoSWID Indexed Label Values 1254 3.1. Version Scheme 1256 The following are an initial set of values for use in the version- 1257 scheme item for the version schemes defined in the ISO/IEC 1258 19770-2:2015 [SWID] specification. Index value in parens indicates 1259 the index value to use in the version-scheme item. 1261 o multipartnumeric (index 0): Numbers separated by dots, where the 1262 numbers are interpreted as integers (e.g.,1.2.3, 1.4.5, 1263 1.2.3.4.5.6.7) 1265 o multipartnumeric+suffix (index 1): Numbers separated by dots, 1266 where the numbers are interpreted as integers with an additional 1267 string suffix(e.g., 1.2.3a) 1269 o alphanumeric (index 2): Strictly a string, sorting is done 1270 alphanumerically 1272 o decimal (index 3): A floating point number (e.g., 1.25 is less 1273 than 1.3) 1275 o semver (index 4): Follows the [SEMVER] specification 1277 The values above are registered in the "SWID/CoSWID Version Schema 1278 Values" registry defined in section Section 4.1. Additional valid 1279 values will likely be registered over time in this registry. 1281 3.2. Entity Role Values 1283 The following table indicates the index value to use for the entity 1284 roles defined in the ISO/IEC 19770-2:2015 [SWID] specification. 1286 | Index | Role Name | 1287 |-------+--------------------------+ 1288 | 0 | tagCreator | 1289 | 1 | softwareCreator | 1290 | 2 | aggregator | 1291 | 3 | distributor | 1292 | 4 | licensor | 1294 The values above are registered in the "SWID/CoSWID Entity Role 1295 Values" registry defined in section Section 4.2. Additional valid 1296 values will likely be registered over time. Additionally, the index 1297 values 226 through 255 have been reserved for private use. 1299 4. IANA Considerations 1301 This document will include requests to IANA: 1303 o Integer indices for SWID content attributes and information 1304 elements. 1306 o Content-Type for CoAP to be used in COSE. 1308 This document has a number of IANA considerations, as described in 1309 the following subsections. 1311 4.1. SWID/CoSWID Version Schema Values Registry 1313 This document uses unsigned 16-bit index values to version-scheme 1314 item values. The initial set of version-scheme values are derived 1315 from the textual version scheme names defined in the ISO/IEC 1316 19770-2:2015 specification [SWID]. 1318 This document defines a new a new registry entitled "SWID/CoSWID 1319 Version Schema Values". Future registrations for this registry are 1320 to be made based on [RFC8126] as follows: 1322 | Range | Registration Procedures | 1323 |--------------+--------------------------+ 1324 | 0-16383 | Standards Action | 1325 | 16384-32767 | Specification Required | 1326 | 32768-65535 | Reserved for Private Use | 1328 Initial registrations for the SWID/CoSWID Version Schema Values 1329 registry are provided below. 1331 | Index | Role Name | Specification | 1332 |-------------+--------------------------+-----------------| 1333 | 0 | multipartnumeric | See section 3.1 | 1334 | 1 | multipartnumeric+suffix | See section 3.1 | 1335 | 2 | alphanumeric | See section 3.1 | 1336 | 3 | decimal | See section 3.1 | 1337 | 4-16383 | Unassigned | | 1338 | 16384 | semver | {{SEMVER}} | 1339 | 16385-32767 | Unassigned | | 1340 | 32768-65535 | Reserved for Private Use | | 1342 4.2. SWID/CoSWID Entity Role Values Registry 1344 This document uses unsigned 8-bit index values to represent entity- 1345 role values. The initial set of Entity roles are derived from the 1346 textual role names defined in the ISO/IEC 19770-2:2015 specification 1347 [SWID]. 1349 This document defines a new a new registry entitled "SWID/CoSWID 1350 Entity Role Values". Future registrations for this registry are to 1351 be made based on [RFC8126] as follows: 1353 | Range | Registration Procedures | 1354 |---------+----------------------------+ 1355 | 0-31 | Standards Action | 1356 | 32-127 | Specification Required | 1357 | 128-255 | Reserved for Private Use | 1359 Initial registrations for the SWID/CoSWID Entity Role Values registry 1360 are provided below. 1362 | Index | Role Name | Specification | 1363 |---------+--------------------------+-----------------| 1364 | 0 | tagCreator | See section 3.2 | 1365 | 1 | softwareCreator | See section 3.2 | 1366 | 2 | aggregator | See section 3.2 | 1367 | 3 | distributor | See section 3.2 | 1368 | 4 | licensor | See section 3.2 | 1369 | 5-49 | Unassigned | | 1370 | 50-225 | Unassigned | | 1371 | 225-255 | Reserved for Private Use | | 1373 5. Security Considerations 1375 SWID tags contain public information about software components and, 1376 as such, do not need to be protected against disclosure on an 1377 endpoint. Similarly, SWID tags are intended to be easily 1378 discoverable by applications and users on an endpoint in order to 1379 make it easy to identify and collect all of an endpoint's SWID tags. 1380 As such, any security considerations regarding SWID tags focus on the 1381 application of SWID tags to address security challenges, and the 1382 possible disclosure of the results of those applications. 1384 A signed SWID tag whose signature is intact can be relied upon to be 1385 unchanged since it was signed. If the SWID tag was created by the 1386 software author, this generally means that it has undergone no change 1387 since the software application with which the tag is associated was 1388 installed. By implication, this means that the signed tag reflects 1389 the software author's understanding of the details of that software 1390 product. This can be useful assurance when the information in the 1391 tag needs to be trusted, such as when the tag is being used to convey 1392 golden measurements. By contrast, the data contained in unsigned 1393 tags cannot be trusted to be unmodified. 1395 SWID tags are designed to be easily added and removed from an 1396 endpoint along with the installation or removal of software 1397 components. On endpoints where addition or removal of software 1398 components is tightly controlled, the addition or removal of SWID 1399 tags can be similarly controlled. On more open systems, where many 1400 users can manage the software inventory, SWID tags may be easier to 1401 add or remove. On such systems, it may be possible to add or remove 1402 SWID tags in a way that does not reflect the actual presence or 1403 absence of corresponding software components. Similarly, not all 1404 software products automatically install SWID tags, so products may be 1405 present on an endpoint without providing a corresponding SWID tag. 1406 As such, any collection of SWID tags cannot automatically be assumed 1407 to represent either a complete or fully accurate representation of 1408 the software inventory of the endpoint. However, especially on 1409 devices that more strictly control the ability to add or remove 1410 applications, SWID tags are an easy way to provide an preliminary 1411 understanding of that endpoint's software inventory. 1413 Any report of an endpoint's SWID tag collection provides information 1414 about the software inventory of that endpoint. If such a report is 1415 exposed to an attacker, this can tell them which software products 1416 and versions thereof are present on the endpoint. By examining this 1417 list, the attacker might learn of the presence of applications that 1418 are vulnerable to certain types of attacks. As noted earlier, SWID 1419 tags are designed to be easily discoverable by an endpoint, but this 1420 does not present a significant risk since an attacker would already 1421 need to have access to the endpoint to view that information. 1422 However, when the endpoint transmits its software inventory to 1423 another party, or that inventory is stored on a server for later 1424 analysis, this can potentially expose this information to attackers 1425 who do not yet have access to the endpoint. As such, it is important 1426 to protect the confidentiality of SWID tag information that has been 1427 collected from an endpoint, not because those tags individually 1428 contain sensitive information, but because the collection of SWID 1429 tags and their association with an endpoint reveals information about 1430 that endpoint's attack surface. 1432 Finally, both the ISO-19770-2:2015 XML schema definition and the 1433 Concise SWID data definition allow for the construction of "infinite" 1434 SWID tags or SWID tags that contain malicious content with the intend 1435 if creating non-deterministic states during validation or processing 1436 of SWID tags. While software product vendors are unlikely to do 1437 this, SWID tags can be created by any party and the SWID tags 1438 collected from an endpoint could contain a mixture of vendor and non- 1439 vendor created tags. For this reason, tools that consume SWID tags 1440 ought to treat the tag contents as potentially malicious and should 1441 employ input sanitizing on the tags they ingest. 1443 6. Acknowledgments 1445 7. Change Log 1447 Changes from version 03 to version 04: 1449 o Re-index label values in the CDDL. 1451 o Added a section describing the CoSWID model in detail. 1453 o Created IANA registries for entity-role and version-scheme 1455 Changes from version 02 to version 03: 1457 o Updated CDDL to allow for a choice between a payload or evidence 1459 o Re-index label values in the CDDL. 1461 o Added item definitions 1463 o Updated references for COSE, CBOR Web Token, and CDDL. 1465 Changes from version 01 to version 02: 1467 o Added extensions for Firmware and CoSWID use as Reference 1468 Integrity Measurements (CoSWID RIM) 1470 o Changes meta handling in CDDL from use of an explicit use of items 1471 to a more flexible unconstrained collection of items. 1473 o Added sections discussing use of COSE Signatures and CBOR Web 1474 Tokens 1476 Changes from version 00 to version 01: 1478 o Added CWT usage for absolute SWID paths on a device 1480 o Fixed cardinality of type-choices including arrays 1482 o Included first iteration of firmware resource-collection 1483 Changes since adopted as a WG I-D -00: 1485 o Removed redundant any-attributes originating from the ISO- 1486 19770-2:2015 XML schema definition 1488 o Fixed broken multi-map members 1490 o Introduced a more restrictive item (any-element-map) to represent 1491 custom maps, increased restriction on types for the any-attribute, 1492 accordingly 1494 o Fixed X.1520 reference 1496 o Minor type changes of some attributes (e.g. NMTOKENS) 1498 o Added semantic differentiation of various name types (e,g. fs- 1499 name) 1501 Changes from version 00 to version 01: 1503 o Ambiguity between evidence and payload eliminated by introducing 1504 explicit members (while still 1506 o allowing for "empty" SWID tags) 1508 o Added a relatively restrictive COSE envelope using cose_sign1 to 1509 define signed CoSWID (single signer only, at the moment) 1511 o Added a definition how to encode hashes that can be stored in the 1512 any-member using existing IANA tables to reference hash-algorithms 1514 Changes from version 01 to version 02: 1516 o Enforced a more strict separation between the core CoSWID 1517 definition and additional usage by moving content to corresponding 1518 appendices. 1520 o Removed artifacts inherited from the reference schema provided by 1521 ISO (e.g. NMTOKEN(S)) 1523 o Simplified the core data definition by removing group and type 1524 choices where possible 1526 o Minor reordering of map members 1528 o Added a first extension point to address requested flexibility for 1529 extensions beyond the any-element 1531 8. Contributors 1533 9. References 1535 9.1. Normative References 1537 [I-D.ietf-ace-cbor-web-token] 1538 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1539 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-12 1540 (work in progress), February 2018. 1542 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1543 Requirement Levels", BCP 14, RFC 2119, 1544 DOI 10.17487/RFC2119, March 1997, 1545 . 1547 [RFC4108] Housley, R., "Using Cryptographic Message Syntax (CMS) to 1548 Protect Firmware Packages", RFC 4108, 1549 DOI 10.17487/RFC4108, August 2005, 1550 . 1552 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1553 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1554 September 2009, . 1556 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1557 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1558 October 2013, . 1560 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1561 Writing an IANA Considerations Section in RFCs", BCP 26, 1562 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1563 . 1565 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1566 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1567 . 1569 [SAM] "Information technology - Software asset management - Part 1570 5: Overview and vocabulary", ISO/IEC 19770-5:2013, 1571 November 2013. 1573 [SEMVER] Preston-Werner, T., "Semantic Versioning 2.0.0", n.d., 1574 . 1576 [SWID] "Information technology - Software asset management - Part 1577 2: Software identification tag", ISO/IEC 19770-2:2015, 1578 October 2015. 1580 [SWID-GUIDANCE] 1581 Waltermire, D., Cheikes, B., Feldman, L., and G. Witte, 1582 "Guidelines for the Creation of Interoperable Software 1583 Identification (SWID) Tags", NISTIR 8060, April 2016, 1584 . 1586 [X.1520] "Recommendation ITU-T X.1520 (2014), Common 1587 vulnerabilities and exposures", April 2011. 1589 9.2. Informative References 1591 [I-D.banghart-sacm-rolie-softwaredescriptor] 1592 Waltermire, D. and S. Banghart, "Definition of the ROLIE 1593 Software Descriptor Extension", draft-banghart-sacm-rolie- 1594 softwaredescriptor-01 (work in progress), May 2017. 1596 [I-D.birkholz-tuda] 1597 Fuchs, A., Birkholz, H., McDonald, I., and C. Bormann, 1598 "Time-Based Uni-Directional Attestation", draft-birkholz- 1599 tuda-04 (work in progress), March 2017. 1601 [I-D.greevenbosch-appsawg-cbor-cddl] 1602 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1603 definition language (CDDL): a notational convention to 1604 express CBOR data structures", draft-greevenbosch-appsawg- 1605 cbor-cddl-11 (work in progress), July 2017. 1607 [I-D.ietf-sacm-terminology] 1608 Birkholz, H., Lu, J., Strassner, J., Cam-Winget, N., and 1609 A. Montville, "Security Automation and Continuous 1610 Monitoring (SACM) Terminology", draft-ietf-sacm- 1611 terminology-14 (work in progress), December 2017. 1613 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1614 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1615 . 1617 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1618 Constrained-Node Networks", RFC 7228, 1619 DOI 10.17487/RFC7228, May 2014, 1620 . 1622 Appendix A. CoSWID Attributes for Firmware (label 60) 1624 The ISO-19770-2:2015 specification of SWID tags assumes the existence 1625 of a file system a software component is installed and stored in. In 1626 the case of constrained-node networks [RFC7228] or network equipment 1627 this assumption might not apply. Concise software instances in the 1628 form of (modular) firmware are often stored directly on a block 1629 device that is a hardware component of the constrained-node or 1630 network equipment. Multiple differentiable block devices or 1631 segmented block devices that contain parts of modular firmware 1632 components (potentially each with their own instance version) are 1633 already common at the time of this writing. 1635 The optional attributes that annotate a firmware package address 1636 specific characteristics of pieces of firmware stored directly on a 1637 block-device in contrast to software deployed in a file-system. In 1638 essence, trees of relative path-elements expressed by the directory 1639 and file structure in CoSWID tags are typically unable to represent 1640 the location of a firmware on a constrained-node (small thing). The 1641 composite nature of firmware and also the actual composition of small 1642 things require a set of attributes to address the identification of 1643 the correct component in a composite thing for each individual piece 1644 of firmware. A single component also potentially requires a number 1645 of distinct firmware parts that might depend on each other 1646 (versions). These dependencies can be limited to the scope of the 1647 component itself or extend to the scope of a larger composite device. 1648 In addition, it might not be possible (or feasible) to store a CoSWID 1649 tag document (permanently) on a small thing along with the 1650 corresponding piece of firmware. 1652 To address the specific characteristics of firmware, the extension 1653 points "$$payload-extension" and "$$evidence-extension" are used to 1654 allow for an additional type of resource description--firmware- 1655 entry--thereby increasing the self-descriptiveness and flexibility of 1656 CoSWID. The optional use of the extension points "$$payload- 1657 extension" and "$$evidence-extension" in respect to firmware MUST 1658 adhere to the following CDDL data definition. 1660 1661 $$payload-extension //= (firmware-entry,) 1662 $$evidence-extension //= (firmware-entry,) 1664 firmware = { 1665 firmware-name, ; inherited from RFC4108 1666 ? firmware-version, 1667 ? firmware-package-identifier, ; inherited from RFC4108 1668 ? dependency, ; inherited from RFC4108 1669 ? component-index, ; equivalent to RFC4108 fwPkgType 1670 ? block-device-identifier, 1671 ? target-hardware-identifier, ; an RFC4108 alternative to model-label 1672 model-label, 1673 ? hash-entry, ; a hash for a single, incl. NI hash-algo index 1674 ? cms-firmware-package, ; RCF4108, experimental, this is an actual firmware blob! 1675 } 1677 firmware-entry = (60: firmware / [ 2* firmware ]) 1678 firmware-name = (61 : text) 1679 firmware-version = (62 : text / int) 1680 component-index = (63 : int) 1681 model-label = (64 text / int) 1682 block-device-identifier = (65 : text / int) 1683 cms-firmware-package = (66: bstr) 1684 firmware-package-identifier = (67: text) 1685 target-hardware-identifier = (68: text) 1686 dependency = (69: { ? firmware-name, 1687 ? firmware-version, 1688 ? firmware-package-identifier, 1689 } 1690 ) 1691 1693 The members of the firmware group that constitutes the content of the 1694 firmware-entry is based on the metadata about firmware Described in 1695 [RFC4108]. As with every semantic differentiation that is supported 1696 by the resource-collection type, the use of firmware-entry is 1697 optional. It is REQUIRED not to instantiate more than one firmware- 1698 entry, as the firmware group is used in a map and therefore only 1699 allows for unique labels. 1701 The optional cms-firmware-package member allows to include the actual 1702 firmware in the CoSWID tag that also expresses its metadata as a 1703 byte-string. This option enables a CoSWID tag to be used as a 1704 container or wrapper that composes both firmware and its metadata in 1705 a single document (which again can be signed, encrypted and/or 1706 compressed). In consequence, a CoSWID tag about firmware can be 1707 conveyed as an identifying document across endpoints or used as a 1708 reference integrity measurement as usual. Alternatively, it can also 1709 convey an actual piece of firmware, serve its intended purpose as a 1710 SWID tag and then - due to the lack of a location to store it - be 1711 discarded. 1713 Appendix B. Signed Concise SWID Tags using COSE 1715 SWID tags, as defined in the ISO-19770-2:2015 XML schema, can include 1716 cryptographic signatures to protect the integrity of the SWID tag. 1717 In general, tags are signed by the tag creator (typically, although 1718 not exclusively, the vendor of the software component that the SWID 1719 tag identifies). Cryptographic signatures can make any modification 1720 of the tag detectable, which is especially important if the integrity 1721 of the tag is important, such as when the tag is providing reference 1722 integrity measurements for files. 1724 The ISO-19770-2:2015 XML schema uses XML DSIG to support 1725 cryptographic signatures. CoSWID tags require a different signature 1726 scheme than this. COSE (CBOR Object Signing and Encryption) provides 1727 the required mechanism [RFC8152]. Concise SWID can be wrapped in a 1728 COSE Single Signer Data Object (cose-sign1) that contains a single 1729 signature. The following CDDL defines a more restrictive subset of 1730 header attributes allowed by COSE tailored to suit the requirements 1731 of Concise SWID. 1733 1734 signed-coswid = #6.997(COSE-Sign1-coswid) ; see TBS7 in current COSE I-D 1736 label = int / tstr ; see COSE I-D 1.4. 1737 values = any ; see COSE I-D 1.4. 1739 unprotected-signed-coswid-header = { 1740 1 => int, ; algorithm identifier 1741 3 => "application/coswid", ; request for CoAP IANA registry to become an int 1742 * label => values, 1743 } 1745 protected-signed-coswid-header = { 1746 4 => bstr, ; key identifier 1747 * label => values, 1748 } 1750 COSE-Sign1-coswid = [ 1751 protected: bstr .cbor protected-signed-coswid-header, 1752 unprotected: unprotected-signed-coswid-header, 1753 payload: bstr .cbor concise-software-identity, 1754 signature: bstr, 1755 ] 1756 1758 Appendix C. CoSWID used as Reference Integrity Measurements (CoSWID 1759 RIM) 1761 A vendor supplied signed CoSWID tag that includes hash-values for the 1762 files that compose a software component can be used as a RIM 1763 (reference integrity measurement). A RIM is a type of declarative 1764 guidance that can be used to assert the compliance of an endpoint by 1765 assessing the installed software. In the context of remote 1766 attestation based on an attestation via hardware rooted trust, a 1767 verifier can appraise the integrity of the conveyed measurements of 1768 software components using a CoSWID RIM provided by a source, such as 1769 [I-D.banghart-sacm-rolie-softwaredescriptor]. 1771 RIM Manifests (RIMM): A group of SWID tags about the same 1772 (sub-)system, system entity, or (sub-)component (compare 1773 [RFC4949]). A RIMM manifest is a distinct document that is 1774 typically conveyed en-block and constitutes declarative guidance 1775 in respect to a specific (target) endpoint (compare 1776 [I-D.ietf-sacm-terminology]). 1778 If multiple CoSWID compose a RIMM, the following CDDL data definition 1779 SHOULD be used. 1781 RIMM = [ + concise-software-identity / signed-coswid ] 1783 Appendix D. CBOR Web Token for Concise SWID Tags 1785 A typical requirement regarding specific instantiations of endpoints 1786 - and, as a result, specific instantiations of software components - 1787 is a representation of the absolute path of a CoSWID tag document in 1788 a file system in order to derive absolute paths of files represented 1789 in the corresponding CoSWID tag. The absolute path of an evidence 1790 CoSWID tag can be included as a claim in the header of a CBOR Web 1791 Token [I-D.ietf-ace-cbor-web-token]. Depending on the source of the 1792 token, the claim can be in the protected or unprotected header 1793 portion. 1795 1796 CDDL TBD 1797 1799 Authors' Addresses 1801 Henk Birkholz 1802 Fraunhofer SIT 1803 Rheinstrasse 75 1804 Darmstadt 64295 1805 Germany 1807 Email: henk.birkholz@sit.fraunhofer.de 1809 Jessica Fitzgerald-McKay 1810 Department of Defense 1811 9800 Savage Road 1812 Ft. Meade, Maryland 1813 USA 1815 Email: jmfitz2@nsa.gov 1817 Charles Schmidt 1818 The MITRE Corporation 1819 202 Burlington Road 1820 Bedford, Maryland 01730 1821 USA 1823 Email: cmschmidt@mitre.org 1824 David Waltermire 1825 National Institute of Standards and Technology 1826 100 Bureau Drive 1827 Gaithersburg, Maryland 20877 1828 USA 1830 Email: david.waltermire@nist.gov