idnits 2.17.1 draft-ietf-sacm-coswid-03.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 15 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 04, 2018) is 2297 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 873, but not defined == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-10 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Downref: Normative reference to an Informational RFC: RFC 7228 ** 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. 'SWID' == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-00 == Outdated reference: A later version (-16) exists of draft-ietf-sacm-terminology-14 Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 3 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: July 8, 2018 Department of Defense 6 C. Schmidt 7 The MITRE Corporation 8 D. Waltermire 9 NIST 10 January 04, 2018 12 Concise Software Identifiers 13 draft-ietf-sacm-coswid-03 15 Abstract 17 This document defines a concise representation of ISO 19770-2:2015 18 Software Identifiers (SWID tags) that is interoperable with the XML 19 schema definition of ISO 19770-2:2015 and augmented for application 20 in Constrained-Node Networks. Next to the inherent capability of 21 SWID tags to express arbitrary context information, CoSWID support 22 the definition of additional semantics via well-defined data 23 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 July 8, 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Concise SWID Extensions . . . . . . . . . . . . . . . . . 4 61 1.2. Requirements Notation . . . . . . . . . . . . . . . . . . 4 62 2. Concise SWID Data Definition . . . . . . . . . . . . . . . . 4 63 3. Description of the SWID Attribute Vocabulary Definition . . . 9 64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 67 7. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 12 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 71 9.2. Informative References . . . . . . . . . . . . . . . . . 13 72 Appendix A. Explicit file-hash Type Used in Concise SWID Tags 73 (label 56) . . . . . . . . . . . . . . . . . . . . . 14 74 Appendix B. CoSWID Attributes for Firmware (label 57) . . . . . 14 75 Appendix C. Signed Concise SWID Tags using COSE . . . . . . . . 16 76 Appendix D. CoSWID used as Reference Integrity Measurements 77 (CoSWID RIM) . . . . . . . . . . . . . . . . . . . . 17 78 Appendix E. CBOR Web Token for Concise SWID Tags . . . . . . . . 18 79 Appendix F. Group Definitions . . . . . . . . . . . . . . . . . 18 80 Appendix G. Item Definitions . . . . . . . . . . . . . . . . . . 19 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 83 1. Introduction 85 SWID tags have several use-applications including but not limited to: 87 o Software Inventory Management, a part of the Software Asset 88 Management [SAM] process, which requires an accurate list of 89 discernible deployed software components. 91 o Vulnerability Assessment, which requires a semantic link between 92 standardized vulnerability descriptions and IT-assets [X.1520]. 94 o Remote Attestation, which requires a link between reference 95 integrity measurements (RIM) and security logs of measured 96 software components [I-D.birkholz-tuda]. 98 SWID tags, as defined in ISO-19770-2:2015 [SWID], provide a 99 standardized format for a record that identifies and describes a 100 specific release of a software product. Different software products, 101 and even different releases of a particular software product, each 102 have a different SWID tag record associated with them. In addition 103 to defining the format of these records, ISO-19770-2:2015 defines 104 requirements concerning the SWID tag life-cycle. Specifically, when 105 a software product is installed on an endpoint, that product's SWID 106 tag is also installed. Likewise, when the product is uninstalled or 107 replaced, the SWID tag is deleted or replaced, as appropriate. As a 108 result, ISO-19770-2:2015 describes a system wherein there is a 109 correspondence between the set of installed software products on an 110 endpoint, and the presence on that endpoint of the SWID tags 111 corresponding to those products. 113 SWID tags are meant to be flexible and able to express a broad set of 114 metadata about a software product. Moreover, there are multiple 115 types of SWID tags, each providing different types of information. 116 For example, a "corpus tag" is used to describe an application's 117 installation image on an installation media, while a "patch tag" is 118 meant to describe a patch that modifies some other application. 119 While there are very few required fields in SWID tags, there are many 120 optional fields that support different uses of these different types 121 of tags. While a SWID tag that consisted only of required fields 122 could be a few hundred bytes in size, a tag containing many of the 123 optional fields could be many orders of magnitude larger. 125 This document defines a more concise representation of SWID tags in 126 the Concise Binary Object Representation (CBOR) [RFC7049]. This is 127 described via the Concise Data Definition Language (CDDL) 128 [I-D.ietf-cbor-cddl]. The resulting Concise SWID data definition is 129 interoperable with the XML schema definition of ISO-19770-2:2015 130 [SWID]. The vocabulary, i.e., the CDDL names of the types and 131 members used in the CoSWID data definition, is mapped to more concise 132 labels represented as small integers. The names used in the CDDL 133 data definition and the mapping to the CBOR representation using 134 integer labels is based on the vocabulary of the XML attribute and 135 element names defined in ISO-19770-2:2015. 137 Real-world instances of SWID tags can be fairly large, and the 138 communication of SWID tags in use-applications such as those 139 described earlier can cause a large amount of data to be transported. 140 This can be larger than acceptable for constrained devices and 141 networks. CoSWID tags significantly reduce the amount of data 142 transported as compared to a typical SWID tag. This reduction is 143 enable through the use of CBOR, which maps human-readable labels of 144 that content to more concise integer labels (indices). This allows 145 SWID tags to be part of an enterprise security solution for a wider 146 range of endpoints and environments. 148 1.1. Concise SWID Extensions 150 This document specifies a standard equivalent to the ISO-19770-2:2015 151 standard. The corresponding CoSWID data definition includes two 152 kinds of augmentation. 154 o the explicit definition of types for attributes that are typically 155 stored in the "any attribute" of an ISO-19770-2:2015 in XML 156 representation. These are covered in the main body of this 157 document. 159 o the inclusion of extension points in the CoSWID data definition 160 that allow for additional uses of CoSWID tags that go beyond the 161 original scope of ISO-19770-2:2015 tags. These are covered in 162 appendices to this document. 164 1.2. Requirements Notation 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 168 "OPTIONAL" in this document are to be interpreted as described in RFC 169 2119, BCP 14 [RFC2119]. 171 2. Concise SWID Data Definition 173 The following is a CDDL representation of the ISO-19770-2:2015 [SWID] 174 XML schema definition of SWID tags. This representation includes 175 every SWID tag fields and attribute and thus supports all SWID tag 176 use cases. The CamelCase notation used in the XML schema definition 177 is changed to a hyphen-separated notation (e.g. ResourceCollection 178 is named resource-collection in the CoSWID data definition). This 179 deviation from the original notation used in the XML representation 180 reduces ambiguity when referencing certain attributes in 181 corresponding textual descriptions. An attribute referred by its 182 name in CamelCase notation explicitly relates to XML SWID tags, an 183 attribute referred by its name in hyphen-separated notation 184 explicitly relates to CoSWID tags. This approach simplifies the 185 composition of further work that reference both XML SWID and CoSWID 186 documents. 188 Human-readable names of members in the CDDL data definition are 189 mapped to integer indices via a block of rules at the bottom of the 190 definition. The 66 character strings of the SWID vocabulary that 191 would have to be stored or transported in full if using the original 192 vocabulary are replaced. 194 Concise Software Identifiers are tailored to be used in the domain of 195 constrained-node networks. A typical endpoint is capable of storing 196 the CoSWID tag of installed software, a constrained-node might lack 197 that capability. CoSWID address these constraints and the 198 corresponding specification is augmented to retain their usefulness 199 in the thing-2-thing domain. Specific examples include, but are not 200 limited to limiting the scope of hash algorithms to the IANA Named 201 Information tables or including firmware attributes addressing 202 devices that do not necessarily provide a file-system to store a 203 CoSWID tag in. 205 In order to create a valid CoSWID document the structure of the 206 corresponding CBOR message MUST adhere to the following CDDL data 207 definition. 209 210 concise-software-identity = { 211 global-attributes, 212 ? entity-entry, 213 ? payload-xor-evidence-entry, 214 ? link-entry, 215 ? software-meta-entry, 216 ; ? payload-entry, 217 ? any-element-entry, 218 ? corpus, 219 ? patch, 220 ? media, 221 swid-name, 222 ? supplemental, 223 tag-id, 224 ? tag-version, 225 ? software-version, 226 ? version-scheme, 227 } 229 any-uri = text 230 label = text / int 232 any-attribute = ( 233 label => text / int / [ 2* text ] / [ 2* int ] 234 ) 236 any-element-map = { 237 global-attributes, 238 * label => any-element-map / [ 2* any-element-map ], 239 } 241 global-attributes = ( 242 ? lang, 243 * any-attribute, 244 ) 246 resource-collection = ( 247 ? directory-entry, 248 ? file-entry, 249 ? process-entry, 250 ? resource-entry 251 * $$resource-extension 252 ) 254 file = { 255 filesystem-item, 256 ? size, 257 ? file-version, 258 ? file-hash, 259 } 261 filesystem-item = ( 262 global-attributes, 263 ? key, 264 ? location, 265 fs-name, 266 ? root, 267 ) 269 directory = { 270 filesystem-item, 271 path-elements, 272 } 274 process = { 275 global-attributes, 276 process-name, 277 ? pid, 278 } 280 resource = { 281 global-attributes, 282 type, 283 } 285 entity = { 286 global-attributes, 287 extended-data, 288 entity-name, 289 ? reg-id, 290 role, 291 ? thumbprint, 292 } 294 evidence = { 295 global-attributes, 296 resource-collection, 297 ? date, 298 ? device-id, 299 } 301 link = { 302 global-attributes, 303 ? artifact, 304 href, 305 ? media-type, 306 ? ownership, 307 rel, 308 ? type, 309 ? use, 310 } 312 software-meta = { 313 global-attributes, 314 ? activation-status, 315 ? channel-type, 316 ? colloquial-version, 317 ? description, 318 ? edition, 319 ? entitlement-data-required, 320 ? entitlement-key, 321 ? generator, 322 ? persistent-id, 323 ? product, 324 ? product-family, 325 ? revision, 326 ? summary, 327 ? unspsc-code, 328 ? unspsc-version, 329 } 331 payload = { 332 global-attributes, 333 resource-collection, 334 } 336 payload-xor-evidence-entry = ((3: evidence) // (6: payload)) 337 tag-id = (0: text) 338 swid-name = (1: text) 339 entity-entry = (2: entity / [ 2* entity ]) 340 evidence-entry = (3: evidence) 341 link-entry = (4: link / [ 2* link ]) 342 software-meta-entry = (5: software-meta / [ 2* software-meta ]) 343 payload-entry = (6: payload) 344 any-element-entry = (7: any-element-map / [ 2* any-element-map ]) 345 corpus = (8: bool) 346 patch = (9: bool) 347 media = (10: text) 348 supplemental = (11: bool) 349 tag-version = (12: integer) 350 software-version = (13: text) 351 version-scheme = (14: text) 352 lang = (15: text) 353 directory-entry = (16: directory / [ 2* directory ]) 354 file-entry = (17: file / [ 2* file ]) 355 process-entry = (18: process / [ 2* process ]) 356 resource-entry = (19: resource / [ 2* resource ]) 357 size = (20: integer) 358 file-version = (21: text) 359 key = (22: bool) 360 location = (23: text) 361 fs-name = (24: text) 362 root = (25: text) 363 path-elements = (26: { * file-entry, 364 * directory-entry, 365 } 366 ) 367 process-name = (27: text) 368 pid = (28: integer) 369 type = (29: text) 370 extended-data = (30: any-element-map / [ 2* any-element-map ]) 371 entity-name = (31: text) 372 reg-id = (32: any-uri) 373 role = (33: text / [2* text]) 374 thumbprint = (34: text) 375 date = (35: time) 376 device-id = (36: text) 377 artifact = (37: text) 378 href = (38: any-uri) 379 ownership = (39: "shared" / "private" / "abandon") 380 rel = (40: text) 381 media-type = (41: text) 382 use = (42: "optional" / "required" / "recommended") 383 activation-status = (43: text) 384 channel-type = (44: text) 385 colloquial-version = (45: text) 386 description = (46: text) 387 edition = (47: text) 388 entitlement-data-required = (48: bool) 389 entitlement-key = (49: text) 390 generator = (50: text) 391 persistent-id = (51: text) 392 product = (52: text) 393 product-family = (53: text) 394 revision = (54: text) 395 summary = (55: text) 396 unspsc-code = (56: text) 397 unspsc-version = (57: text) 398 file-hash = (58: [ hash-alg-id: int, 399 hash-value: bstr, 400 ] 401 ) 402 404 3. Description of the SWID Attribute Vocabulary Definition 406 Yet to be written still... 408 4. IANA Considerations 410 This document will include requests to IANA: 412 o Integer indices for SWID content attributes and information 413 elements. 415 o Content-Type for CoAP to be used in COSE. 417 5. Security Considerations 419 SWID tags contain public information about software products and, as 420 such, do not need to be protected against disclosure on an endpoint. 421 Similarly, SWID tags are intended to be easily discoverable by 422 applications and users on an endpoint in order to make it easy to 423 identify and collect all of an endpoint's SWID tags. As such, any 424 security considerations regarding SWID tags focus on the application 425 of SWID tags to address security challenges, and the possible 426 disclosure of the results of those applications. 428 A signed SWID tag whose signature is intact can be relied upon to be 429 unchanged since it was signed. If the SWID tag was created by the 430 software author, this generally means that it has undergone no change 431 since the software application with which the tag is associated was 432 installed. By implication, this means that the signed tag reflects 433 the software author's understanding of the details of that software 434 product. This can be useful assurance when the information in the 435 tag needs to be trusted, such as when the tag is being used to convey 436 golden measurements. By contrast, the data contained in unsigned 437 tags cannot be trusted to be unmodified. 439 SWID tags are designed to be easily added and removed from an 440 endpoint along with the installation or removal of software products. 441 On endpoints where addition or removal of software products is 442 tightly controlled, the addition or removal of SWID tags can be 443 similarly controlled. On more open systems, where many users can 444 manage the software inventory, SWID tags may be easier to add or 445 remove. On such systems, it may be possible to add or remove SWID 446 tags in a way that does not reflect the actual presence or absence of 447 corresponding software products. Similarly, not all software 448 products automatically install SWID tags, so products may be present 449 on an endpoint without providing a corresponding SWID tag. As such, 450 any collection of SWID tags cannot automatically be assumed to 451 represent either a complete or fully accurate representation of the 452 software inventory of the endpoint. However, especially on devices 453 that more strictly control the ability to add or remove applications, 454 SWID tags are an easy way to provide an preliminary understanding of 455 that endpoint's software inventory. 457 Any report of an endpoint's SWID tag collection provides information 458 about the software inventory of that endpoint. If such a report is 459 exposed to an attacker, this can tell them which software products 460 and versions thereof are present on the endpoint. By examining this 461 list, the attacker might learn of the presence of applications that 462 are vulnerable to certain types of attacks. As noted earlier, SWID 463 tags are designed to be easily discoverable by an endpoint, but this 464 does not present a significant risk since an attacker would already 465 need to have access to the endpoint to view that information. 466 However, when the endpoint transmits its software inventory to 467 another party, or that inventory is stored on a server for later 468 analysis, this can potentially expose this information to attackers 469 who do not yet have access to the endpoint. As such, it is important 470 to protect the confidentiality of SWID tag information that has been 471 collected from an endpoint, not because those tags individually 472 contain sensitive information, but because the collection of SWID 473 tags and their association with an endpoint reveals information about 474 that endpoint's attack surface. 476 Finally, both the ISO-19770-2:2015 XML schema definition and the 477 Concise SWID data definition allow for the construction of "infinite" 478 SWID tags or SWID tags that contain malicious content with the intend 479 if creating non-deterministic states during validation or processing 480 of SWID tags. While software product vendors are unlikely to do 481 this, SWID tags can be created by any party and the SWID tags 482 collected from an endpoint could contain a mixture of vendor and non- 483 vendor created tags. For this reason, tools that consume SWID tags 484 ought to treat the tag contents as potentially malicious and should 485 employ input sanitizing on the tags they ingest. 487 6. Acknowledgements 489 7. Change Log 491 Changes from version 00 to version 01: 493 o Added CWT usage for absolute SWID paths on a device 495 o Fixed cardinality of type-choices including arrays 497 o Included first iteration of firmware resource-collection 499 Changes since adopted as a WG I-D -00: 501 o Removed redundant any-attributes originating from the ISO- 502 19770-2:2015 XML schema definition 504 o Fixed broken multi-map members 506 o Introduced a more restrictive item (any-element-map) to represent 507 custom maps, increased restriction on types for the any-attribute, 508 accordingly 510 o Fixed X.1520 reference 512 o Minor type changes of some attributes (e.g. NMTOKENS) 514 o Added semantic differentiation of various name types (e,g. fs- 515 name) 517 Changes from version 00 to version 01: 519 o Ambiguity between evidence and payload eliminated by introducing 520 explicit members (while still 522 o allowing for "empty" SWID tags) 524 o Added a relatively restrictive COSE envelope using cose_sign1 to 525 define signed CoSWID (single signer only, at the moment) 527 o Added a definition how to encode hashes that can be stored in the 528 any-member using existing IANA tables to reference hash-algorithms 530 Changes from version 01 to version 02: 532 o Enforced a more strict separation between the core CoSWID 533 definition and additional usage by moving content to corresponding 534 appendices. 536 o Removed artifacts inherited from the reference schema provided by 537 ISO (e.g. NMTOKEN(S)) 539 o Simplified the core data definition by removing group and type 540 choices where possible 542 o Minor reordering of map members 544 o Added a first extension point to address requested flexibility for 545 extensions beyond the any-element 547 8. Contributors 549 9. References 551 9.1. Normative References 553 [I-D.ietf-ace-cbor-web-token] 554 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 555 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-10 556 (work in progress), December 2017. 558 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 559 Requirement Levels", BCP 14, RFC 2119, 560 DOI 10.17487/RFC2119, March 1997, 561 . 563 [RFC4108] Housley, R., "Using Cryptographic Message Syntax (CMS) to 564 Protect Firmware Packages", RFC 4108, 565 DOI 10.17487/RFC4108, August 2005, 566 . 568 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 569 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 570 . 572 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 573 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 574 October 2013, . 576 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 577 Constrained-Node Networks", RFC 7228, 578 DOI 10.17487/RFC7228, May 2014, 579 . 581 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 582 RFC 8152, DOI 10.17487/RFC8152, July 2017, 583 . 585 [SAM] "Information technology - Software asset management - Part 586 5: Overview and vocabulary", ISO/IEC 19770-5:2013, 587 November 2013. 589 [SWID] "Information technology - Software asset management - Part 590 2: Software identification tag'", ISO/IEC 19770-2:2015, 591 October 2015. 593 [X.1520] "Recommendation ITU-T X.1520 (2014), Common 594 vulnerabilities and exposures", April 2011. 596 9.2. Informative References 598 [I-D.banghart-sacm-rolie-softwaredescriptor] 599 Waltermire, D. and S. Banghart, "Definition of the ROLIE 600 Software Descriptor Extension", draft-banghart-sacm-rolie- 601 softwaredescriptor-01 (work in progress), May 2017. 603 [I-D.birkholz-tuda] 604 Fuchs, A., Birkholz, H., McDonald, I., and C. Bormann, 605 "Time-Based Uni-Directional Attestation", draft-birkholz- 606 tuda-04 (work in progress), March 2017. 608 [I-D.ietf-cbor-cddl] 609 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 610 definition language (CDDL): a notational convention to 611 express CBOR data structures", draft-ietf-cbor-cddl-00 612 (work in progress), July 2017. 614 [I-D.ietf-sacm-terminology] 615 Birkholz, H., Lu, J., Strassner, J., Cam-Winget, N., and 616 A. Montville, "Security Automation and Continuous 617 Monitoring (SACM) Terminology", draft-ietf-sacm- 618 terminology-14 (work in progress), December 2017. 620 Appendix A. Explicit file-hash Type Used in Concise SWID Tags (label 621 56) 623 CoSWID add explicit support for the representation of file-hashes 624 using algorithms that are registered at the Named Information Hash 625 Algorithm Registry via the file-hash member (label 56). 627 file-hash = (56: [ hash-alg-id: int, hash-value: bstr ] ) 629 The number used as a value for hash-alg-id MUST refer the ID in the 630 Named Information Hash Algorithm table; other hash algorithms MUST 631 NOT be used. The hash-value MUST represent the raw hash value of the 632 file-entry the file-hash type is included in. 634 Appendix B. CoSWID Attributes for Firmware (label 57) 636 The ISO-19770-2:2015 specification of SWID tags assumes the existence 637 of a file system a software component is installed and stored in. In 638 the case of constrained-node networks [RFC7228] or network equipment 639 this assumption might not apply. Concise software instances in the 640 form of (modular) firmware are often stored directly on a block 641 device that is a hardware component of the constrained-node or 642 network equipment. Multiple differentiable block devices or 643 segmented block devices that contain parts of modular firmware 644 components (potentially each with their own instance version) are 645 already common at the time of this writing. 647 The optional attributes that annotate a firmware package address 648 specific characteristics of pieces of firmware stored directly on a 649 block-device in contrast to software deployed in a file-system. In 650 essence, trees of relative path-elements expressed by the directory 651 and file structure in CoSWID tags are typically unable to represent 652 the location of a firmware on a constrained-node (small thing). The 653 composite nature of firmware and also the actual composition of small 654 things require a set of attributes to address the identification of 655 the correct component in a composite thing for each individual piece 656 of firmware. A single component also potentially requires a number 657 of distinct firmware parts that might depend on each other 658 (versions). These dependencies can be limited to the scope of the 659 component itself or extend to the scope of a larger composite device. 660 In addition, it might not be possible (or feasible) to store a CoSWID 661 tag document (permanently) on a small thing along with the 662 corresponding piece of firmware. 664 To address the specific characteristics of firmware, the extension 665 point "$$resource-extension" is used to allow for an additional type 666 of resource description--firmware-entry--thereby increasing the self- 667 descriptiveness and flexibility of CoSWID. The optional use of the 668 extension point "$$resource-extension" in respect to firmware MUST 669 adhere to the following CDDL data definition. 671 672 $$resource-extension //= (firmware-entry,) 674 firmware = { 675 firmware-name, ; inherited from RFC4108 676 ? firmware-version, 677 ? firmware-package-identifier, ; inherited from RFC4108 678 ? dependency, ; inherited from RFC4108 679 ? component-index, ; equivalent to RFC4108 fwPkgType 680 ? block-device-identifier, 681 ? target-hardware-identifier, ; an RFC4108 alternative to model-label 682 model-label, 683 ? firmware-hash, ; a hash for a single, incl. NI hash-algo index 684 ? firmware-package, ; RCF4108, experimental, this is an actual firmware blob! 685 } 687 firmware-entry = (57: firmware / [ 2* firmware ]) 688 firmware-hash = (58: [ hash-alg-id: int, 689 hash-value: bstr, 690 ] 691 ) 692 firmware-name = (59 : text) 693 firmware-version = (60 : text / int) 694 component-index = (61 : int) 695 model-label = (62: text / int) 696 block-device-identifier = (63 : text / int) 697 firmware-package = (64: bstr) 698 firmware-package-identifier = (65: text) 699 target-hardware-identifier = (66: text) 700 dependency = (67: { ? firmware-name, 701 ? firmware-version, 702 ? firmware-package-identifier, 703 } 704 ) 705 707 The members of the firmware group that constitutes the content of the 708 firmware-entry is based on the metadata about firmware defined in 709 [RFC4108]. As with every semantic differentiation that is supported 710 by the resource-collection type, the use of firmware-entry is 711 optional. It is REQUIRED not to instantiate more than one firmware- 712 entry, as the firmware group is used in a map and therefore only 713 allows for unique labels. 715 The optional cms-firmware-package member allows to include the actual 716 firmware in the CoSWID tag that also expresses its metadata as a 717 byte-string. This option enables a CoSWID tag to be used as a 718 container or wrapper that composes both firmware and its metadata in 719 a single document (which again can be signed, encrypted and/or 720 compressed). In consequence, a CoSWID tag about firmware can be 721 conveyed as an identifying document across endpoints or used as a 722 reference integrity measurement as usual. Alternatively, it can also 723 convey an actual piece of firmware, serve its intended purpose as a 724 SWID tag and then - due to the lack of a location to store it - be 725 discarded. 727 Appendix C. Signed Concise SWID Tags using COSE 729 SWID tags, as defined in the ISO-19770-2:2015 XML schema, can include 730 cryptographic signatures to protect the integrity of the SWID tag. 731 In general, tags are signed by the tag creator (typically, although 732 not exclusively, the vendor of the software product that the SWID tag 733 identifies). Cryptographic signatures can make any modification of 734 the tag detectable, which is especially important if the integrity of 735 the tag is important, such as when the tag is providing reference 736 integrity measurments for files. 738 The ISO-19770-2:2015 XML schema uses XML DSIG to support 739 cryptographic signatures. CoSWID tags require a different signature 740 scheme than this. COSE (CBOR Object Signing and Encryption) provides 741 the required mechanism [RFC8152]. Concise SWID can be wrapped in a 742 COSE Single Signer Data Object (cose-sign1) that contains a single 743 signature. The following CDDL defines a more restrictive subset of 744 header attributes allowed by COSE tailored to suit the requirements 745 of Concise SWID. 747 748 signed-coswid = #6.997(COSE-Sign1-coswid) ; see TBS7 in current COSE I-D 750 label = int / tstr ; see COSE I-D 1.4. 751 values = any ; see COSE I-D 1.4. 753 unprotected-signed-coswid-header = { 754 1 => int, ; algorithm identifier 755 3 => "application/coswid", ; request for CoAP IANA registry to become an int 756 * label => values, 757 } 759 protected-signed-coswid-header = { 760 4 => bstr, ; key identifier 761 * label => values, 762 } 764 COSE-Sign1-coswid = [ 765 protected: bstr .cbor protected-signed-coswid-header, 766 unprotected: unprotected-signed-coswid-header, 767 payload: bstr .cbor concise-software-identity, 768 signature: bstr, 769 ] 770 772 Appendix D. CoSWID used as Reference Integrity Measurements (CoSWID 773 RIM) 775 A vendor supplied signed CoSWID tag that includes hash-values for the 776 files that compose a software component can be used as a RIM 777 (reference integrity measurement). A RIM is a type of declarative 778 guidance that can be used to assert the compliance of an endpoint by 779 assessing the installed software. In the context of remote 780 attestation based on an attestation via hardware rooted trust, a 781 verifier can appraise the integrity of the conveyed measurements of 782 software components using a CoSWID RIM provided by a source, such as 783 [I-D.banghart-sacm-rolie-softwaredescriptor]. 785 RIM Manifests (RIMM): A group of SWID tags about the same 786 (sub-)system, system entity, or (sub-)component (compare 787 [RFC4949]). A RIMM manifest is a distinct document that is 788 typically conveyed en-block and constitutes declarative guidance 789 in respect to a specific (target) endpoint (compare 790 [I-D.ietf-sacm-terminology]). 792 If multiple CoSWID compose a RIMM, the following CDDL data definition 793 SHOULD be used. 795 RIMM = [ + concise-software-identity / signed-coswid ] 797 Appendix E. CBOR Web Token for Concise SWID Tags 799 A typical requirement regarding specific instantiations of endpoints 800 - and, as a result, specific instantiations of software components - 801 is a representation of the absolute path of a CoSWID tag document in 802 a file system in order to derive absolute paths of files represented 803 in the corresponding CoSWID tag. The absolute path of an evidence 804 CoSWID tag can be included as a claim in the header of a CBOR Web 805 Token [I-D.ietf-ace-cbor-web-token]. Depending on the source of the 806 token, the claim can be in the protected or unprotected header 807 portion. 809 810 CDDL TBD 811 813 Appendix F. Group Definitions 815 These groups are intermediate CDDL data definitions that are reused 816 in several items in the CoSWID CDDL data definition. 818 o resource-collection group: A list of items both used in evidence 819 (discovered by an inventory process) and payload (installed in a 820 system entity) content of a CoSWID tag document to structure and 821 differentiate the content of specific CoSWID tag types. Potential 822 content includes directories, files, processes, resources or 823 firmwares. 825 o filesystem group: A list of items both used in representing the 826 nodes of a file-system hierarchy, i.e. directory items that allow 827 one or more directories to be defined in the file structure, and 828 file items that allow one or more files to be specified for a 829 given location. 831 o global-attributes: A list of items including an optional language 832 definition to support the processing of text-string values and an 833 unbounded set of any-attribute items. 835 o any-attribute: A specific rule providing a restricted frame to 836 include arbitrary information via members that constitute key 837 value(s) pairs where both keys and values can be integers or text- 838 strings. 840 Appendix G. Item Definitions 842 This Appendix includes the description of every primitive and non- 843 primitive type the concise-software-identifier is composed of. Every 844 integer label included at the end of the CDDL data definition is 845 addressed in this section. 847 1. tag-id: An identifier uniquely referencing a (composite) 848 software component. The tag identifier is intended to be 849 globally unique. There are no strict guidelines on how this 850 identifier is structured, but examples include a 16 byte GUID 851 (e.g. class 4 UUID). 853 2. swid-name: This item provides the software component name as it 854 would typically be referenced. For example, what would be seen 855 in the add/remove dialog on a Windows device, or what is 856 specified as the name of a packaged software product or a patch 857 identifier name on a Linux device. 859 3. entity: Specifies the organizations related to the software 860 component referenced by this CoSWID tag. 862 4. evidence: This item is used to provide results from a scan of a 863 system where software that does not have a CoSWID tag is 864 discovered. This information is not provided by the software- 865 creator, and is instead created when a system is being scanned 866 and the evidence for why software is believed to be installed on 867 the device is provided in the evidence item. 869 5. link: A reference to any another item (can include details that 870 are related to the CoSWID tag such as details on where specific 871 resources can be found, e.g. vulnerability database 872 associations, ROLIE feeds, MUD files, etc). This is modeled 873 directly to match the HTML [LINK] element; it is critical for 874 streamlining software discovery scenarios to ensure their 875 consistency. 877 6. software-meta: An open-ended collection of key/value data 878 related to this CoSWID. The attributes included in this Element 879 are predefined attributes to ensure common usage across the 880 industry. The schema allows for any additional attribute to be 881 included in a CoSWID tag, though it is recommended that industry 882 norms for new attributes are defined and followed to the degree 883 possible. 885 7. payload: The items that may be installed on a system entity when 886 the software component is installed. Note that payload may be a 887 superset of the items installed and - depending on optimization 888 mechanisms in respect to that system entity - may or may not 889 include every item that could be created or executed on the 890 corresponding system entitiy when software components are 891 installed. In general, payload will be used to indicate the 892 files that may be installed with a software component. 893 Therefore payload will often be a superset of those files (i.e. 894 if a particular optional sub-component is not installed, the 895 files associated with that software component may be included in 896 payload, but not installed in the system entity). 898 8. any-element: A default map that can contain arbitrary map 899 members and even nested maps (which would be also any-elements). 900 In essence, the any-element allows items not defined in this 901 CDDL data definition to be included in a Concise Software 902 Identifier. 904 9. corpus: Set to true, if this attribute specifies that this SWID 905 tag is a collection of information that describes the pre- 906 installation data of software component. 908 10. patch: A set of files that is intended to modify an existing set 909 of files (including configuration files, scripts and 910 corresponding environment variables that are create by the OS 911 for the runtime environment) that composes a software component. 912 A software component patch does neither alter the version number 913 (see 13) nor the release details (descriptive english text, see 914 44) of a software components. [revision 52?]. If a Concise SWID 915 tag is a patch, it MUST contain the patch item and its value 916 MUST be set to true. It is recommended but not required to 917 include a rel(ation) item in a patch CoSWID. If a CoSWID 918 includes a patch member, but not a rel member, it is implied 919 that it SHOULD be installed independently of any other CoSWID 920 tag document - even if an effective but not explicit 921 relationship exists. 923 11. media: This text value is a hint to the tag consumer to 924 understand what this SWID tag applies to. This item can also be 925 included in the link item to represent a attributes defined by 926 the W3C Media Queries Recommendation (see http://www.w3.org/TR/ 927 css3-mediaqueries/). A hint to the consumer of the link to what 928 the target item is applicable for. 930 12. supplemental: Specifies that this tag provides supplemental tag 931 data that can be merged with primary tag data to create a 932 complete record of the software information. Supplemental tags 933 will often be provided at install time and may be provided by 934 different entities (such as the tag consumer, or a Value Added 935 Reseller). 937 13. tag-version: This item indicates if a specific release of a 938 software component has more than one tag that can represent that 939 specific release. This may be the case if a CoSWID tag producer 940 creates and releases an incorrect tag that they subsequently 941 want to fix, but with no underlying changes to the product the 942 CoSWID tag represents. This could happen if, for example, a 943 patch is distributed that has a link reference that does not 944 cover all the various software releases it can patch. A newer 945 CoSWID tag for that patch can be generated and the tag-version 946 value incremented to indicate that the data is updated. 948 14. software-version: Underlying development version for the 949 software component. 951 15. version-scheme: Scheme used for the version number. Valid 952 enumerations are : * alphanumeric: strictly a string, sorting 953 alphanumerically * decimal: a floating point number (i.e., 1.25 954 is less than 1.3 ) * multipartnumeric: numbers separated via 955 dots, where the numbers are * interpreted as integers (ie, 1.2.3 956 , 1.4.5.6 , 1.2.3.4.5.6.7). This string * convention is similar 957 to OIDs. * multipartnumeric+suffix: numbers separated via dots, 958 where the numbers are * interpreted as integers with an 959 additional string suffix (e.g., 1.2.3a). * semver: a string as 960 defined by the semver.org spec [FiXME: reference] * unknown: the 961 last resort choice, no attempt should be made to order these 963 16. lang: An RFC5646 conferment language tag or corresponding IANA 964 index integer. 966 17. directory: A directory item allows one or more directories to be 967 defined in the file structure. 969 18. file: A file element that allows one or more files to be 970 specified for a given location. 972 19. process: Provides process (software component in execution) 973 information for data that will show up in a devices process 974 table. 976 20. resource: A set of items that can be used to provide arbitrary 977 resource information about an application installed on a system 978 entity, or evidence collected from a system entity. 980 21. size: The file size in bytes of the file. 982 22. file-version The file version. 984 23. key: Files that are considered important or required for the use 985 of a software component. Typical key files would be those 986 which, if not available on a system entity, would cause the 987 software component not to execute or function properly. Key 988 files will typically be used to validate that a software 989 component referenced by the CoSWID tag document is actually 990 installed on a specific system entity. 992 24. location: The directory or location where a file was found or 993 can expected to be located. This text-string is intended to 994 include the filename itself. This SHOULD be the relative path 995 represented by the root item. 997 25. fs-name: The file name or directory name without any path 998 characters. 1000 26. root: A system-specific root folder that the location item is an 1001 offset from. If this is not specified the assumption is the 1002 root is the same folder as the location of the CoSWID tag. The 1003 text-string value represents a path expression relative to the 1004 CoSWID tag document location in the (composite) file-system 1005 hierarchy. 1007 27. path-elements: Provides the ability to apply a directory 1008 structure to the path expressions for files defined in a payload 1009 or evidence item. 1011 28. process-name: The process name as it will be found in the system 1012 entity's process table. 1014 29. pid: The process ID for the process in execution that can be 1015 included in the process item as part of an evidence tag. 1017 30. type: The type of resource represented via a text-string 1018 (typically, registry-key, port or root-uri) 1020 31. extended-data: An open-ended collection of elements that can be 1021 used to attach arbitrary metadata to an entity item. 1023 32. entity-name: The text-string name of the organization claiming a 1024 particular role in the CoSWID tag. 1026 33. reg-id: The registration id is intended to uniquely identify a 1027 naming authority in a given scope (e.g. global, organization, 1028 vendor, customer, administrative domain, etc.) that is implied 1029 by the referenced naming authority. The value of an 1030 registration ID MUST be a RFC 3986 URI. The scope SHOULD be the 1031 scope of an organization. In a given scope, the registration id 1032 MUST be used consistently. 1034 34. role: The relationship between this organization and this tag. 1035 The role of tag creator is required for every CoSWID tag. The 1036 role of an entity may include any role value, but the per- 1037 defined roles include: "aggregator", "distributor", "licensor", 1038 "software-creator", "tag-creator". The enumerations of this 1039 will include a request to IANA in order to be reference-able via 1040 an integer index. 1042 35. thumbprint: This value provides a hexadecimal string that 1043 contains a hash (i.e. the thumbprint) of the signing entities 1044 certificate [s] [FIXME: this requires the same structure as 1045 file-hash?]. 1047 36. date: The sate and time evidence represented by an evidence item 1048 was gathered. 1050 37. device-id: A text-string identifier for a device evidence was 1051 gathered from. 1053 38. artifact: For installation media (rel="installation-media") - 1054 dictates the canonical name for the file. Items with the same 1055 artifact name should be considered mirrors of each other (so 1056 download from wherever works). 1058 39. href: The link to the item being referenced. The href can point 1059 to several different things, and can be any of the following: * 1060 a relative uri (no scheme), which is interpreted depending on 1061 context (for example, "./folder/supplemental.coswid") * a 1062 physical file location with any system-acceptable URI scheme 1063 (e.g., file:// http:// https:// ftp://) * an URI with "coswid:" 1064 as the scheme, which refers to another CoSWID by tag-id. This 1065 URI would need to be resolved in the context of the system by 1066 software that can lookup other CoSWID tags (for example, * 1067 "coswid:2df9de35-0aff-4a86-ace6-f7dddd1ade4c"). an URI with 1068 "swidpath:" as the scheme, which refers to another CoSIWD via an 1069 XPATH query. This URI would need to be resolved in the context 1070 of the system entity via dedicated software components that can 1071 lookup other CoSWID tags and select the appropriate tag based on 1072 an XPATH query. Examples include: * 1073 swidpath://SoftwareIdentity[Entity/@regid='http://contoso.com'] 1074 would * retrieve all CoSWID tags that include an entity where 1075 the regid was * "Contoso". * swidpath://SoftwareIdentity[Meta/@ 1076 persistentId='b0c55172-38e9-4e36-be86-92206ad8eddb'] * would 1077 retrieve CoSWID tags that matched the persistent-id. See XPATH 1078 query standard : http://www.w3.org/TR/xpath20/ [FIXME: Concise 1079 XPATH representation is covered in the YANG-CBOR I-D] 1081 40. ownership: Determines the relative strength of ownership of the 1082 software components. Valid enumerations are: abandon, private, 1083 shared 1085 41. rel: The relationship between this CoSWID and the target file. 1086 Relationships can be identified by referencing the IANA 1087 registration library: https://www.iana.org/assignments/link- 1088 relations/link-relations.xhtml. 1090 42. media-type: The IANA MediaType for the target file; this 1091 provides the consumer with intelligence of what to expect. See 1092 http://www.iana.org/assignments/media-types/media-types.xhtml 1093 for more details on link type. 1095 43. use: Determines if the target software is a hard requirement or 1096 not. Valid enumerations are: required, recommended, optional, 1098 44. activation-status: Identification of the activation status of 1099 this software title (e.g. Trial, Serialized, Licensed, 1100 Unlicensed, etc). Typically, this is used in supplemental tags. 1102 45. channel-type: Provides information on which channel this 1103 particular software was targeted for (e.g. Volume, Retail, OEM, 1104 Academic, etc). Typically used in supplemental tags. 1106 46. colloquial-version: The informal or colloquial version of the 1107 product (i.e. 2013). Note that this version may be the same 1108 through multiple releases of a software product where the 1109 version specified in entity is much more specific and will 1110 change for each software release. Note that this representation 1111 of version is typically used to identify a group of specific 1112 software releases that are part of the same release/support 1113 infrastructure (i.e. Fabrikam Office 2013). This version is 1114 used for string comparisons only and is not compared to be an 1115 earlier or later release (that is done via the entity version 1116 [FIXME: consistency). 1118 47. description: A longer, detailed description of the software. 1119 This description can be multiple sentences (differentiated from 1120 summary, which is a very short, one-sentence description). 1122 48. edition: The variation of the product (Extended, Enterprise, 1123 Professional, Standard etc). 1125 49. entitlement-data-required: An indicator to determine if there 1126 should be accompanying proof of entitlement when a software 1127 license reconciliation is completed. 1129 50. entitlement-key: A vendor-specific textual key that can be used 1130 to reconcile the validity of an entitlement. (e.g. serial 1131 number, product or license key). 1133 51. generator: The name of the software tool that created a CoSWID 1134 tag. This item is typically used if tags are created on the fly 1135 or via a catalog-based analysis for data found on a computing 1136 device. 1138 52. persistent-id: A GUID used to represent products installed where 1139 the product are related, but may be different versions. For 1140 example, an "upgradeCode" (see http://msdn.microsoft.com/en- 1141 us/library/aa372375(v=vs.85).aspx as an reference for this 1142 example). 1144 53. product: The base name of the product (e.g. [FIXME: what are 1145 appropriate examples?]. 1147 54. product-family: The overall product family this software belongs 1148 to. Product family is not used to identify that a product is 1149 part of a suite, but is instead used when a set of products that 1150 are all related may be installed on multiple different devices. 1151 For example, an enterprise backup system may consist of a backup 1152 services, multiple different backup services that support mail 1153 services, databases and ERP systems, as well as individual 1154 software components that backup client system entities. In such 1155 an usage scenario, all software components that are part of the 1156 backup system would have the same product-family name so they 1157 can be grouped together in respect to reporting systems. 1159 55. revision: The informal or colloquial representation of the sub- 1160 version of the given product (ie, SP1, R2, RC1, Beta 2, etc). 1161 Note that the version will provide very exact version details, 1162 the revision is intended for use in environments where reporting 1163 on the informal or colloquial representation of the software is 1164 important (for example, if for a certain business process, an 1165 organization recognizes that it must have, for example 1166 "ServicePack 1" or later of a specific product installed on all 1167 devices, they can use the revision data value to quickly 1168 identify any devices that do not meet this requirement). 1169 Depending on how a software organizations distributes revisions, 1170 this value could be specified in a primary (if distributed as an 1171 upgrade) or supplemental (if distributed as a patch) CoSWID tag. 1173 56. summary: A short (one-sentence) description of the software. 1175 57. unspsc-code: An 8 digit code that provides UNSPSC classification 1176 of the software product this SWID tag identifies. For more 1177 information see, http://www.unspsc.org/. 1179 58. unspsc-version: The version of the UNSPSC code used to define 1180 the UNSPSC code value. For more information see, 1181 http://www.unspsc.org/. 1183 Authors' Addresses 1185 Henk Birkholz 1186 Fraunhofer SIT 1187 Rheinstrasse 75 1188 Darmstadt 64295 1189 Germany 1191 Email: henk.birkholz@sit.fraunhofer.de 1193 Jessica Fitzgerald-McKay 1194 Department of Defense 1195 9800 Savage Road 1196 Ft. Meade, Maryland 1197 USA 1199 Email: jmfitz2@nsa.gov 1201 Charles Schmidt 1202 The MITRE Corporation 1203 202 Burlington Road 1204 Bedford, Maryland 01730 1205 USA 1207 Email: cmschmidt@mitre.org 1209 David Waltermire 1210 National Institute of Standards and Technology 1211 100 Bureau Drive 1212 Gaithersburg, Maryland 20877 1213 USA 1215 Email: david.waltermire@nist.gov