Jeff Platzer
Cisco Systems
August 20, 2003

Security Device Event Exchange (SDEE) Specification


Abstract

Network and host-based security devices may generate various types of events that include alert, policy violation and audit events. The Security Device Event Exchange (SDEE) is a standard that specifies the format of the messages as well as the protocol used to communicate the events generated by security devices. The current version of SDEE only specifies the messaging for the Intrusion Detection System (IDS) Alert Event. While SDEE communications may consist of bindings to multiple transport protocols, the current version of SDEE specifies only the binding to HTTP. 


1.0 Introduction

1.1 Overview

SDEE communications consist of exchanging request and response messages. SDEE clients initiate request messages to SDEE providers. SDEE providers respond to request messages with response messages. Both SDEE clients and providers are referred to as SDEE agents in this document.

SDEE providers are sources of security event data. Providers may be event originators and/or event brokers. Clients obtain events by sending event request messages to providers.

There are two types of event requests - queries and subscriptions.

Queries are used to retrieve events, based on the query's filter criteria, that are available on the provider at the time the query request is issued. Queries are stateless - meaning that successive query retrieval operations are not affected by previous query operations. The query request message specifies the filter criteria for the types of events to be returned in the response.

Subscriptions allow clients to establish live event feeds where newer events are returned in each successive retrieval operation. Subscriptions are stateful. Successive subscription retrieval operations attempt to return the oldest set of events that are newer than the set of events returned in the previous retrieval operation.

Before the client can retrieve events using a subscription, the client must open a subscription by sending a subscription-open request message. This message is used to specify the filter criteria for the types of events to be retrieved in the subscription. Once opened, events can be retrieved using subscription retrieval request messages. The client closes the subscription using the subscription-close request message.

Providers may respond to query requests, subscription requests or both.

1.1.  Specification of Requirements

In this document, several words are used to signify the requirements of the specification.  These words, when used in the context of signifying requirements, are capitalized.  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [6].

1.2 Terminology

BNF

Backus-Naur Form (this specification utilizes the augmented BNF that is defined in RFC 2616, rather than the original BNF specified in RFC 822)

HTTP

HyperText Transfer Protocol

IDS

Intrusion Detection System

SDEE

Security Device Event Exchange

SOAP

Simple Object Access Protocol

SSL

Secure Sockets Layer

TCP

Transaction Control Protocol

TLS

Transaction Layer Security

XML

eXtensible Markup Language

1.3 Use of Examples

The XML elements shown in example messages are provided for illustrative purposes only. See the SDEE XML Schema specification for the normative descriptions of these elements.

Some of the examples include XML elements that are qualified with the SDEE namespace, "http://example.org/2003/08/sdee". The URL path "http://example.org" is intended to be used as a placeholder until an actual URL address is established for the SDEE schema, at which time the SDEE namespace value will be updated with the schema's actual URL address.

2.0 Response Messages

This section specifies the format of the response messages returned by SDEE providers. SDEE response messages are formatted as XML documents. These messages are exchanged using the SOAP (version 1.2) protocol.

SOAP (version 1.2) supports different message exchange patterns for specifying how SOAP messages are exchanged. SDEE utilizes SOAP's Response message exchange pattern (MEP). The Response MEP defines a pattern for the exchange of a non-SOAP message acting as a request followed by a SOAP message acting as a response.

In the case of SDEE, non-SOAP messages are used by clients to request events, and SDEE providers respond with SOAP messages. The details of the events request message are specific to the transport protocol binding (see 3.0 Transport Protocol).

2.1 Events Response Message

The response to an event retrieval request (see 3.1.3 Query Messaging and 3.1.4.2 Retrieving events) consists of a SOAP message that contains either an SDEE events element or a SOAP fault element in the SOAP message's body. The events element contains the events returned by the SDEE provider. The SOAP fault element is returned in the SOAP message's body in case an error occurs in the handling of the client's request.

Example 1: Events Response SOAP message

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
  <sd:oobInfo xmlns:sd="http://example.org/2003/08/sdee">
   <sd:sessionId>12345</sd:sessionId>
  </sd:oobInfo>
 </env:Header>
 <env:Body>
  <sd:events xmlns:sd="http://example.org/2003/08/sdee">
   <sd:evIdsAlert eventId="1234567" vendor="example" severity="low">...</sd:evIdsAlert>
   <sd:evIdsAlert eventId="1234568" vendor="example" severity="low">...</sd:evIdsAlert>
  </sd:events>
 </env:Body>
</env:Envelope>

In Example 1, the SOAP envelope contains a Header and a Body child element. Each of the Header element's direct child elements are referred to as a header block. The information in the Body element is referred to as the SOAP body. 

The example message contains a single header block consisting of the oobInfo element (see oobInfo  Header Block). This header block contains the sessionId element that is used to maintain a SDEE Session in this case (see 3.1.2 SDEE Session).

The SOAP body for an events response message contains a single child element - the SDEE events element. The events element has a type described by the SDEE XML Schema. The annotated SDEE schema serves as the specification for the XML elements in the SOAP header block and the bodies of SDEE messages. The schema document is best viewed with an XML viewer/editor that is capable of graphically rendering XML schema elements.

The events element is defined in the SDEE schema to contain zero or more security device event child elements. A security device event element consists of the data for a single event generated by a security device. Some devices may aggregate the data for multiple events into a single event, in which case the event element would consist of the aggregated event data.

The format of security device event elements may either be specified in the SDEE schema or externally to the schema. The SDEE schema specifies common event elements. The events element is specified such that it may contain any child element. The events element's children should be security device elements. The ability to include security device event elements that are specified externally to the schema allows providers to report proprietary event types. 

The SDEE schema currently specifies a single security device event element - the evIdsAlert element. The evIdsAlert element consists of the alert data generated by intrusion detection systems. The schema specifies the core information reported in IDS alerts. The evIdsAlert element and its child elements include optional extension elements and attributes that may be used to represent vendor specific information (see 2.8 Vendor Specified Extensions).

