XDAS API


Files
file	xdas.h
	XDAS client interface header file.
Modules
	API Portability
Data Structures
struct	xdas_buffer_desc_struct
	XDAS UTF-8 content buffer descriptor. More...
struct	xdas_audit_record_desc_struct
	XDAS in-memory audit record structure. More...
XDAS General Audit Service API
All callers must initiate a session with the XDAS before they can use any of the services it provides. The initialization of the session supports the mutual authentication of the audit client and audit service components and establishes the audit client�s XDAS authorities. The caller is returned a handle to the XDAS service which is then used for all XDAS API functions. On completion, the caller must terminate the XDAS session. The XDAS General Audit Service API is part of the Basic XDAS specification conformance class.
XDASXPC int XDASAPI	xdas_initialize_session (int minor_status, const char org_info, xdas_audit_ref_t *das_ref)
	Initialize an XDAS session for use within the process.
XDASXPC int XDASAPI	xdas_terminate_session (int minor_status, xdas_audit_ref_t das_ref)
	Terminate an XDAS session.
XDAS Audit Read API
The Audit Read API is used to extract records from the XDAS audit stream for analysis. The interface supports the copying of a record into a buffer where the contents may be examined by the caller. The interfaces are available to privileged callers who possess the XDAS_AUDIT_READ authority. The XDAS Audit Read API is part of the Basic XDAS specification conformance class.
XDASXPC int XDASAPI	xdas_close_audit_stream (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_stream_t audit_stream_ref)
	Closes an XDAS audit stream.
XDASXPC int XDASAPI	xdas_get_next (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_stream_t audit_stream_ref, unsigned max_records, xdas_buffer_t audit_record_buffer, unsigned no_of_records)
	Fill an output buffer with the next set of records in an audit stream.
XDASXPC int XDASAPI	xdas_open_audit_stream (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_stream_t audit_stream_ref)
	Opens an XDAS audit stream and associates it with an XDAS session.
XDASXPC int XDASAPI	xdas_parse_record (int *minor_status, xdas_audit_ref_t das_ref, xdas_buffer_t audit_record_buffer, unsigned record_number, xdas_audit_record_t audit_record)
	Parse a specified XDAS record from an XDAS record buffer.
XDASXPC int XDASAPI	xdas_rewind_audit_stream (int *minor_status, xdas_audit_ref_t das_ref, xdas_audit_stream_t audit_stream_ref)
	Rewind an audit stream read pointer.
XDAS Audit Log Import API
This service permits domain specific audit services to import their own audit records into the XDAS service for consolidation and analysis at the distributed system level. Only callers with the XDAS_AUDIT_IMPORT authority are permitted to use this function. The XDAS Audit Log Import API is part of the XDAS specification Import API Option conformance class.
XDASXPC int XDASAPI	xdas_import_event_records (int minor_status, xdas_audit_ref_t das_ref, xdas_buffer_t audit_record_buffer, size_t position_in_buffer)
	Import event records from an external service into the XDAS common format.
XDAS Audit Event Service Client API
Callers submit security relevant events to the Audit Event Service Client API. The functions builds the record from the information given by the caller and from the processing environment. The interfaces cover the creation, filling and committing of an audit record to the audit trail. The XDAS Audit Event Service Client API is part of the XDAS specification Event Submission API Option conformance class.
XDASXPC int XDASAPI	xdas_commit_record (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_rec_desc_t audit_record_descriptor)
	Write a completed audit record to the associated audit stream.
XDASXPC int XDASAPI	xdas_discard_record (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_rec_desc_t audit_record_descriptor)
	Discard a previously created audit record.
XDASXPC int XDASAPI	xdas_put_event_info (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_rec_desc_t audit_record_descriptor, unsigned event_number, unsigned outcome, const char initiator_information, const char target_information, const char *event_information)
	Add specific event information to an audit record.
XDASXPC int XDASAPI	xdas_start_record (int minor_status, xdas_audit_ref_t das_ref, xdas_audit_rec_desc_t audit_record_descriptor, unsigned event_number, unsigned outcome, const char initiator_information, const char target_information, const char *event_information)
	Creates a new event record object.
XDASXPC int XDASAPI	xdas_timestamp_record (int *minor_status, xdas_audit_ref_t das_ref, xdas_audit_rec_desc_t audit_record_descriptor)
	Add a timestamp to the specified audit record.
XDAS Audit Event Management API
The Audit Event Management API provides the means whereby the Audit Event Discrimination Service and the Audit Event Disposition Service are configured. Only callers with the XDAS_AUDIT_CONTROL authority are permitted to use these interfaces. The XDAS Audit Event Management API is part of the XDAS specification Filter Management API Option conformance class.
XDASXPC int XDASAPI	xdas_create_filter (int minor_status, xdas_audit_ref_t das_ref, const char name, unsigned filter_type, const char filter_exp, const char filter_act)
	Create a named audit filter.
XDASXPC int XDASAPI	xdas_delete_filter (int minor_status, xdas_audit_ref_t das_ref, const char name)
	Delete an audit filter by name.
XDASXPC int XDASAPI	xdas_disable_filter (int minor_status, xdas_audit_ref_t das_ref, const char name)
	Disable an audit filter by name.
XDASXPC int XDASAPI	xdas_enable_filter (int minor_status, xdas_audit_ref_t das_ref, const char name)
	Enable an audit filter by name.
XDASXPC int XDASAPI	xdas_get_filter (int minor_status, xdas_audit_ref_t das_ref, const char name, unsigned filter_type, xdas_buffer_t filter_exp, xdas_buffer_t filter_act, unsigned filter_status)
	Get an audit filter by name.
XDASXPC int XDASAPI	xdas_list_filters (int minor_status, xdas_audit_ref_t das_ref, char filter_name_list, size_t buffer_size)
	Return a list of all defined audit filter names.
