SACM Working Group H. Birkholz
Internet-Draft Fraunhofer SIT
Intended status: Standards Track J. Fitzgerald-McKay
Expires: December 26, 2019 Department of Defense
C. Schmidt
The MITRE Corporation
D. Waltermire
NIST
June 24, 2019

Concise Software Identification Tags
draft-ietf-sacm-coswid-10

Abstract

This document defines a concise representation of ISO/IEC 19770-2:2015 Software Identification (SWID) tags that are interoperable with the XML schema definition of ISO/IEC 19770-2:2015. Next to the inherent capability of SWID tags to express arbitrary context information, Concise SWID (CoSWID) tags support the definition of additional semantics via well-defined data definitions incorporated by extension points.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on December 26, 2019.

Copyright Notice

Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1. Introduction

SWID tags have several use-applications including but not limited to:

SWID tags, as defined in ISO-19770-2:2015 [SWID], provide a standardized XML-based record format that identifies and describes a specific release of a software component. Different software components, and even different releases of a particular software component, each have a different SWID tag record associated with them. SWID tags are meant to be flexible and able to express a broad set of metadata about a software component.

While there are very few required fields in SWID tags, there are many optional fields that support different use scenarios. A SWID tag consisting of only required fields might be a few hundred bytes in size; however, a tag containing many of the optional fields can be many orders of magnitude larger. Thus, real-world instances of SWID tags can be fairly large, and the communication of SWID tags in use-applications, such as those described earlier, can cause a large amount of data to be transported. This can be larger than acceptable for constrained devices and networks. Concise SWID (CoSWID) tags significantly reduce the amount of data transported as compared to a typical SWID tag. This reduction is enabled through the use of CBOR, which maps the human-readable labels of SWID data items to more concise integer labels (indices). The use of CBOR to express SWID information in CoSWID tags allows both CoSWID and SWID tags to be part of an enterprise security solution for a wider range of endpoints and environments.

1.1. The SWID and CoSWID Tag Lifecycle

In addition to defining the format of a SWID tag record, ISO/IEC 19770-2:2015 defines requirements concerning the SWID tag lifecycle. Specifically, when a software component is installed on an endpoint, that software component’s SWID tag is also installed. Likewise, when the software component is uninstalled or replaced, the SWID tag is deleted or replaced, as appropriate. As a result, ISO/IEC 19770-2:2015 describes a system wherein there is a correspondence between the set of installed software components on an endpoint, and the presence of the corresponding SWID tags for these components on that endpoint. CoSWIDs share the same lifecycle requirements as a SWID tag.

  1. Primary Tag - A SWID or CoSWID tag that identifies and describes a software component is installed on a computing device. A primary tag is intended to be installed on an endpoint along with the corresponding software component.
  2. Patch Tag - A SWID or CoSWID tag that identifies and describes an installed patch which has made incremental changes to a software component installed on an endpoint. A patch tag is intended to be installed on an endpoint along with the corresponding software component patch.
  3. Corpus Tag - A SWID or CoSWID tag that identifies and describes an installable software component in its pre-installation state. A corpus tag can be used to represent metadata about an installation package or installer for a software component, a software update, or a patch.
  4. Supplemental Tag - A SWID or CoSWID tag that allows additional information to be associated with a referenced SWID tag. This helps to ensure that SWID Primary and Patch Tags provided by a software provider are not modified by software management tools, while allowing these tools to provide their own software metadata.

The type of a tag is determined by specific data elements, which is discussed in Section 3.

                                  +------------+
                                  v            |
Installation     Product       Product      Product       Product
  Media      -> Installed  ->  Patched   -> Upgraded   -> Removed
 Deployed

 Corpus         Primary        Primary      xPrimary      xPrimary
                Supplemental   Supplemental xSupplemental xSuplemental
                               Patch        xPatch
                                            Primary
                                            Supplemental

Figure 1: Use of Tag Types in the Software Lifecycle

Note: While not fully illustrated in the figure, supplemental tags can be associated with any corpus, primary, or patch tag to provide additional metadata about an installer, installed software, or installed patch respectively.

Understanding the use of CoSWIDs in the software lifecycle provides a basis for understanding the information provided in a CoSWID and the associated semantics of this information. Each of the different SWID and CoSWID tag types provide different sets of information. For example, a “corpus tag” is used to describe a software component’s installation image on an installation media, while a “patch tag” is meant to describe a patch that modifies some other software component.

1.2. Concise SWID Format

This document defines the CoSWID tag format, a more concise representation of SWID information in the Concise Binary Object Representation (CBOR) [RFC7049]. The structure of a CoSWID is described via the Concise Data Definition Language (CDDL) [RFC8610]. The resulting CoSWID data definition is aligned to the information able to be expressed with the XML schema definition of ISO-19770-2:2015 [SWID]. This alignment allows both SWID and CoSWID tags to represent a common set of SWID information and to support all SWID tag use cases. To achieve this end, the CDDL representation includes every SWID tag field and attribute.

The vocabulary, i.e., the CDDL names of the types and members used in the CoSWID data definition, are mapped to more concise labels represented as small integer values. The names used in the CDDL data definition and the mapping to the CBOR representation using integer labels is based on the vocabulary of the XML attribute and element names defined in ISO/IEC 19770-2:2015.

1.3. Requirements Notation

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Concise SWID Data Definition

The following is a CDDL representation for a CoSWID tag. The CamelCase [CamelCase] notation used in the XML schema definition is changed to a hyphen-separated notation [KebabCase] (e.g. ResourceCollection is named resource-collection) in the CoSWID data definition. In essence, [KebabCase] “looks-like-this”. This deviation from the original notation used in the XML representation reduces ambiguity when referencing certain attributes in corresponding textual descriptions. An attribute referred to by its name in CamelCase notation explicitly relates to XML SWID tags; an attribute referred to by its name in KebabCase notation explicitly relates to CoSWID tags. This approach simplifies the composition of further work that reference both XML SWID and CoSWID documents.

