hpux man page for audit_intro

audit_intro(3)						     Library Functions Manual						    audit_intro(3)

NAME
       audit_intro - Introduction to the DCE Audit API runtime.

DESCRIPTION
       This  introduction  gives  general information about the DCE Audit Application Programming Interface (API) and an overview of the following
       parts of the DCE Audit API runtime: Runtime services Environment variables Data types and structures Permissions required

   Runtime Services
       The following is an alphabetical list of the Audit API routines.  With each routine name is its description.  The types of application pro-
       gram that will most likely call the routine are enclosed in parentheses.

       Closes  an  audit  trail  (client/server  applications,	audit  trail  analysis	and  examination  tools).   Performs  the  audit action(s)
       (client/server applications).  Discards an audit record which releases the memory (client/server applications,  audit  trail  analysis  and
       examination tools).  Frees the memory allocated for an event information structure returned from calling the dce_aud_get_ev_info() function
       (audit trail analysis and examination tools).  Frees the memory allocated to a designated audit record header structure (audit trail analy-
       sis  and examination tools).  Gets the event-specific information of a specified audit record (audit trail analysis and examination tools).
       Gets the header of a specified audit record (audit trail analysis and examination tools).  Gets the length  of  a  specified  audit  record
       (client/server  applications, audit trail analysis and examination tools).  Reads the next audit record from a specified audit trail into a
       buffer (audit trail analysis and examination tools).  Opens a specified audit trail for read or write  (client/server  applications,  audit
       trail  analysis	and  examination tools).  Formats an audit record into a human-readable form (audit trail analysis and examination tools).
       Adds event-specific information to a specified audit record buffer (client/server applications).  Sets a limit  to  the	audit  trail  size
       (client/server  applications).  Determines whether a specified event should be audited given the client's binding information and the event
       outcome.  If the event should be audited or if it is not yet known whether the event should be audited because the event outcome  is  still
       unknown, memory for the audit record descriptor is allocated and the address of this memory is returned to the caller (client/server appli-
       cations).  Determines whether a specified event should be audited given the client/server name and the event outcome.  If the event  should
       be  audited  or if it is not yet known whether the event should be audited because the event outcome is still unknown, memory for the audit
       record descriptor is allocated and the address of this memory is returned to the caller (client/server applications).  Determines whether a
       specified  event  should be audited given the client's Privilege Attribute Certificate (PAC) and the event outcome.  If the event should be
       audited or if it is not yet known whether the event should be audited because the event outcome is still  unknown,  memory  for	the  audit
       record descriptor is allocated and the address of this memory is returned to the caller (client/server applications).  Determines whether a
       specified event should be audited given the server's binding information and the event outcome.	If the event should be audited or if it is
       not  yet  known	whether  the event should be audited because the event outcome is still unknown, memory for the audit record descriptor is
       allocated and the address of this memory is returned to the caller (client/server applications).   Determines  whether  a  specified  event
       should  be audited given the client/server UUID and the event outcome.  If the event must be audited, or if the outcome of the event is not
       yet known, the memory for the audit record descriptor  is  allocated  and  the  address	of  this  structure  is  returned  to  the  caller
       (client/server applications).

   Audit Data Types
       The  following  subsections  list  the data types and structures used by applications to perform auditing and to analyze audit trails.  The
       Audit APIs allow applications to include event-specific information in audit records.  Event-specific information must  be  represented	as
       information items using the following data type.  typedef struct {
	       unsigned16 format;
	       union {
		   idl_small_int small_int;
		   idl_short_int short_int;
		   idl_long_int long_int;
		   idl_hyper_int hyper_int;
		   idl_usmall_int usmall_int;
		   idl_ushort_int ushort_int;
		   idl_ulong_int ulong_int;
		   idl_uhyper_int uhyper_int;
		   idl_short_float short_float;
		   idl_long_float long_float;
		   idl_boolean boolean;
		   uuid_t uuid;
		   utc_t utc;
		   sec_acl_t * acl;
		   idl_byte * byte_string;
		   idl_char * char_string;
	       } data; } dce_aud_ev_info_t;

       The  format  field  of the above data structure defines formatting information that is used to determine the type of the data referenced by
       the data field.	The following table shows possible values of the format field, their corresponding data types, and their sizes.

					     +--------------------------------------------------------------+
					     |		Event Data Format Specifiers -- intro(3)	    |
					     +---------------------------+-----------------+----------------+
					     |Specifier 		 | Data Type	   | Size	    |
					     +---------------------------+-----------------+----------------+
					     |aud_c_evt_info_small_int	 | idl_small_int   | 1 byte	    |
					     |aud_c_evt_info_short_int	 | idl_short_int   | 2 bytes	    |
					     |aud_c_evt_info_long_int	 | idl_long_int    | 4 bytes	    |
					     |aud_c_evt_info_hyper_int	 | idl_hyper_int   | 8 bytes	    |
					     |aud_c_evt_info_usmall_int  | idl_usmall_int  | 1 bytes	    |
					     |aud_c_evt_info_ushort_int  | idl_ushort_int  | 2 bytes	    |
					     |aud_c_evt_info_ulong_int	 | idl_ulong_int   | 4 bytes	    |
					     |aud_c_evt_info_uhyper_int  | idl_uhyper_int  | 8 bytes	    |
					     |aud_c_evt_info_short_float | idl_short_float | 4 bytes	    |
					     |aud_c_evt_info_long_float  | idl_long_float  | 8 bytes	    |
					     |aud_c_evt_info_boolean	 | idl_boolean	   | 1 byte	    |
					     |aud_c_evt_info_uuid	 | uuid_t	   | 16 bytes	    |
					     |aud_c_evt_info_utc	 | utc_t	   | 16 bytes	    |
					     |aud_c_evt_info_acl	 | sec_acl_t *	   | variable size  |
					     |aud_c_evt_info_byte_string | idl_byte *	   | variable size  |
					     |aud_c_evt_info_char_string | idl_char *	   | variable size  |
					     +---------------------------+-----------------+----------------+
       Byte strings and character strings are terminated with a 0 (zero) byte.	New data types can be added to this list if  they  are	used  fre-
       quently.  Servers could use the pickling service of the IDL compiler to encode complex data types into byte strings that are to be included
       in an audit record.  The following data structure is used to store header information obtained from an audit  record.   This  structure	is
       normally only used by audit trail analysis and examination tools.  That is, it is hidden from client/server applications.  typedef struct {
	       unsigned32	  format;
	       uuid_t		  server;
	       unsigned32	  event;
	       unsigned16	  outcome;
	       unsigned16	  authz_st;
	       uuid_t		  client;
	       uuid_t		  cell;
	       unsigned16	  num_groups;
	       utc_t		  time;
	       char		  *addr;
	       uuid_t		  *groups;  }  dce_aud_hdr_t;  Contains the version number of the tail format of the event used for the event-spe-
       cific information.  With this format version number, the audit analysis tools can accommodate changes in the formats of the  event-specific
       information.  For example, the event-specific information of an event may initially be defined to be a 32-bit integer, and later changed to
       a character string.  Format version 0 (zero) is assigned to the initial format for each event.  Contains the UUID of the server that gener-
       ates  the  audit record.  Contains the event number.  Indicates whether the event failed or succeeded.  If the event failed, the reason for
       the failure is given.  Indicates how the client is authorized: by a name or by a DCE Privilege Attribute Certificate (PAC).   Contains  the
       UUID  of  the  client.	Contains the UUID of the client's cell.  Contains the number of local group privileges the client used for access.
       Contains the UUIDs of the local group privileges that are used by the client for the access.  By default, the group information is  not	be
       included  in  the  header  (num_groups  is  set to 0 in this case), to minimize the size of the audit records.  If the group information is
       deemed as important, it can be included.

       Information about foreign groups (global groups that do not belong to the same cell where the client is registered) is not included in this
       version	of  audit  header but may be included in later versions when global groups are supported.  Contains a timestamp of utc_t type that
       records the time when the server committed the audit record (that is, after providing the event	information  through  audit  API  function
       calls).	 Recording this time, rather than recording the time when the audit record is appended to an audit trail, will better maintain the
       sequence of events.  The implementation of the audit subsystem may involve communication between the server  and  a  remote  audit  daemon,
       incurring  indefinite delays by network problems or intruders.  The inaccuracy in the utc_t timestamp may be useful for correlating events.
       When searching for events in an audit trail that occur within a time interval, if the results of the comparisons between  the  time  of	an
       event  and  the	interval's  starting  and ending times is maybe (because of inaccuracies), then the event should be returned.  Records the
       client's address (port address of the caller).  Port addresses are not authenticated. A caller can provide a fraudulent port address  to  a
       DCE  server.   However,	if  this unauthenticated port address is deemed to be useful information, a DCE server can record this information
       using this field.

       The identity of the server cell is not recorded in the header, because of the assumption that all audit records in an audit trail  are  for
       servers	within a single cell, and implicitly, the server cell is the local cell.  An opaque data type, dce_aud_rec_t, is used to represent
       an audit record descriptor.  An audit record descriptor may be created, manipulated, or disposed of by the following functions:	The  func-
       tions  dce_aud_start(), dce_aud_start_with_pac(), dce_aud_start_with_name(), dce_aud_start_with_server_binding(), and dce_aud_next() return
       a record descriptor.  The function dce_aud_put_ev_info() adds event information to an audit record through a record descriptor.	The  func-
       tions  dce_aud_get_header(),  dce_aud_get_ev_info(), and dce_aud_length() get the event and record information through a record descriptor.
       The function dce_aud_commit() commits an audit record through its descriptor.  The function dce_aud_discard() disposes of a record descrip-
       tor.   The  function  dce_aud_discard() is necessary only after reading the record (that is, after invoking dce_aud_next().  An opaque data
       type, dce_aud_trail_t, is used to represent an audit trail descriptor.  The dce_aud_open() function opens an  audit  trail  and	returns  a
       trail  descriptor; dce_aud_next() obtains an audit record from this descriptor; and dce_aud_commit() commits an audit record from and to an
       opened audit trail through this descriptor.  The dce_aud_close() function disposes of this descriptor.

   Environment Variables
       The Audit API routines use the following environment variables: If this environment variable is defined at  the	time  the  application	is
       started,  auditing  is turned off.  If this environment variable is defined, filtering is enabled.  Sets the limit of the audit trail size.
       This variable overrides the limit set by the dce_aud_set_trail_size_limit() function.

   Permissions Required
       To use an Audit daemon's audit record logging service, you need the log (l) permission to the Audit daemon.

RELATED INFORMATION
       Books:  OSF DCE Administration Reference, OSF DCE Application Development Guide.

RELATED INFORMATION
       Books:  OSF DCE Administration Reference, OSF DCE Application Development Guide.

																    audit_intro(3)