XDAS Standard Error Codes
One or more status codes are returned by each XDAS-API routine. Two distinct sorts of status code are returned. These are termed XDAS status codes and minor status codes. An implementation of XDAS functions shall return XDAS_S_COMPLETE and other status values appropriate for the implementation of the function. The characteristics of a particular implementation may make some status returns inappropriate for that implementation. XDAS-API routines return XDAS status codes as their integer function value. These codes indicate major status errors that are independent of the underlying mechanism used to provide the security service. A XDAS status code can indicate a single fatal generic API error from the routine error and a single calling error. These errors are encoded into the 32-bit XDAS status code. Changes to the original OpenGroup XDAS specification: 1) Moved XDAS_S_NOT_SUPPORTED from position 24 to position 27 because position 24 was in use twice (also by XDAS_S_RECORD_SYNTAX_ERROR) 2) Added XDAS_S_INVALID_FILTER_ACTION because it wasn't there, and all other types of filter information were represented (and used).
#define	XDAS_S_COMPLETE 0
#define	XDAS_S_AUTHORIZATION_FAILURE 1
#define	XDAS_S_BUFF_TOO_SMALL 2
#define	XDAS_S_END 3
#define	XDAS_S_FAILURE 4
#define	XDAS_S_INCOMPLETE_RECORD 5
#define	XDAS_S_INVALID_ACTION_LIST 6
#define	XDAS_S_INVALID_AUDIT_STREAM 7
#define	XDAS_S_INVALID_DAS_REF 8
#define	XDAS_S_INVALID_EVENT_INFO 9
#define	XDAS_S_INVALID_EVENT_NO 10
#define	XDAS_S_INVALID_FILTER 11
#define	XDAS_S_INVALID_FILTER_EXPR 12
#define	XDAS_S_INVALID_FILTER_LIST 13
#define	XDAS_S_INVALID_FILTER_TYPE 14
#define	XDAS_S_INVALID_INITIATOR_INFO 15
#define	XDAS_S_INVALID_ORIG_INFO 16
#define	XDAS_S_INVALID_OUTCOME 17
#define	XDAS_S_INVALID_RECORD_DESCRIPTOR 18
#define	XDAS_S_INVALID_RECORD_NUMBER 19
#define	XDAS_S_INVALID_SECURITY_CONTEXT 20
#define	XDAS_S_INVALID_TARGET_INFO 21
#define	XDAS_S_NO_AUDIT 22
#define	XDAS_S_NO_DECISION_YET 23
#define	XDAS_S_RECORD_SYNTAX_ERROR 24
#define	XDAS_S_STORAGE_FAILURE 25
#define	XDAS_S_SERVICE_FAILURE 26
#define	XDAS_S_NOT_SUPPORTED 27
#define	XDAS_S_INVALID_FILTER_ACTION 28
OpenXDAS Minor Status Codes.
These minor status codes are returned in the `minor_status` parameter of XDAS API functions as implemented by OpenXDAS. These values are only returned in `minor_status` parameters if the return value of the API function is XDAS_S_FAILURE. All other XDAS return values set the `minor_status` output parameter to zero (OXDAS_MS_NO_ERROR).
#define	OXDAS_MS_NO_ERROR 0
#define	OXDAS_MS_UNKNOWN_ERROR 1
#define	OXDAS_MS_OUT_OF_MEMORY 2
#define	OXDAS_MS_NET_INIT_FAILED 3
#define	OXDAS_MS_NET_GENERAL_ERROR 4
#define	OXDAS_MS_NET_BAD_SOCKET 5
#define	OXDAS_MS_NET_CONN_ABORTED 6
#define	OXDAS_MS_NET_CONN_RESET 7
#define	OXDAS_MS_NET_NOT_CONNECTED 8
#define	OXDAS_MS_NET_SHUTDOWN 9
#define	OXDAS_MS_NET_TIMEDOUT 10
#define	OXDAS_MS_NET_CONN_REFUSED 11
#define	OXDAS_MS_PROTOCOL 12
XDAS Calling Error Codes
If a XDAS-API routine returns a XDAS status code containing a non-zero value, the call failed. If the Calling Error field is non-zero, the invoking application�s call of the routine was erroneous. Calling errors are defined in Table 6-1 of the XDAS Preliminary Specification document.
#define	XDAS_S_CALL_INACCESSIBLE_READ (1 << 16)
#define	XDAS_S_CALL_INACCESSIBLE_WRITE (2 << 16)
#define	XDAS_S_CALL_BAD_STRUCTURE (3 << 16)
XDAS Error Macros
These macros may be used to extract routine or calling error codes from routine return values. XDAS_ERROR simply returns true if the return value is an error.
#define	XDAS_ROUTINE_ERROR(e) ((e) & 0x0000FFFF)
#define	XDAS_CALLING_ERROR(e) ((e) & 0xFFFF0000)
#define	XDAS_ERROR(e) ((e) ? 1 : 0)
XDAS Basic Event Types
The generic set of XDAS events numbers. XDAS conforming implementations are required to handle all these defined audit events as valid. An application or system developer that submits or imports security domain specific events to the XDAS service must map those events to these XDAS generic events or register their own set of audit events with the OpenGroup. The following table is a duplicate of Figure 6-2 of the Open Group XDAS Preliminary Specification, and describes the bit-format of event types: Bit: 01234 8 16 24 31 -------------------------------------- Format A: \|0\| set-id \| event-id \| -------------------------------------- Format B: \|10\| set-id \| event-id \| -------------------------------------- Format C: \|110\| set-id \| event-id \| -------------------------------------- Format D: \|1110\| event-id \| -------------------------------------- Format E: \|11111\| reserved \| -------------------------------------- Changes to the original OpenGroup XDAS specification: 1) The specified list of generic class A events had one duplicate at position 0x01000024, XDAS_AE_START_SYS was a duplicate of the previous event XDAS_AE_MODIFY_DATA_ITEM_CONTENTS. To maintain the event list order, each event from XDAS_AE_START_SYS to XDAS_AE_AUD_DS_CORR has been shifted up one numeric value.
#define	XDAS_AE_CREATE_ACCOUNT 0x01000001
#define	XDAS_AE_DELETE_ACCOUNT 0x01000002
#define	XDAS_AE_DISABLE_ACCOUNT 0x01000003
#define	XDAS_AE_ENABLE_ACCOUNT 0x01000004
#define	XDAS_AE_QUERY_ACCOUNT 0x01000005
#define	XDAS_AE_MODIFY_ACCOUNT 0x01000006
#define	XDAS_AE_CREATE_SESSION 0x01000007
#define	XDAS_AE_TERMINATE_SESSION 0x01000008
#define	XDAS_AE_QUERY_SESSION 0x01000009
#define	XDAS_AE_MODIFY_SESSION 0x0100000A
#define	XDAS_AE_CREATE_DATA_ITEM 0x0100000B
#define	XDAS_AE_DELETE_DATA_ITEM 0x0100000C
#define	XDAS_AE_QUERY_DATA_ITEM_ATT 0x0100000D
#define	XDAS_AE_MODIFY_DATA_ITEM_ATT 0x0100000E
#define	XDAS_AE_INSTALL_SERVICE 0x0100000F
#define	XDAS_AE_REMOVE_SERVICE 0x01000010
#define	XDAS_AE_QUERY_SERVICE_CONFIG 0x01000011
#define	XDAS_AE_MODIFY_SERVICE_CONFIG 0x01000012
#define	XDAS_AE_DISABLE_SERVICE 0x01000013
#define	XDAS_AE_ENABLE_SERVICE 0x01000014
#define	XDAS_AE_INVOKE_SERVICE 0x01000015
#define	XDAS_AE_TERMINATE_SERVICE 0x01000016
#define	XDAS_AE_QUERY_PROCESS_CONTEXT 0x01000017
#define	XDAS_AE_MODIFY_PROCESS_CONTEXT 0x01000018
#define	XDAS_AE_CREATE_PEER_ASSOC 0x01000019
#define	XDAS_AE_TERMINATE_PEER_ASSOC 0x0100001A
#define	XDAS_AE_QUERY_ASSOC_CONTEXT 0x0100001B
#define	XDAS_AE_MODIFY_ASSOC_CONTEXT 0x0100001C
#define	XDAS_AE_RECEIVE_DATA_VIA_ASSOC 0x0100001D
#define	XDAS_AE_SEND_DATA_VIA_ASSOC 0x0100001E
#define	XDAS_AE_CREATE_DATA_ITEM_ASSOC 0x0100001F
#define	XDAS_AE_TERMINATE_DATA_ITEM_ASSOC 0x01000020
#define	XDAS_AE_QUERY_DATA_ITEM_ASSOC_CONTEXT 0x01000021
#define	XDAS_AE_MODIFY_DATA_ITEM_ASSOC_CONTEXT 0x01000022
#define	XDAS_AE_QUERY_DATA_ITEM_CONTENTS 0x01000023
#define	XDAS_AE_MODIFY_DATA_ITEM_CONTENTS 0x01000024
#define	XDAS_AE_START_SYS 0x01000025
#define	XDAS_AE_SHUTDOWN_SYS 0x01000026
#define	XDAS_AE_RESOURCE_EXHAUST 0x01000027
#define	XDAS_AE_RESOURCE_CORRUPT 0x01000028
#define	XDAS_AE_BACKUP_DATASTORE 0x01000029
#define	XDAS_AE_RECOVER_DATASTORE 0x0100002A
#define	XDAS_AE_AUD_CONFIG 0x0100002B
#define	XDAS_AE_AUD_DS_FULL 0x0100002C
#define	XDAS_AE_AUD_DS_CORR 0x0100002D
#define	XDAS_AE_MODIFY_AUTH_TOKEN 0x02000001
#define	XDAS_AE_APPROVAL_RECEIVED 0x02000002
#define	XDAS_AE_APPROVAL_REQUESTED 0x02000003
#define	XDAS_AE_REQUEST_ESCALATED 0x02000004
#define	XDAS_AE_NOTIFICATION_SENT 0x02000005
#define	XDAS_AE_CREATE_ROLE 0x02000006
#define	XDAS_AE_DELETE_ROLE 0x02000007
#define	XDAS_AE_DISABLE_ROLE 0x02000008
#define	XDAS_AE_ENABLE_ROLE 0x02000009
#define	XDAS_AE_QUERY_ROLE 0x0200000A
#define	XDAS_AE_MODIFY_ROLE 0x0200000B
XDAS Basic Event Classes
Similar to event numbers, event-class numbers encode the identification of an event-class set, as well as the identification of a unique event class within that set. A set of event-class numbers is assigned (upon request) by the OpenGroup to an organization or a vendor. The organization or vendor then has the authority to use the the event-class numbers within that set. Conceptually, each event class number is a pair (set-id, class-id), where set-id identifies an event-class set, and the class-id identifies an event class within in the set. In practice, each event-class number must have one of the formats illustrated in Figure 6-3 of the Open Group XDAS Preliminary Specification. This table is reproduced here: Bit: 01234 8 16 24 31 -------------------------------------- Format A: \|0\| set-id \| class-id \| -------------------------------------- Format B: \|10\| set-id \| class-id \| -------------------------------------- Format C: \|110\| class-id \| -------------------------------------- Format D: \|111\| reserved \| --------------------------------------
#define	XDAS_AEC_ACCOUNT_MANAGEMENT 0x01000001
#define	XDAS_AEC_USER_SESSION 0x01000002
#define	XDAS_AEC_DATA_ITEM_MANAGEMENT 0x01000003
#define	XDAS_AEC_SERVICE_MANAGEMENT 0x01000004
#define	XDAS_AEC_SERVICE_UTILIZE 0x01000005
#define	XDAS_AEC_PEER_ASSOC_MANAGEMENT 0x01000006
#define	XDAS_AEC_DATA_ITEM_CONTENT_ACCESS 0x01000007
#define	XDAS_AEC_EXCEPTIONAL 0x01000008
#define	XDAS_AEC_AUDIT_SERVICE 0x01000009
XDAS Outcome Codes
XDAS outcome codes represent the outcome of a given event. The outcome codes are structured into sets for SUCCESS, FAILURE, and DENIAL. Multiple codes from within one of these sets may be returned by a single call by combining them using a bitwise OR, but it is not permitted for outcome codes from the different sets to be returned by a single call. For example, multiple SUCCESS codes may be returned by one call, but SUCCESS and FAILURE codes may not be returned by a single call. Changes to the original OpenGroup XDAS specification: 1) There are two outcome tables in the XDAS preliminary specification. One is in section 4.4, Identification of Audit Events. The other is in section 6.11, XDAS Event Outcome Codes. These two tables are in disagreement with one another in several ways so the OpenXDAS implementation tries to compensate with executive decisions where necessary. The first issue is a missing event in section 6.11 which is specified in the table in section 4.4.4 - XDAS_OUT_ALREADY_ENABLED. Since XDAS_OUT_ALREADY_DISABLED exists in both tables, OpenXDAS assumes that the missing entry in section 6.11 is an oversight. Unfortunately, there is no slot in the bitmap for this addition. The value of XDAS_OUT_LOST_ASSOCIATION was reduced by one in order to make room in the bitmap for XDAS_OUT_ALREADY_ENABLED. 2) The remaining discrepencies are limited to simple naming differences in the definition names. Arbitrary decisions were made to choose the names for OpenXDAS. These include XDAS_OUT_NON_EXISTENT, XDAS_OUT_INSUFFICIENT_PRIVILEGE and XDAS_OUT_INVALID_CREDENTIALS.
#define	XDAS_OUT_NOT_SPECIFIED 0xFFFFFFFF
#define	XDAS_OUT_SUCCESS 0x00000000
#define	XDAS_OUT_PRIV_USED 0x00000100
#define	XDAS_OUT_PRIV_GRANTED 0x00000200
#define	XDAS_OUT_PRIV_REVOKED 0x00000400
#define	XDAS_OUT_PRESELECT_CRITERIA_SET 0x00000800
#define	XDAS_OUT_THRESHOLDS_SET 0x00001000
#define	XDAS_OUT_ACTIONS_SET 0x00002000
#define	XDAS_OUT_FAILURE 0x00000001
#define	XDAS_OUT_SERVICE_UNAVAILABLE 0x00000101
#define	XDAS_OUT_SERVICE_FAILURE 0x00000201
#define	XDAS_OUT_HARDWARE_FAILURE 0x00000401
#define	XDAS_OUT_LOST_ASSOCIATION 0x00000801
#define	XDAS_OUT_ALREADY_ENABLED 0x00001001
#define	XDAS_OUT_ALREADY_DISABLED 0x00002001
#define	XDAS_OUT_SERVICE_ERROR 0x00004001
#define	XDAS_OUT_BUSY 0x00008001
#define	XDAS_OUT_DISABLED 0x00010001
#define	XDAS_OUT_INVALID_INPUT 0x00020001
#define	XDAS_OUT_ENTITY_EXISTS 0x00040001
#define	XDAS_OUT_ENTITY_NON_EXISTENT 0x00080001
#define	XDAS_OUT_DENIAL 0x00000002
#define	XDAS_OUT_INSUFFICIENT_PRIVILEGE 0x00000102
#define	XDAS_OUT_INVALID_IDENTITY 0x00000202
#define	XDAS_OUT_INVALID_CREDENTIALS 0x00000402
XDAS Filter Types
Filters are used to set the criteria for preselecting events to be recorded, or for selecting records to be imported from an audit stream. A filter expression is defined as a UTF-8 character string. It is a sequence of variable length fields, separated by colon (":") delimiters, as set out below. Note that if a colon is part of an alphanumeric string, then it shall be escaped. The format for a single filter expression is defined as: include/exclude flag:attribute:operator:value A filter may be defined as a list of filter expressions which shall be evaluated in the sequence in which they are listed. The intention is that a subsequent expression may define exceptions to previous expression. For example, an expression may exclude a set of events based on event class, but a subsequent expression, based on event number, may specifically include a subset of the events otherwise excluded by reference to event class.
#define	XDAS_C_SUBMIT 1
#define	XDAS_C_IMPORT 2
XDAS Filter Expression Flags
#define	XDAS_C_INCLUDE 1
#define	XDAS_C_EXCLUDE 2
XDAS Filter Attributes
#define	XDAS_VERSION 1
#define	XDAS_TIME_OFFSET 2
#define	XDAS_TIME_UNCERT_INTER 3
#define	XDAS_TIME_UNCERT_INDIC 4
#define	XDAS_TIME_SOURCE 5
#define	XDAS_TIME_TIME_ZONE 6
#define	XDAS_EVENT_NUMBER 7
#define	XDAS_OUTCOME 8
#define	XDAS_ORG_LOC_NAME 9
#define	XDAS_ORG_LOC_ADD 10
#define	XDAS_ORG_SERV_TYPE 11
#define	XDAS_ORG_AUTH_AUTH 12
#define	XDAS_ORG_PRINC_NAME 13
#define	XDAS_ORG_PRINC_IDENTITY 14
#define	XDAS_INT_AUTH_AUTH 15
#define	XDAS_INT_PRINC_NAME 16
#define	XDAS_INT_PRINC_IDENTITY 17
#define	XDAS_TGT_LOC_NAME 18
#define	XDAS_TGT_LOC_ADD 19
#define	XDAS_TGT_SERV_TYPE 20
#define	XDAS_TGT_AUTH_AUTH 21
#define	XDAS_TGT_PRINC_NAME 22
#define	XDAS_TGT_PRINC_IDENTITY 23
XDAS Filter Expression Operators
#define	XDAS_O_EQ 1
#define	XDAS_O_NE 2
#define	XDAS_O_GT 3
#define	XDAS_O_LT 4
#define	XDAS_O_GE 5
#define	XDAS_O_LE 6
#define	XDAS_O_BT 7
#define	XDAS_O_SS 8
XDAS Event Action Masks
A filter may also define the disposition of an event submitted to, or imported into the XDAS service. A filter action expression is defined as a UTF-8 character string. It is a sequence of variable length fields, separated by colon (":") delimiters, as set out below. Note that if a colon is part of an alphanumeric string, then it shall be escaped. The format for a single filter expression is defined as: action mask:text string The components of the action mask are defined here. The format of the text string is implementation defined. A filter may be defined as a list of filter actions which shall be executed in the sequence in which they are listed. Action bits may be OR'd together to indicate that multiple actions are desired for a given class of events.
#define	XDAS_ACT_LOG 1
#define	XDAS_ACT_ALARM 2
#define	XDAS_ACT_ACTION 4
Defines
#define	XDAS_RECORD_VERSION "0"
	XDAS record format version number - currently at 0.