2.2 Open Subscription Response Message

The response to an open subscription request consists of a SOAP message with a Body element that contains either an SDEE subscriptionId element or a SOAP fault element. The subscriptionId element contains the subscription's identifier that is used in all further subscription requests.  The SOAP fault element is returned in the SOAP message's body in case an error occurs in the handling of the client's request.

Example 2: Open Subscription Response SOAP message

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <sd:subscriptionId xmlns:sd="http://example.org/2003/08/sdee">12654</sd:subscriptionId>
 </env:Body>
</env:Envelope>

2.3 Close and Cancel Subscription Response Messages

The response to a close or cancel subscription request consists of a SOAP message with a Body element that is either empty or contains a SOAP fault element. A response with an empty SOAP body indicates that the close or cancel subscription request was successfully handled. The SOAP fault element is returned in the SOAP message's body in case an error occurs in the handling of the client's request.

Example 3: Close or Cancel Subscription Response SOAP message

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body/>
</env:Envelope>

2.4 Specification Version Response Message

The specification version request is used to obtain the version of the SDEE specification that the provider is using as well as the versions of any vendor-specific extension specifications used by the provider. The response to a specification version request is a SOAP message with a Body element that contains either an SDEE specificationVersions element or a SOAP fault element. The SOAP fault element is returned in the SOAP message's body in case an error occurs in the handling of the client's request.

Example 4: Specification Versions Response SOAP message

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <sd:specificationVersions xmlns:sd="http://example.org/2003/08/sdee">
    <sd:specification>http://example.org/2003/08/10/sdee.html</sd:specification>
    <sd:specification>http://example.com/2003/08/21/vendorExample.html</sd:specification>
  </sd:specificationVersions>
 </env:Body>
</env:Envelope>

The specificationVersions element has one type of child element - the specification element. The specification element's value is a URI that is specified by the BNF:

URI-path "/" Gregorian-year "/" Gregorian-month "/" Gregorian-day "/" specification-name

The URI-path is a namespace qualifier for specification's name (the specification-name value). The URI-path MUST be a unique namespace that serves to disambiguate the name of the specification. The Gregorian-year, Gregorian-month and Gregorian-day values provide the specification's version as a date. The complete URI MAY, but is not required to resolve to an actual web address.

Upon receipt of a valid specification version request, a provider MUST respond with a SOAP body that contains the specificationVersions child element. The specificationVersions element MUST contain the a specification child element that specifies the version of the SDEE specification implemented by the provider. The specificationVersions element SHOULD contain an additional specification child element for each pertinent SDEE extension specification implemented by the provider.

2.5 Fault Response Message

SDEE providers will return a SOAP fault message (see Example 5) whenever an error occurs while processing a client's request. The error may result from an incorrect request, the providers inability to handle a request or for other reasons. The fault element has two child elements that are used to identify the error. The Code child element provides an encoded identification of the error. The Reason child element provides a context-specific description of the error. The Code element's Value child element provides a SOAP specified general identification of the error while the Value child element of the Code element's Subcode child element provides a more specific error identification using values specified in the SDEE schema.  

Example 5: Fault Response SOAP message

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:sd="http://example.org/2003/08/sdee">
 <env:Body>
  <env:Fault>
   <env:Code>
     <env:Value>env:Sender</env:Value>
     <env:Subcode>
      <env:Value>sd:errNotFound</env:Value>
     </env:Subcode>
   </env:Code>
   <env:Reason>
     <env:Text xml:lang="en">The subscription does not exist</env:Text>
   </env:Reason>
  </env:Fault>
 </env:Body>
</env:Envelope>

2.6 oobInfo Header Block

The oobInfo header block, as defined in the SDEE XML Schema, is used to communicate out-of-band message information from the provider to the client. Providers may use this header block to communicate information to the client independently from the information contained in the SOAP body. Examples of the types of information communicated in this header block include session identification information, provider state information or message digest information. The oobInfo header block MAY be included in any response message including a SOAP fault message.

The oobInfo header block is the only header block specified in the SDEE schema. The oobInfo header block allows extension child elements (through the use of schema wildcards) to be added after all specified child elements. The support for extension elements allows vendors to add their own child elements, as extension elements, to the oobInfo header block. Clients MUST ignore unrecognized oobInfo header block elements that are not specified in the SDEE schema.

2.7 Backward and Forward Compatibility

SDEE messages are intended to support backward compatibility where older clients may recognize newer message formats output from newer providers, and forward compatibility where newer clients may recognize older message formats output by older providers.

Backward compatibility is achieved through the use of extension elements. Many elements in the SDEE schema support the inclusion of extension child elements and attributes through the use of schema wildcards. In the case of extension child elements, the schema specifies that all extension child elements must be added after all specified child elements. This is done to support the ability to add new core child elements (after the specified child elements) to future versions of the schema while maintaining backward compatibility with older parsers. In this case, older parsers SHOULD treat newly specified elements as unrecognized extension elements. Clients SHOULD process the known elements and ignore the unrecognized elements that appear to be extension elements.

Schema versioning is used to support forward compatibility. Newer clients receiving messages with older formats can validate against the older schema version reported in the messages.

The schema version for SDEE messages are specified by including a version date in the XML namespace path. The schema namespace path for SDEE elements is specified by the BNF: URI-path "/" Gregorian-year "/" Gregorian-month "/" "sdee". The Gregorian-month and Gregorian-year values in the namespace path are used to specify the schema version's date.

The use of schema versions can present a problem for an older client that does not recognize a newer schema version. However, older clients can rely on the convention that newer schema versions will be backwardly compatible with an older schema version that is recognized by the client.

