Concise Software Identification Tags
Extracted elements (30)
CBOR was chosen to represent SWID information because it significantly reduces data size compared to XML — the CBOR scaffolding takes up 10 percent or less of the XML equivalent, resulting in 50–85 percent overall size reduction, making CoSWID suitable for constrained devices and networks.
CDDL sockets (extension points) such as $$coswid-extension, $$entity-extension, and $$resource-collection-extension allow well-formed extensions to be defined in supplementary CDDL without modifying the base specification, supporting uses that go beyond ISO/IEC 19770-2:2015.
Integer indices are used instead of text labels to avoid the need for an explicit CoSWID version number. New constructs can be added by assigning new integer indices via the CoSWID Items registry; deprecated constructs can be replaced with new indices, allowing implementations to identify constructs by index alone.
The patch item's value MUST NOT be set to 'true' if installation of the associated package changes the software component's version number; version-changing updates use a new primary tag instead. This distinction between patching and upgrading preserves accurate software inventory tracking.
The 'swidpath' URI scheme carries XPath queries that MUST use SWID XML attribute names (CamelCase), not CoSWID CDDL names (KebabCase). This specification does not define how to resolve an XPath query in the context of CBOR.
While SWID and CoSWID are intended to share the same implicit information model, this document does not define the information model or a mapping between the two formats. Future revisions of ISO/IEC 19770-2:2015 or this specification may cause the implicit information models to diverge.
An entity item MUST be provided with the role of 'tag-creator' for every CoSWID tag, identifying the organization that created the tag. An entity item SHOULD be provided with the role of 'software-creator' if this information is known.
Encoders SHOULD NOT use string values based on registered registry names, as these are less concise than their integer index equivalents. However, a decoder MUST be prepared to accept text strings not specified in this document.
If corpus, patch, and supplemental are all 'false', or if corpus is 'true', a software-version item MUST be included with the version of the software component. This ensures primary and corpus tags always carry version information.
Text strings in CoSWID MUST be encoded in UTF-8 consistent with the Net-Unicode definition in RFC 5198. All names registered with IANA for CoSWID MUST also be valid XML Schema NMTOKEN values to ensure compatibility with the SWID specification.
The hash-alg-id in a hash-entry MUST refer to an ID in the IANA Named Information Hash Algorithm Registry with a Status of 'current'; other hash algorithms MUST NOT be used. If the algorithm is unknown, the integer value '0' MUST be used.
The location item within filesystem-item MUST be either an absolute path, a path relative to the parent directory item, or a path relative to the CoSWID tag location if no parent is defined. It MUST NOT include the file's name, which is provided separately by fs-name.
The patch and supplemental items MUST NOT both be set to 'true'. If the patch item is 'true', the tag MUST contain at least one link item with rel='patches' and an href identifying the patched software.
The tag-id MUST be globally unique. If represented as a 16-byte binary string, it MUST be a valid UUID as defined by RFC 4122. A textual tag-id MUST NOT contain a sequence of two underscores ('__'), as that sequence is used as a separator in Software Identifiers.
When producing a revised tag, the new tag-version value MUST be greater than the old tag-version value. This allows a tag producer to correct a previously released tag without changing the software component it describes.
CoSWID tags are not intended to contain confidential information. Tag authors are explicitly advised not to record unprotected, private software license keys in the entitlement-key field. Deployment of CoSWID tags describing installed software on an endpoint reveals software inventory, which may be sensitive.
The concise-swid-tag map is the root CBOR structure for a CoSWID tag. It contains required fields tag-id (index 0), software-name (index 1), entity (index 2), and tag-version (index 12), plus optional fields including corpus, patch, supplemental, software-version, version-scheme, link, payload, and evidence.
The entity-entry map (index 2) contains entity-name (index 31), optional reg-id URI (index 32), role (index 33) as an integer label with text escape, and optional thumbprint (index 34) as a hash-entry providing a hash of the signing entity's public key certificate.
The evidence-entry map extends resource-collection with date (index 35, epoch-based integer-time), device-id (index 36), and location (index 23, always absolute path). Evidence is generated ad hoc on the target device and is mutually exclusive with payload.
The link-entry map establishes relationship arcs between a CoSWID tag and another resource. Key fields are href (index 38, URI-reference), rel (index 40, relationship type), and optional ownership (index 39), media-type (index 41), use (index 42), and artifact (index 37).
The resource-collection group defines the content of payload and evidence items, supporting directory entries (index 16), file entries (index 17), process entries (index 18), and resource entries (index 19). File entries include size (index 20), file-version (index 21), key flag (index 22), location (index 23), and optional hash.
The software-meta-entry map (index 5) provides an open-ended key/value store with predefined keys including activation-status (43), entitlement-key (49), persistent-id (51), product (52), product-family (53), summary (55), and UNSPSC classification codes (56, 57).
IANA created five registries for Software ID enumeration values: Version Scheme Values (Section 6.2.4), Entity Role Values (Section 6.2.5), Link Ownership Values (Section 6.2.6), Link Relationship Values (Section 6.2.7), and Link Use Values (Section 6.2.8). All use integer indices with a text escape mechanism.
IANA created the 'CoSWID Items' registry to assign unique integer index values to new data items added to the CoSWID model via CDDL sockets. Registration policy and initial values are defined in Section 6.1.
IANA registered the 'application/swid+cbor' media type for CoSWID tags and a corresponding CoAP Content-Format entry (Section 6.4). A CBOR tag was also registered (Section 6.5) to allow CoSWID tags to be self-identifying within CBOR data streams.
IANA registered the 'swid' and 'swidpath' URI schemes (Section 6.6). The 'swid:' scheme is used in link href values to reference another SWID or CoSWID tag by tag-id; 'swidpath:' references a tag via an XPath query for compatibility with SWID.
CoSWID tags SHOULD be signed to ensure integrity and authenticity. Section 7 defines signed CoSWID tag structure; unsigned tags cannot be trusted as authoritative records of software identity for security-sensitive use cases such as remote attestation or vulnerability assessment.
Tag type is determined by first-match rules: (1) Primary — corpus, patch, supplemental all false; (2) Supplemental — supplemental is true; (3) Corpus — corpus is true; (4) Patch — patch is true. A tag with both corpus and patch true resolves as a corpus tag.
CoSWID uses CBOR encoding where 57 human-readable CDDL vocabulary labels are mapped to small integer indices. This reduces scaffolding overhead to 10 percent or less compared to XML SWID, achieving 50–85 percent overall size reduction in generic usage scenarios.
The hash-entry is a two-element CBOR array: [hash-alg-id: int, hash-value: bytes]. The hash-value MUST be raw bytes (not base64-encoded) produced by the algorithm identified by hash-alg-id. Used for both file hashes (index 7) and entity thumbprints (index 34).