Typedefs
typedef struct xdas_buffer_desc_struct	xdas_buffer_desc
	XDAS UTF-8 content buffer descriptor.
typedef struct xdas_buffer_desc_struct *	xdas_buffer_t
typedef struct xdas_audit_record_desc_struct	xdas_audit_record_desc
	XDAS in-memory audit record structure.
typedef struct xdas_audit_record_desc_struct *	xdas_audit_record_t
typedef void *	xdas_audit_ref_t
	XDAS session handle.
typedef void *	xdas_audit_stream_t
	XDAS audit stream handle.
typedef void *	xdas_audit_rec_desc_t
	XDAS event record handle.

Detailed Description

The XDAS specification defines a series of API sets, each of which provide some level of conformance with the standard. The OpenXDAS implementation modifies the standard in several places in minor ways - mostly to make it usable and implementable. This interface header file documents each place where OpenXDAS deviates from the standard, and why.

The audit event record format is defined as an UTF-8 character encoding in an xdas_buffer_t structure. Fields are delineated with colons (:); where a colon is part of the alphanumeric string. "%" shall be used as the escape character. The character immediately following a "%" is not interpreted. For example, "%%" yields "%", "%:" yields ":", "%%%:" yields "%:".

Empty strings are represented by two adjacent separator characters. Note that this is an ordered sequence. The sequence of fields in the XDAS audit event record format is specified as follows. Note that the angle-bracketed symbols represent field names and are not a literal part of the text. All other characters are literal. Also note that field tags that begin with "hex_" or "dec_" represent utf-8 hexadecimal or decimal string values. All other fields are simple string fields:

      HDR:
      <four_digit_hex_length_in_bytes>:
      <decimal_xdas_record_version>:
      <hex_time_offset>:
      <hex_time_uncertainty_interval>:
      <hex_time_uncertainty_indicator>:
      <time_source>:
      <time_zone>:
      <hex_event_number>:
      <hex_outcome>:
      ORG:
      <org_location_name>:
      <org_location_address>:
      <org_service-type>:
      <org_auth_authority>:
      <org_principal_name>:
      <org_principal_id>:
      INT:
      <int_auth_authority>:
      <int_domain_specific_name>:
      <int_domain_specific_id>:
      TGT:
      <tgt_location_name>:
      <tgt_location_address>:
      <tgt_service-type>:
      <tgt_auth_authority>:
      <tgt_principal_name>:
      <tgt_principal_id>:
      SRC:
      <pointer_to_source_domain>:
      EVT:
      <event_specific_information>:
      END

Changes to the original OpenGroup XDAS specification:

1) Changed length_in_bytes field above to four_digit_hex_length_in_bytes, and specified that it must use exactly four (4) hexadecimal digits, padded with zeros on the left so that it would be simple to replace a placeholder value with the real length value without changing the length of the string. The meaning of this field is also cloudy in the spec. OpenXDAS defines this field to mean the total length of the record from the start of the opening "HDR:" tag to the end of the closing "END" tag, not including any potential terminating NULL character.

2) Removed unnecessary xdas_release_buffer function. This routine was only necessary because a few routines had returned allocated buffers. These issues have all been fixed, so the API no longer returns allocated buffers.

3) Removed unnecessary xdas_release_filter_list function. This routine was only necessary because xdas_list_filters returned an allocated list of filter names in the form of an array of xdas_buffer_desc objects. The new method is to allow the caller to pass a buffer that can be formatted into a null-terminated array of filter names.

4) Added the XDAS_OUT_NOT_SPECIFIED outcome pseudo-code so that a value may be passed into xdas_put_event_info that indicates that the current value should not be changed. The original specification indicated that NULL (zero) should be passed in the outcome parameter to indicate this condition, but zero already indicates a successful outcome.

5) Removed the XDAS_C_NO_BUF definition, as it was only a confusing alias for NULL or zero passed in a parameter, or specified in the xdas_buffer_t fields of the xdas_audit_record_desc structure.

6) Made the minor_status code parameter on all API's optional. Since the specification states that callers will not want to do anything with this value except possibly print or log it, there's no need for it to be mandatory.

7) Removed OM_uint32 from the interface, as it's very difficult to create a portable interface with sized types, and generally unnecessary. Sized types are usually required in the implementation of wire interfaces, not in public API's. Within the implementation of a library, sized-types are relatively simple to access and consume, but extremely difficult in the interface, where you can only be sure of a few things in the compilation environment of public header files. This change also updates the XDAS standard to a 32-bit standard - that is, implementing platforms must have at least a 32-bit processor word size. This is a common base requirement of software standards today, as there are very few 8- or 16-bit word-size processors remaining (even in embedded systems), and none are capable of running even a simple implementation of XDAS. Those that wish to do so may wish to implement the submission API only, as this portion of the XDAS specification is not be negatively impacted by these type changes.

Define Documentation

#define OXDAS_MS_NET_BAD_SOCKET 5

Definition at line 471 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_CONN_ABORTED 6

Definition at line 472 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_CONN_REFUSED 11

Definition at line 477 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_CONN_RESET 7

Definition at line 473 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_GENERAL_ERROR 4

Definition at line 470 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_INIT_FAILED 3

Definition at line 469 of file xdas.h.

Referenced by xdas_library_init().

#define OXDAS_MS_NET_NOT_CONNECTED 8

Definition at line 474 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_SHUTDOWN 9

Definition at line 475 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NET_TIMEDOUT 10

Definition at line 476 of file xdas.h.

Referenced by xdas_map_network_error_to_minor().

#define OXDAS_MS_NO_ERROR 0

Definition at line 466 of file xdas.h.

#define OXDAS_MS_OUT_OF_MEMORY 2

Definition at line 468 of file xdas.h.

Referenced by ev_check(), ev_parse(), xdas_initialize_session(), xdas_open_audit_stream(), xdas_put_event_info(), xdas_req_rsp(), xdas_send_import_record(), xdas_send_record(), and xdas_start_record().

#define OXDAS_MS_PROTOCOL 12

Definition at line 478 of file xdas.h.

Referenced by xdasd_event_process(), and xdasd_net_dispatch().

#define OXDAS_MS_UNKNOWN_ERROR 1

Definition at line 467 of file xdas.h.

Referenced by ev_check(), ev_parse(), xdas_initialize_session(), xdas_put_event_info(), xdas_service_connect(), and xdas_start_record().

#define XDAS_ACT_ACTION 4

Definition at line 809 of file xdas.h.

#define XDAS_ACT_ALARM 2

Definition at line 808 of file xdas.h.

#define XDAS_ACT_LOG 1

Definition at line 807 of file xdas.h.

#define XDAS_AE_APPROVAL_RECEIVED 0x02000002

Definition at line 592 of file xdas.h.

#define XDAS_AE_APPROVAL_REQUESTED 0x02000003

Definition at line 593 of file xdas.h.

#define XDAS_AE_AUD_CONFIG 0x0100002B

Definition at line 586 of file xdas.h.

#define XDAS_AE_AUD_DS_CORR 0x0100002D

Definition at line 588 of file xdas.h.

Referenced by main().

#define XDAS_AE_AUD_DS_FULL 0x0100002C

Definition at line 587 of file xdas.h.

#define XDAS_AE_BACKUP_DATASTORE 0x01000029

Definition at line 584 of file xdas.h.

#define XDAS_AE_CREATE_ACCOUNT 0x01000001

Definition at line 544 of file xdas.h.

#define XDAS_AE_CREATE_DATA_ITEM 0x0100000B

Definition at line 554 of file xdas.h.

#define XDAS_AE_CREATE_DATA_ITEM_ASSOC 0x0100001F

Definition at line 574 of file xdas.h.

#define XDAS_AE_CREATE_PEER_ASSOC 0x01000019

Definition at line 568 of file xdas.h.

#define XDAS_AE_CREATE_ROLE 0x02000006

Definition at line 596 of file xdas.h.

#define XDAS_AE_CREATE_SESSION 0x01000007

Definition at line 550 of file xdas.h.

#define XDAS_AE_DELETE_ACCOUNT 0x01000002

Definition at line 545 of file xdas.h.

#define XDAS_AE_DELETE_DATA_ITEM 0x0100000C

Definition at line 555 of file xdas.h.

#define XDAS_AE_DELETE_ROLE 0x02000007

Definition at line 597 of file xdas.h.

#define XDAS_AE_DISABLE_ACCOUNT 0x01000003

Definition at line 546 of file xdas.h.

#define XDAS_AE_DISABLE_ROLE 0x02000008

Definition at line 598 of file xdas.h.

#define XDAS_AE_DISABLE_SERVICE 0x01000013

Definition at line 562 of file xdas.h.

#define XDAS_AE_ENABLE_ACCOUNT 0x01000004

Definition at line 547 of file xdas.h.

#define XDAS_AE_ENABLE_ROLE 0x02000009

Definition at line 599 of file xdas.h.

#define XDAS_AE_ENABLE_SERVICE 0x01000014

Definition at line 563 of file xdas.h.

#define XDAS_AE_INSTALL_SERVICE 0x0100000F

Definition at line 558 of file xdas.h.

