Jeff Platzer
Cisco Systems
August
20, 2003
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.
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.
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].
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
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.
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).
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).
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>
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>
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.
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>
oobInfo Header
BlockThe 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.
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.
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.
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
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.
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.
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.
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.
startTime
- Restricts the retrieval of all event types. 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.
stopTime
- Restricts the retrieval of all event types. 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.
events -
Restricts the retrieval of all event types. The query will retrieve only the events that have event types in the uri-es-events-list.
maxNbrOfEvents
- Restricts the retrieval of all event types. 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.
idsAlertSeverities
- Restricts the retrieval of evIdsAlert
events. 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.1Authorization: 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.1User-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.
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.
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.
startTime
- Restricts the retrieval of all event types. 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..
events -
Restricts the retrieval of all event types. Subscription-get requests will retrieve only the events that have event types in the uri-es-events-list.
idsAlertSeverities
- Restricts the retrieval of evIdsAlert
events. 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.
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:
timeout
The maximum number of seconds the provider will block before returning. When this parameter is not specified, the request MAY NOT timeout.
maxNbrOfEvents
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.
confirm
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.
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.
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:
confirm
token value of yes in
the request's URI.
confirm
token/value pair in the request's URI. Because the default confirm
token value is yes,
omitting the confirm
token/value pair from the subscription request's URI implicitly confirms the
events received in the previous subscription-get operation. The provider does not confirm previously returned, but unconfirmed events under the following conditions:
confirm
token value of no.
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.
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.
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.
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.
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.1User-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.1User-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>
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.
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.
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.
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*5digituri-host-ip = ipv4-address | ipv6-addressuri-host = uri-nameuri-host-name = +( uri-name "." ) <top-level-domain-name>
uri-path = uri-tokenuri-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-valueuri-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-secondsuri-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-charsuri-element = *uri-element-charsuri-value = *uri-value-charsuri-token-chars = allowable-reserved | unreserved | escapeduri-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-addressalphanum = 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.
Hypertext Transfer Protocol -- HTTP/1.1 (PDF)