NAME

dce_aud_start —  Determines whether a specified event should be audited given the client binding information and the event outcome.  Used by client/server applications

Synopsis

void dce_aud_start(
unsigned32 event,
rpc_binding_handle_t binding,
unsigned32 options,
unsigned32 outcome,
dce_aud_rec_t ∗ard,
unsigned32 ∗status);

Parameters

Input

eventSpecifies the event to be audited.  This is a 32-bit event number.  The event field in the audit record header will be set to this number. 

bindingSpecifies the client’s RPC binding handle from which the client identification information is retrieved to set the client, cell, num_groups, groups, and addr fields in the audit record header. 

optionsSpecifies the optional header information desired (aud_c_evt_all_info, aud_c_evt_group_info, or aud_c_evt_address_info). 

It can also be used to specify whether the audit records are always logged (aud_c_evt_always_log) or that an alarm message is always sent to the standard output (aud_c_evt_always_alarm).  If any of these two options is selected, the filter is bypassed. 

The value of the options parameter is the bitwise OR of any selected combination of the following option values:

aud_c_evt_all_info
Includes all optional information (groups and address) in the audit record header.

aud_c_evt_groups_info
Includes the groups information in the audit record header.

aud_c_evt_address_info
Includes the client address information in the audit record header.

aud_c_evt_always_log
Bypasses the filter mechanism and indicates that the event must be logged.

aud_c_evt_always_alarm
Bypasses the filter mechanism and indicates that an alarm message must be sent to the system console for the event.

outcomeThe event outcome to be stored in the header.  The following event outcome values are defined:

aud_c_esl_cond_success
The event was completed successfully.

aud_c_esl_cond_denial
The event failed because of access denial.

aud_c_esl_cond_failure
The event failed because of reasons other than access denial.

aud_c_esl_cond_pending
The event is in an intermediate state, and the outcome is pending, being one in a series of connected events, where the application desires to record the real outcome only after the last event.

aud_c_esl_cond_unknown
The event outcome (denial, failure, pending, or success) is still unknown. This outcome exists only between a dce_aud_start() (all varieties of this routine) call and the next dce_aud_commit() call.  You can also use 0 to specify this outcome. 

Output

ardReturns a pointer to an audit record buffer.  If the event does not need to be audited because it is not selected by the filters, or if the environment variable DCEAUDITOFF has been set, a NULL pointer is returned.  If the function is called with outcome set to aud_c_esl_cond_unknown, it is possible that the function cannot determine whether the event should be audited.  In this case, the audit record descriptor is still allocated and its address is returned to the caller.  An outcome other than aud_c_esl_cond_unknown must be provided when calling the dce_aud_commit() function. 

statusThe status code returned by this function.  This status code indicates whether the routine was completed successfully or not.  If the routine was not completed successfully, the reason for the failure is given. 

Description

The dce_aud_start() function determines if an audit record should be generated for the specified event.  The decision is based on the event filters, an environment variable (DCEAUDITOFF), the client’s identity provided in the binding parameter, and the event outcome (if it is provided in the outcome parameter).  If this event needs to be audited, the function allocates an audit record descriptor and returns a pointer to it, (that is, ard).  If the event does not need to be audited, a NULL ard is returned.  If an internal error(s) has occurred, a NULL pointer is returned in ard.  If the aud_c_evt_always_log or aud_c_evt_always_alarm option is selected, an audit record descriptor will always be created and returned. 

The dce_aud_start() function is designed to be used by RPC applications.  Non-RPC applications that use the DCE authorization model (that is, DCE ACL and PAC) must use dce_aud_start_with_pac().  Non-RPC applications that do not use the DCE authorization model must use dce_aud_start_with_name(). 

This function obtains the client identity information from the RPC binding handle and records it in the newly-created audit record descriptor. 

Event-specific information can be added to the record by calling the dce_aud_put_ev_info() function.  This function can be called multiple times after calling dce_aud_start() and before calling dce_aud_commit().  A completed audit record will be appended to an audit trail file or sent to the audit daemon (depending on the value of the description parameter used in the previous call to dce_aud_open) by calling dce_aud_commit(). 

This function searches for all relevant filters (for the specified subject and outcome, if these are specified), summarizes the actions for each possible event outcome, and records an outcome-action table with ard.  If the outcome is specified when calling this function and the outcome does not require any action according to filters, then this function returns a NULL ard. 

If the outcome is not specified in the dce_aud_start() call, dce_aud_start() returns a NULL ard if no action is required for all possible outcomes. 

The caller should not change the outcome between the dce_aud_start() and dce_aud_commit() calls arbitrarily.  In this case, the outcome can be made more specific, for example, from aud_c_esl_cond_unknown to aud_c_esl_cond_success or from aud_c_esl_cond_pending to aud_c_esl_cond_success. 

An outcome change from aud_c_esl_cond_success to aud_c_esl_cond_denial is not logically correct because the outcome aud_c_esl_cond_success may have caused a NULL ard to be returned in this function.  If the final outcome can be aud_c_esl_cond_success, then it should be specified in this function, or use aud_c_esl_cond_unknown. 

This function can be called with the outcome parameter taking a value of zero or the union (logical OR) of selected values from the set of constants aud_c_esl_cond_success, aud_c_esl_cond_failure, aud_c_esl_cond_denial, and aud_c_esl_cond_pending.  The outcome parameter used in the dce_aud_commit() function should take one value from the same set of constants. 

If dce_aud_start() used a nonzero value for outcome, then the constant used for outcome in the dce_aud_commit() call should have been selected in the dce_aud_start() call. 

Return Values

No value is returned. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

aud_s_ok
The call was successful.

Status codes passed from rpc_binding_to_string_binding()

Status codes passed from rpc_string_free()

Status codes passed from dce_aud_start_with_name()

Status codes passed from sec_cred_get_initiator()

Status codes passed from sec_cred_get_v1_pac()

Status codes passed from dce_aud_start_with_pac()

Status codes passed from sec_cred_get_delegate()

Related Information

Functions: dce_aud_commit(3sec), dce_aud_open(3sec), dce_aud_put_ev_info(3sec), dce_aud_start_with_name(3sec), dce_aud_start_with_pac(3sec), dce_aud_start_with_server_binding(3sec).