#define XDAS_AE_INVOKE_SERVICE 0x01000015

Definition at line 564 of file xdas.h.

#define XDAS_AE_MODIFY_ACCOUNT 0x01000006

Definition at line 549 of file xdas.h.

#define XDAS_AE_MODIFY_ASSOC_CONTEXT 0x0100001C

Definition at line 571 of file xdas.h.

#define XDAS_AE_MODIFY_AUTH_TOKEN 0x02000001

Definition at line 591 of file xdas.h.

#define XDAS_AE_MODIFY_DATA_ITEM_ASSOC_CONTEXT 0x01000022

Definition at line 577 of file xdas.h.

#define XDAS_AE_MODIFY_DATA_ITEM_ATT 0x0100000E

Definition at line 557 of file xdas.h.

#define XDAS_AE_MODIFY_DATA_ITEM_CONTENTS 0x01000024

Definition at line 579 of file xdas.h.

#define XDAS_AE_MODIFY_PROCESS_CONTEXT 0x01000018

Definition at line 567 of file xdas.h.

#define XDAS_AE_MODIFY_ROLE 0x0200000B

Definition at line 601 of file xdas.h.

#define XDAS_AE_MODIFY_SERVICE_CONFIG 0x01000012

Definition at line 561 of file xdas.h.

#define XDAS_AE_MODIFY_SESSION 0x0100000A

Definition at line 553 of file xdas.h.

#define XDAS_AE_NOTIFICATION_SENT 0x02000005

Definition at line 595 of file xdas.h.

#define XDAS_AE_QUERY_ACCOUNT 0x01000005

Definition at line 548 of file xdas.h.

#define XDAS_AE_QUERY_ASSOC_CONTEXT 0x0100001B

Definition at line 570 of file xdas.h.

#define XDAS_AE_QUERY_DATA_ITEM_ASSOC_CONTEXT 0x01000021

Definition at line 576 of file xdas.h.

#define XDAS_AE_QUERY_DATA_ITEM_ATT 0x0100000D

Definition at line 556 of file xdas.h.

#define XDAS_AE_QUERY_DATA_ITEM_CONTENTS 0x01000023

Definition at line 578 of file xdas.h.

#define XDAS_AE_QUERY_PROCESS_CONTEXT 0x01000017

Definition at line 566 of file xdas.h.

#define XDAS_AE_QUERY_ROLE 0x0200000A

Definition at line 600 of file xdas.h.

#define XDAS_AE_QUERY_SERVICE_CONFIG 0x01000011

Definition at line 560 of file xdas.h.

#define XDAS_AE_QUERY_SESSION 0x01000009

Definition at line 552 of file xdas.h.

#define XDAS_AE_RECEIVE_DATA_VIA_ASSOC 0x0100001D

Definition at line 572 of file xdas.h.

#define XDAS_AE_RECOVER_DATASTORE 0x0100002A

Definition at line 585 of file xdas.h.

#define XDAS_AE_REMOVE_SERVICE 0x01000010

Definition at line 559 of file xdas.h.

#define XDAS_AE_REQUEST_ESCALATED 0x02000004

Definition at line 594 of file xdas.h.

#define XDAS_AE_RESOURCE_CORRUPT 0x01000028

Definition at line 583 of file xdas.h.

#define XDAS_AE_RESOURCE_EXHAUST 0x01000027

Definition at line 582 of file xdas.h.

#define XDAS_AE_SEND_DATA_VIA_ASSOC 0x0100001E

Definition at line 573 of file xdas.h.

#define XDAS_AE_SHUTDOWN_SYS 0x01000026

Definition at line 581 of file xdas.h.

#define XDAS_AE_START_SYS 0x01000025

Definition at line 580 of file xdas.h.

#define XDAS_AE_TERMINATE_DATA_ITEM_ASSOC 0x01000020

Definition at line 575 of file xdas.h.

#define XDAS_AE_TERMINATE_PEER_ASSOC 0x0100001A

Definition at line 569 of file xdas.h.

#define XDAS_AE_TERMINATE_SERVICE 0x01000016

Definition at line 565 of file xdas.h.

#define XDAS_AE_TERMINATE_SESSION 0x01000008

Definition at line 551 of file xdas.h.

#define XDAS_AEC_ACCOUNT_MANAGEMENT 0x01000001

Definition at line 633 of file xdas.h.

#define XDAS_AEC_AUDIT_SERVICE 0x01000009

Definition at line 641 of file xdas.h.

#define XDAS_AEC_DATA_ITEM_CONTENT_ACCESS 0x01000007

Definition at line 639 of file xdas.h.

#define XDAS_AEC_DATA_ITEM_MANAGEMENT 0x01000003

Definition at line 635 of file xdas.h.

#define XDAS_AEC_EXCEPTIONAL 0x01000008

Definition at line 640 of file xdas.h.

#define XDAS_AEC_PEER_ASSOC_MANAGEMENT 0x01000006

Definition at line 638 of file xdas.h.

#define XDAS_AEC_SERVICE_MANAGEMENT 0x01000004

Definition at line 636 of file xdas.h.

#define XDAS_AEC_SERVICE_UTILIZE 0x01000005

Definition at line 637 of file xdas.h.

#define XDAS_AEC_USER_SESSION 0x01000002

Definition at line 634 of file xdas.h.

#define XDAS_C_EXCLUDE 2

Definition at line 739 of file xdas.h.

Referenced by xdas_create_filter().

#define XDAS_C_IMPORT 2

Definition at line 731 of file xdas.h.

#define XDAS_C_INCLUDE 1

Definition at line 738 of file xdas.h.

Referenced by xdas_create_filter().

#define XDAS_C_SUBMIT 1

Definition at line 730 of file xdas.h.

#define XDAS_CALLING_ERROR ( e ) ((e) & 0xFFFF0000)

Definition at line 504 of file xdas.h.

#define XDAS_ERROR ( e ) ((e) ? 1 : 0)

Definition at line 505 of file xdas.h.

#define XDAS_EVENT_NUMBER 7

Definition at line 752 of file xdas.h.

#define XDAS_INT_AUTH_AUTH 15

Definition at line 760 of file xdas.h.

#define XDAS_INT_PRINC_IDENTITY 17

Definition at line 762 of file xdas.h.

#define XDAS_INT_PRINC_NAME 16

Definition at line 761 of file xdas.h.

#define XDAS_O_BT 7

Definition at line 781 of file xdas.h.

#define XDAS_O_EQ 1

Definition at line 775 of file xdas.h.

#define XDAS_O_GE 5

Definition at line 779 of file xdas.h.

#define XDAS_O_GT 3

Definition at line 777 of file xdas.h.

#define XDAS_O_LE 6

Definition at line 780 of file xdas.h.

#define XDAS_O_LT 4

Definition at line 778 of file xdas.h.

#define XDAS_O_NE 2

Definition at line 776 of file xdas.h.

#define XDAS_O_SS 8

Definition at line 782 of file xdas.h.

#define XDAS_ORG_AUTH_AUTH 12

Definition at line 757 of file xdas.h.

#define XDAS_ORG_LOC_ADD 10

Definition at line 755 of file xdas.h.

#define XDAS_ORG_LOC_NAME 9

Definition at line 754 of file xdas.h.

#define XDAS_ORG_PRINC_IDENTITY 14

Definition at line 759 of file xdas.h.

#define XDAS_ORG_PRINC_NAME 13

Definition at line 758 of file xdas.h.

#define XDAS_ORG_SERV_TYPE 11

Definition at line 756 of file xdas.h.

#define XDAS_OUT_ACTIONS_SET 0x00002000

Definition at line 686 of file xdas.h.

#define XDAS_OUT_ALREADY_DISABLED 0x00002001

Definition at line 694 of file xdas.h.

#define XDAS_OUT_ALREADY_ENABLED 0x00001001

Definition at line 693 of file xdas.h.

#define XDAS_OUT_BUSY 0x00008001

Definition at line 696 of file xdas.h.

#define XDAS_OUT_DENIAL 0x00000002

Definition at line 702 of file xdas.h.

Referenced by xdas_is_valid_outcome().

#define XDAS_OUT_DISABLED 0x00010001

Definition at line 697 of file xdas.h.

#define XDAS_OUT_ENTITY_EXISTS 0x00040001

Definition at line 699 of file xdas.h.

#define XDAS_OUT_ENTITY_NON_EXISTENT 0x00080001

Definition at line 700 of file xdas.h.

Referenced by main().

#define XDAS_OUT_FAILURE 0x00000001

Definition at line 688 of file xdas.h.

Referenced by xdas_is_valid_outcome().

#define XDAS_OUT_HARDWARE_FAILURE 0x00000401

Definition at line 691 of file xdas.h.

#define XDAS_OUT_INSUFFICIENT_PRIVILEGE 0x00000102

Definition at line 703 of file xdas.h.

#define XDAS_OUT_INVALID_CREDENTIALS 0x00000402

Definition at line 705 of file xdas.h.

#define XDAS_OUT_INVALID_IDENTITY 0x00000202

Definition at line 704 of file xdas.h.

#define XDAS_OUT_INVALID_INPUT 0x00020001

Definition at line 698 of file xdas.h.

#define XDAS_OUT_LOST_ASSOCIATION 0x00000801

Definition at line 692 of file xdas.h.

#define XDAS_OUT_NOT_SPECIFIED 0xFFFFFFFF

Definition at line 678 of file xdas.h.

Referenced by main(), xdas_commit_record(), xdas_put_event_info(), and xdas_start_record().

#define XDAS_OUT_PRESELECT_CRITERIA_SET 0x00000800

Definition at line 684 of file xdas.h.

#define XDAS_OUT_PRIV_GRANTED 0x00000200

Definition at line 682 of file xdas.h.

#define XDAS_OUT_PRIV_REVOKED 0x00000400

Definition at line 683 of file xdas.h.

#define XDAS_OUT_PRIV_USED 0x00000100

Definition at line 681 of file xdas.h.

#define XDAS_OUT_SERVICE_ERROR 0x00004001

Definition at line 695 of file xdas.h.

#define XDAS_OUT_SERVICE_FAILURE 0x00000201

Definition at line 690 of file xdas.h.

#define XDAS_OUT_SERVICE_UNAVAILABLE 0x00000101

Definition at line 689 of file xdas.h.

#define XDAS_OUT_SUCCESS 0x00000000

Definition at line 680 of file xdas.h.

Referenced by xdas_is_valid_outcome().

#define XDAS_OUT_THRESHOLDS_SET 0x00001000

Definition at line 685 of file xdas.h.

#define XDAS_OUTCOME 8

Definition at line 753 of file xdas.h.

#define XDAS_RECORD_VERSION "0"

XDAS record format version number - currently at 0.

The XDAS event record version field is populated with this value to indicate which version of the xdas record format is in use by a given record. This value is defined as a string for the sake of the implementation.

Definition at line 396 of file xdas.h.

Referenced by xdas_calc_max_record_len(), and xdas_format_record().

#define XDAS_ROUTINE_ERROR ( e ) ((e) & 0x0000FFFF)

Definition at line 503 of file xdas.h.

#define XDAS_S_AUTHORIZATION_FAILURE 1

#define XDAS_S_BUFF_TOO_SMALL 2

