RFC 8412
Software Inventory Message and Attributes (SWIMA) for PA-TNC
Pages: 101
Proposed Standard
Proposed Standard
Part 4 of 6 – Pages 46 to 67
5. Software Inventory Messages and Attributes
This section describes the format and semantics of the SWIMA protocol. This protocol uses the PA-TNC message header format [RFC5792].5.1. PA Subtype (aka PA-TNC Component Type)
The NEA PB-TNC [RFC5793] interface provides a general message-batching protocol capable of carrying one or more PA-TNC messages between the Posture Broker Client and Posture Broker Server. When PB-TNC is carrying a PA-TNC message, the PB-TNC message headers contain a 32-bit identifier called the "PA Subtype". The PA Subtype field indicates the type of component associated with all of the PA-TNC attributes carried by the PB-TNC message. The core set of PA Subtypes is defined in the PA-TNC specification. This specification defines a new "SWIMA Attributes" PA Subtype, which is registered in Section 10.2 of this document and is used as a namespace for the collection of SWIMA attributes defined in this document. For more information on PB-TNC messages and PA-TNC messages, as well as their message headers, see the PB-TNC [RFC5793] and PA-TNC [RFC5792] specifications, respectively.5.2. SWIMA Attribute Overview
Each PA-TNC attribute described in this specification is intended to be sent between the SWIMA-PC and SWIMA-PV and so will be carried in a PB-TNC message indicating a PA Subtype of "SWIMA Attributes". PB-TNC messages MUST always include the SWIMA Attributes Subtype defined in Section 5.1 when carrying SWIMA attributes over PA-TNC. The attributes defined in this specification appear below, along with a short summary of their purposes. PA-TNC attribute types are identified in the PA-TNC Attribute Header via the PA-TNC Attribute Vendor ID field and the PA-TNC Attribute Type field; see Section 4.1 of [RFC5792] for details. Table 1 identifies the appropriate values for these fields for each attribute type used within the SWIMA protocol. All attributes have a PEN value of 0x000000. Both the hexadecimal and decimal values are provided in the Integer column in the table. Each attribute is described in greater detail in subsequent sections (identified in the table's Description column).
+--------------+-----------------+----------------------------------+
| Attribute | Integer | Description |
| Name | | |
+--------------+-----------------+----------------------------------+
| SWIMA | 0x0000000D (13) | Request sent from a SWIMA-PV to |
| Request | | a SWIMA-PC for the SWIMA-PC to |
| | | provide a software inventory or |
| | | event list. It might also |
| | | establish a subscription. |
| | | (Section 5.6) |
| | | |
| Software | 0x0000000E (14) | An inventory sent without |
| Identifier | | Software Inventory Evidence |
| Inventory | | Records sent from a SWIMA-PC. |
| | | (Section 5.7) |
| | | |
| Software | 0x0000000F (15) | A collection of events impacting |
| Identifier | | the endpoint's Software |
| Events | | Inventory Evidence Collection, |
| | | where events do not include |
| | | Software Inventory Evidence |
| | | Records. (Section 5.8) |
| | | |
| Software | 0x00000010 (16) | An inventory including Software |
| Inventory | | Inventory Evidence Records sent |
| | | from a SWIMA-PC. (Section 5.9) |
| | | |
| Software | 0x00000011 (17) | A collection of events impacting |
| Events | | the endpoint's Software |
| | | Inventory Evidence Collection, |
| | | where events include Software |
| | | Inventory Evidence Records. |
| | | (Section 5.10) |
| | | |
| Subscription | 0x00000012 (18) | A request for a list of a |
| Status | | SWIMA-PV's active subscriptions |
| Request | | on a SWIMA-PC. (Section 5.11) |
| | | |
| Subscription | 0x00000013 (19) | A list of a SWIMA-PV's active |
| Status | | subscriptions on a SWIMA-PC. |
| Response | | (Section 5.12) |
| | | |
| Source | 0x00000014 (20) | A request for information about |
| Metadata | | a SWIMA-PC's data sources. |
| Request | | (Section 5.13) |
| | | |
| Source | 0x00000015 (21) | Descriptive metadata about a | | Metadata | | SWIMA-PC's data sources. | | Response | | (Section 5.14) | | | | | | PA-TNC Error | 0x00000008 (8) | An error attribute as defined in | | | | the PA-TNC specification | | | | [RFC5792]. | +--------------+-----------------+----------------------------------+ Table 1: SWIMA Attribute Enumeration Because one of the Software Identifier Inventory, Software Identifier Events, Software Inventory, or Software Events attributes is expected to be sent to a SWIMA-PV in direct response to a SWIMA Request attribute or in fulfillment of an active subscription, those four attribute types are referred to collectively in this document as "SWIMA Response attributes". All SWIMA-PVs MUST be capable of sending SWIMA Request attributes and be capable of receiving and processing all SWIMA Response attributes as well as PA-TNC Error attributes. All SWIMA-PCs MUST be capable of receiving and processing SWIMA Request attributes and be capable of sending all types of SWIMA Response attributes as well as PA-TNC Error attributes. SWIMA-PVs MUST ignore any SWIMA Request attributes that they receive. SWIMA-PCs MUST ignore any SWIMA Response attributes or PA-TNC Error attributes that they receive.5.3. Message Diagram Syntax
This specification uses diagrams to define the syntax of new PA-TNC messages and attributes. Each diagram depicts the format and size of each field in bits. Implementations MUST send the bits depicted in each diagram as they are shown from left to right for each 32-bit quantity, "traversing" the diagram from top to bottom. Fields representing numeric values MUST be sent in network (big endian) byte order. Descriptions of bit field (e.g., flag) values refer to the position of the bit within the field. These bit positions are numbered from the most significant bit through the least significant bit. As such, an octet with only bit 0 set would have a value of 0x80 (1000 0000), an octet with only bit 1 set would have a value of 0x40 (0100 0000), and an octet with only bit 7 set would have a value of 0x01 (0000 0001).
5.4. Normalization of Text Encoding
In order to ensure consistency of transmitted attributes, some fields require normalization of their format. When this is necessary, this information is indicated in the field's description. In such cases, the field contents MUST be normalized to Network Unicode format as defined in RFC 5198 [RFC5198]. Network Unicode format defines a refinement of UTF-8 [RFC3629] that ensures a normalized expression of characters. SWIMA-PCs and SWIMA-PVs MUST NOT perform conversion and normalization on any field values except those specifically identified in the following sections as requiring normalization. Note, however, that some data models require additional normalization before source information is added to an endpoint's Software Inventory Evidence Collection as a record. The references from the "Software Data Model Types" registry (see Section 10.5) will note where this is necessary.5.5. Request IDs
All SWIMA Request attributes MUST include a Request ID value. The Request ID field provides a value that identifies a given request relative to other requests between a SWIMA-PV and the receiving SWIMA-PC. Specifically, the SWIMA-PV assigns each SWIMA Request attribute a Request ID value that is intended to be unique within the lifetime of a given network Connection ID. In the case that a SWIMA Request requests the establishment of a subscription and the receiving SWIMA-PC agrees to that subscription, the Request ID of that SWIMA Request (i.e., the establishing request of the subscription) becomes that subscription's Subscription ID. All attributes sent in fulfillment of this subscription include a flag indicating that the attribute fulfills a subscription and the subscription's Subscription ID. A SWIMA-PV MUST NOT reuse a Request ID value in communications with a given SWIMA-PC while that Request ID is also serving as a Subscription ID for an active subscription with that SWIMA-PC. In the case where a SWIMA-PC receives a SWIMA Request from a given SWIMA-PV where that Request ID is also the Subscription ID of an active subscription with that SWIMA-PV, the SWIMA-PC MUST respond with a PA-TNC Error attribute with an error code of SWIMA_SUBSCRIPTION_ID_REUSE_ERROR. Note that this error does not cancel the indicated subscription. Subscription Status Requests and Subscription Status Responses do not include Request IDs.
In the case where all possible Request ID values have been exhausted within the lifetime of a single network Connection ID, the sender MAY reuse previously used Request IDs within the same network connection if the ID is not being used as a Subscription ID. In the case where reuse is necessary due to exhaustion of possible ID values, the SWIMA-PV SHOULD structure the reuse to maximize the time between original and subsequent use. The Request ID value is included in a SWIMA Response attribute directly responding to this SWIMA Request to indicate which SWIMA Request was received and caused the response. Request IDs can be randomly generated or sequential, as long as values are not repeated per the rules in this paragraph. SWIMA-PCs are not required to check for duplicate Request IDs, except insofar as is necessary to detect Subscription ID reuse.5.6. SWIMA Request
A SWIMA-PV sends this attribute to a SWIMA-PC to request that the SWIMA-PC send software inventory information to the SWIMA-PV. A SWIMA-PC MUST NOT send this attribute. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | Software Identifier Count | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Earliest EID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | SUB-BLOCK (Repeated "Software Identifier Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 6: SWIMA Request Attribute 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Identifier Length | Software Identifier (var len) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 7: SWIMA Request Attribute SUB-BLOCK
+---------------+---------------------------------------------------+
| Field | Description |
+---------------+---------------------------------------------------+
| Flags: Bit 0 | If set (1), the SWIMA-PC MUST delete all |
| - Clear | subscriptions established by the requesting |
| Subscriptions | SWIMA-PV (barring any errors). |
| | |
| Flags: Bit 1 | If set (1), in addition to responding to the |
| - Subscribe | request as described, the SWIMA-PC MUST establish |
| | a subscription with parameters matching those in |
| | the SWIMA Request attribute (barring any errors). |
| | |
| Flags: Bit 2 | If unset (0), the SWIMA-PC's response MUST |
| - Result Type | include Software Inventory Evidence Records, and |
| | thus the response MUST be a Software Inventory, |
| | Software Events, or PA-TNC Error attribute. If |
| | set (1), the response MUST NOT include Software |
| | Inventory Evidence Records, and thus the response |
| | MUST be a Software Identifier Inventory, Software |
| | Identifier Events, or PA-TNC Error attribute. |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 3-7 - | to zero on transmission and ignored upon |
| Reserved | reception. |
| | |
| Software | A 3-byte unsigned integer indicating the number |
| Identifier | of Software Identifiers that follow. If this |
| Count | value is non-zero, this is a targeted request, as |
| | described in Section 3.5. The Software |
| | Identifier Length and Software Identifier fields |
| | are repeated, in order, the number of times |
| | indicated in this field. In the case where |
| | Software Identifiers are present, the SWIMA-PC |
| | MUST only report software that corresponds to the |
| | identifiers the SWIMA-PV provided in this |
| | attribute (or respond with a PA-TNC Error |
| | attribute). This field value MAY be 0, in which |
| | case there are no instances of the Software |
| | Identifier Length and Software Identifier fields. |
| | In this case, the SWIMA-PV is indicating an |
| | interest in all Software Inventory Evidence |
| | Records on the endpoint (i.e., this is not a |
| | targeted request). |
| | |
| Request ID | A value that uniquely identifies this SWIMA |
| | Request from a particular SWIMA-PV. |
| | |
| Earliest EID | In the case where the SWIMA-PV is requesting | | | software events, this field contains the EID | | | value of the earliest event the SWIMA-PV wishes | | | to have reported. (Note: The report will be | | | inclusive of the event with this EID value.) In | | | the case where the SWIMA-PV is requesting an | | | inventory, then this field MUST be 0 | | | (0x00000000). In the case where this field is | | | non-zero, the SWIMA-PV is requesting events, and | | | the SWIMA-PC MUST respond using a Software | | | Events, Software Identifier Events, or PA-TNC | | | Error attribute. In the case where this field is | | | zero, the SWIMA-PV is requesting an inventory, | | | and the SWIMA-PC MUST respond using a Software | | | Inventory, Software Identifier Inventory, or | | | PA-TNC Error attribute. | | | | | Software | A 2-byte unsigned integer indicating the length, | | Identifier | in bytes, of the Software Identifier field. | | Length | | | | | | Software | A string containing the Software Identifier value | | Identifier | from a Software Inventory Evidence Record. This | | | field value MUST be normalized to Network Unicode | | | format, as described in Section 5.4. This string | | | MUST NOT be null terminated. | +---------------+---------------------------------------------------+ Table 2: SWIMA Request Attribute Fields The SWIMA-PV sends the SWIMA Request attribute to a SWIMA-PC to request the indicated information. Note that between the Result Type flag and the Earliest EID field, the SWIMA-PC is constrained to a single possible SWIMA Response attribute type (or a PA-TNC Error attribute) in its response to the request. The Subscribe flag and the Clear Subscriptions flag are used to manage subscriptions for the requesting SWIMA-PV on the receiving SWIMA-PC. Specifically, an attribute with the Subscribe flag set seeks to establish a new subscription by the requesting SWIMA-PV to the given SWIMA-PC, while an attribute with the Clear Subscriptions flag set seeks to delete all existing subscriptions by the requesting SWIMA-PV on the given SWIMA-PC. Note that in the latter case, only the subscriptions associated with the Connection ID and the Posture Validator Identifier of the requester are deleted as described in Section 3.8.3. A newly established subscription has the parameters outlined in the SWIMA Request attribute. Specifically, the Result Type flag indicates the type of result to send in fulfillment of the
subscription, the value of the Earliest EID field indicates whether the fulfillment attributes list inventories or events, and the fields describing Software Identifiers (if present) indicate if and how a subscription is targeted. In the case that the SWIMA-PC is unable or unwilling to comply with the SWIMA-PV's request to establish or clear subscriptions, the SWIMA-PC MUST respond with a PA-TNC Error attribute with the SWIMA_SUBSCRIPTION_DENIED_ERROR error code. If the SWIMA-PV requests that subscriptions be cleared but has no existing subscriptions, this is not an error. An attribute requesting the establishment of a subscription is effectively doing "double duty", as it is a request for an immediate response from the SWIMA-PC in addition to setting up the subscription. Assuming that the SWIMA-PC is willing to comply with the subscription, it MUST send an appropriate response attribute to a request with the Subscribe flag set containing all requested information. The same is true of the Clear Subscriptions flag -- assuming that there is no error, the SWIMA-PC MUST generate a response attribute without regard to the presence of this flag, in addition to clearing its subscription list. Both the Subscribe flag and the Clear Subscriptions flag MAY be set in a single SWIMA Request attribute. In the case where this request is successful, the end result MUST be equivalent to the SWIMA-PC clearing its subscription list for the given SWIMA-PV first and then creating a new subscription in accordance with the request parameters. In other words, do not first create the new subscription and then clear all the subscriptions (including the one that was just created). In the case that the requested actions are successfully completed, the SWIMA-PC MUST respond with a SWIMA Response attribute. The specific type of SWIMA Response attribute depends on the Result Type flag and the Earliest EID field, as described above. In the case where there is a failure that prevents some part of this request from completing, the SWIMA-PC MUST NOT add a new subscription, MUST NOT clear the old subscriptions, and MUST respond with a PA-TNC Error attribute. In other words, the SWIMA-PC MUST NOT partially succeed at implementing such a request; either all actions succeed or none succeed. The Earliest EID field is used to indicate if the SWIMA-PV is requesting an inventory or event list from the SWIMA-PC. A value of 0 (0x00000000) represents a request for inventory information. Otherwise, the SWIMA-PV is requesting event information. For Earliest EID values other than 0, the SWIMA-PC MUST respond with event records, as described in Section 3.7. Note that the request does not identify a particular EID Epoch, since responses can only include events in the SWIMA-PC's current EID Epoch.
The Software Identifier Count indicates the number of Software Identifiers in the attribute. This number might be any value between 0 and 16,777,216, inclusive. A single Software Identifier is represented by the following fields: Software Identifier Length and Software Identifier. These fields are repeated a number of times equal to the Software Identifier Count, which may be 0. The Software Identifier Length field indicates the number of bytes allocated to the Software Identifier field. The Software Identifier field contains a Software Identifier as described in Section 3.4.1. The presence of one or more Software Identifiers is used by the SWIMA-PV to indicate a targeted request, which seeks only inventories of or events affecting software corresponding to the given identifiers. The SWIMA-PC MUST only report software that matched the Software Identifiers provided in the SWIMA-PV's SWIMA Request attribute.5.7. Software Identifier Inventory
A SWIMA-PC sends this attribute to a SWIMA-PV to convey the inventory of the endpoint's Software Inventory Evidence Collection without the inclusion of Software Inventory Evidence Records. This list might represent a complete inventory or a targeted list of records, depending on the parameters in the SWIMA-PV's request. A SWIMA-PV MUST NOT send this attribute. The SWIMA-PC sends this attribute either (1) in fulfillment of an existing subscription where the establishing request has a Result Type of 1 and the Earliest EID is zero or (2) in direct response to a SWIMA Request attribute where the Result Type is 1 and the Earliest EID is zero. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | Software Identifier Count | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID Copy / Subscription ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | EID Epoch | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Last EID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | SUB-BLOCK (Repeated "Software Identifier Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 8: Software Identifier Inventory Attribute
1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Identifier | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data Model Type PEN |Data Model Type| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Id Num | Reserved | Software Identifier Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Identifier (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Locator Length |Software Locator (variable len)| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 9: Software Identifier Inventory Attribute SUB-BLOCK +----------------+--------------------------------------------------+ | Field | Description | +----------------+--------------------------------------------------+ | Flags: Bit 0 - | In the case that this attribute is sent in | | Subscription | fulfillment of a subscription, this bit MUST be | | Fulfillment | set (1). In the case that this attribute is a | | | direct response to a SWIMA Request, this bit | | | MUST be unset (0). | | | | | Flags: Bits | Reserved for future use. This field MUST be set | | 1-7 - Reserved | to zero on transmission and ignored upon | | | reception. | | | | | Software | The number of Software Identifiers that follow. | | Identifier | This field is an unsigned integer. The Record | | Count | Identifier, Data Model Type PEN, Data Model | | | Type, Source Identification Number, Reserved, | | | Software Identifier Length, Software Identifier, | | | Software Locator Length, and Software Locator | | | fields are repeated, in order, the number of | | | times indicated in this field. This field value | | | MAY be 0, in which case there are no instances | | | of these fields. | | | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field is a 4-byte unsigned |
| | integer. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the Private |
| Type PEN | Enterprise Number (PEN) of the organization that |
| | assigned the meaning of the Data Model Type |
| | value. |
| | |
| Data Model | A 1-byte unsigned integer containing an |
| Type | identifier number that identifies the data model |
| | of the reported record. |
| | |
| Source | The Source Identifier number associated with the |
| Identification | source from which this software installation |
| Number | inventory instance was reported. |
| | |
| Reserved | Reserved for future use. This field MUST be set |
| | to zero on transmission and ignored upon |
| | reception. |
| | |
| Software | A 2-byte unsigned integer indicating the length, |
| Identifier | in bytes, of the Software Identifier field. |
| Length | |
| | |
| Software | A string containing the Software Identifier |
| Identifier | value from a Software Inventory Evidence Record. |
| | This field value MUST be normalized to Network |
| | Unicode format, as described in Section 5.4. |
| | This string MUST NOT be null terminated. |
| | |
| Software | A 2-byte unsigned integer indicating the length, | | Locator Length | in bytes, of the Software Locator field. | | | | | Software | A string containing the Software Locator value. | | Locator | This field value MUST first be normalized to | | | Network Unicode format, as described in | | | Section 5.4, and then encoded as a URI | | | [RFC3986]. This string MUST NOT be null | | | terminated. | +----------------+--------------------------------------------------+ Table 3: Software Identifier Inventory Attribute Fields In the case that this attribute is sent in fulfillment of a subscription, the Subscription Fulfillment bit MUST be set (1). In the case that this attribute is sent in direct response to a SWIMA Request, the Subscription Fulfillment bit MUST be unset (0). Note that the SWIMA Response attribute sent in direct response to a SWIMA Request that establishes a subscription (i.e., a subscription's establishing request) MUST be treated as a direct response to that SWIMA Request (and thus the Subscription Fulfillment bit is unset). SWIMA Response attributes are only treated as being in fulfillment of a subscription (i.e., Subscription Fulfillment bit set) if they are sent following a change event, as shown in Figure 3. The Software Identifier Count field indicates the number of Software Identifiers present in this inventory. Each Software Identifier is represented by the following set of fields: Record Identifier, Data Model Type PEN, Data Model Type, Source Identification Number, Reserved, Software Identifier Length, Software Identifier, Software Locator Length, and Software Locator. These fields will appear once for each reported record. When responding directly to a SWIMA Request attribute, the Request ID Copy / Subscription ID field MUST contain an exact copy of the Request ID field from that SWIMA Request. When this attribute is sent in fulfillment of an existing subscription on this SWIMA-PC, this field MUST contain the Subscription ID of the fulfilled subscription. The EID Epoch field indicates the EID Epoch of the Last EID value. The Last EID field MUST contain the EID of the last recorded change event (see Section 3.7 for more about EIDs and recorded events) at the time this inventory was collected. In the case where there are no recorded change events at the time that this inventory was collected, the Last EID field MUST contain 0. These fields can be
interpreted to indicate that the provided inventory reflects the state of the endpoint after all changes up to and including this last event have been accounted for. The Data Model Type PEN and Data Model Type fields are used to identify the data model associated with the given software record. These fields are discussed more in Section 3.4.2. The Source Identification Number field is used to identify the source that provided the given record, as described in Section 3.1.5.8. Software Identifier Events
A SWIMA-PC sends this attribute to a SWIMA-PV to convey events where the affected records are reported without Software Inventory Evidence Records. A SWIMA-PV MUST NOT send this attribute. The SWIMA-PC sends this attribute either (1) in fulfillment of an existing subscription where the establishing request has a Result Type of 1 and the Earliest EID is non-zero or (2) in direct response to a SWIMA Request attribute where the Result Type is 1 and the Earliest EID is non-zero. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | Event Count | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID Copy / Subscription ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | EID Epoch | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Last EID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Last Consulted EID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | SUB-BLOCK (Repeated "Event Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 10: Software Identifier Events Attribute
1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | EID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | +- -+ | | +- -+ | Timestamp | +- -+ | | +- -+ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Identifier | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data Model Type PEN |Data Model Type| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Id Num | Action | Software Identifier Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Identifier (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Locator Length |Software Locator (variable len)| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 11: Software Identifier Events Attribute SUB-BLOCK
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Flags: Bit 0 - | In the case that this attribute is sent in |
| Subscription | fulfillment of a subscription, this bit MUST be |
| Fulfillment | set (1). In the case that this attribute is a |
| | direct response to a SWIMA Request, this bit |
| | MUST be unset (0). |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 1-7 - Reserved | to zero on transmission and ignored upon |
| | reception. |
| | |
| Event Count | The number of events that are reported in this |
| | attribute. This field is a 3-byte unsigned |
| | integer. The EID, Timestamp, Record Identifier, |
| | Data Model Type PEN, Data Model Type, Source |
| | Identification Number, Action, Software |
| | Identifier Length, Software Identifier, Software |
| | Locator Length, and Software Locator fields are |
| | repeated, in order, the number of times |
| | indicated in this field. This field value MAY |
| | be 0, in which case there are no instances of |
| | these fields. |
| | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field contains the EID of the |
| | SWIMA-PC's last recorded change event (which |
| | might or might not be included as an event |
| | record in this attribute). |
| | |
| Last Consulted | The EID of the last event record that was |
| EID | consulted when generating the event record list |
| | included in this attribute. This is different |
| | from the Last EID field value if and only if |
| | this attribute is conveying a partial list of |
| | event records. See Section 3.7.5 for more on |
| | partial lists of event records. |
| | |
| EID | The EID of the event in this event record. |
| | |
| Timestamp | The timestamp associated with the event in this |
| | event record. This timestamp is the SWIMA-PC's |
| | best understanding of when the given event |
| | occurred. Note that this timestamp might be an |
| | estimate. The Timestamp date and time MUST be |
| | represented as an ASCII string that is expressed |
| | in Coordinated Universal Time (UTC) and is |
| | compliant with RFC 3339 [RFC3339], with the |
| | additional restrictions that the 'T' delimiter |
| | and the 'Z' suffix MUST be capitalized and |
| | fractional seconds (time-secfrac) MUST NOT be |
| | included. This field conforms to the date-time |
| | ABNF production from Section 5.6 of RFC 3339, |
| | with the above restrictions. Leap seconds are |
| | permitted, and SWIMA-PVs MUST support them. The |
| | Timestamp string MUST NOT be null terminated or |
| | padded in any way. The length of this field is |
| | always 20 octets. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the PEN of |
| Type PEN | the organization that assigned the meaning of |
| | the Data Model Type value. |
| | |
| Data Model | A 1-byte unsigned integer containing an |
| Type | identifier number that identifies the data model |
| | of the reported record. |
| | |
| Source | The Source Identifier number associated with the |
| Identification | source for the software installation inventory |
| Number | instance that this event record reported. |
| | |
| Action | The type of event that is recorded in this event | | | record. Possible values are as follows: 1 = | | | CREATION - the addition of a record to the | | | endpoint's Software Inventory Evidence | | | Collection; 2 = DELETION - the removal of a | | | record from the endpoint's Software Inventory | | | Evidence Collection; 3 = ALTERATION - an | | | alteration that was made to a record within the | | | endpoint's Software Inventory Evidence | | | Collection. All other values are reserved for | | | future use and MUST NOT be used when sending | | | attributes. In the case where a SWIMA-PV | | | receives an event record that uses an action | | | value other than the ones defined here, it MUST | | | ignore that event record but SHOULD process | | | other event records in this attribute as normal. | | | | | Software | A 2-byte unsigned integer indicating the length, | | Identifier | in bytes, of the Software Identifier field. | | Length | | | | | | Software | A string containing the Software Identifier | | Identifier | value from a Software Inventory Evidence Record. | | | This field value MUST first be normalized to | | | Network Unicode format, as described in | | | Section 5.4. This string MUST NOT be null | | | terminated. | | | | | Software | A 2-byte unsigned integer indicating the length, | | Locator Length | in bytes, of the Software Locator field. | | | | | Software | A string containing the Software Locator value. | | Locator | This field value MUST first be normalized to | | | Network Unicode format, as described in | | | Section 5.4, and then encoded as a URI | | | [RFC3986]. This string MUST NOT be null | | | terminated. | +----------------+--------------------------------------------------+ Table 4: Software Identifier Events Attribute Fields The first few fields in the Software Identifier Events attribute mirror those in the Software Identifier Inventory attribute. The primary difference is that instead of conveying an inventory the attribute conveys zero or more event records, consisting of the EID, Timestamp, Record Identifier, Data Model Type PEN, Data Model Type,
Source Identification Number, Action, Software Identifier Length, Software Identifier, Software Locator Length, and Software Locator fields of the affected Software Inventory Evidence Record. With regard to the Timestamp field, it is important to note that clock skew between the SWIMA-PC and SWIMA-PV as well as between different SWIMA-PCs within an enterprise might make correlation of Timestamp values difficult. This specification does not attempt to resolve clock skew issues, although other mechanisms (which are outside the scope of this specification) do exist to reduce the impact of clock skew and make the timestamp more useful for such correlation. Instead, SWIMA uses the Timestamp value primarily as a means to indicate the amount of time between two events on a single endpoint. For example, by taking the difference of the times for when a record was removed and then subsequently re-added, one can get an indication as to how long the system was without the given record (and thus without the associated software). Since this will involve comparison of Timestamp values all originating on the same system, clock skew between the SWIMA-PC and SWIMA-PV is not an issue. However, if the SWIMA-PC's clock was adjusted between two recorded events, it is possible for such a calculation to lead to misunderstandings regarding the temporal distance between events. Users of this field need to be aware of the possibility for such occurrences. In the case where the Timestamp values of two events appear to contradict the EID ordering of those events (i.e., the later EID has an earlier timestamp), the recipient MUST treat the EID ordering as correct. All events recorded in a Software Identifier Events attribute are required to be part of the same EID Epoch. Specifically, all such reported events MUST have an EID that is from the same EID Epoch and that is the same as the EID Epoch of the Last EID and Last Consulted EID values. The SWIMA-PC MUST NOT report events with EIDs from different EID Epochs. The Last Consulted EID field contains the EID of the last event record considered for inclusion in this attribute. If this attribute contains a partial event set (as described in Section 3.7.5), this field value will be less than the Last EID value; if this attribute contains a complete event set, the Last EID and Last Consulted EID values are identical. If multiple events are sent in a Software Identifier Events attribute, the order in which they appear within the attribute is not significant. The EIDs associated with them are used for ordering the indicated events appropriately. Also note that a single software record might be reported multiple times in an attribute, such as if multiple events involving the associated record were being reported.
5.9. Software Inventory
A SWIMA-PC sends this attribute to a SWIMA-PV to convey a list of inventory records. A SWIMA-PV MUST NOT send this attribute. The SWIMA-PC sends this attribute either (1) in fulfillment of an existing subscription where the establishing request has a Result Type of 0 and the Earliest EID is zero or (2) in direct response to a SWIMA Request attribute where the Result Type is 0 and the Earliest EID is zero. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | Record Count | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID Copy / Subscription ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | EID Epoch | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Last EID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | SUB-BLOCK (Repeated "Record Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 12: Software Inventory Attribute 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Identifier | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data Model Type PEN |Data Model Type| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Id Num | Reserved | Software Identifier Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Identifier (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Software Locator Length |Software Locator (variable len)| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 13: Software Inventory Attribute SUB-BLOCK
+----------------+--------------------------------------------------+
| Field | Description |
+----------------+--------------------------------------------------+
| Flags: Bit 0 - | In the case that this attribute is sent in |
| Subscription | fulfillment of a subscription, this bit MUST be |
| Fulfillment | set (1). In the case that this attribute is a |
| | direct response to a SWIMA Request, this bit |
| | MUST be unset (0). |
| | |
| Flags: Bits | Reserved for future use. This field MUST be set |
| 1-7 - Reserved | to zero on transmission and ignored upon |
| | reception. |
| | |
| Record Count | The number of records that follow. This field |
| | is a 3-byte unsigned integer. The Record |
| | Identifier, Data Model Type PEN, Data Model |
| | Type, Source Identification Number, Reserved, |
| | Software Identifier Length, Software Identifier, |
| | Software Locator Length, Software Locator, |
| | Record Length, and Record fields are repeated, |
| | in order, the number of times indicated in this |
| | field. This field value MAY be 0, in which case |
| | there are no instances of these fields. |
| | |
| Request ID | In the case where this attribute is in direct |
| Copy / | response to a SWIMA Request attribute from a |
| Subscription | SWIMA-PV, this field MUST contain an exact copy |
| ID | of the Request ID field from that SWIMA Request. |
| | In the case where this attribute is sent in |
| | fulfillment of an active subscription, this |
| | field MUST contain the Subscription ID of the |
| | subscription being fulfilled by this attribute. |
| | |
| EID Epoch | The EID Epoch of the Last EID value. This field |
| | is a 4-byte unsigned integer. |
| | |
| Last EID | The EID of the last event recorded by the |
| | SWIMA-PC, or 0 if the SWIMA-PC has no recorded |
| | events. This field is a 4-byte unsigned |
| | integer. |
| | |
| Record | A 4-byte unsigned integer containing the Record |
| Identifier | Identifier value from a Software Inventory |
| | Evidence Record. |
| | |
| Data Model | A 3-byte unsigned integer containing the PEN of | | Type PEN | the organization that assigned the meaning of | | | the Data Model Type value. | | | | | Data Model | A 1-byte unsigned integer containing an | | Type | identifier number that identifies the data model | | | of the reported record. | | | | | Source | The Source Identifier number associated with the | | Identification | source from which this software installation | | Number | inventory instance was reported. | | | | | Reserved | Reserved for future use. This field MUST be set | | | to zero on transmission and ignored upon | | | reception. | | | | | Software | A 2-byte unsigned integer indicating the length, | | Identifier | in bytes, of the Software Identifier field. | | Length | | | | | | Software | A string containing the Software Identifier | | Identifier | value from a Software Inventory Evidence Record. | | | This field value MUST first be normalized to | | | Network Unicode format, as described in | | | Section 5.4. This string MUST NOT be null | | | terminated. | | | | | Software | A 2-byte unsigned integer indicating the length, | | Locator Length | in bytes, of the Software Locator field. | | | | | Software | A string containing the Software Locator value. | | Locator | This field value MUST first be normalized to | | | Network Unicode format, as described in | | | Section 5.4, and then encoded as a URI | | | [RFC3986]. This string MUST NOT be null | | | terminated. | | | | | Record Length | A 4-byte unsigned integer indicating the length, | | | in bytes, of the Record field. | | | | | Record | A Software Inventory Evidence Record expressed | | | as a string. The record MUST be converted and | | | normalized to Network Unicode format, as | | | described in Section 5.4. This string MUST NOT | | | be null terminated. | +----------------+--------------------------------------------------+ Table 5: Software Inventory Attribute Fields
The Software Inventory attribute contains some number of Software Inventory Evidence Records along with the core response attribute fields. Given that the size of records can vary considerably, the length of this attribute is highly variable and, if transmitting a complete inventory, can be extremely large. To avoid unnecessarily overburdening the network, enterprises might wish to constrain the use of Software Inventory attributes to targeted requests. When copying a Software Inventory Evidence Record into the Record field, the record MUST be converted and normalized to use Network Unicode format prior to its inclusion in the Record field.
(page 67 continued on part 5)