Older schema versions MAY be deprecated. Once an older version has been deprecated for a sufficient period of time, the schema version MAY be declared to be obsolete. Newer schema versions are not required to be compatible with obsolete versions. Consequently, clients that rely on obsolete schema versions may not be compatible with newer message formats.

2.8 Vendor Specified Extensions

The provider's vendor may utilize the extension elements and attributes, specified for SDEE elements, for the purpose of including vendor specified extensions in SDEE elements. The vendor may, for example, use the extension elements and attributes to include product specific information in SDEE elements.

Extension elements MUST only be children of SDEE elements that allow wildcard elements as children. Extension elements MUST be positioned within the SDEE element at the location where wildcard elements are permitted. Similarly, extension attributes MUST only be attributes of SDEE elements that allow wildcard attributes.

Extension elements and attributes MUST be qualified with a non-SDEE namespace qualifier.

The vendor SHOULD provide a schema and MAY provide a specification to specify their extensions.

3.0 Transport Protocol

SDEE messages are communicated using SOAP. However, SOAP is a messaging protocol that requires a binding to a transport protocol. There are several existing specifications that specify SOAP's binding to different transport protocols. Where applicable, SDEE conforms to those specifications. However, the transport protocol bindings for request messages are largely unspecified for SOAP's Response MEP since requests are non-SOAP messages.

This section specifies the SDEE requests as well SDEE specific behavior for the transport protocols utilized by SDEE. HTTP is the only binding currently specified

3.1 Binding to HTTP

The SOAP standard specifies SOAP's binding to the HTTP protocol (see SOAP Version 1.2 Part 2, HTTP Binding). SDEE communications conform to SOAP's HTTP Binding specification for the Response MEP. The message exchange state tables, the use of HTTP headers and the use of HTTP response codes are described by the SOAP specification.

However, the HTTP request messages are largely unspecified by SOAP's HTTP Binding specification for the Response MEP. This section specifies the HTTP request messages used by SDEE. SDEE specific behavior that is outside the scope of the SOAP HTTP Binding specification is also described in this section.

The SOAP specification requires servers that implement the HTTP Binding to implement both the Request-Response MEP and the Response MEP. Currently, SDEE does not utilize any SOAP requests. All SDEE HTTP requests consist of non-SOAP messages.

3.1.1 Overview

SDEE communications begin with a client initiating an unencrypted HTTP or an encrypted HTTP over TLS/SSL connection with an SDEE provider over which SDEE requests and responses will be communicated. Once a connection is established, the client may initiate requests to the provider. The provider acts on the requests and responds back to each of the client's request messages with an SDEE response message.

The provider must supply a URL for handling the Query and/or Subscription requests.

3.1.2 SDEE Session

As a security measure, SDEE providers may require clients' requests to be authorized. Providers may support various authorization methods (see 3.1.6.1 Authorization). Authorization typically consist of authenticating a client's identity and ensuring that the client has sufficient privileges for the requested action.

However, it may be costly (in terms of resource usage) for a provider to re-authenticate the client's identity for every request sent by each client. It can be significantly more efficient for a provider to authenticate a client's identity once and then authorize further requests based on the client's authenticated identity.

A provider MAY establish a session for the purpose of maintaining a client's authentication status over multiple request/response exchanges. The provider establishes a session by sending a session identifier in the oobInfo header block's sessionId child element (see 2.6 oobInfo Header Block). The session identifier is used to associate requests with the authenticated client issuing the requests. The session identifier MUST be unique among clients and SHOULD be hard to guess. A large random number is an example of a session identifier value.

After receiving a response containing a session identifier in the oobInfo header block, the client should report the session identifier in all further requests. The client reports the session identifier using the sessionId token in the HTTP request's URI line.

Alternately, a provider can establish an SDEE session by exchanging the session identifier value using HTTP cookies. The client can direct the provider to return the session identified using HTTP cookies by including the sessionCookies token in the URI line of the request that is being used to authorize the client's identity. The provider sends the session identifier as a HTTP cookie. Clients should return the cookie value in all further requests. This functionality is provided to support web browser clients.

A client that establishes an unencrypted connection with the provider to exchange SDEE requests and responses is vulnerable to having their session hijacked by an eavesdropper. Session hijacking occurs when an eavesdropper that has access to the requests or responses containing the client authentication information or session identifier is able to use this information to impersonate the client. For this reason, communications should be secured (see 3.1.6 Security) when the possibility for malicious activity exists.

Providers need not report the session identifier in every response. The session identifier only needs to be reported in the response that follows client authentication or when the session identifier value changes.

Providers may expire sessions. The provider sends an HTTP Unauthorized response code upon receipt of a request with an expired session identifier. The client may initiate a new session by re-authenticating.

Providers are not required to implement SDEE sessions. Providers that implement SDEE sessions must support the capability to report the session identifier in the oobInfo header block. Providers may optionally implement the capability to exchange the session identifier using HTTP cookies.

3.1.3 Query Messaging

Queries are used to retrieve events, based on the query's filter criteria, that are available from the provider at the time the query request is issued. The client sends a query request message to the provider, and the provider responds with a response message that contains either an SDEE events element or a SOAP fault element in the SOAP message's body.

The query message consists of an HTTP Get request that is issued to the provider's URL for handling queries. The query's filter criteria is specified using the request's URI query parameters. The following URI tokens (see 3.1.7 Request URI Parameters for the specification of the URI tokens and values) are used to specify the criteria for the events to be retrieved in a query. Only events that meet all of the query criteria will be retrieved.

The query will retrieve only the events that have a creation time greater than or equal to the uri-time-value. If startTime is not specified or the startTime value is less than the oldest stored event's creation time, the query begins with the oldest event stored.

The query will retrieve only the events that have a creation time less than or equal to the uri-time-value. If stopTime is not specified or the stopTime value is greater than the newest stored event's creation time, the query ends with the newest event stored.

The query will retrieve only the events that have event types in the uri-es-events-list.