Definition at line 427 of file xdas.h.

#define XDAS_S_CALL_BAD_STRUCTURE (3 << 16)

#define XDAS_S_CALL_INACCESSIBLE_READ (1 << 16)

#define XDAS_S_CALL_INACCESSIBLE_WRITE (2 << 16)

Definition at line 491 of file xdas.h.

Referenced by xdas_initialize_session(), xdas_open_audit_stream(), and xdas_start_record().

#define XDAS_S_COMPLETE 0

Definition at line 425 of file xdas.h.

Referenced by ev_check(), ev_logger_append(), ev_parse(), xdas_discard_record(), xdas_initialize_session(), xdas_open_audit_stream(), xdas_put_event_info(), xdas_send_record(), xdas_start_record(), xdas_terminate_session(), xdas_timestamp_record(), and xdasd_event_check_and_submit().

#define XDAS_S_END 3

Definition at line 428 of file xdas.h.

#define XDAS_S_FAILURE 4

Definition at line 429 of file xdas.h.

Referenced by ev_check(), ev_parse(), xdas_initialize_session(), xdas_library_init(), xdas_open_audit_stream(), xdas_put_event_info(), xdas_req_rsp(), xdas_send_import_record(), xdas_send_record(), xdas_service_connect(), xdas_start_record(), xdasd_event_process(), and xdasd_net_dispatch().

#define XDAS_S_INCOMPLETE_RECORD 5

Definition at line 430 of file xdas.h.

Referenced by ev_parse(), and xdas_commit_record().

#define XDAS_S_INVALID_ACTION_LIST 6

Definition at line 431 of file xdas.h.

#define XDAS_S_INVALID_AUDIT_STREAM 7

Definition at line 432 of file xdas.h.

Referenced by xdas_close_audit_stream(), xdas_get_next(), xdas_open_audit_stream(), and xdas_rewind_audit_stream().

#define XDAS_S_INVALID_DAS_REF 8

#define XDAS_S_INVALID_EVENT_INFO 9

Definition at line 434 of file xdas.h.

#define XDAS_S_INVALID_EVENT_NO 10

Definition at line 435 of file xdas.h.

#define XDAS_S_INVALID_FILTER 11

Definition at line 436 of file xdas.h.

Referenced by xdas_create_filter(), xdas_delete_filter(), xdas_disable_filter(), xdas_enable_filter(), and xdas_get_filter().

#define XDAS_S_INVALID_FILTER_ACTION 28

Definition at line 453 of file xdas.h.

Referenced by xdas_create_filter().

#define XDAS_S_INVALID_FILTER_EXPR 12

Definition at line 437 of file xdas.h.

Referenced by xdas_create_filter().

#define XDAS_S_INVALID_FILTER_LIST 13

Definition at line 438 of file xdas.h.

Referenced by xdas_list_filters().

#define XDAS_S_INVALID_FILTER_TYPE 14

Definition at line 439 of file xdas.h.

Referenced by xdas_create_filter().

#define XDAS_S_INVALID_INITIATOR_INFO 15

Definition at line 440 of file xdas.h.

Referenced by xdas_put_event_info(), and xdas_start_record().

#define XDAS_S_INVALID_ORIG_INFO 16

Definition at line 441 of file xdas.h.

Referenced by xdas_initialize_session().

#define XDAS_S_INVALID_OUTCOME 17

Definition at line 442 of file xdas.h.

Referenced by xdas_put_event_info(), and xdas_start_record().

#define XDAS_S_INVALID_RECORD_DESCRIPTOR 18

Definition at line 443 of file xdas.h.

Referenced by xdas_commit_record(), xdas_discard_record(), xdas_put_event_info(), xdas_start_record(), and xdas_timestamp_record().

#define XDAS_S_INVALID_RECORD_NUMBER 19

Definition at line 444 of file xdas.h.

#define XDAS_S_INVALID_SECURITY_CONTEXT 20

Definition at line 445 of file xdas.h.

#define XDAS_S_INVALID_TARGET_INFO 21

Definition at line 446 of file xdas.h.

Referenced by xdas_put_event_info(), and xdas_start_record().

#define XDAS_S_NO_AUDIT 22

Definition at line 447 of file xdas.h.

Referenced by ev_check(), xdas_put_event_info(), xdas_start_record(), and xdasd_event_check_and_submit().

#define XDAS_S_NO_DECISION_YET 23

Definition at line 448 of file xdas.h.

Referenced by ev_check(), and xdasd_event_check_and_submit().

#define XDAS_S_NOT_SUPPORTED 27

Definition at line 452 of file xdas.h.

Referenced by xdas_close_audit_stream(), xdas_internal_create_filter(), xdas_internal_delete_filter(), xdas_internal_enable_filter(), xdas_internal_get_filter(), xdas_internal_get_next(), xdas_internal_list_filters(), xdas_internal_open_audit_stream(), xdas_internal_parse_record(), and xdas_internal_rewind_audit_stream().

#define XDAS_S_RECORD_SYNTAX_ERROR 24

Definition at line 449 of file xdas.h.

Referenced by xdas_internal_import_event_records().

#define XDAS_S_SERVICE_FAILURE 26

#define XDAS_S_STORAGE_FAILURE 25

Definition at line 450 of file xdas.h.

Referenced by ev_logger_append().

#define XDAS_TGT_AUTH_AUTH 21

Definition at line 766 of file xdas.h.

#define XDAS_TGT_LOC_ADD 19

Definition at line 764 of file xdas.h.

#define XDAS_TGT_LOC_NAME 18

Definition at line 763 of file xdas.h.

#define XDAS_TGT_PRINC_IDENTITY 23

Definition at line 768 of file xdas.h.

#define XDAS_TGT_PRINC_NAME 22

Definition at line 767 of file xdas.h.

#define XDAS_TGT_SERV_TYPE 20

Definition at line 765 of file xdas.h.

#define XDAS_TIME_OFFSET 2

Definition at line 747 of file xdas.h.

#define XDAS_TIME_SOURCE 5

Definition at line 750 of file xdas.h.

#define XDAS_TIME_TIME_ZONE 6

Definition at line 751 of file xdas.h.

#define XDAS_TIME_UNCERT_INDIC 4

Definition at line 749 of file xdas.h.

#define XDAS_TIME_UNCERT_INTER 3

Definition at line 748 of file xdas.h.

#define XDAS_VERSION 1

Definition at line 746 of file xdas.h.

Typedef Documentation

typedef void* xdas_audit_rec_desc_t

XDAS event record handle.

Definition at line 952 of file xdas.h.

typedef struct xdas_audit_record_desc_struct xdas_audit_record_desc

XDAS in-memory audit record structure.

Changes to the original OpenGroup XDAS specification:

1) Changed record_number, time_offset, time_uncertainty_interval, time_uncertainty_indicator, event_number and outcome fields to simple unsigned ints - see general notes.

2) Changed length field to size_t - see general notes.

3) According to the spec, time_offset (a uint32 sized quantity) is supposed to contain the number of milliseconds since the start of the epoch (Jan 1, 1970), but this is impossible as we've already gone well over 4 billion milliseconds since then. OpenXDAS stores seconds in this field rather than milliseconds.

4) Removed unnecessary "const" qualifier from the record_number field.

5) Removed service version field because that information is not stored in the record anywhere. The only version information found in an XDAS record is the record format version, which is not necessary, since the record has been completely parsed into this structure.

6) Removed unnecessary level of indirection from xdas_buffer_t fields.

It seems that the XDAS specification authors originally indended users to allocate xdas_buffer_desc objects to which parsed data would be copied. But this is not specified, just assumed from the context.

A much more efficient approach is to simply set the value member to point into the retrieved buffer data, and the size member to the number of bytes of character data in the field pointed to by the value member.

When used for input to an XDAS function, the length member may be optionally zero'd to indicate that the character data pointed to by the value member is zero-terminated.

When used for output, the parser will use the length member to indicate the length of the string pointed to by the value member. This allows the parser to maintain the pristine state of the wire buffer associated with the record by not having to over-write delimiters with zero-termination characters.

When using this structure to parse records retrieved with xdas_get_next, a caller should populate the desired xdas_buffer_t fields with the addresses of actual xdas_buffer_desc objects. Those fields set to zero will not be parsed and returned. This approach requires a bit more setup on the part of a caller, but provides the flexibility and potential speed increase of allowing only certain fields to be parsed and returned.

typedef struct xdas_audit_record_desc_struct * xdas_audit_record_t

typedef void* xdas_audit_ref_t

XDAS session handle.

Definition at line 944 of file xdas.h.

typedef void* xdas_audit_stream_t

XDAS audit stream handle.

Definition at line 948 of file xdas.h.

typedef struct xdas_buffer_desc_struct xdas_buffer_desc

XDAS UTF-8 content buffer descriptor.

Remarks:: If length is zero, then value is zero-terminated. If value is zero then the field is unused and length is ignored.

Changes to the original OpenGroup XDAS specification:

1) Replaced void * with char * on value field. Since buffer descriptors are always meant to point to constant UTF-8 character data it makes little sense to be so generic about the content type. Also, it's important to note that the original XDAS specification defined many of the functions as taking a const pointer to an xdas_buffer_t object, which did not do what was clearly intended - to protect the contents of the value field. A const xdas_buffer_t parameter only protected the address stored in the value field, not the contents of the value field. To protect the contents of the value field, the value field must be specified as "const" within the structure. We've chosen NOT to do this since the buffer only ever returns pointers to information in user specified buffers.

typedef struct xdas_buffer_desc_struct * xdas_buffer_t

Function Documentation

XDASXPC int XDASAPI xdas_close_audit_stream	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_stream_t *	audit_stream_ref
	)

Closes an XDAS audit stream.

The xdas_close_audit_stream function is a member of the XDAS Audit Read API, as well as the Basic XDAS specification conformance class.

The function closes the audit stream, previously opened for reading, specified by the audit_stream_ref handle. Once an audit stream is closed, that audit stream is no longer valid for use in any XDAS function call.

The caller must possess the XDAS_AUDIT_READ authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in,out]`	audit_stream_ref	- on entry, the address of the audit stream handle to be closed, obtained via a call to xdas_open_audit_stream. On exit, the value returned in this handle is zero.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_AUDIT_STREAM if the specified audit stream handle is not valid.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

Note:: An implementation may reclaim any storage associated with an audit stream when that audit stream is closed.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Removed "const" qualifier from the audit_stream_ref handle parameter. It is not constant in practice, as we'll be reassigning a value of zero to the handle from within the routine.

Definition at line 219 of file xdas_stub.c.

References fp_xdas_close_audit_stream, xdas_assert, XDAS_AUDIT_READ, XDAS_AUDIT_SERVICE, xdas_internal_close_audit_stream(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_AUDIT_STREAM, XDAS_S_INVALID_DAS_REF, XDAS_S_NOT_SUPPORTED, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), xdas_validate_session(), and xdas_validate_stream().

XDASXPC int XDASAPI xdas_commit_record	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_rec_desc_t *	audit_record_descriptor
	)

Write a completed audit record to the associated audit stream.

The xdas_commit_record function is a member of the XDAS Audit Event Service Client API, as well as the XDAS specification Event Submission API Option conformance class.

The function writes the audit record identified by audit_record_descriptor to the current audit stream controlled by the audit service and accessed by das_ref. The XDAS implementation adds the time information to the audit record unless a previous call to xdas_timestamp_record has been made using audit_record_descriptor. The caller must have the XDAS_AUDIT_SUBMIT authority.

If any of the event_number, outcome, initiator_information, target_information and event_information parameters to xdas_start_record and xdas_put_event_info have not been completed in at least one such call, even when component fields are empty, then this call shall return XDAS_S_INCOMPLETE_RECORD.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in,out]`	audit_record_descriptor	- on entry, the address of a handle to an audit record returned through a previous call to xdas_start_record. On successful completion `audit_record_descriptor` is no longer a valid reference to an audit record, and this parameter returns zero.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INCOMPLETE_RECORD if the audit record has not been fully populated by the caller.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_RECORD_DESCRIPTOR if the specified audit record descriptor is not valid.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

