Ingres CL SA
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - SA
Abstract
This the specification of the SA facility provided by the compatibility library
Version: 1.1, 20-May-2008, Steve Ball
Document History
- Revision 1.1, 18-May-2008, Steve Ball
- Updated to Word doc and new styles
- Revision 1.0 from code, 3-Mar-1994, Steve Ball
Specification
Introduction
The Secure eXtensions Facility within the DBMS has been designed so that physical implementation of reading/writing audit logs is kept separate from the rest of SXF. The design provides a call interface to the physical layer which may be determined at DBMS start-up time from a list of available interfaces. Using this design an interface is provided to enable SXF to write to a security audit subsystem provided by a C2 or above, secure operating system.
The call interface provided by the system to write audits will vary from system to system. SA provides an implementation independent way of writing audit records to the operating system audit trail.
Library
CL
Current Platforms
OS Level auditing has been ported to only Sun CMW and HP BLS; both B1 secure operating systems, neither of these operating systems have ports for the current version of Ingres. In the absence of a system port a no-op version of SA is executed in sadummy.c. In order to port SA to a new platform the coder would write their platform specific code using sadummy.c, wrap the new file with an #ifdef for the new platform string, and add the new platform to the undefined list in sadummy.c
Restrictions and Assumptions
It is assumed that the relevant operating system will provide a way to read the audit records generated by calls to SA, based on this assumption a write only interface to SA is provided. There is therefore no definition of a SAread routine in the specification and the specified interface to all other routines will restrict itself to write only operations.
HEADER FILE <SA.H>
The header file <sa.h> must be included before using any of the functions provided. The headers <gl.h>, <sl.h> and <tm.h> will also be needed when using SAwrite. The header <sa.h> will additionally include <sacl.h> which defines the following.
SA_AUD_REC - audit record structure
This structure contains all the fields that make up an Ingres audit record, the caller is expected allocate the memory for the structure before calling SA, and in the case of SAwrite will have filled the structure with a valid audit record to be written.
Since it is expected that the audit trail be read using operating system tools, the audit record will be passed in a format that will not require translation using Ingres structures or facilities, except those available in GL and CL. Thus most fields will be passed as pointers to character strings which will contain plain text, either blank pad fixed length or null terminated as indicated, some fields may be null as indicated. If the operating system audit record contains special fields which need to be filled in, then they will either be constructed in SA or translated from the fields passed in SA_AUD_REC. A date an time field will also be included in the audit record, on most systems this will be automatically filled in by the operating system routines before writing the record, in cases where it is not, SA will add this field before passing the record to the operating system. SA will not assume that it has been passed a valid date and time, the sa_evtime field will normally be null when writing an audit record.
typedef struct _SA_AUD_REC
{
SYSTIME *sa_evtime; /* Desc: Time the event occurred
** Length: As determined by SYSTIME
** Null: YES */
char *sa_eventtype; /* Desc: The type of audit event
**length:SA_MAX_EVENT,Null Terminated
** Null: NO */
char *sa_ruserid; /* Desc: Real identity of the user
** length: GL_MAXNAME, Blank Pad
** Null: NO */
char *sa_euserid; /* Desc: Effective identity of the user
** length: GL_MAXNAME, Blank Pad
** Null: NO */
char *sa_dbname; /* Desc: Database action applies to
** length GL_MAXNAME, Blank Pad
** Null: YES */
char *sa_messtxt; /* Desc: Textual message
**length:SA_MAX_MESSTXT,Null Terminated
** Null: NO */
bool sa_status; /* Desc: Did operation succeed ?
** Length: Single Byte, contains ’Y’ or ’N’
** Null: NO */
char *sa_userpriv; /* Desc: privilege list of the user
** length: SA_MAX_PRIVLEN, fixed
** Null: NO */
char *sa_objpriv; /* Desc: privileges changed by GRANT
** length: SA_MAX_PRIVLEN, fixed
** Null: NO */
char *sa_accesstype; /* Desc: access type of audit operation
**length: SA_MAX_ACCLEN, Null Terminated
** Null: NO */
char *sa_objowner; /* Desc: Owner of the object being accessed
** length: GL_MAXNAME, Blank Pad
** Null: YES */
char *sa_objname; /* Desc: Name of the object being accessed
** length: GL_MAXNAME, Blank Pad
** Null: YES */
char *sa_detail_txt; /* Desc: Additional text detail
**length: SA_MAX_TXTLEN, Null Terminated
** Null: YES */
i4 sa_detail_int; /* Desc: Additional integer detail
** length: 4 bytes
** Null: YES (indicated by 0) */
SL_LABEL *sa_sec_label; /* Desc: Security label
** length: as determined by SL_LABEL
** Null: YES */
char *sa_sess_id; /* Desc: Unique session ID
**Length: SA_MAX_SESSIDLEN, Null Terminated
** Null: YES */
} SA_AUD_REC;
Executable Interface
The following functions are provided.
SAsupports_osaudit - Does SA support writing to OS audit logs ?
This routine is used to determine wether SA supports the writing of operating system audit logs, it returns TRUE if SA support has been coded and is currently functional and FALSE otherwise. The caller may assume that if TRUE is returned, then the other SA routines required to write to the operating system audit trail are fully functional, and that this version of the operating system supports the functionality to write operating system audits, it may optionally check that the functionality has been enabled or installed on this particular system thereby ensuring the successful return of other operating system calls required for SA.
Inputs:
| None. |
Outputs:
| None. |
Returns:
| TRUE | SA will support writing to OS audit logs. |
| FALSE | SA will not support writing to OS audit logs. |
Definition:
| bool | SAsupports_osaudit() |
SAopen - Open an operating system audit trail
This routine opens the operating system audit trail described by aud_desc, if aud_desc is NULL it will open the current system audit trail. If aud_desc is not NULL it will point a character string containing the description of the audit trail. Reading of operating system audit trails will not initially be supported and thus aud_desc should always be NULL. The flags parameter specifies options for opening and reading the audit trail, it is set to a bit-wise or of flag values, since reading of the audit trails is not initially supported, SA_WRITE is the only valid flag. a descriptor is returned from the routine that may be used to access this audit trail in future SA calls. This routine should be non-blocking to the server, that is, it should not wait on the completion of an operating system event (I/O call). It may be assumed that the routine will be called from the context of a CS initialized thread, and may therefore use CSsuspend and CSresume for asynchronous OS calls.
Inputs:
| aud_desc | description of the audit trail to open |
| flags | flags to use when opening the audit trail |
| (SA_WRITE is currently the only valid flag). |
Outputs:
| aud_trail_d | descriptor to use for this audit trail |
| err_code | pointer to a variable used to return OS errors |
Returns:
| OK | if operation succeeded; otherwise system specific error status. |
| SA_NOACCESS | The caller has no access to this audit trail. |
| SA_NOPRIV | The caller has no privileges to read/write audits. |
Definition:
STATUS
SAopen( char *aud_desc,
longnat flags,
PTR aud_trail_d,
CL_ERR_DESC *err_code)
SAclose - Close an operating system audit trail
This routine closes an operating system audit trail previously opened by SAopen, the routine checks that the given trail is open before attempting to close it. An SAclose implies an SAflush, and all outstanding audit writes must be guaranteed before the close. The audit trail should be referenced by it’s descriptor, passed back by SAopen
Inputs:
| aud_trail_d | descriptor that identifies this audit trail |
Outputs:
| err_code | pointer to a variable used to return OS errors |
Returns:
| OK | if operation succeeded; otherwise system specific status. |
| SA_NOOPEN | the audit trail described by this descriptor has not been opened |
Definition:
STATUS
SAclose( PTR aud_trail_d,
CL_ERR_DESC *err_code)
SAwrite - Write an audit record to the operating system audit trail
This routine writes an audit record to the operating system audit trail. This routine should not block the server, that is it should not wait for the completion of an operating system event (I/O call). It may be assumed that the routine will be called from the context of a CS initialized thread, and may therefore use CSsuspend and CSresume for asynchronous OS calls. A call to SAwrite will not necessarily guarantee that the audit will be written. if the caller wishes to guarantee writes a subsequent call to SAflush must be used. SAwrite will attempt, if possible, to write an additional field(s), other than those passed in SA_AUD_REC, to the operating system audit trail, that will uniquely identify the record as an Ingres audit record coming from a specific installation. The audit trail will be identified by it’s description passed back from SAopen.
Inputs:
| aud_trail_d | a descriptor that identifies this audit trail |
| aud_rec | the audit record to be written |
Outputs:
| err_code | pointer to a variable used to return OS errors. |
Returns:
| OK | if operation succeeded; otherwise system specific error status. |
| SA_NOOPEN | the audit trail described by this descriptor has not been opened |
| SA_NOWRITE | this audit trail may not be written to |
Definition:
STATUS
SAwrite( PTR aud_trail_d,
SA_AUD_REC *aud_rec,
CL_ERR_DESC *err_code)
SAflush - hand all buffered audits to the operating system
This routine ensures that all buffered audits for a specific audit trail are handed to the operating system for audit, the routine will wait for all system audit calls to be completed before returning. If SAwrite guarantees the writes then this routine will be a no-op since there is never anything to do. The audit trail will be identified by it’s descriptor passed back from SAopen.
Inputs:
| aud_trail_d | a descriptor that identifies this audit trail |
Outputs:
| err_code | pointer to a variable used to return OS errors |
Returns:
| OK | if the operation succeeded, otherwise system specific status. |
| SA_NOOPEN | the audit trail described by this descriptor has not been opened |
Definition:
STATUS
SAflush( PTR aud_trail_d,
CL_ERR_DESC *err_code)
|
Ingres Compatability Library |
