## DCE Audit Service Concepts

This topic briefly describes the DCE Audit Service concepts that are relevant to DCE application programming.

Audit Clients
All RPC-based servers, such as DCE servers and user-written application servers, are potential audit clients. The DCE Security Service, DTS, and the DCE Audit Service itself are auditable. That is, code points (discussed below) are already in place on these services.

The audit daemon can also audit itself.

Code Point
A code point is a location in the application server program where DCE audit APIs are used. Code points generally correspond to operations or functions offered by the application server for which audit is required. For example, if a bank server offers the cash withdrawal function acct_withdraw( ), this function may be deemed to be an auditable event and be designated as a code point.

As mentioned previously, code points are already in place in the DCE Security Service, DTS, and DCE Audit Service. Code points and their associated events for the DCE Security Service are documented in the sec_audit_events(5sec) reference page. Code points and their associated events for the DTS are documented in the dts_audit_events(5sec) reference page. Code points and their associated events for the DCE Audit Service are documented in the aud_audit_events(5sec) reference page.

Events
An audit event is any event that an audit client wishes to record. Generally, audit events involve the integrity of the system. For example, when a client withdraws cash from his bank account, this can be an audit event.

An audit event is associated with a code point in the application server code.

The terms audit event, event, and auditable event are used interchangeably in this guide.

Event Names and Event Numbers
Each event has a symbolic name as well as a 32-bit number assigned to it. Symbolic names are used only for documentation in identifying audit events. In creating event classes, the administrator uses the event numbers associated with these events.

Event numbers are 32-bit integers. Each event number is a tuple made up of a set-id and the event-id. The set-id corresponds to a set of event numbers and is assigned by OSF to an organization or vendor. The event-id identifies an event within the set of events. The organization or vendor manages the issuance of the event ID numbers to generate an event number.

Event numbers must be consecutive. That is, within a range of event numbers, no gaps in the consecutive order of the numbers are allowed.

The structure and administration of event numbers can be likened to the structure and administration of IP addresses. Recall that an IP address is a tuple of a network ID (analogous to the set-id) and a host ID (analogous to the event-id). The format and administration of event numbers are also analogous to IP addresses, as will be discussed in the next topics.

Event Number Formats
Events numbers follow one of five formats (A to E), depending on the number of audit events in the organization. The format of an event number can be determined from its four high-order bits.

Format A can be used by large organizations (such as OSF or major DCE vendors) that need more than 16 bits for the event-id. This format allocates 7 bits to the set-id and 24 bits to the event-id. Format A event numbers with zero (0) as its set-id are assigned to OSF. That is, all event numbers used by OSF have a zero in the most significant byte.

Format B can be used by intermediate-sized organizations that need 8 to 16 bits for the event-id.

Format C can be used by small organizations that need less than 8 bits for the event-id.

Format D is not administered by OSF and can be used freely within the cell. These event numbers may not be unique across cells and should not be used by application servers that are installed in more than one cell.

Format E is reserved for future use.

The event number formats are illustrated in the following figure.

Event Number Formats

Sample Event Numbers for DCE Servers
Following are examples of event numbers in the security and time servers, as defined in a header file used by the security server and time server programs, respectively.

/* Event numbers 0x00000100 to 0x000001FF are assigned to the

security server. */

#define AS_Request 0x00000100

#define TGS_TicketReq 0x00000101

#define TGS_RenewReq 0x00000102

#define TGS_ValidateReq 0x00000103

...

/* Event numbers 0x00000200 to 0x000002FF are

assigned to the time server. */

#define CNTRL_Create 0x00000200

#define CNTRL_Delete 0x00000201

#define CNTRL_Enable 0x00000202

#define CNTRL_Disable 0x00000203

...

Sample Event Numbers for Application Servers
The following is an example of the event numbers in a banking server application, as defined in the application's header file.

#define evt_vn_bank_server_acct_open 0x01000000

#define evt_vn_bank_server_acct_close 0x01000001

#define evt_vn_bank_server_acct_withdraw 0x01000002

#define evt_vn_bank_server_acct_deposit 0x01000003

#define evt_vn_bank_server_acct_transfer 0x01000004

Administration of Event Numbers
Organizations and vendors must administer the event numbers assigned to them (through the set-id) to maintain the unique assignment of event numbers.

Event Class
Audit events can be logically grouped together into an event class. Event classes provide an efficient mechanism by which sets of events can be specified by a single value. Generally, an event class consists of audit events with some commonality. For example, in a bank server program, the cash transaction events (deposit, withdrawal, and transfer) may be grouped into an event class.

Typically, the administrator creates and maintains event classes. For more details to event classes, see the OSF DCE Administration Guide - Core Components.

Event Class Number
Each event class is assigned an event class number. Like the event number, the event class number is a 32-bit integer and is administered by OSF. Event class numbers are discussed in more detail in the OSF DCE Administration Guide - Core Components.

Filters
Once the code points are identified and placed in the application server, all audit events corresponding to the code points will be logged in the audit trail file, irrespective of the outcome of these audit events. However, recording all audit events under all conditions may neither be practical nor necessary. Filters provide a means by which audit records are logged only when certain conditions are satisfied. A filter is composed of filter guides that specify these conditions. Filter guides also specify what action to take if the condition (outcome) is met.

A filter answers the following questions:

· Who will be audited?

· What events will be audited?

· What should be the outcome of these events before an audit record is written?

· Will the audit record be logged in the audit trail file or displayed on the system console, or both?

For example, for the bank server program, you can impose the following conditions before an audit record is written:

"Audit all withdrawal transactions (the audit events) that fail because of access denial (outcome of the event) that are performed by all customers in the DCE cell (who to audit).''

Filter Subject Identity
A filter is associated with one filter subject, which denotes to what the filter applies. The filter subject is the client of the distributed application who caused the event to happen.

For more information on the filter subject identity, see the OSF DCE Administration Guide - Core Components.

Audit Records
An audit record has a header and a trailer. The header contains the common information of all events; for example, the identities of the client and the server, group privileges used, address, and time. The trailer contains event-specific information; for example, the dollar amount of a fund-transfer event.

Audit records are initialized and filled by calling the audit API functions.

There are four stages in the writing of an audit record:

1. First, the code point registers an audit event. At this point, the audit record does not yet have any form.

2. The audit record descriptor is built. This is a representation of the audit data that is built by the dce_aud_start( ), dce_aud_put_ev_info( ), and dce_aud_commit( ) functions. This is stored in a data structure in the client's core memory until the dce_aud_commit( ) function is called. This data is not IDL-encoded until the dce_aud_commit( ) call.

3. The audit record is written to the log. This is stored as IDL-encoded data in the audit log.

4. The audit record is transformed into human-readable form. This is a representation built in a data structure in the core memory by calls to the dce_aud_next( ) and dce_aud_print( ) functions. This is not an IDL-encoded representation.

Audit Trail File
The audit trail file contains all the audit records that are written by the audit daemon or the audit APIs. You can specify either a central audit trail file or a local audit trail file. The central audit trail file is maintained by the audit daemon. The local audit trail file is maintained by the audit library. The terms audit trail file and audit trail are used interchangeably in this guide.

##