XDAS_S_SERVICE_FAILURE if there has been an audit service failure.

XDAS_S_STORAGE_FAILURE if the audit record cannot be written to stable storage.

Note:: An implementation may reclaim any storage associated with audit_record_descriptor when that audit_record_descriptor is closed.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Removed the "const" qualifier from the audit_record_descriptor handle parameter, as the parameter is not in fact constant in practice. The parameter returns a zero value on successful completion.

Definition at line 297 of file xdas_stub.c.

References xdas_record_tag::event_number, xdas_record_tag::evt_info, fp_xdas_commit_record, xdas_record_tag::int_info, xdas_record_tag::outcome, xdas_record_tag::tgt_info, xdas_record_tag::time_offset, xdas_assert, XDAS_AUDIT_SERVICE, XDAS_AUDIT_SUBMIT, xdas_internal_discard_record(), XDAS_OUT_NOT_SPECIFIED, XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INCOMPLETE_RECORD, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_RECORD_DESCRIPTOR, XDAS_S_SERVICE_FAILURE, xdas_send_record(), xdas_session_has_rights(), xdas_set_record_timestamp(), xdas_validate_record(), and xdas_validate_session().

Referenced by main().

XDASXPC int XDASAPI xdas_create_filter	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		const char *	name,
		unsigned	filter_type,
		const char *	filter_exp,
		const char *	filter_act
	)

Create a named audit filter.

The xdas_create_filter function is a member of the XDAS Audit Event Management API, as well as the XDAS specification Filter Management API Option conformance class.

The function creates a filter for the name specified. If a filter with the specified name already exists the call fails. On creation the filter is in a disabled state.

The caller must possess the XDAS_AUDIT_CONTROL authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	name	- the name of the filter.
`[in]`	filter_type	- the type of the filter. This may be either XDAS_C_SUBMIT or XDAS_C_IMPORT.
`[in]`	filter_exp	- the expression list which defines the criteria for detection of the event.
`[in]`	filter_act	- the list of actions to be taken when the event is submitted or imported.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_ACTION_LIST if the action list specified is not valid.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_FILTER if the filter name specified already exists or the name parameter is NULL.

XDAS_S_INVALID_FILTER_EXP if the filter expression supplied is not valid or the filter_exp parameter is NULL.

XDAS_S_INVALID_FILTER_TYPE if the filter type specified is not recognized.

XDAS_S_INVALID_FILTER_ACTION if the filter action specified is not recognized or the filter_act parameter is NULL.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Changed filter_type parameter to simple unsigned int - see general notes.

3) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

4) Changed the type of the name parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero- terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

5) Removed unnecessary "const" qualifier from the filter_type parameter.

6) Changed the type of the filter_exp parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero-terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

7) Changed the type of the filter_act parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero-terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

8) Added XDAS_S_INVALID_FILTER_ACTION as a possible error code returned if the filter action string is invalid (flags unrecognized, or parameter is NULL).

Definition at line 371 of file xdas_stub.c.

References fp_xdas_create_filter, xdas_assert, XDAS_AUDIT_CONTROL, XDAS_AUDIT_SERVICE, XDAS_C_EXCLUDE, XDAS_C_INCLUDE, xdas_internal_create_filter(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_FILTER, XDAS_S_INVALID_FILTER_ACTION, XDAS_S_INVALID_FILTER_EXPR, XDAS_S_INVALID_FILTER_TYPE, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_delete_filter	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		const char *	name
	)

Delete an audit filter by name.

The xdas_delete_filter function is a member of the XDAS Audit Event Management API, as well as the XDAS specification Filter Management API Option conformance class.

The function deletes the filter defined by name from the XDAS system. This may involve deleting copies of the filter from all agents managed via a particular instance of the XDAS interface. The function does not wait upon the successful deletion of all instances of the filter maintained by XDAS agents. The caller must possess the XDAS_AUDIT_CONTROL authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	name	- the name of the filter.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_FILTER if the filter name specified already exists.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Changed the type of the name parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero- terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

Definition at line 386 of file xdas_stub.c.

References fp_xdas_delete_filter, xdas_assert, XDAS_AUDIT_CONTROL, XDAS_AUDIT_SERVICE, xdas_internal_delete_filter(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_FILTER, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_disable_filter	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		const char *	name
	)

Disable an audit filter by name.

The xdas_disable_filter function is a member of the XDAS Audit Event Management API, as well as the XDAS specification Filter Management API Option conformance class.

The function disables the filter specified by name. It sets the state of the filter to disabled. If necessary the disabled state of the filter may require propagation to all XDAS agents managed by a particular instance of the XDAS Interface. The function does not wait upon the successful disabling of all instances of the filter maintained by XDAS agents. The caller must possess the XDAS_AUDIT_CONTROL authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	name	- the name of the filter.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_FILTER if the filter name specified already exists.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Changed the type of the name parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero- terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

Definition at line 397 of file xdas_stub.c.

References fp_xdas_disable_filter, xdas_assert, XDAS_AUDIT_CONTROL, XDAS_AUDIT_SERVICE, xdas_internal_enable_filter(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_FILTER, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_discard_record	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_rec_desc_t *	audit_record_descriptor
	)

Discard a previously created audit record.

The xdas_discard_record function is a member of the XDAS Audit Event Service Client API, as well as the XDAS specification Event Submission API Option conformance class.

The function clears the buffer specified by audit_record_descriptor and releases the memory used by it. The caller must have the XDAS_AUDIT_SUBMIT authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	audit_record_descriptor	- a handle to an audit record returned through a previous call to xdas_start_record. On successful completion `audit_record_descriptor` is no longer a valid reference to an audit record.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_RECORD_DESCRIPTOR if the specified audit record descriptor is not valid.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Note:: An implementation may reclaim any storage associated with audit_record_descriptor when that audit_record_descriptor is closed.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Removed the "const" qualifier from the audit_record_descriptor handle parameter. In practice, this parameter is not constant, as it returns a zero value.

Definition at line 309 of file xdas_stub.c.

References fp_xdas_discard_record, xdas_assert, XDAS_AUDIT_SERVICE, XDAS_AUDIT_SUBMIT, xdas_internal_discard_record(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_COMPLETE, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_RECORD_DESCRIPTOR, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), xdas_validate_record(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_enable_filter	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		const char *	name
	)

Enable an audit filter by name.

The xdas_enable_filter function is a member of the XDAS Audit Event Management API, as well as the XDAS specification Filter Management API Option conformance class.

The function enables the filter corresponding to the name specified. If necessary the enabled state of the filter may require propagation to all XDAS agents managed by a particular instance of the XDAS Interface. The function does not wait upon the successful enabling of all instances of the filter maintained by XDAS agents. The caller must possess the XDAS_AUDIT_CONTROL authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	name	- the name of the filter.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_FILTER if the filter name specified already exists.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Changed the type of the name parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero- terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

Definition at line 408 of file xdas_stub.c.

References fp_xdas_enable_filter, xdas_assert, XDAS_AUDIT_CONTROL, XDAS_AUDIT_SERVICE, xdas_internal_enable_filter(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_FILTER, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_get_filter	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		const char *	name,
		unsigned *	filter_type,
		xdas_buffer_t	filter_exp,
		xdas_buffer_t	filter_act,
		unsigned *	filter_status
	)

Get an audit filter by name.

The xdas_get_filter function is a member of the XDAS Audit Event Management API, as well as the XDAS specification Filter Management API Option conformance class.

The function returns the components of the filter referred to by name. The caller must possess the XDAS_AUDIT_CONTROL authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	name	- the name of the filter.
`[out]`	filter_type	- (optional) the address of storage for the type of the filter. This may either be XDAS_C_SUBMIT or XDAS_C_IMPORT. If this value is not desired, pass zero.
`[out]`	filter_exp	- (optional) a buffer descriptor in which to return the contents of the filter expression that determines the events to be selected by this filter. If this value is not desired, pass zero.
`[out]`	filter_act	- (optional) a buffer descriptor in which to return the contents of the filter action list that contains the actions to be carried out for events selected by this filter. If this value is not desired, pass zero.
`[out]`	filter_status	- (optional) the address of storage for the enabled or disabled state of the filter. If the filter is enabled a boolean value of true (1) is returned, otherwise a boolean value of false (0) is returned. If this value is not desired, pass zero.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_FILTER if the filter name specified does not exist or is NULL.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Changed filter_type and filter_status parameters to simple unsigned ints - see general notes.

3) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

4) Changed the type of the name parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero- terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

5) Removed the unnecessary level of indirection from the filter_exp parameter.

6) Removed the unnecessary level of indirection from the filter_act parameter.

7) Changed the return value in filter_status to be boolean instead of the specified reverse-boolean logic.

8) Made all output parameters optional so that only desired information may be returned.

Definition at line 419 of file xdas_stub.c.

References fp_xdas_get_filter, xdas_assert, XDAS_AUDIT_CONTROL, XDAS_AUDIT_SERVICE, xdas_internal_get_filter(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_FILTER, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_get_next	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_stream_t	audit_stream_ref,
		unsigned	max_records,
		xdas_buffer_t	audit_record_buffer,
		unsigned *	no_of_records
	)

Fill an output buffer with the next set of records in an audit stream.

The xdas_get_next function is a member of the XDAS Audit Read API, as well as the Basic XDAS specification conformance class.

The function copies up to max_records complete records from the audit stream accessed by audit_stream_ref into the caller-specified buffer, audit_record_buffer. The actual number of records retrieved by the function is returned in no_of_records. If the function successfully reads a record or records from the audit stream, the cursor associated with the audit stream referred to by audit_stream_ref will be advanced to the next unread record in the audit stream. If the call is unsuccessful, the position of the cursor is not changed.

The caller must have the XDAS_AUDIT_READ authority.

If there are no more available audit records, no_of_records is set to 0 and the function returns XDAS_S_END. If the size of audit_record_buffer specified by the caller is too small to hold a single audit record, no_of_records is set to 0 and the function returns XDAS_S_BUFF_TOO_SMALL.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	audit_stream_ref	- the associated audit stream handle, obtained through a previous call to xdas_open_audit_stream.
`[in]`	max_records	- specifies the maximum number of records to be returned in `audit_record_buffer`. If `max_records` is zero then the buffer is filled to capacity.
`[out]`	audit_record_buffer	- buffer to which audit records are to be copied.
`[out]`	no_of_records	- returns the number of records returned in `audit_record_buffer`.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_BUFF_TOO_SMALL if the buffer specified by the caller is not large enough to return a single record.