This token specifies maximum number of events that will be retrieved in the query. Additionally, some providers MAY impose an upper-limit on the number of events that can be retrieved in a query. See the provider's documentation to determine a provider's upper-limit.

This token limits the retrieval of evIdsAlert events to those events that have severities in the uri-es-alert-sev-list.

Providers MAY support a subset of the specified query tokens. Additionally, providers MAY support their own proprietary supplemental query tokens. In order to support interoperability and backward compatibility, providers MUST process requests that contain unrecognized query tokens. Providers MAY ignore unrecognized tokens. Providers MUST return a SOAP fault with the subcode value "errUnacceptableValue" in this case that a recognized token's value is invalid.

If the request is successful, the provider will return a a response message with an SDEE events element that contains all the provider's events that meet the query criteria. Events are returned in order of creation time (oldest to newest). If the maxNbrOfEvents limit (or the provider limit) is reached for a query, the client will need to perform one or more additional queries to retrieve the remainder of the events. This implies that the client may get some duplicates because the new query has to specify a startTime equal to the last event time received. Using event subscriptions instead of event queries can simplify multiple retrieval operations since event subscriptions do not have the same event duplication problem.

Example query messaging:

Example 6 shows an example of a query request message that may be sent by an SDEE client. An example of a query response message that may be returned by an SDEE provider is shown in Example 7.

Example 6: Query Request HTTP Message

GET /cgi-bin/event-server?startTime=0077590400314257&events=evIdsAlert&maxNbrOfEvents=100&idsAlertSeverities=medium+high HTTP/1.1
Authorization: Basic bmM0cvFuZ3I6XY0RYWrN
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

The HTTP request message in Example 6 is a query request for evIdsAlert events that occurred at or after the time specified by the startTime token and have medium or high severity values. The request limits the number of events returned in the response to no more than 100 events. The client also authorizes the request using the HTTP Authorization header (see 3.1.6.1 Authorization).

Example 7: Query Response HTTP Message

HTTP/1.1 200 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:39 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
  <sd::oobInfo xmlns:sd="http://example.org/2003/08/sdee">
   <sd:sessionId>12345</sd:sessionId>
  </sd:oobInfo>
 </env:Header>
 <env:Body>
  <sd:events xmlns:sd="http://example.org/2003/08/sdee">
   <sd:evIdsAlert eventId="1234567" vendor="example" severity="medium">...</sd:evIdsAlert>
   ...
   <sd:evIdsAlert eventId="1234667" vendor="example" severity="high">...</sd:evIdsAlert>
  </sd:events>
 </env:Body>
</env:Envelope>

The HTTP response message in Example 7 is a response to the query request. The response contains the session identifier in the sessionId element and the events in the SOAP body.

Example 8: Second Query Request HTTP Message

GET /cgi-bin/event-server?startTime=0077590400314956&events=evIdsAlert&maxNbrOfEvents=100
&idsAlertSeverities=medium+high&sessionId=12345 HTTP/1.1
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

The second query request in Example 8 includes the sessionId URI parameter with session identifier value that was returned in the previous response's SOAP Header section (see 3.1.2 SDEE Session). If a provider requires request authorization and does not support the use of sessions, then the client would need to re-authenticate their identity in each request.

Example 9: Query Response HTTP Message

HTTP/1.1 200 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:39 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <sd:events xmlns:sd="http://example.org/2003/08/sdee">
   <sd:evIdsAlert eventId="1234668" vendor="example" severity="medium">...</sd:evIdsAlert>
   ...
   <sd:evIdsAlert eventId="1234768" vendor="example" severity="high">...</sd:evIdsAlert>
  </sd:events>
 </env:Body>
</env:Envelope>

The second response, in Example 9, contains events in the SOAP body. However, the session identifier is omitted from this response since it only needs to be sent in the response to the client's successful authentication request.

3.1.4 Subscription Messaging

Subscriptions allow clients to establish live event feeds where newer events are returned in each successive retrieval operation.

The SDEE client initiates an event subscription by sending a subscription-open request to an SDEE provider. Once the subscription is opened, the client sends subscription-get messages to the provider to retrieve events from the subscription. The subscription-open request specifies the query criteria that restrict which events may be retrieved from the subscription. The first subscription-get request begins retrieving the oldest events on the provider that match the subscription's query criteria. Successive subscription-get requests pick up where the previous subscription-get requests leave off, and begin retrieving the oldest events that match the subscription's query criteria and are newer than the last event retrieved by the previous subscription-get request. Events are returned in order of creation time (oldest to newest). When no matching events are available on the provider, subscription retrieval operations will block until a matching event is available or until a specified timeout period has elapsed.