Human-readable labels of members in CDDL map data definitions are mapped to integer indices via a block of rules at the bottom of the definition. The 57 character strings of the SWID vocabulary are replacesm which would have to be stored or transported in full if using the original vocabulary.

In CBOR, an array is encoded using bytes that identify the array, and the array’s length or stop point (see [RFC7049]). To make items that support 1 or more values, the following CDDL notion is used.

_name_ = (_label_: _data_ / [ 2* _data_ ])

The CDDL rule above allows for a more efficient CBOR encoding of the data when a single value is used. This is accomplished by avoiding the need to first encode the array. Conversely, hen two or more values are encoded, the bytes identifing the array are used. This modeling pattern is used frequently in the CoSWID CDDL data definition to allow for more effecient encoding of single values.

The following subsections describe the different parts of the CoSWID model.

2.1. Concise SWID Extensions

The corresponding CoSWID data definition includes two kinds of augmentation.

The following CDDL sockets (extension points) are defined in this document, which allow the addition of new information structures to their respective CDDL groups.

Map Name CDDL Socket Defined in
concise-swid-tag $$coswid-extension Section 2.2
entity-entry $$entity-extension Section 2.5
link-entry $$link-extension Section 2.6
software-meta-entry $$meta-extension Section 2.7
file-entry $$file-extension Section 2.8.2
directory-entry $$directory-extension Section 2.8.2
process-entry $$process-extension Section 2.8.2
resource-entry $$resource-extension Section 2.8.2
payload-entry $$payload-extension Section 2.8.3
evidence-entry $$evidence-extension Section 2.8.4

The CoSWID Items Registry defined in Section 5.1 provides a registration mechanism allowing new items, and their associated index values, to be added to the CoSWID model through the use of the CDDL sockets described above. This registration mechanism provides for well-known index values for data items in CoSWID extensions, allowing these index values to be recognized by implementations supporting a given extension.

The following CDDL sockets defined in this document allow for adding new values to corresponding type-choices (i.e. to represent enumerations) via custom CDDL data definitions.

Enumeration Name CDDL Socket Defined in
version-scheme $version-scheme Section 4.1
role $role Section 4.2
ownership $ownership Section 4.3
rel $rel Section 4.4
use $use Section 4.5

A number of SWID/CoSWID value registries are also defined in Section 5.2 that allow new valid values to be registered with IANA for the enumerations above. This registration mechanism supports the definition of new well-known index values and names for new enumeration values used by SWID and CoSWID. This registration mechanism allows new standardized enumerated values to be shared between both specifications (and implementations) over time.

2.2. The concise-swid-tag Group

The CDDL data definition for the root concise-swid-tag map is as follows and this rule and its constraints MUST be followed when creating or validating a CoSWID tag:

concise-swid-tag = {
  global-attributes,
  tag-id => text,
  tag-version => integer,
  ? corpus => bool,
  ? patch => bool,
  ? supplemental => bool,
  software-name => text,
  ? software-version => text,
  ? version-scheme => $version-scheme,
  ? media => text,
  ? software-meta =>  software-meta-entry / [ 2* software-meta-entry ],
  entity => entity-entry / [ 2* entity-entry ],
  ? link => link-entry / [ 2* link-entry ],
  ? (( payload => payload-entry ) // ( evidence => evidence-entry )),
  * $$coswid-extension 
}

tag-id = 0
software-name = 1
entity = 2
evidence = 3
link = 4
software-meta = 5
payload = 6
corpus = 8
patch = 9
media = 10
supplemental = 11
tag-version = 12
software-version = 13
version-scheme = 14

$version-scheme /= multipartnumeric
$version-scheme /= multipartnumeric-suffix
$version-scheme /= alphanumeric
$version-scheme /= decimal
$version-scheme /= semver
$version-scheme /= uint / text
multipartnumeric = 1
multipartnumeric-suffix = 2
alphanumeric = 3
decimal = 4
semver = 16384

The following describes each member of the concise-swid-tag root map.

2.3. concise-swid-tag Co-constraints

The following co-constraints apply to the information provided by in the concise-swid-tag group.

2.4. The global-attributes Group

The global-attributes group provides a list of items including an optional language definition to support the processing of text-string values and an unbounded set of any-attribute items allowing for additional items to be provided as a general point of extension in the model.

The CDDL for the global-attributes follows:

global-attributes = (
  ? lang,
  * any-attribute,
)

any-attribute = (
  label => text / int / [ 2* text ] / [ 2* int ]
)

label = text / int

The following describes each child item of this group.

2.5. The entity-entry Group

The CDDL for the entity-entry group follows:

entity-entry = {
  global-attributes,
  entity-name => text,
  ? reg-id => any-uri,
  role => $role / [ 2* $role ],
  ? thumbprint => hash-entry,
  * $$entity-extension,
}
entity-name = 31
reg-id = 32
role = 33
thumbprint = 34

$role /= tag-creator
$role /= software-creator
$role /= aggregator
$role /= distributor
$role /= licensor
$role /= uint / text
tag-creator=1
software-creator=2
aggregator=3
distributor=4
licensor=5

The following describes each child item of this group.

2.6. The link-entry Map

The CDDL for the link-entry map follows:

link-entry = {
  global-attributes,
  ? artifact => text,
  href => any-uri,
  ? media => text,
  ? ownership => $ownership,
  rel => $rel,
  ? media-type => text,
  ? use => $use,
  * $$link-extension,
}
media = 10
artifact = 37
href = 38
ownership = 39
rel = 40
media-type = 41
use = 42

$ownership /= shared
$ownership /= private
$ownership /= abandon
$ownership /= uint / text
shared=1
private=2
abandon=3

$rel /= ancestor
$rel /= component
$rel /= feature
$rel /= installationmedia
$rel /= packageinstaller
$rel /= parent
$rel /= patches
$rel /= requires
$rel /= see-also
$rel /= supersedes
$rel /= supplemental
$rel /= uint / text
ancestor=1
component=2
feature=3
installationmedia=4
packageinstaller=5
parent=6
patches=7
requires=8
see-also=9
supersedes=10
supplemental=11

$use /= optional
$use /= required
$use /= recommended
$use /= uint / text
optional=1
required=2
recommended=3

The following describes each member of this map.

2.7. The software-meta-entry Map

The CDDL for the software-meta-entry map follows:

software-meta-entry = {
  global-attributes,
  ? activation-status => text,
  ? channel-type => text,
  ? colloquial-version => text,
  ? description => text,
  ? edition => text,
  ? entitlement-data-required => bool,
  ? entitlement-key => text,
  ? generator => text,
  ? persistent-id => text,
  ? product => text,
  ? product-family => text,
  ? revision => text,
  ? summary => text,
  ? unspsc-code => text,
  ? unspsc-version => text,
  * $$meta-extension,
}
activation-status = 43
channel-type = 44
colloquial-version = 45
description = 46
edition = 47
entitlement-data-required = 48
entitlement-key = 49
generator = 50
persistent-id = 51
product = 52
product-family = 53
revision = 54
summary = 55
unspsc-code = 56
unspsc-version = 57

The following describes each child item of this group.

2.8. The Resource Collection Definition

2.8.1. The hash-entry Array

CoSWID adds explicit support for the representation of hash entries using algorithms that are registered in the IANA “Named Information Hash Algorithm Registry” using the hash-entry member (label 58).

hash-entry = [ hash-alg-id: int, hash-value: bytes ]

The number used as a value for hash-alg-id MUST refer an ID in the “Named Information Hash Algorithm Registry” (see https://www.iana.org/assignments/named-information/named-information.xhtml); other hash algorithms MUST NOT be used. The hash-value MUST represent the raw hash value of the hashed resource generated using the hash algorithm indicated by the hash-alg-id.

2.8.2. The resource-collection Group

A list of items both used in evidence (created by a software discovery process) and payload (installed in an endpoint) content of a CoSWID tag document to structure and differentiate the content of specific CoSWID tag types. Potential content includes directories, files, processes, or resources.

The CDDL for the resource-collection group follows:

resource-collection = (
  ? directory => directory-entry,
  ? file => file-entry,
  ? process => process-entry,
  ? resource => resource-entry,
)

filesystem-item = (
  global-attributes,
  ? key => bool,
  ? location => text,
  fs-name => text,
  ? root => text,
)

path-elements-entry = [ [ * file-entry ],
                        [ * directory-entry ],
                      ]

file-entry = {
  filesystem-item,
  ? size => integer,
  ? file-version => text,
  ? hash => hash-entry,
  * $$file-extension
}

directory-entry = {
  filesystem-item,
  path-elements => path-elements-entry,
  * $$directory-extension
}

process-entry = {
  global-attributes,
  process-name => text,
  ? pid => integer,
  * $$process-extension
}

resource-entry = {
  global-attributes,
  type => text,
  * $$resource-extension
}

directory = 16
file = 17
process = 18
resource = 19
size = 20
file-version = 21
key = 22
location = 23
fs-name = 24
root = 25
path-elements = 26
process-name = 27
pid = 28
type = 29

The following describes each member of the groups and maps illustrated above.

2.8.3. The payload-entry Group

The CDDL for the payload-entry group follows:

payload-entry = {
  global-attributes,
  resource-collection,
  * $$payload-extension
}

The following describes each child item of this group.

2.8.4. The evidence-entry Group

The CDDL for the evidence-entry group follows:

evidence-entry = {
  global-attributes,
  resource-collection,
  ? date => time,
  ? device-id => text,
  * $$evidence-extension
}
date = 35
device-id = 36

The following describes each child item of this group.

2.9. Full CDDL Definition

In order to create a valid CoSWID document the structure of the corresponding CBOR message MUST adhere to the following CDDL data definition.

concise-swid-tag = {
  global-attributes,
  tag-id => text,
  tag-version => integer,
  ? corpus => bool,
  ? patch => bool,
  ? supplemental => bool,
  software-name => text,
  ? software-version => text,
  ? version-scheme => $version-scheme,
  ? media => text,
  ? software-meta =>  software-meta-entry / [ 2* software-meta-entry ],
  entity => entity-entry / [ 2* entity-entry ],
  ? link => link-entry / [ 2* link-entry ],
  ? (( payload => payload-entry ) // ( evidence => evidence-entry )),
  * $$coswid-extension 
}

any-uri = text
label = text / int

$version-scheme /= multipartnumeric
$version-scheme /= multipartnumeric-suffix
$version-scheme /= alphanumeric
$version-scheme /= decimal
$version-scheme /= semver
$version-scheme /= uint / text

any-attribute = (
  label => text / int / [ 2* text ] / [ 2* int ]
)

global-attributes = (
  ? lang => text,
  * any-attribute,
)

hash-entry = [ hash-alg-id: int,
               hash-value: bytes,
             ]

entity-entry = {
  global-attributes,
  entity-name => text,
  ? reg-id => any-uri,
  role => $role / [ 2* $role ],
  ? thumbprint => hash-entry,
  * $$entity-extension,
}

$role /= tag-creator
$role /= software-creator
$role /= aggregator
$role /= distributor
$role /= licensor
$role /= uint / text

link-entry = {
  global-attributes,
  ? artifact => text,
  href => any-uri,
  ? media => text,
  ? ownership => $ownership,
  rel => $rel,
  ? media-type => text,
  ? use => $use,
  * $$link-extension 
}

$ownership /= shared
$ownership /= private
$ownership /= abandon
$ownership /= uint / text

$rel /= ancestor 
$rel /= component
$rel /= feature
$rel /= installationmedia
$rel /= packageinstaller
$rel /= parent
$rel /= patches
$rel /= requires
$rel /= see-also
$rel /= supersedes
$rel /= supplemental
$rel /= uint / text

$use /= optional
$use /= required
$use /= recommended
$use /= uint / text

software-meta-entry = {
  global-attributes,
  ? activation-status => text,
  ? channel-type => text,
  ? colloquial-version => text,
  ? description => text,
  ? edition => text,
  ? entitlement-data-required => bool,
  ? entitlement-key => text,
  ? generator => text,
  ? persistent-id => text,
  ? product => text,
  ? product-family => text,
  ? revision => text,
  ? summary => text,
  ? unspsc-code => text,
  ? unspsc-version => text,
  * $$meta-extension,
}

resource-collection = (
  ? directory => directory-entry,
  ? file => file-entry,
  ? process => process-entry,
  ? resource => resource-entry,
  * $$resource-collection-extension
)

file-entry = {
  filesystem-item,
  ? size => integer,
  ? file-version => text,
  ? hash => hash-entry,
  * $$file-extension
}

path-elements-entry = [ [ * file-entry ],
                        [ * directory-entry ],
                      ]

directory-entry = {
  filesystem-item,
  path-elements => path-elements-entry,
  * $$directory-extension
}

process-entry = {
  global-attributes,
  process-name => text,
  ? pid => integer,
  * $$process-extension
}

resource-entry = {
  global-attributes,
  type => text,
  * $$resource-extension
}

filesystem-item = (
  global-attributes,
  ? key => bool,
  ? location => text,
  fs-name => text,
  ? root => text,
)

payload-entry = {
  global-attributes,
  resource-collection,
  * $$payload-extension 
}

evidence-entry = {
  global-attributes,
  resource-collection,
  ? date => time,
  ? device-id => text,
  * $$evidence-extension 
}

; "global map member" integer indexes
tag-id = 0
software-name = 1
entity = 2
evidence = 3
link = 4
software-meta = 5
payload = 6
hash = 7
corpus = 8
patch = 9
media = 10
supplemental = 11
tag-version = 12
software-version = 13
version-scheme = 14
lang = 15
directory = 16
file = 17
process = 18
resource = 19
size = 20
file-version = 21
key = 22
location = 23
fs-name = 24
root = 25
path-elements = 26
process-name = 27
pid = 28
type = 29
entity-name = 31
reg-id = 32
role = 33
thumbprint = 34
date = 35
device-id = 36
artifact = 37
href = 38
ownership = 39
rel = 40
media-type = 41
use = 42
activation-status = 43
channel-type = 44
colloquial-version = 45
description = 46
edition = 47
entitlement-data-required = 48
entitlement-key = 49
generator = 50
persistent-id = 51
product = 52
product-family = 53
revision = 54
summary = 55
unspsc-code = 56
unspsc-version = 57

; "version-scheme" integer indexes
multipartnumeric = 1
multipartnumeric-suffix = 2
alphanumeric = 3
decimal = 4
semver = 16384

; "role" integer indexes
tag-creator=1
software-creator=2
aggregator=3
distributor=4
licensor=5

; ownership integer indexes
shared=1
private=2
abandon=3

; "rel" integer indexes
ancestor=1
component=2
feature=3
installationmedia=4
packageinstaller=5
parent=6
patches=7
requires=8
see-also=9
supersedes=10
supplemental=11

; "use" integer indexes
optional=1
required=2
recommended=3

3. Determining the Type of CoSWID

The operational model for SWID and CoSWID tags was introduced in Section 1.1, which described four different CoSWID tag types. The following additional rules apply to the use of CoSWID tags to ensure that created tags properly identify the tag type.

The first matching rule MUST determine the type of the CoSWID tag.

  1. Primary Tag: A CoSWID tag MUST be considered a primary tag if the corpus, patch, and supplemental items are “false”.
  2. Supplemental Tag: A CoSWID tag MUST be considered a supplemental tag if the supplemental item is set to “true”.
  3. Corpus Tag: A CoSWID tag MUST be considered a corpus tag if the corpus item is “true”.
  4. Patch Tag: A CoSWID tag MUST be considered a patch tag if the patch item is “true”.

4. CoSWID Indexed Label Values

4.1. Version Scheme

The following table contains a set of values for use in the concise-swid-tag group’s version-scheme item. These values match the version schemes defined in the ISO/IEC 19770-2:2015 [SWID] specification. Index value indicates the value to use as the version-scheme item’s value. The Version Scheme Name provides human-readable text for the value. The Definition describes the syntax of allowed values for each entry.

Index Version Scheme Name Definition
1 multipartnumeric Numbers separated by dots, where the numbers are interpreted as integers (e.g.,1.2.3, 1.4.5, 1.2.3.4.5.6.7)
2 multipartnumeric+suffix Numbers separated by dots, where the numbers are interpreted as integers with an additional textual suffix (e.g., 1.2.3a)
3 alphanumeric Strictly a string, sorting is done alphanumerically
4 decimal A floating point number (e.g., 1.25 is less than 1.3)
16384 semver Follows the [SEMVER] specification

The values above are registered in the IANA “SWID/CoSWID Version Scheme Value” registry defined in section Section 5.2.1. Additional entires will likely be registered over time in this registry. Additionally, the index values 32768 through 65535 have been reserved for private use.

4.2. Entity Role Values

The following table indicates the index value to use for the entity-entry group’s role item (see Section 2.5). These values match the entity roles defined in the ISO/IEC 19770-2:2015 [SWID] specification. The “Index” value indicates the value to use as the role item’s value. The “Role Name” provides human-readable text for the value. The “Definition” describes the semantic meaning of each entry.

Index Role Name Definition
1 tagCreator The person or organization that created the containing SWID or CoSWID tag
2 softwareCreator From [SAM], “person or organization that creates a software product (3.46) or package”
3 aggregator From {{SWID}, “An organization or system that encapsulates software from their own and/or other organizations into a different distribution process (as in the case of virtualization), or as a completed system to accomplish a specific task (as in the case of a value added reseller).”
4 distributor From [SWID], “An entity that furthers the marketing, selling and/or distribution of software from the original place of manufacture to the ultimate user without modifying the software, its packaging or its labelling.”
5 licensor From [SAM] as “software licensor”, a “person or organization who owns or holds the rights to issue a software license for a specific software package”

The values above are registered in the IANA “SWID/CoSWID Entity Role Value” registry defined in section Section 5.2.2. Additional valid values will likely be registered over time. Additionally, the index values 128 through 255 have been reserved for private use.

4.3. Link Ownership Values

The following table indicates the index value to use for the link-entry group’s ownership item (see Section 2.6). These values match the link ownership values defined in the ISO/IEC 19770-2:2015 [SWID] specification. The “Index” value indicates the value to use as the link-entry group ownership item’s value. The “Ownership Type” provides human-readable text for the value. The “Definition” describes the semantic meaning of each entry.

Index Ownership Type Definition
1 abandon If the software component referenced by the CoSWID tag is uninstalled, then the referenced software SHOULD not be uninstalled
2 private If the software component referenced by the CoSWID tag is uninstalled, then the referenced software SHOULD be uninstalled as well.
3 shared If the software component referenced by the CoSWID tag is uninstalled, then the referenced software SHOULD be uninstalled if no other components sharing the software.

The values above are registered in the IANA “SWID/CoSWID Link Ownership Value” registry defined in section Section 5.2.3. Additional valid values will likely be registered over time. Additionally, the index values 128 through 255 have been reserved for private use.

4.4. Link Rel Values

The following table indicates the index value to use for the link-entry group’s rel item (see Section 2.6). These values match the link rel values defined in the ISO/IEC 19770-2:2015 [SWID] specification. The “Index” value indicates the value to use as the link-entry group ownership item’s value. The “Relationship Type” provides human-readable text for the value. The “Definition” describes the semantic meaning of each entry.

Index Relationship Type Definition
1 ancestor The link references a SWID/CoSWID tag for an ancestor of this software. This can be useful to define an upgrade path.
2 component The link references a SWID/CoSWID tag for a separate component of this software.
3 feature The link references a configurable feature of this software, that can be enabled or disabled without changing the installed files.
4 installationmedia The link references the installation package that can be used to install this software.
5 packageinstaller The link references the installation software needed to install this software.
6 parent The link references a SWID/CoSWID tag that is the parent of this SWID/CoSWID tag.
7 patches The link references a SWID/CoSWID tag that this software patches. Typically only used for patch SWID/CoSWID tags (see Section 1.1).
8 requires The link references a prerequisite for installing this software. A patch SWID/CoSWID tag (see Section 1.1) can use this to represent base software or another patch that needs to be installed first.
9 see-also The link references other software that may be of interest that relates to this software.
10 supersedes The link references another software that this software replaces. A patch SWID/CoSWID tag (see Section 1.1) can use this to represent another patch that this patch incorporates or replaces.
11 supplemental The link references a SWID/CoSWID tag that this tag supplements. Used on supplemental SWID/CoSWID tags (see Section 1.1).

The values above are registered in the IANA “SWID/CoSWID Link Relationship Value” registry defined in section Section 5.2.4. Additional valid values will likely be registered over time. Additionally, the index values 32768 through 65535 have been reserved for private use.

4.5. Link Use Values

The following table indicates the index value to use for the link-entry group’s use item (see Section 2.6). These values match the link use values defined in the ISO/IEC 19770-2:2015 [SWID] specification. The “Index” value indicates the value to use as the link-entry group use item’s value. The “Use Type” provides human-readable text for the value. The “Definition” describes the semantic meaning of each entry.

Index Use Type Definition
1 optional From [SWID], “Not absolutely required; the [Link]‘d software is installed only when specified.”
2 required From [SWID], “The [Link]‘d software is absolutely required for an operation software installation.”
3 recommended From [SWID], “Not absolutely required; the [Link]‘d software is installed unless specified otherwise.”

The values above are registered in the IANA “SWID/CoSWID Link Use Value” registry defined in section Section 5.2.5. Additional valid values will likely be registered over time. Additionally, the index values 128 through 255 have been reserved for private use.

5. IANA Considerations

This document has a number of IANA considerations, as described in the following subsections.

5.1. CoSWID Items Registry

This document uses integer values as index values in CBOR maps.

This document defines a new a new registry titled “CoSWID Items”. Future registrations for this registry are to be made based on [RFC8126] as follows:

Range Registration Procedures
0-32767 Standards Action
32768-4294967295 Specification Required

All negative values are reserved for Private Use.

Initial registrations for the “CoSWID Items” registry are provided below. Assignments consist of an integer index value, the item name, and a reference to the defining specification.

Index Item Name Specification
0 tag-id RFC-AAAA
1 software-name RFC-AAAA
2 entity RFC-AAAA
3 evidence RFC-AAAA
4 link RFC-AAAA
5 software-meta RFC-AAAA
6 payload RFC-AAAA
7 hash RFC-AAAA
8 corpus RFC-AAAA
9 patch RFC-AAAA
10 media RFC-AAAA
11 supplemental RFC-AAAA
12 tag-version RFC-AAAA
13 software-version RFC-AAAA
14 version-scheme RFC-AAAA
15 lang RFC-AAAA
16 directory RFC-AAAA
17 file RFC-AAAA
18 process RFC-AAAA
19 resource RFC-AAAA
20 size RFC-AAAA
21 file-version RFC-AAAA
22 key RFC-AAAA
23 location RFC-AAAA
24 fs-name RFC-AAAA
25 root RFC-AAAA
26 path-elements RFC-AAAA
27 process-name RFC-AAAA
28 pid RFC-AAAA
29 type RFC-AAAA
31 entity-name RFC-AAAA
32 reg-id RFC-AAAA
33 role RFC-AAAA
34 thumbprint RFC-AAAA
35 date RFC-AAAA
36 device-id RFC-AAAA
37 artifact RFC-AAAA
38 href RFC-AAAA
39 ownership RFC-AAAA
40 rel RFC-AAAA
41 media-type RFC-AAAA
42 use RFC-AAAA
43 activation-status RFC-AAAA
44 channel-type RFC-AAAA
45 colloquial-version RFC-AAAA
46 description RFC-AAAA
47 edition RFC-AAAA
48 entitlement-data-required RFC-AAAA
49 entitlement-key RFC-AAAA
50 generator RFC-AAAA
51 persistent-id RFC-AAAA
52 product RFC-AAAA
53 product-family RFC-AAAA
54 revision RFC-AAAA
55 summary RFC-AAAA
56 unspsc-code RFC-AAAA
57 unspsc-version RFC-AAAA
58-4294967295 Unassigned

5.2. SWID/CoSWID Value Registries

The following IANA registries provide a mechanism for new valid values to be added over time to common enumerations used by SWID and CoSWID.

5.2.1. SWID/CoSWID Version Scheme Value Registry

This document uses unsigned 16-bit index values to represent version-scheme item values. The initial set of version-scheme values are derived from the textual version scheme names defined in the ISO/IEC 19770-2:2015 specification [SWID].

This document defines a new a new registry titled “SWID/CoSWID Version Scheme Values”. Future registrations for this registry are to be made based on [RFC8126] as follows:

[TO BE REMOVED: This registration should take place at the following location: https://www.iana.org/assignments/swid]

Range Registration Procedures
0-16383 Standards Action
16384-32767 Specification Required
32768-65535 Reserved for Private Use

Initial registrations for the “SWID/CoSWID Version Scheme Value” registry are provided below. Assignments consist of an integer Index value, the Version Scheme Name, and a reference to the defining specification.

Index Version Scheme Name Specification
0 Reserved
1 multipartnumeric See Section 4.1
2 multipartnumeric+suffix See Section 4.1
3 alphanumeric See Section 4.1
4 decimal See Section 4.1
5-16383 Unassigned
16384 semver [SEMVER]
16385-32767 Unassigned
32768-65535 Reserved for Private Use

5.2.2. SWID/CoSWID Entity Role Value Registry

This document uses unsigned 8-bit index values to represent entity-entry role item values. The initial set of Entity roles are derived from the textual role names defined in the ISO/IEC 19770-2:2015 specification [SWID].

This document defines a new a new registry titled “SWID/CoSWID Entity Role Values”. Future registrations for this registry are to be made based on [RFC8126] as follows:

[TO BE REMOVED: This registration should take place at the following location: https://www.iana.org/assignments/swid]

Range Registration Procedures
0-31 Standards Action
32-127 Specification Required
128-255 Reserved for Private Use

Initial registrations for the “SWID/CoSWID Entity Role Value” registry are provided below. Assignments consist of an integer Index value, a Role Name, and a reference to the defining specification.

Index Role Name Specification
0 Reserved
1 tagCreator See Section 4.2
2 softwareCreator See Section 4.2
3 aggregator See Section 4.2
4 distributor See Section 4.2
5 licensor See Section 4.2
6-127 Unassigned
128-255 Reserved for Private Use

5.2.3. SWID/CoSWID Link Ownership Value Registry

This document uses unsigned 8-bit index values to represent link-entry ownership item values. The initial set of Link ownership values are derived from the textual ownership names defined in the ISO/IEC 19770-2:2015 specification [SWID].

This document defines a new a new registry titled “SWID/CoSWID Link Ownership Values”. Future registrations for this registry are to be made based on [RFC8126] as follows:

[TO BE REMOVED: This registration should take place at the following location: https://www.iana.org/assignments/swid]

Range Registration Procedures
0-31 Standards Action
32-127 Specification Required
128-255 Reserved for Private Use

Initial registrations for the “SWID/CoSWID Link Ownership Value” registry are provided below. Assignments consist of an integer Index value, an Ownership Type Name, and a reference to the defining specification.

Index Ownership Type Name Definition
0 Reserved
1 abandon See Section 4.3
2 private See Section 4.3
3 shared See Section 4.3
4-16384 Unassigned
16385-32767 Unassigned
32768-65535 Reserved for Private Use

5.2.4. SWID/CoSWID Link Relationship Value Registry

This document uses unsigned 16-bit index values to represent link-entry rel item values. The initial set of rel values are derived from the textual rel names defined in the ISO/IEC 19770-2:2015 specification [SWID].

This document defines a new a new registry titled “SWID/CoSWID Link Relationship Values”. Future registrations for this registry are to be made based on [RFC8126] as follows:

[TO BE REMOVED: This registration should take place at the following location: https://www.iana.org/assignments/swid]

Range Registration Procedures
0-16383 Standards Action
16384-32767 Specification Required
32768-65535 Reserved for Private Use

Initial registrations for the “SWID/CoSWID Link Relationship Value” registry are provided below. Assignments consist of an integer Index value, the Relationship Type Name, and a reference to the defining specification.

Index Relationship Type Name Specification
0 Reserved
1 ancestor See Section 4.4
2 component See Section 4.4
3 feature See Section 4.4
4 installationmedia See Section 4.4
5 packageinstaller See Section 4.4
6 parent See Section 4.4
7 patches See Section 4.4
8 requires See Section 4.4
9 see-also See Section 4.4
10 supersedes See Section 4.4
11 supplemental See Section 4.4
12-16384 Unassigned
16385-32767 Unassigned
32768-65535 Reserved for Private Use

5.2.5. SWID/CoSWID Link Use Value Registry

This document uses unsigned 8-bit index values to represent link-entry use item values. The initial set of Link use values are derived from the textual names defined in the ISO/IEC 19770-2:2015 specification [SWID].

This document defines a new a new registry titled “SWID/CoSWID Link Use Values”. Future registrations for this registry are to be made based on [RFC8126] as follows:

[TO BE REMOVED: This registration should take place at the following location: https://www.iana.org/assignments/swid]

Range Registration Procedures
0-31 Standards Action
32-127 Specification Required
128-255 Reserved for Private Use

Initial registrations for the “SWID/CoSWID Entity Role Value” registry are provided below. Assignments consist of an integer Index value, the Link Use Type Name, and a reference to the defining specification.

Index Link Use Type Name Specification
0 Reserved
1 optional See Section 4.5
2 required See Section 4.5
3 recommended See Section 4.5
4-127 Unassigned
128-255 Reserved for Private Use

5.3. swid+cbor Media Type Registration

IANA is requested add the following to the IANA “Media Types” registry.

Type name: application

Subtype name: swid+cbor

Required parameters: none

Optional parameters: none

Encoding considerations: Must be encoded as using [RFC7049]. See RFC-AAAA for details.

Security considerations: See Section 6 of RFC-AAAA.

Interoperability considerations: Applications MAY ignore any key value pairs that they do not understand. This allows backwards compatible extensions to this specification.

Published specification: RFC-AAAA

Applications that use this media type: The type is used by Software asset management systems, Vulnerability assessment systems, and in applications that use remote integrity verification.

Fragment identifier considerations: Fragment identification for application/swid+cbor is supported by using fragment identifiers as specified by RFC-AAAA. [Section to be defined]

Additional information:

Magic number(s): first five bytes in hex: da 53 57 49 44

File extension(s): coswid

Macintosh file type code(s): none

Macintosh Universal Type Identifier code: org.ietf.coswid conforms to public.data

Person & email address to contact for further information: Henk Birkholz <henk.birkholz@sit.fraunhofer.de>

Intended usage: COMMON

Restrictions on usage: None

Author: Henk Birkholz <henk.birkholz@sit.fraunhofer.de>

Change controller: IESG

5.4. CoAP Content-Format Registration

IANA is requested to assign a CoAP Content-Format ID for the CoSWID media type in the “CoAP Content-Formats” sub-registry, from the “IETF Review or IESG Approval” space (256..999), within the “CoRE Parameters” registry [RFC7252]:

CoAP Content-Format IDs
Media type Encoding ID Reference
application/swid+cbor - TBD1 RFC-AAAA

5.5. CBOR Tag Registration

IANA is requested to allocate a tag in the “CBOR Tags” registry”, preferably with the specific value requested:

Tag Data Item Semantics
1398229316 map Concise Software Identifier (CoSWID) [RFC-AAAA]

6. Security Considerations

SWID and CoSWID tags contain public information about software components and, as such, do not need to be protected against disclosure on an endpoint. Similarly, SWID tags are intended to be easily discoverable by applications and users on an endpoint in order to make it easy to identify and collect all of an endpoint’s SWID tags. As such, any security considerations regarding SWID tags focus on the application of SWID tags to address security challenges, and the possible disclosure of the results of those applications.

A signed SWID tag whose signature has been validated can be relied upon to be unchanged since it was signed. If the SWID tag was created by the software provider, is signed, and the software provider can be authenticated as the originator of the signature, then the tag can be considered authoritative. In this way, an authoritative SWID tag contains information about a software product provided by the maintainer of the product, who is expected to be an expert in their own product. Thus, authoritative SWID tags can be trusted to represent authoritative information about the software product. Having an authoritative SWID tag can be useful when the information in the tag needs to be trusted, such as when the tag is being used to convey reference integrity measurements for software components. By contrast, the data contained in unsigned tags cannot be trusted to be unmodified.

SWID tags are designed to be easily added and removed from an endpoint along with the installation or removal of software components. On endpoints where addition or removal of software components is tightly controlled, the addition or removal of SWID tags can be similarly controlled. On more open systems, where many users can manage the software inventory, SWID tags can be easier to add or remove. On such systems, it can be possible to add or remove SWID tags in a way that does not reflect the actual presence or absence of corresponding software components. Similarly, not all software products automatically install SWID tags, so products can be present on an endpoint without providing a corresponding SWID tag. As such, any collection of SWID tags cannot automatically be assumed to represent either a complete or fully accurate representation of the software inventory of the endpoint. However, especially on devices that more strictly control the ability to add or remove applications, SWID tags are an easy way to provide an preliminary understanding of that endpoint’s software inventory.

Any report of an endpoint’s SWID tag collection provides information about the software inventory of that endpoint. If such a report is exposed to an attacker, this can tell them which software products and versions thereof are present on the endpoint. By examining this list, the attacker might learn of the presence of applications that are vulnerable to certain types of attacks. As noted earlier, SWID tags are designed to be easily discoverable by an endpoint, but this does not present a significant risk since an attacker would already need to have access to the endpoint to view that information. However, when the endpoint transmits its software inventory to another party, or that inventory is stored on a server for later analysis, this can potentially expose this information to attackers who do not yet have access to the endpoint. For this reason, it is important to protect the confidentiality of SWID tag information that has been collected from an endpoint, not because those tags individually contain sensitive information, but because the collection of SWID tags and their association with an endpoint reveals information about that endpoint’s attack surface.

Finally, both the ISO-19770-2:2015 XML schema definition and the Concise SWID data definition allow for the construction of “infinite” SWID tags or SWID tags that contain malicious content with the intent if creating non-deterministic states during validation or processing of SWID tags. While software product vendors are unlikely to do this, SWID tags can be created by any party and the SWID tags collected from an endpoint could contain a mixture of vendor and non-vendor created tags. For this reason, tools that consume SWID tags ought to treat the tag contents as potentially malicious and employ input sanitizing on the tags they ingest.

7. Acknowledgments

TBD

8. Change Log

Changes from version 03 to version 09:

Changes from version 02 to version 03:

Changes from version 01 to version 02:

Changes from version 00 to version 01:

Changes since adopted as a WG I-D -00:

Changes from version 06 to version 07:

Changes from version 05 to version 06:

Changes from version 04 to version 05:

Changes from version 03 to version 04:

Changes from version 02 to version 03:

Changes from version 01 to version 02:

Changes from version 00 to version 01:

9. Contributors

10. References

10.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013.
[RFC7252] Shelby, Z., Hartke, K. and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014.
[RFC8126] Cotton, M., Leiba, B. and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017.
[RFC8610] Birkholz, H., Vigano, C. and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019.
[SAM] "Information technology - Software asset management - Part 5: Overview and vocabulary", ISO/IEC 19770-5:2015, November 2013.
[SEMVER] Preston-Werner, T., "Semantic Versioning 2.0.0", n.d..
[SWID] "Information technology - Software asset management - Part 2: Software identification tag", ISO/IEC 19770-2:2015, October 2015.
[SWID-GUIDANCE] Waltermire, D., Cheikes, B., Feldman, L. and G. Witte, "Guidelines for the Creation of Interoperable Software Identification (SWID) Tags", NISTIR 8060, April 2016.
[W3C.REC-css3-mediaqueries-20120619] Rivoal, F., "Media Queries", World Wide Web Consortium Recommendation REC-css3-mediaqueries-20120619, June 2012.
[W3C.REC-xpath20-20101214] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., Kay, M., Robie, J. and J. Simeon, "XML Path Language (XPath) 2.0 (Second Edition)", World Wide Web Consortium Recommendation REC-xpath20-20101214, December 2010.
[X.1520] "Recommendation ITU-T X.1520 (2014), Common vulnerabilities and exposures", April 2011.

10.2. Informative References

[CamelCase] "UpperCamelCase", August 2014.
[I-D.birkholz-rats-tuda] Fuchs, A., Birkholz, H., McDonald, I. and C. Bormann, "Time-Based Uni-Directional Attestation", Internet-Draft draft-birkholz-rats-tuda-00, March 2019.
[KebabCase] "KebabCase", December 2014.
[RFC4122] Leach, P., Mealling, M. and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005.
[RFC8322] Field, J., Banghart, S. and D. Waltermire, "Resource-Oriented Lightweight Information Exchange (ROLIE)", RFC 8322, DOI 10.17487/RFC8322, February 2018.
[RFC8520] Lear, E., Droms, R. and D. Romascanu, "Manufacturer Usage Description Specification", RFC 8520, DOI 10.17487/RFC8520, March 2019.

Appendix A. Signed Concise SWID Tags using COSE

SWID tags, as defined in the ISO-19770-2:2015 XML schema, can include cryptographic signatures to protect the integrity of the SWID tag. In general, tags are signed by the tag creator (typically, although not exclusively, the vendor of the software component that the SWID tag identifies). Cryptographic signatures can make any modification of the tag detectable, which is especially important if the integrity of the tag is important, such as when the tag is providing reference integrity measurements for files.

The ISO-19770-2:2015 XML schema uses XML DSIG to support cryptographic signatures. CoSWID tags require a different signature scheme than this. COSE (CBOR Object Signing and Encryption) provides the required mechanism [RFC8152]. Concise SWID can be wrapped in a COSE Single Signer Data Object (COSE_Sign1) that contains a single signature. The following CDDL defines a more restrictive subset of header attributes allowed by COSE tailored to suit the requirements of Concise SWID tags.

<CODE BEGINS>
signed-coswid = #6.18(COSE-Sign1-coswid)

cose-label = int / tstr
cose-values = any

protected-signed-coswid-header = {
    1 => int,                      ; algorithm identifier
    3 => "application/swid+cbor",
    * cose-label => cose-values,
}

unprotected-signed-coswid-header = {
    4 => bstr,                     ; key identifier
    * cose-label => cose-values,
}

COSE-Sign1-coswid = [
    protected: bstr .cbor protected-signed-coswid-header,
    unprotected: unprotected-signed-coswid-header,
    payload: bstr .cbor concise-swid-tag,
    signature: bstr,
]
<CODE ENDS>

Optionally, the COSE_Sign structure that allows for more than one signature to be applied to a CoSWID tag MAY be used. The corresponding usage scenarios are domain-specific and require well-defined application guidance. Representation of the corresponding guidance is out-of-scope of this document.

Additionally, the COSE Header counter signature MAY be used as an attribute in the unprotected header map of the COSE envelope of a CoSWID. The application of counter signing enables second parties to provide a signature on a signature allowing for a proof that a signature existed at a given time (i.e., a timestamp).

Authors' Addresses

Henk Birkholz Fraunhofer SIT Rheinstrasse 75 Darmstadt, 64295 Germany EMail: henk.birkholz@sit.fraunhofer.de
Jessica Fitzgerald-McKay Department of Defense 9800 Savage Road Ft. Meade, Maryland USA EMail: jmfitz2@nsa.gov
Charles Schmidt The MITRE Corporation 202 Burlington Road Bedford, Maryland 01730 USA EMail: cmschmidt@mitre.org
David Waltermire National Institute of Standards and Technology 100 Bureau Drive Gaithersburg, Maryland 20877 USA EMail: david.waltermire@nist.gov