XDAS_S_END if the end of the audit stream has been reached.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_AUDIT_STREAM if the specified audit stream handle is not valid.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Changed max_records and no_of_records parameters to unsigned ints

see general notes.

3) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

4) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the audit_stream_ref handle parameter.

5) Removed the unecessary "const" qualifier from the integer max_records parameter.

6) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the audit_record_buffer parameter.

7) Added the ability to simply return as many records as will fit in the buffer by passing zero for max_records.

Definition at line 231 of file xdas_stub.c.

References fp_xdas_get_next, xdas_assert, XDAS_AUDIT_READ, XDAS_AUDIT_SERVICE, xdas_internal_get_next(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_AUDIT_STREAM, XDAS_S_INVALID_DAS_REF, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), xdas_validate_session(), and xdas_validate_stream().

XDASXPC int XDASAPI xdas_import_event_records	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_buffer_t	audit_record_buffer,
		size_t *	position_in_buffer
	)

Import event records from an external service into the XDAS common format.

The xdas_import_event_records function is a member of the XDAS Audit Log Import API, as well as XDAS specification Import API Option conformance class.

The function allows a caller to import audit event records in the XDAS format directly to the XDAS service. The caller places one or more complete audit event records into the buffer referred to by audit_record_buffer from which they are copied and integrated into the XDAS audit stream. The function reads audit records until the start of a next record is not found. The implementation may select the records that are actually imported based upon some selection criteria. The caller is not advised of the disposition of the audit records it submits.

Records specified in audit_record_buffer may be placed end-to-end with no intervening space or separation characters, however this routine will parse records starting with the "HDR" tag and ending with the "END" tag, so intervening characters, or white space are simply ignored.

The caller must possess the XDAS_AUDIT_IMPORT authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	audit_record_buffer	- a pointer to a buffer containing the properly formatted sequence of audit records to be imported.
`[out]`	position_in_buffer	- if a syntax error is detected during the import process, the zero-based buffer position at which the import failed is returned in this parameter.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the audit_record_buffer parameter.

Definition at line 284 of file xdas_stub.c.

References fp_xdas_import_event_records, xdas_assert, XDAS_AUDIT_IMPORT, XDAS_AUDIT_SERVICE, xdas_internal_import_event_records(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

Referenced by main().

XDASXPC int XDASAPI xdas_initialize_session	(	int *	minor_status,
		const char *	org_info,
		xdas_audit_ref_t *	das_ref
	)

Initialize an XDAS session for use within the process.

The xdas_initialize_session function is a member of the XDAS General Audit Service API, as well as the Basic XDAS specification conformance class.

The function initiates a session between the caller identified by org_info and the distributed audit service. The org_info data is inserted by the implementation into every audit record submitted by the caller via subsequent calls to XDAS functions within the XDAS session. Validates the security context implicit in the caller's process address space to ensure that the caller is authorized to use the XDAS service.

If successful, returns das_ref, a handle to the XDAS server.

The use of this function must itself be audited by the XDAS service.

The caller must have the XDAS_AUDIT_SERVICE authority.

All callers must initiate a session with the XDAS before they can use any of the services it provides. The initialization of the session supports the mutual authentication of the audit client and audit service components and establishes the audit client�s XDAS authorities. The caller is returned a handle to the XDAS service which is then used for all XDAS API functions. On completion, the caller must terminate the XDAS session. The behaviour if a client dies or exits without calling terminate session is implementation defined. An implementation may take specific action to try and detect and terminate such sessions itself to address any potential denial of service risks.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	org_info	- specifies the originator information in XDAS, colon-separated text field format.
`[out]`	das_ref	- returns the XDAS session handle.

Returns:

XDAS_S_COMPLETE on successful completion.

XDAS_S_AUTHORIZATION_FAILURE if the caller is not authorized to initialize an XDAS session.

XDAS_S_FAILURE if an implementation specific error or failure has occurred.

XDAS_S_INVALID_ORIG_INFO if the originator information supplied has a syntax error.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed originally specified security context parameter. The format of this data passed in this parameter was implementation defined, even though it was passed as an opaque parameter. This leads to portability issues in the caller's interface (API). Also, the security context can easily be obtained from within the implementation by calling get{u/g}id for Unix platforms, or GetSecurityToken from Windows. Membership in a special group can define who has the appropriate access level for a given operation. This may be seen as imposing a fair amount on the installation, but it can also be said that passing implementation-defined and platform-specific security information in through the API is not secure.

3) Passing originator info as a string, rather than as a buffer descriptor. This information is much easier to format as a string, and internal implementations would be unwise to not allocate their own copy of the data anyway.

Definition at line 190 of file xdas_stub.c.

References BAD_SOCKET, fp_xdas_initialize_session, load_xdas_client(), malloc, xdas_session_tag::org_info, OXDAS_MS_OUT_OF_MEMORY, OXDAS_MS_UNKNOWN_ERROR, xdas_session_tag::s, xdas_session_tag::signature, xdas_assert, XDAS_AUDIT_SERVICE, xdas_elemcount, xdas_internal_terminate_session(), xdas_library_init(), xdas_parse_info(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_CALL_INACCESSIBLE_WRITE, XDAS_S_COMPLETE, XDAS_S_FAILURE, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_ORIG_INFO, XDAS_S_SERVICE_FAILURE, xdas_service_connect(), xdas_session_has_rights(), XDAS_SESSION_SIG, xdas_set_session_rights(), and xdas_set_time_info().

Referenced by main().

XDASXPC int XDASAPI xdas_list_filters	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		char **	filter_name_list,
		size_t *	buffer_size
	)

Return a list of all defined audit filter names.

The xdas_list_filters function is a member of the XDAS Audit Event Management API, as well as the XDAS specification Filter Management API Option conformance class.

The function yields a zero-terminated array of pointers to filter names. The caller must possess the XDAS_AUDIT_CONTROL authority.

The memory for holding the array of pointers and the name filter buffers is allocated by the caller and passed in the filter_name_list parameter. If the buffer specified in this pointer is insufficient, as specified in the buffer_size parameter on input, the function will return the required buffer size in buffer_size. The caller should reallocate the buffer and call this routine again.