For example, a client opens a subscription and specifies (in the subscription-open request's query criteria) that the subscription will retrieve only high severity events. If events 1 (with a high severity), 2 (with a low severity) and 3 (with a high severity) are stored on the provider, then the provider will return events 1 and 3 in response to the client's first subscription-get request. Next events 4 (with a low severity), 5 (with a high severity) and 6 (with a low severity) occur and are stored on the provider. The provider will respond to the next subscription-get request by returning event 5. If the client issues another subscription-get, the request will be blocked until another high severity event is available on the provider.

A subscription should be closed when it is no longer needed.

3.1.4.1 Opening a subscription

An SDEE client sends a subscription-open request to an SDEE provider to open a subscription. A subscription-open request is an HTTP Get request with a URI that contains the token pair "action=open" and optional query filter criteria parameters.

The presence of the the token pair "action=open" in the request's URI differentiates the subscription-open request from an event query request. The client uses the action token to specify the action that the provider is to perform.

The subscription's filter criteria is specified using the request's URI query parameters. The following URI tokens (see 3.1.7 Request URI Parameters for the specification of the URI tokens and values) are used to specify the criteria for the events to be retrieved using a subscription. Only events that meet all of the query criteria will be retrieved with subscription-get requests.

The first subscription-get requests will begin retrieving events that have a creation time greater than or equal to the uri-time-value. If the startTime is less than the oldest event's creation time, the subscription retrieval begins with the oldest event stored on the provider. If startTime is not specified or the startTime value is greater than the newest stored event's creation time, the subscription begins with the next event to be stored..

Subscription-get requests will retrieve only the events that have event types in the uri-es-events-list.

This token limits the retrieval of evIdsAlert events to those events that have severities in the uri-es-alert-sev-list.

Providers MAY support a subset of the specified query tokens. Additionally, providers MAY support their own proprietary supplemental query tokens. In order to support interoperability and backward compatibility, providers must process requests that contain unrecognized query tokens. Providers MAY ignore unrecognized tokens. Providers must return a SOAP fault with the subcode value "errUnacceptableValue" in this case that a recognized token's value is invalid.

If the request is successful, the provider will create a subscription that the client can use to retrieve events that meet the specified query criteria. The provider returns a subscription identifier in the SOAP body's subscriptionId element. The subscription identifier is the subscription's unique identifier that the client will use in further requests pertaining to the given subscription.

Providers MAY support multiple concurrently open subscriptions. Providers MAY also limit the number of concurrently open subscriptions. See the provider's documentation for more information on the provider's limits. If fulfilling a client's subscription-open request would cause the number of open subscriptions to exceed the provider's limit, the provider MUST return a SOAP fault response with the subcode value "errLimitExceeded".

A client receiving a SOAP fault response with the subcode value "errLimitExceeded", in response to a subscription-open request, may issue a subscription-close request to the provider in order to cause the provider to close an open subscription. The problem is that the client may not have knowledge of a subscription identifier for a subscription that is appropriate to close; therefore the client may alternately include the token/value pair, "force=yes", in the subscription-open request's URI to direct the provider to close the least recently used (LRU) subscription and open the client's subscription in place of the closed subscription. Providers MAY optionally support processing the force token in the subscription-open request. If a provider does not process the force token, the provider, in response to receiving a subscription-open request with a force token in a situation where the number of open subscriptions has reached the limit, MUST NOT change the state of the open subscriptions, but MUST return a SOAP fault response with the subcode value "errLimitExceeded" to the client.

A SOAP fault response with the subcode value "errNotAvailable" is used to indicate the subscription could not be opened for some other reason.

It is important to differentiate between an SDEE subscription and an SDEE session (see 3.1.2 SDEE Session). Subscriptions and sessions are used for different purposes. Sessions are used to bypass the need for clients to authenticate each request, while subscriptions are used to keep track of which events the client may retrieve in the next subscription-get operation. For example, a client may open multiple subscriptions for the purpose of retrieving different event information from each subscription. All of the communication for both subscriptions could be performed using a single session. Conversely, a client that is using a subscription could drop a session and re-establish another session without affecting the state of the subscription.

Once a subscription is opened, the subscription can be used to retrieve events.

3.1.4.2 Retrieving events

A subscription-get request is used to retrieve events from an open subscription. A subscription-get request is a HTTP Get request with a URI that contains the subscriptionId token, an optional "action=get" token pair and optional subscription retrieval parameters. The subscriptionId token's value is the subscription identifier returned in the provider's response to the subscription-open request. The request's URI can optionally include the token pair "action=get" to explicitly specify that the request is a subscription-get request. If the action token is omitted from a subscription request then the request is treated as subscription-get request by default.

The default behavior of a subscription-get is to delay its response until at least one event is available to return to the client. The maximum amount of time the provider may block while waiting for the availability of a matching event is subject to the requirements of section 3.1.4.3.

When an event retrieval request for a given subscription is blocked, the client may abort the blocked request by issuing a subscription-close (see 3.1.4.7 Closing a subscription) or a subscription-cancel request (see 3.1.4.6 Canceling a subscription). Sending a subscription-cancel request or subscription-close request for a subscription that has a retrieval request blocked on another connection, causes the blocked retrieval request to unblock and return a response body with an empty events element. This behavior is specified in order to allow clients to override requests that are blocked waiting on events. Additionally, this behavior is needed to handle that case where the connection for a blocked request is broken and the client needs to reestablish event subscription processing on a new connection.

The request's URI can optionally include subscription retrieval parameters (see 3.1.7 Request URI Parameters for the specification of the URI tokens and values). The following retrieval parameters are used to tune the provider's response to retrieval requests:

The maximum number of seconds the provider will block before returning. When this parameter is not specified, the request MAY NOT timeout.

Maximum number of events to retrieve in the query. Some providers impose an upper-limit on the number of events that can be retrieved in a query. See the provider's documentation to determine a provider's upper-limit. When this parameter is not specified, the provider will return all events, up to a provider imposed limit, that match the subscription's query criteria.

Indicates whether or not events were successfully received in the previous subscription-get operation.

The response may contain the oobInfo header block with a missedEvents child element. The missedEvents child element informs the client if un-retrieved events have been overwritten or otherwise removed from the provider since the client's last retrieval request. This situation can occur on providers that limit event storage space. If a client retrieves events too infrequently, the provider can overwrite un-retrieved events between event retrievals. When missedEvents element's value is "true", the client has missed events. The missedEvents element may be omitted when a client has not missed events.

The provider will return a SOAP fault in the response's body to indicate a request error. The SOAP fault's subcode value (see 2.5 Fault Response Message) is "errNotFound" if the specified subscription is not open on the provider. The SOAP fault's subcode value "errInUse" is used to indicate that a retrieval operation is already in progress for the subscription.

3.1.4.3 Controlling the provider's blocking time and response length

Clients may include the timeout token/value pair in a request to limit the amount of time that a response may be blocked waiting for any subscription events to become available. A timeout occurs when no subscription events have become available within the specified period of time. When the timeout occurs, the provider returns a SOAP body with an empty events element. A timeout value of zero indicates that the provider should immediately return all available events. If timeout is not provided by the client, the provider defaults to its maximum time allowable for blocking on subscription-get request. If timeout is provided and its value exceeds the provider's maximum blocking time then the provider's maximum blocking time is used.

Clients may include the maxNbrOfEvents token/value pair in a request to limit the quantity of data that is returned by the subscription-get. The number of events returned in the provider's response can range between zero and the maximum number of events specified in the request. The maxNbrOfEvents token is used to specify an upper limit for the maximum number of events that can be returned in a response. If a client fails to specify a maximum number of events or the specified maximum number of events exceeds the provider's upper limit, the provider will use its upper limit to limit the number of events returned in a response.

3.1.4.4 Confirming receipt of events in a subscription

Clients must confirm the receipt of events returned in the response to a subscription-get. Unconfirmed events are repeatedly returned by the provider until confirmed. Clients may use the URI confirm token/value pair to affect the confirmation of events.

The following conditions cause events returned in the previous subscription-get operation to be confirmed on the provider:

The provider does not confirm previously returned, but unconfirmed events under the following conditions:

Clients can confirm the events received in the previous subscription-get operation by issuing the next subscription-get request without the confirm token/value pair in the request's URI. An example of a situation where client would issue a subscription request with a confirm token value of no is where communications with the provider failed while the client was receiving the response to the previous subscription-get request.

3.1.4.5 Resuming subscriptions

When a client is restarted, it may resume previously opened subscriptions that were not closed. To accomplish this, the client may initiate subscription-get requests using the subscription identifier that was provided when the subscription was opened. If the subscription is still open, the provider will use that subscription identifier to match up with internal subscription state information and resume the subscription exactly where it left off. As with any other subscription-get request, the subscription retrieval returns the oldest unconfirmed events that match the subscription's query criteria.

It is possible that a previously issued subscription-get request may still be blocked waiting to complete an event retrieval operation. This situation could occur if the client shutdown without closing a subscription that is blocked on a event retrieval operation. When a provider receives a subscription-get request for a blocked request, the provider MUST return a SOAP fault response with the subcode value "errInUse". Upon receiving this fault response to a subscription-get request, the client MAY send a subscription-cancel request to unblock the subscription. After completing the subscription-cancel request, the subscription will be unblocked and the client can resend the subscription-get request.

A SOAP fault response with the subcode value "errNotFound" indicates that the subscription is no longer available. In this case, a new subscription would need to be opened.

3.1.4.6 Canceling a subscription

A subscription request that is blocked waiting on events can be interrupted using the subscription-cancel request. A subscription-cancel request is a HTTP Get request with a URI that contains the subscription identifier (using the subscriptionId token) and the token pair "action=cancel". The subscription-cancel request is sent on a connection that is different from the connection on which the blocked subscription retrieval request was sent.  

If the request is successful, the provider returns a response with an empty SOAP body. The provider will return a SOAP fault containing the subcode value (see 2.5 Fault Response Message) "errNotFound" if the referenced subscription is not open.

3.1.4.7 Closing a subscription

When a client is through with a subscription, the client should close the subscription by sending a subscription-close request to the provider. A subscription-close request is a HTTP Get request with a URI that contains the subscription identifier (using the subscriptionId token) and the token pair "action=close". It is important that unused subscriptions are closed since providers may allow only a limited number of open subscriptions.

If the request is successful, the provider returns a response with an empty SOAP body. The provider will return a SOAP fault containing the subcode value (see 2.5 Fault Response Message) "errNotFound" if the referenced subscription is not open.

A subscription MAY remain open indefinitely. Alternately, a provider MAY terminate a subscription for various reasons. A provider MAY limit the amount of time that an active and/or inactive subscription may remain open. Once a provider terminates a subscription, the provider SHALL respond to any further subscription requests by returning a SOAP fault with the subcode value "errNotFound" since the subscription is no longer open. If the provider terminates the subscription while the client is blocked waiting on a subscription-get request to complete, the provider SHALL return a response that contains an empty events element in the SOAP body. It is important to note that the lifecycle of a subscription is independent from the lifecycle of the the client's connection to the provider or the client's session (see 3.1.2 SDEE Session) with the provider.

3.1.4.8 Subscription example

Example 10 shows the client's attempt to resume a subscription, which has already been closed for the purpose of this example. The client sends a subscription-get request, along with the client's authorization data, to the provider.

Example 10: Subscription-get Request HTTP Message

GET /cgi-bin/event-server?subscriptionId=sub-1-1A2B3C4D&action=get HTTP/1.1
Authorization: Basic bmM0cvFuZ3I6XY0RYWrN
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

In Example 11, the provider responds to the request in Example 10 with an error because the subscription was previously closed and therefore no longer exists on the provider. Although the provider returns an error, the provider's response contains the session identifier in the sessionId element in the header block since the client successfully authenticated their identity. It is important to note that an HTTP response status of 400 is returned along with the SOAP fault, per the SOAP specification, to indicate a problem with the client's request.

Example 11: Failed Subscription-get Response HTTP Message

HTTP/1.1 400 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:39 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
 xmlns:sd="http://example.org/2003/08/sdee">
 <env:Header>
  <sd:oobInfo>
   <sd:sessionId>12345</sd:sessionId>
  </sd:oobInfo>
 </env:Header>
 <env:Body>
  <env:Fault>
   <env:Code>
     <env:Value>env:Sender</env:Value>
     <env:Subcode>
      <env:Value>sd:errNotFound</env:Value>
     </env:Subcode>
   </env:Code>
   <env:Reason>
     <env:Text xml:lang="en">The subscription does not exist</env:Text>
   </env:Reason>
  </env:Fault>
 </env:Body>
</env:Envelope>

Since the response in Example 11 indicates that the subscription does not exist, the client initiates a subscription-open request in Example 12. The client's request includes the sessionId URI parameter with session identifier value that was returned in the previous response's SOAP Header section (see 3.1.2 SDEE Session).

Example 12: Subscription-open Request HTTP Message

GET /cgi-bin/event-server?action=open&startTime=0077590476543210&events=evIdsAlert
&alertSeverities=medium+high&sessionId=12345 HTTP/1.1
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

Example 13 shows the providers response to the subscription-open message. The SOAP body contains the subscription identifier in the subscriptionId element.

Example 13: Subscription-open Response HTTP Message

HTTP/1.1 200 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:40 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <sd:subscriptionId xmlns="http://example.org/2003/08/sdee">sub-2-2C4B6C8D</sd:subscriptionId>
 </env:Body>
</env:Envelope>

In Example 14, the client sends an event retrieval request with the newly opened subscription's identifier. The subscription identifier is sent using the subscriptionId URI parameter.

Example 14: Subscription-get Request HTTP Message

GET /cgi-bin/event-server?subscriptionId=sub-2-2C4B6C8D&maxNbrOfEvents=100
&sessionId=12345 HTTP/1.1
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

Example 15 shows the response to the subscription-get request. The SOAP body's events element contains the first set of events that match the filter criteria specified in the subscription-open message.

Example 15: Subscription-get Response HTTP Message

HTTP/1.1 200 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:42 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <sd:events xmlns:sd="http://example.org/2003/08/sdee">
   <sd:evIdsAlert eventId="1234668" vendor="example" severity="medium">...</sd:evIdsAlert>
   ...
   <sd:evIdsAlert eventId="1234795" vendor="example" severity="high">...</sd:evIdsAlert>
  </sd:events>
 </env:Body>
</env:Envelope>

In Example 16, the client sends a second subscription-get request message for the purpose of retrieving the next set of events.

Example 16: Second Subscription-get Request HTTP Message

GET /cgi-bin/event-server?subscriptionId=sub-2-2C4B6C8D&maxNbrOfEvents=100&sessionId=12345 HTTP/1.1
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

Example 17 shows the provider's response to the subscription-get request. The response message contains the next set of events matching the event filter criteria.

Example 17: Second Subscription-get Response HTTP Message

HTTP/1.1 200 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:42 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <sd:events xmlns:sd="http://example.org/2003/08/sdee">
   <sd:evIdsAlert eventId="1234797" vendor="example" severity="medium">...</sd:evIdsAlert>
   ...
   <sd:evIdsAlert eventId="1234822" vendor="example" severity="high">...</sd:evIdsAlert>
  </sd:events>
 </env:Body>
</env:Envelope>

The client closes the subscription when the subscription in no longer being used. Example 18 shows the client's subscription-close request.

Example 18: Subscription-close Request HTTP Message

GET /cgi-bin/event-server?action=close&subscriptionId=sub-2-2C4B6C8D&sessionId=12345 HTTP/1.1
User-Agent: SDEE Client/1.0
Host: 10.1.9.201
From: eventMgr

Example 19 shows the provider's response to the subscription-close request.

Example 19: Subscription-close Response HTTP Message

HTTP/1.1 200 OK
Provider: exampleProvider/1.0
Date: Mon, 14 Jun 2003 17:25:42 GMT
Content-type: text/xml;
Content-Length: 43177
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body/>
</env:Envelope>

3.1.5 Specification Version Messaging

Clients may need to obtain the version of the SDEE specification that the provider is using as well as the versions of any vendor-specific extension specifications used by the provider. The client obtains the specification version information by sending a specification version request to the provider.  The provider responds to a specification version request with a response message that contains either an SDEE specificationVersions element or a SOAP fault element in the SOAP message's body. Upon receipt of a valid specification version request, a provider MUST respond with a SOAP body that contains the specificationVersions child element.

 A specification version request is a HTTP Get request issued to the provider's URL with a URI parameter that consist of the token/value pair "action=getVersions". Section 2.4 Specification Version Response Message describes the response to the specification version request. For the purpose of backward compatibility, this request in its current form must be perpetually supported by providers.

3.1.6 Security

3.1.6.1 Authorization

As a security measure, SDEE providers may require clients' requests to be authorized. Before a provider processes a request, the provider determines whether or not the client is authorized to issue the request.  Authorization generally involves authenticating the client’s identity and determining if the client’s privileges are sufficient to perform the request. The client agent is responsible for providing the necessary credentials to authorize its  requests. The provider is responsible for validating the client's credentials and enforcing security policies.

The provider may support the use of HTTP Basic Authentication (see RFC 2617) to authenticate the client's identity. With HTTP Basic Authentication, the client agent authenticates its identity by including an HTTP “Authorization” header in a request message. The HTTP “Authorization” header's value consists of an encoded representation of the client's username and password (see RFC 2617).

With HTTP Basic Authentication, if the provider fails to authenticate a client's identity or the provider determines that the client is not authorized for the request, the provider will return a response message with a 401 (Unauthorized) status code. The response will also contain the HTTP header “WWW-Authenticate: Basic” to indicate that the client may use HTTP Basic Authentication (see RFC 2617) to authenticate their identity.

A client that establishes a unencrypted connection with the provider to exchange SDEE requests and responses is vulnerable to having their requests impersonated by an eavesdropper. Impersonation occurs when an eavesdropper that has access to the requests or responses containing the client authentication information, is able to use this information to impersonate the client. For this reason, communications should be secured (see 3.1.6.2 Integrity and Confidentiality) when the possibility for malicious activity exists.

Alternately, providers may support the use of X.509 client certificates to authenticate the client's identity. The use of X.509 client certificates is beyond the scope of this document.

Once the provider has authenticated the client's identity, the client's identity may be automatically authenticated in further requests through a session established between the provider and client (see 3.1.2 SDEE Session) if the provider supports SDEE Sessions.

3.1.6.2 Integrity and Confidentiality

SDEE messages may be securely exchanged (using the TLS version 1 or the SSL version 3 protocols) between agents that are configured to support these protocols. The client initiates a TCP connection to an HTTP or "HTTP over TLS/SSL" server on the target host. TCP provides a reliable stream transport. The TLS/SSL protocol provides cipher and secret key negotiation, session privacy and integrity, server authentication and optional client authentication.

3.1.7 Request URI Parameters

While SDEE response data is exchanged in the SOAP body, the request is specified in the HTTP URI line. The syntax for the URI line is specified using a BNF language with the extensions specified in RFC 2616. It is important to note that linear white space (LWS) is not allowed anywhere in the URI line.

The following extended BNF specifies the syntax of the SDEE request URI.

uri      = uri-scheme "://" uri-authority [ ":" uri-port ] [ "/" uri-path ] [ uri-parameters ]
 
uri-scheme    = "http" | "https"
uri-authority = uri-host-ip | uri-host | uri-host-name
uri-port      = 1*5digit
uri-host-ip   = ipv4-address | ipv6-address
uri-host      = uri-name
uri-host-name = +( uri-name "." ) <top-level-domain-name>
uri-path      = uri-token
 
uri-parameters      = ( uri-es-query
                   | uri-es-subscription-open
                   | uri-es-subscription-get
                   | uri-es-subscription-cancel
                   | uri-es-subscription-close 
                   | uri-es-get-versions )
                   [ "&" uri-session-id-pair ]
                   [ "&" uri-session-cookie-pair ]
                   
uri-es-query       = [ "?" uri-es-query-tokens
                   [ "&" uri-es-stop-time-pair ]
                   [ "&" uri-es-max-events-pair ] ]
 
uri-es-subscription-open = "?" "action=open"
                   [ "&" uri-es-query-tokens ]
                   [ "&" uri-force-pair ]
 
uri-es-subscription-get = "?" uri-es-subscription-id-pair
                   [ "&" "action=get" ]
                   [ "&" uri-es-subscription-get-tokens ]
 
uri-es-subscription-close = "?" uri-es-subscription-id-pair
                   "&" "action=close"
 
uri-es-get-versions = "action=getVersions"
 
uri-es-query-tokens  = ( uri-es-events-pair
                   | uri-es-start-time-pair
                   | uri-es-alert-sev-pair )
                   [ "&" uri-es-query-tokens ] 
; note: each pair item may appear no more than once in uri-es-query-tokens
                                                
uri-es-subscription-get-tokens  = ( uri-es-confirm-pair
                   | uri-es-max-events-pair
                   | uri-es-timeout-pair ) [ "&" uri-es-subscription-get-tokens ]
; note: each pair item may appear no more than once in uri-es-subscription-get-tokens
 
uri-es-start-time-pair = "startTime" "=" uri-time-value
uri-time-value         = 1*20digit    ; the number of nanoseconds since the start
                                      ; of the UNIX epoch (GMT)
 
uri-es-stop-time-pair = "stopTime" "=" uri-time-value
 
uri-es-events-pair = "events" "=" uri-es-events-list
uri-es-events-list = uri-es-event | uri-es-events-list "+" uri-es-event
uri-es-event       = uri-element        ; Any type of security event element
 
uri-es-max-events-pair = "maxNbrOfEvents" "=" uri-es-nbr-of-events
uri-es-nbr-of-events= 1*5digit
 
uri-es-alert-sev-pair = "alertSeverities" "=" uri-es-alert-sev-list
uri-es-alert-sev-list = uri-es-alert-sev | uri-es-alert-sev-list "+" uri-es-alert-sev
uri-es-alert-sev      = "informational"  ; See the IDIOM Specification of Alert Severities
                      | "low"
                      | "medium"
                      | "high"
 
uri-es-subscription-id-pair = "subscriptionId" "=" uri-subscription-token
uri-subscription-token      = uri-value
 
uri-force-pair      = "force" "=" uri-yes-or-no
 
uri-es-confirm-pair = "confirm" "=" uri-yes-or-no
uri-yes-or-no       = "yes" | "no"
 
uri-es-timeout-pair   = "timeout" "=" uri-es-nbr-of-seconds
uri-es-nbr-of-seconds = 1*5digit
 
uri-session-id-pair   = "sessionId" "=" uri-token-chars
 
uri-session-cookie-pair = "sessionCookies" "=" uri-yes-or-no
 
; ----- basic types -----
 
uri-name      = alpha *alphanumeric
uri-token     = +uri-token-chars
uri-element   = *uri-element-chars
uri-value     = *uri-value-chars
 
uri-token-chars    = allowable-reserved | unreserved | escaped
uri-element-chars  = uri-token-chars | "="
uri-value-chars    = uri-element-chars | "+"
 
allowable-reserved = ";" | "/" | ":" | "@"  | "$" | ","
unreserved = alphanum | mark
mark = "-" | "_" | "." | "!" | "~" | "*" | "'" |
       "(" | ")"
 
escaped = "%" hex hex
hex = digit | "A" | "B" | "C" | "D" | "E" | "F" |
      "a" | "b" | "c" | "d" | "e" | "f"
 
ipv4-address = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
ipv6-address = ipv4-address "." ipv4-address "." ipv4-address "."
               ipv4-address
 
alphanum = alpha | digit
alpha = lowalpha | upalpha
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
           "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
           "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
           "y" | "z"
upalpha  = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
           "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
           "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
           "Y" | "Z"
digit  = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
          "8" | "9"

where:

<top-level-domain-name> is a legal top level domain name.


Reference Documents

SOAP (version 1.2) Part 1

SOAP (version 1.2) Part 2

SOAP (version 1.2) Tutorial

Hypertext Transfer Protocol -- HTTP/1.1 (PDF)

The TLS Protocol Version 1.0

Uniform Resource Identifiers (URI): Generic Syntax

HTTP Authentication -- RFC 2617