RFC 8412
Software Inventory Message and Attributes (SWIMA) for PA-TNC
Pages: 101
Proposed Standard
Proposed Standard
Part 5 of 6 – Pages 67 to 86
5.10. Software Events
A SWIMA-PC sends this attribute to a SWIMA-PV to convey a list of events that include 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 0 and the Earliest EID is non-zero or (2) in direct response to a SWIMA Request attribute where the Result Type is 0 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 14: Software 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)| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 15: Software 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 being 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, 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 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. |
| | |
| 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 6: Software Events Attribute Fields The fields of this attribute are used in the same way as the corresponding fields of the previous attributes. As with the Software Inventory attribute, a Software Events attribute can be quite large if many events have occurred following the event indicated by a request's Earliest EID. As such, it is recommended that the SWIMA Request attributes only request that full records be sent (Result Type set to zero) in a targeted request, thus constraining the response just to records that match a given set of Software Identifiers. As with the Software Identifier Events attribute, this attribute MUST only contain event records with EIDs coming from the current EID Epoch of the SWIMA-PC. As with the Software Inventory attribute, the SWIMA-PC MUST perform conversion and normalization of the record.5.11. Subscription Status Request
A SWIMA-PV sends this attribute to a SWIMA-PC to request a list of active subscriptions for which the requesting SWIMA-PV is the subscriber. A SWIMA-PC MUST NOT send this attribute. This attribute has no fields. A SWIMA-PC MUST respond to this attribute by sending a Subscription Status Response attribute (or a PA-TNC Error attribute if it is unable to correctly provide a response).
5.12. Subscription Status Response
A SWIMA-PC sends this attribute to a SWIMA-PV to report the list of active subscriptions for which the receiving SWIMA-PV is the subscriber. A SWIMA-PV 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Status Flags | Subscription Record Count | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | SUB-BLOCK (Repeated "Subscription Record Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 16: Subscription Status Response 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-SUB-BLOCK (Repeated "Software Identifier Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 17: Subscription Status Response Attribute SUB-BLOCK 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 18: Subscription Status Response Attribute SUB-SUB-BLOCK
+--------------+----------------------------------------------------+ | Field | Description | +--------------+----------------------------------------------------+ | Status | Reserved for future use. This field MUST be set | | Flags: Bits | to zero on transmission and ignored upon | | 0-7 - | reception. | | Reserved | | | | | | Subscription | The number of subscription records that follow. | | Record Count | This field is a 3-byte unsigned integer. The | | | Flags, Software Identifier Count, Request ID, and | | | Earliest EID fields, and zero or more instances of | | | Software Identifier Length and Software | | | Identifier, are repeated, in order, the number of | | | times indicated in this field. (The Software | | | Identifier Length and Software Identifier fields | | | within each of these sets of fields are repeated a | | | number of times equal to the preceding Software | | | Identifier Count value.) The Subscription Record | | | Count field value MAY be 0, in which case there | | | are no instances of these fields. | | | | | Flags, | For each active subscription, these fields contain | | Software | an exact copy of the fields with the corresponding | | Identifier | name provided in the subscription's establishing | | Count, | request. | | Request ID, | | | Earliest | | | EID, | | | Software | | | Identifier | | | Length, and | | | Software | | | Identifier | | +--------------+----------------------------------------------------+ Table 7: Subscription Status Response Fields A Subscription Status Response contains zero or more subscription records. Specifically, it MUST contain one subscription record for each active subscription associated with the party that sent the Subscription Status Request to which this attribute is a response. As described in Section 3.8.2, the SWIMA-PC MUST use the requester's Connection ID and its Posture Validator Identifier to determine which subscriptions are associated with the requester.
A SWIMA-PC MUST send a Subscription Status Response attribute in response to a Subscription Status Request attribute, except in cases where the SWIMA-PC experiences an error condition that prevents it from correctly populating the Subscription Status Response attribute (in which case it MUST respond with a PA-TNC Error attribute appropriate to the type of error experienced). If there are no active subscriptions associated with the requesting party, the Subscription Status Response attribute will consist only of its Status Flags field and a Subscription Record Count field with a value of 0, and no additional fields. Each subscription record included in a Subscription Status Response attribute duplicates the fields of the SWIMA Request attribute that was the establishing request of a subscription. Note that the Request ID field in the record captures the Subscription ID associated with the given subscription record (since the Subscription ID is the same as the Request ID of the establishing request). Note also that if the establishing request is targeted, then its Record Count field will be non-zero and, within that subscription record, the Software Identifier Length and Software Identifier fields are repeated, in order, the number of times indicated in the Record Count field. As such, each subscription record can be different sizes. If the establishing request is not targeted (Record Count field is 0), the subscription record has no Software Identifier Length or Software Identifier fields. When a SWIMA-PV compares the information received in a Subscription Status Response to its own records of active subscriptions, it should be aware that the SWIMA-PC might be unable to distinguish this SWIMA-PV from other SWIMA-PVs on the same NEA Server. As a result, it is possible that the SWIMA-PC will report more subscription records than the SWIMA-PV recognizes. For this reason, SWIMA-PVs SHOULD NOT automatically assume that extra subscriptions reported in a Subscription Status Response indicate a problem.5.13. Source Metadata Request
A SWIMA-PV sends this attribute to a SWIMA-PC to request metadata about sources that the SWIMA-PC is using to collect software inventory information. A SWIMA-PC MUST NOT send this attribute. This attribute has no fields. A SWIMA-PC MUST respond to this attribute by sending a Source Metadata Response attribute (or a PA-TNC Error attribute if it is unable to correctly provide a response).
5.14. Source Metadata Response
A SWIMA-PC sends this attribute to a SWIMA-PV to provide descriptive metadata about the sources of software inventory information used by the SWIMA-PC. A SWIMA-PV 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reserved | Source Count | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | | SUB-BLOCK (Repeated "Source Count" times) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 19: Source Metadata Response 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Id Num | Metadata Length | Metadata (var)| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 20: Source Metadata Response Attribute SUB-BLOCK
+----------------+--------------------------------------------------+ | Field | Description | +----------------+--------------------------------------------------+ | Reserved | Reserved for future use. This field MUST be set | | | to zero on transmission and ignored upon | | | reception. | | | | | Source Count | The number of source records that follow. The | | | Source Identification Number, Metadata Length, | | | and Metadata fields are repeated, in order, the | | | number of times indicated by this field. This | | | field MAY be 0, in which case no fields follow | | | (but this would only be done to indicate that | | | the SWIMA-PC has no active sources; this would | | | not be a typical situation). | | | | | Source | The Source Identifier number associated with the | | Identification | described source for any communications with the | | Number | recipient SWIMA-PV. | | | | | Metadata | A 2-byte unsigned integer indicating the length, | | Length | in bytes, of the Metadata field. | | | | | Metadata | A string containing descriptive metadata about | | | the indicated data source. This string MUST NOT | | | be null terminated. | +----------------+--------------------------------------------------+ Table 8: Source Metadata Response Fields A Source Metadata Response attribute contains zero or more records, each describing one of the data sources the SWIMA-PC uses to collect software inventory information. It SHOULD contain one metadata record for each source that the SWIMA-PC uses. (There might be reasons not to inform certain SWIMA-PVs of the presence of certain data sources.) The attribute MUST contain a metadata record for each source that has been identified in inventory or event messages to the given SWIMA-PV. A SWIMA-PC MUST send a Source Metadata Response attribute in response to a Source Metadata Request attribute, except in cases where the SWIMA-PC experiences an error condition that prevents it from correctly populating the Source Metadata Response attribute (in which case it MUST respond with a PA-TNC Error attribute appropriate to the type of error experienced).
The Source Count field indicates how many source metadata records are included in the attribute. Each included record consists of a Source Identification Number field, a Metadata Length field, and a Metadata field. The Source Identification Number field in the Source Metadata Response attribute corresponds to the Source Identification Number field in inventory and event messages. In the case where (1) the Source Identification Number value in this attribute matches a Source Identification Number field in an inventory or event record and (2) both the Source Metadata Response and the inventory or event record were sent to the same SWIMA-PV, the source described in the Metadata field MUST be the same source that provided the inventory or event record associated with this Source Identifier. Recall that a SWIMA-PC MAY use different Source Identification Number associations with different SWIMA-PVs. As such, the association between a Source Identification Number and the conveyed metadata is also only meaningful for communications between the sending SWIMA-PC and receiving SWIMA-PV. When sending to a given SWIMA-PV, the SWIMA-PC MUST use the recipient SWIMA-PV's Source Identification Number associations. The Metadata Length field indicates the length, in bytes, of the Metadata field. The Metadata field contains information about the indicated data source. This specification does not dictate a format for the contents of the Metadata field. This field MAY include machine-readable information. For broadest utility, the Metadata field SHOULD include human-readable, descriptive information about the data source.5.15. PA-TNC Error as Used by SWIMA
The PA-TNC Error attribute is defined in the PA-TNC specification [RFC5792], and its use here conforms to that specification. A PA-TNC Error can be sent due to any error in the PA-TNC exchange and might also be sent in response to error conditions specific to the SWIMA exchange. The latter case utilizes error codes defined below. A PA-TNC Error MUST be sent by a SWIMA-PC in response to a SWIMA Request in the case where the SWIMA-PC encounters a fatal error (i.e., an error that prevents further processing of an exchange) relating to the attribute exchange. A SWIMA-PV MUST NOT send this attribute. In the case where the SWIMA-PV experiences a fatal error, it MUST handle the error without sending a PA-TNC Error attribute. The SWIMA-PV MAY take other actions in response to the error, such as logging the cause of the error or even taking actions to isolate the endpoint.
A PA-TNC Error attribute is sent instead of a SWIMA Response attribute when certain issues prevent the reliable creation of a SWIMA Response. As such, a SWIMA-PC MUST NOT send both a PA-TNC Error attribute and a SWIMA Response attribute in response to a single SWIMA Request attribute. Table 9 lists the error code values for the PA-TNC Error attribute that are specific to the SWIMA exchange. Error codes are shown in both hexadecimal and decimal format. In all of these cases, the Error Code Vendor ID field MUST be set to 0x000000, corresponding to the IETF SMI PEN. The error information structures for each error code are described in the following subsections. Note that a message with a SWIMA attribute might also result in an error condition covered by the IETF Standard PA-TNC Error Codes defined in Section 4.2.8 of [RFC5792]. For example, a SWIMA attribute might have an invalid parameter, leading to an error code of "Invalid Parameter". In this case, the SWIMA-PC MUST use the appropriate PA-TNC Error Code value as defined in Section 4.2.8 of [RFC5792].
+----------------+--------------------------------------------------+ | Error Code | Description | | Value | | +----------------+--------------------------------------------------+ | 0x00000004 (4) | SWIMA_ERROR. This indicates a fatal error | | | (i.e., an error that precludes the creation of a | | | suitable response attribute) other than the | | | errors described below but still specific to the | | | processing of SWIMA attributes. The Description | | | field SHOULD contain additional diagnostic | | | information. | | | | | 0x00000005 (5) | SWIMA_SUBSCRIPTION_DENIED_ERROR. This indicates | | | that the SWIMA-PC denied the SWIMA-PV's request | | | to establish a subscription. The Description | | | field SHOULD contain additional diagnostic | | | information. | | | | | 0x00000006 (6) | SWIMA_RESPONSE_TOO_LARGE_ERROR. This indicates | | | that the SWIMA-PC's response to the SWIMA-PV's | | | request was too large to be serviced. The error | | | information structure indicates the largest | | | possible size of a response supported by the | | | SWIMA-PC (see Section 5.15.2). The Description | | | field SHOULD contain additional diagnostic | | | information. | | | | | 0x00000007 (7) | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR. This | | | indicates that the SWIMA-PC experienced an error | | | while fulfilling a given subscription. The | | | error information includes the Subscription ID | | | of the relevant subscription, as well as a | | | sub-error that describes the nature of the error | | | the SWIMA-PC experienced. The SWIMA-PC and | | | SWIMA-PV MUST treat the identified subscription | | | as cancelled. | | | | | 0x00000008 (8) | SWIMA_SUBSCRIPTION_ID_REUSE_ERROR. This | | | indicates that the SWIMA-PC received a SWIMA | | | Request from a given SWIMA-PV where the Request | | | ID of that SWIMA Request is currently used as | | | the Subscription ID of an active subscription | | | with that SWIMA-PV. This error does not cancel | | | the identified subscription. | +----------------+--------------------------------------------------+ Table 9: PA-TNC Error Codes for SWIMA
The following subsections describe the structures present in the error information fields. Note that all error structures include a variable-length field but do not include any fields indicating the length of those fields. A length field is unnecessary because all other fields in the PA-TNC Error attribute are of fixed length, and thus the length of the variable-length field can be found by subtracting the size of these fixed-length fields from the PA-TNC Attribute Length field in the PA-TNC Attribute Header.5.15.1. SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information
The SWIMA_ERROR error code indicates that the sender (the SWIMA-PC) has encountered an error that is related to the processing of a SWIMA Request attribute but that is not covered by SWIMA error codes that are more specific. The SWIMA_SUBSCRIPTION_DENIED_ERROR is used when the SWIMA-PV sends a request to establish a subscription or clear all subscriptions from the given SWIMA-PV but the SWIMA-PC is unable or unwilling to comply with this request. The SWIMA_SUBSCRIPTION_ID_REUSE_ERROR is used when the SWIMA-PC receives a SWIMA Request whose Request ID duplicates a Subscription ID of an active subscription with the request's sender. All of these error codes use the following error information structure. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Copy of Request ID / Subscription ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Description (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 21: SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information
+--------------+----------------------------------------------------+ | Field | Description | +--------------+----------------------------------------------------+ | Copy of | In the case that this error condition is generated | | Request ID / | in direct response to a SWIMA Request attribute, | | Subscription | this field MUST contain an exact copy of the | | ID | Request ID field in the SWIMA Request attribute | | | that caused this error. In the case that the | | | attribute in question is generated in fulfillment | | | of an active subscription, this field MUST contain | | | the Subscription ID of the subscription for which | | | the attribute was generated. (This is only | | | possible if the error code is SWIMA_ERROR, as the | | | other errors are not generated by subscription | | | fulfillment.) Note that in the case of failed | | | subscription fulfillment, the indicated error | | | appears as a sub-error for a | | | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR, as described | | | in Section 5.15.3. | | | | | Description | A UTF-8 [RFC3629] string describing the condition | | | that caused this error. This field MAY be zero- | | | length. However, senders SHOULD include some kind | | | of description in all PA-TNC Error attributes with | | | these error codes. This field MUST NOT be null | | | terminated. | +--------------+----------------------------------------------------+ Table 10: SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR Information Fields This error information structure is used with SWIMA_ERROR, SWIMA_SUBSCRIPTION_DENIED_ERROR, and SWIMA_SUBSCRIPTION_ID_REUSE_ERROR status codes to identify the SWIMA Request attribute that precipitated the error condition and to describe the error. The Description field contains text describing the error. The SWIMA-PC MAY encode machine-interpretable information in this field but SHOULD also include a human-readable description of the error, since the receiving SWIMA-PV might not recognize the SWIMA-PC's encoded information.
5.15.2. SWIMA_RESPONSE_TOO_LARGE_ERROR Information
The SWIMA_RESPONSE_TOO_LARGE_ERROR error code indicates that a SWIMA-PC's response to a SWIMA-PV's SWIMA Request attribute was too large to send. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Copy of Request ID / Subscription ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Maximum Allowed Size | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Description (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 22: SWIMA_RESPONSE_TOO_LARGE_ERROR Information
+--------------+----------------------------------------------------+ | Field | Description | +--------------+----------------------------------------------------+ | Copy of | In the case that the attribute in question is | | Request ID / | generated in direct response to a SWIMA Request, | | Subscription | this field MUST contain an exact copy of the | | ID | Request ID field in the SWIMA Request attribute | | | that caused this error. In the case that the | | | attribute in question is generated in fulfillment | | | of an active subscription, this field MUST contain | | | the Subscription ID of the subscription for which | | | the attribute was generated. Note that in the | | | latter case, the SWIMA_RESPONSE_TOO_LARGE_ERROR | | | appears as a sub-error for a | | | SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR, as described | | | in Section 5.15.3. | | | | | Maximum | This field MUST contain an unsigned integer | | Allowed Size | indicating the largest permissible size, in bytes, | | | of the SWIMA attribute that the SWIMA-PC is | | | currently willing to send in response to a SWIMA | | | Request attribute. | | | | | Description | A UTF-8 [RFC3629] string describing the condition | | | that caused this error. This field MAY be zero- | | | length. However, senders SHOULD include some kind | | | of description in all PA-TNC Error attributes with | | | this error code. This field MUST NOT be null | | | terminated. | +--------------+----------------------------------------------------+ Table 11: SWIMA_RESPONSE_TOO_LARGE_ERROR Information Fields This error structure is used with the SWIMA_RESPONSE_TOO_LARGE_ERROR status code to identify the SWIMA Request attribute that precipitated the error condition and to describe the error. The Maximum Allowed Size field indicates the largest attribute the SWIMA-PC is willing to send in response to a SWIMA Request under the current circumstances. Note that under other circumstances, the SWIMA-PC might be willing to return larger or smaller responses than indicated (such as if the endpoint connects to the NEA Server using a different network protocol). The other fields in this error information structure have the same meanings as corresponding fields in the SWIMA_ERROR and SWIMA_SUBSCRIPTION_DENIED_ERROR information structures.
5.15.3. SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information
The SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR error code indicates that the SWIMA-PC encountered an error while fulfilling a subscription. The bytes after the first 4 octets duplicate a PA-TNC Error attribute (as described in Section 4.2.8 of PA-TNC [RFC5792]) that is used to identify the nature of the encountered error. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Subscription ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reserved | Sub-error Code Vendor ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Sub-error Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Sub-error Information (variable length) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 23: SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information
+--------------+----------------------------------------------------+ | Field | Description | +--------------+----------------------------------------------------+ | Subscription | This field MUST contain the Subscription ID of the | | ID | subscription whose fulfillment caused this error. | | | | | Reserved | This field MUST contain the value of the Reserved | | | field of a PA-TNC Error attribute that describes | | | the error condition encountered during | | | subscription processing. | | | | | Sub-error | This field MUST contain the value of the Error | | Code Vendor | Code Vendor ID field of a PA-TNC Error attribute | | ID | that describes the error condition encountered | | | during subscription processing. | | | | | Sub-error | This field MUST contain the value of the Error | | Code | Code field of a PA-TNC Error attribute that | | | describes the error condition encountered during | | | subscription processing. | | | | | Sub-error | This field MUST contain the value of the Error | | Information | Information field of a PA-TNC Error attribute that | | | describes the error condition encountered during | | | subscription processing. | +--------------+----------------------------------------------------+ Table 12: SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR Information Fields This error structure is used with the SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR status code. The first 4 octets of this error structure contain the Subscription ID of the subscription that was being fulfilled when the error occurred. The remaining fields of this error structure duplicate the fields of a PA-TNC Error attribute, referred to as the "sub-error". The error code of the sub-error corresponds to the code of the error that the SWIMA-PC encountered while fulfilling the given subscription. The sub-error MUST NOT have an error code of SWIMA_SUBSCRIPTION_FULFILLMENT_ERROR. The SWIMA-PC sending a PA-TNC Error attribute with this error code, and the SWIMA-PV receiving it, MUST treat the subscription identified by the Subscription ID field as cancelled. All other subscriptions are unaffected.
(next page on part 6)