This routine will fill the buffer to capacity regardless of whether there is sufficient space or not for all filter names. However, an effective way to manage this function call is to call it twice, first with a null filter_name_list buffer and a valid buffer_size parameter containing zero, and then again with a filter_name_list buffer allocated to the size specified in buffer_size on return from the first call.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[out]`	filter_name_list	- the address of raw storage in which the filter name list should be returned, formatted as a zero-terminated list of names. This buffer will contain both the names and an array of pointers to the names. The caller may simply free the buffer when done if it was allocated originally on the heap.
`[in,out]`	buffer_size	- on entry, contains the size in bytes of the `filter_name_list` buffer. Returns the number of bytes consumed or required for the complete name list.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_FILTER_LIST if the filter name list buffer is NULL, but the size is NOT zero.

XDAS_S_BUFF_TOO_SMALL if the filter_name_list buffer is too small to return all of the available filter names.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Note:: The proper use of this function is not exactly obvious. The filter_name_list parameter actually points to a raw buffer of bytes on entry. On return, this buffer may be interpreted as its true type - a zero-terminated array of character pointers. The space in this buffer that follows the array is used to return the actual string data. The pointers in the pointer array refer to the space at the end of the buffer on return.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Changed the type of the filter_name_list parameter from xdas_buffer_t ** to char ** as this information is better specified in simple zero-terminated array of strings.

4) Changed the calling paradigm from one of function-allocated buffer space to caller allocated buffer space. The caller is expected to pass the initial size of the filter_name_list buffer in the new buffer_size parameter, and then examine buffer_size on return to determine the required amount of space to retrieve all filter names. This alleviates the need to have "resource release" functions. The function also returns a new return value XDAS_S_BUFF_TOO_SMALL to indicate that the filter_name_list buffer is insufficient to hold all filter names.

5) Added XDAS_S_INVALID_FILTER_LIST as a valid return value for an invalid combination of filter_name_list buffer pointer and buffer_size parameters.

Definition at line 435 of file xdas_stub.c.

References fp_xdas_list_filters, xdas_assert, XDAS_AUDIT_CONTROL, XDAS_AUDIT_SERVICE, xdas_internal_list_filters(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_FILTER_LIST, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_open_audit_stream	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_stream_t *	audit_stream_ref
	)

Opens an XDAS audit stream and associates it with an XDAS session.

The xdas_open_audit_stream function is a member of the XDAS Audit Read API, as well as the Basic XDAS specification conformance class.

The function opens the audit stream for reading and returns a handle to the audit stream in audit_stream_ref. A caller may obtain more than one handle to the audit stream, each of which is independent of any other handles. The caller must possess the XDAS_AUDIT_READ authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the XDAS session handle to be associated with the new audit stream, obtained through a previous call to xdas_initialize_session.
`[out]`	audit_stream_ref	- returns the new audit stream handle value.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

Note:: IMPORTANT: The xdas_open_audit_stream function is used to open streams for read-only access. An audit stream is not necessary for event submission.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Removed unnecessary level of indirection from the audit_stream_ref parameter.

Definition at line 246 of file xdas_stub.c.

References fp_xdas_open_audit_stream, malloc, OXDAS_MS_OUT_OF_MEMORY, xdas_stream_tag::signature, xdas_assert, XDAS_AUDIT_READ, XDAS_AUDIT_SERVICE, xdas_internal_close_audit_stream(), xdas_internal_open_audit_stream(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_CALL_INACCESSIBLE_WRITE, XDAS_S_COMPLETE, XDAS_S_FAILURE, XDAS_S_INVALID_AUDIT_STREAM, XDAS_S_INVALID_DAS_REF, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), XDAS_STREAM_SIG, and xdas_validate_session().

XDASXPC int XDASAPI xdas_parse_record	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_buffer_t	audit_record_buffer,
		unsigned	record_number,
		xdas_audit_record_t	audit_record
	)

Parse a specified XDAS record from an XDAS record buffer.

The xdas_parse_record function is a member of the XDAS Audit Read API, as well as the Basic XDAS specification conformance class.

The function parses and decomposes record number record_number in audit_record_buffer filled with a number of records by a previous call to xdas_get_next. Records are extracted from audit_record_buffer by starting with record number 0 and iterating through one less than the number of records returned by xdas_get_next. If record_number does not match a record within audit_record_buffer then XDAS_S_INVALID_RECORD_NUMBER is returned.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	audit_record_buffer	- a pointer to a buffer containing the audit records to be parsed, filled by a previous call to xdas_get_next.
`[in]`	record_number	- indicates which record should be parsed and returned in `audit_record`. The first record number is zero.
`[out]`	audit_record	- the audit record structure to be populated with buffer record information.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_EVENT_NO if the specified record number is not valid.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Changed record_number parameter to unsigned int type - see general notes.

3) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

4) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the audit_record_buffer parameter.

5) Changed the type of the audit_record_buffer parameter from xdas_audit_desc_t to xdas_buffer_t. This parameter is supposed to contain buffer information returned by xdas_get_next. This was clearly a mistake by the XDAS specification authors.

6) Removed unnecessary "const" qualifier from integer record_number parameter.

7) Removed unnecessary level of indirection from the audit_record parameter.

Definition at line 258 of file xdas_stub.c.

References fp_xdas_parse_record, xdas_assert, XDAS_AUDIT_READ, XDAS_AUDIT_SERVICE, xdas_internal_parse_record(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_DAS_REF, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), and xdas_validate_session().

XDASXPC int XDASAPI xdas_put_event_info	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_rec_desc_t *	audit_record_descriptor,
		unsigned	event_number,
		unsigned	outcome,
		const char *	initiator_information,
		const char *	target_information,
		const char *	event_information
	)

Add specific event information to an audit record.

The xdas_put_event_info function is a member of the XDAS Audit Event Service Client API, as well as the XDAS specification Event Submission API Option conformance class.

The function adds event information to an audit record or overwrites existing information. If the combination of information submitted and already present in the audit record referred to by audit_record_descriptor is insufficient to evaluate applicable preselection criteria, the function returns XDAS_S_NO_DECISION_YET to the caller. If there is sufficient information for evaluation of applicable pre-selection checks the XDAS_S_COMPLETE or XDAS_S_NO_AUDIT are returned to the caller. Multiple calls to xdas_put_event_info may be made. For any individual parameter, information supplied in this call will overwrite any previous information supplied.

Although several parameters are optional in this call, a caller shall have populated all the parameters, even when empty, in one or more sequences of calls to xdas_start_record and xdas_put_event_info before a call to xdas_commit_record shall be successful.

The caller must have the XDAS_AUDIT_SUBMIT authority.

If successful, the function returns XDAS_S_COMPLETE, XDAS_S_NO_DECISION_YET or XDAS_S_NO_AUDIT. If XDAS_S_NO_AUDIT is returned, then audit_record_descriptor is no longer a valid reference to an audit record.

If XDAS_S_NO_DECISION_YET is returned, then the caller should continue to construct the audit record by subsequent calls to xdas_put_event_info.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	audit_record_descriptor	- a handle to an audit record returned through a previous call to xdas_start_record.
`[in]`	event_number	- (optional) the event number of the detected event. If specified as a zero value then the event number currently associated with `audit_record_descriptor` is unchanged. Otherwise `event_number` overwrites the current value. Only event numbers configured as registered by the implementation shall be valid. Any other event number shall result in the return of XDAS_S_INVALID_EVENT_NO.
`[in]`	outcome	- (optional) the outcome of the event determined by the caller. If specified as XDAS_OUT_NOT_SPECIFIED (0xFFFFFFFF) then the outcome code currently associated with audit_record_descriptor is unchanged by this call. Otherwise `outcome` overwrites the current value. Only the outcome codes listed in Table 6-7 of the XDAS specification are valid.
`[in]`	initiator_information	- (optional) the information describing the initiator in the format required by the XDAS common audit format. If specified as NULL the current initiator information associated with `audit_record_descriptor` is unchanged by this call. Otherwise the contents of `initiator_information` overwrite the current value associated with `audit_record_descriptor`.
`[in]`	target_information	- (optional) the information on the target of the event in the format required by the XDAS common audit format. If specified as NULL the current target information associated with the `audit_record_descriptor` supplied is unchanged by this call. Otherwise the contents of `target_information` overwrite the current value associated with `audit_record_descriptor`.
`[in]`	event_information	- (optional) the event-specific information in common separated, name '=' value pairs that is to be added to the audit record specified by `audit_record_descriptor`. If specified as NULL the current event specific information associated with `audit_record_descriptor` is unchanged by this call. Otherwise the contents of `event_information` overwrite the current value associated with `audit_record_descriptor`.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

XDAS_S_INVALID_EVENT_INFO if the event specific information given is not valid or not formatted correctly.

XDAS_S_INVALID_EVENT_NO if the event number specified is not valid.

XDAS_S_INVALID_INITIATOR_INFO if the intiator information given has a syntax error.

XDAS_S_INVALID_OUTCOME if the outcome supplied is not valid.

XDAS_S_INVALID_RECORD_DESCRIPTOR if the specified audit record descriptor is not valid.

XDAS_S_INVALID_TARGET_INFO if the target information given has a syntax error.

XDAS_S_NO_AUDIT if the specified event does not need to be audited.

XDAS_S_NO_DECISION_YET if the audit service has insufficient information to decide if the event requires auditing.

XDAS_S_NOT_SUPPORTED if the called function is not supported by this implementation.

Note:: An implementation may reclaim any storage associated with the audit record descriptor when XDAS_S_NO_AUDIT is returned.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Changed event_number and outcome parametera to simple unsigned ints

see general notes.

3) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

4) Removed the "const" qualifier from the audit_record_descriptor handle parameter. This parameter is not really const, as the function could close the handle and return the handle value as zero.

5) Removed unnecessary "const" qualifier from the event_number parameter.

6) Removed unnecessary "const" qualifier from the outcome parameter.

7) Changed the type of the initiator_information parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero-terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

8) Changed the type of the target_information parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero-terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

9) Changed the type of the event_information parameter from const xdas_buffer_t * to const char * as this information is better specified in simple zero-terminated string format. Also note that both the "const" qualifier and the extra level of indirection on the original xdas_buffer_t type were unnecessary.

Todo:: Validate event_information - return XDAS_S_INVALID_EVENT_INFO.

Todo:: Do some sort of string array comparison here.

Todo:: Do some sort of string array comparison here.

Definition at line 321 of file xdas_stub.c.

References xdas_record_tag::event_number, xdas_record_tag::evt_info, xdas_record_tag::fmt_cache_dirty, fp_xdas_put_event_info, free, xdas_record_tag::int_info, xdas_record_tag::last_status, xdas_record_tag::outcome, OXDAS_MS_OUT_OF_MEMORY, OXDAS_MS_UNKNOWN_ERROR, strdup(), xdas_record_tag::tgt_info, xdas_assert, XDAS_AUDIT_SERVICE, XDAS_AUDIT_SUBMIT, xdas_elemcount, xdas_internal_discard_record(), xdas_is_valid_outcome(), XDAS_OUT_NOT_SPECIFIED, xdas_parse_info(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_COMPLETE, XDAS_S_FAILURE, XDAS_S_INVALID_DAS_REF, XDAS_S_INVALID_INITIATOR_INFO, XDAS_S_INVALID_OUTCOME, XDAS_S_INVALID_RECORD_DESCRIPTOR, XDAS_S_INVALID_TARGET_INFO, XDAS_S_NO_AUDIT, XDAS_S_SERVICE_FAILURE, xdas_send_record(), xdas_session_has_rights(), xdas_validate_record(), and xdas_validate_session().

Referenced by main().

XDASXPC int XDASAPI xdas_rewind_audit_stream	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_stream_t	audit_stream_ref
	)

Rewind an audit stream read pointer.

The xdas_rewind_audit_stream function is a member of the XDAS Audit Read API, as well as the Basic XDAS specification conformance class.

The function rewinds the audit stream referred to by xdas_stream_ref so that the read cursor associated with the xdas_stream_ref points to the first record in the audit stream. The caller must possess the XDAS_AUDIT_READ authority.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[in]`	audit_stream_ref	- the audit stream handle to be rewound.

Returns:

XDAS_S_COMPLETE on success.

XDAS_S_AUTHORIZATION_FAILURE if the caller does not possess the required authority.

XDAS_S_FAILURE if an implementation-specific error or failure occurred.

XDAS_S_INVALID_AUDIT_STREAM if the specified audit stream handle is not valid.

XDAS_S_INVALID_DAS_REF if the audit service handle supplied does not represent a valid audit service session.

Changes to the original OpenGroup XDAS specification:

1) Changed return value and minor_status parameter types to simple ints

see general notes.

2) Removed unnecessary level of indirection and the unnecessary "const" qualifier from the das_ref handle parameter.

3) Removed unnecessary level of indirection from the audit_stream_ref handle parameter.

Definition at line 272 of file xdas_stub.c.

References fp_xdas_rewind_audit_stream, xdas_assert, XDAS_AUDIT_READ, XDAS_AUDIT_SERVICE, xdas_internal_rewind_audit_stream(), XDAS_S_AUTHORIZATION_FAILURE, XDAS_S_CALL_BAD_STRUCTURE, XDAS_S_CALL_INACCESSIBLE_READ, XDAS_S_INVALID_AUDIT_STREAM, XDAS_S_INVALID_DAS_REF, XDAS_S_SERVICE_FAILURE, xdas_session_has_rights(), xdas_validate_session(), and xdas_validate_stream().

XDASXPC int XDASAPI xdas_start_record	(	int *	minor_status,
		xdas_audit_ref_t	das_ref,
		xdas_audit_rec_desc_t *	audit_record_descriptor,
		unsigned	event_number,
		unsigned	outcome,
		const char *	initiator_information,
		const char *	target_information,
		const char *	event_information
	)

Creates a new event record object.

The xdas_start_record function is a member of the XDAS Audit Event Service Client API, as well as the XDAS specification Event Submission API Option conformance class.

The function returns the xdas_audit_rec_desc handle of the audit record to the caller. If the optional parameters are not specified in the call, then the audit record is initialized, but requires full population by subsequent calls to xdas_put_event_info.

If the optional parameters are specified, the function determines whether a specified event should be audited, given the event_number, outcome and initiator_information supplied. If the event should be audited a valid xdas_audit_rec_desc handle is returned to the caller. If the audit event does not require auditing then audit_record_descriptor is returned as NULL. The caller must have the XDAS_AUDIT_SUBMIT authority.

Although several parameters are optional in this call, a caller shall have populated all the parameters, even when empty, in one or more sequences of calls to this function and xdas_put_event_info before a call to xdas_commit_record shall be successful.

Parameters:

`[out]`	minor_status	- (optional) return storage for an implementation- specific minor status code, if the return value is XDAS_S_FAILURE.
`[in]`	das_ref	- the associated XDAS session handle, obtained through a previous call to xdas_initialize_session.
`[out]`	audit_record_descriptor	- returns a handle to an audit record as defined by the optional input parameters. If the event does not need to be audited (based on filtering), zero is returned.
`[in]`	event_number	- (optional) the event number of the detected event. Only event numbers configured as registered by the implementation shall be valid. Any other event number shall result in the return of XDAS_S_INVALID_EVENT_NO. Use zero for not specified.
`[in]`	outcome	- (optional) the outcome of the event determined by the caller. Only the outcome codes listed in Table 6-7 of the XDAS specification are valid. Use XDAS_OUT_NOT_SPECIFIED for not specified.
`[in]`	initiator_information	- (optional) the information describing the initiator in the format required by the XDAS common audit format. Use NULL (zero) for not specified.
`[in]`	target_information	- (optional) information on the target of the event in the format required by the XDAS common audit format. Use NULL (zero) for not specified.
`[in]`	event_information	- (optional) information specific to the event in common separated, name '=' value pairs. Use NULL (zero) for not specified.