auditwrite(3)

名前 | 形式 | 機能説明 | パラメタ | 属性 | 戻り値 | エラー | 使用例 | ファイル | 関連項目 | 注意事項

名前

auditwrite- ユーザーレベルの監査レコードの作成と書き込み

形式

cc [flag...] file... -lbsm -lsocket -lnsl -lintl -ltsol [library...]


#include <bsm/auditwrite.h>

#include <bsm/audit_uevents.h>

#include <tsol/priv.h>

#include <tsol/label.h>

int auditwrite(...,AW_END);

機能説明

auditwrite() は、ユーザーレベルのプログラムの監査用の単一機能プログラマインタフェースを提供します。auditwrite() の主要機能は、監査レコードの作成、監査レコードの待機、保存領域の確保、トラステッドサーバー監査のサポートです。 監査レコードを作成するのに必要な特権については、「注意事項」を参照してください。

監査レコードの作成

auditwrite() は、完全な監査レコードを作成したり、既存の部分的な監査レコードに情報を追加します。auditwrite() を一回呼び出すだけで作成、書き込みできる監査レコードをシングルショット監査レコード、auditwrite() を 2 回以上呼び出して作成される監査レコードをマルチショット監査レコードといいます。「使用例」を参照してください。

監査レコードの待機

監査レコードは、しきい値を指定することによって待ち行列に入れることができます。しきい値に達すると、1 回の操作で複数のレコードの内容が書き込みされます。このバッチ処理によってシステムコールのオーバーヘッドが最小限になります。

保存領域の確保

保存領域として特殊な監査レコードバッファーが要求されることがあります。保存領域に格納される属性は、auditwrite() で作成される後続のすべてのレコードに付加されます。

トラステッドサーバーの監査のサポート

一部のトラステッドサーバーは、非トラステッドクライアントプロセスの代わりに働いて、 セキュリティチェックを実行したり TCB オブジェクトにアクセスしたりします。トラステッドサーバーは、場合によっては、当該クライアントの監査特性を使って監査レコードを生成します。AW_SERVER コマンドは、呼び出し元がトラステッドサーバであること、情報がまだ指定されていない場合には、各監査レコードに補足情報を追加しなければならないことを auditwrite() に通知します。

パラメタ

auditwrite() は、変数を引数にとります。引数には 3 つのタイプがあります。1 つのタイプは、制御コマンドと呼ばれ、 auditwrite() の動作を制御します。auditwrite() 呼び出し行には制御コマンドは 1 つしか使用できません。もう 1 つの引数タイプは属性コマンドです。属性コマンドは、監査レコードを構成する属性を記述します。制御コマンドと属性コマンドは、auditwrite() 呼び出し行の中で任意の順序で指定できます。最後の引数タイプはターミネータコマンドです。ターミネータコマンド AW_END は、auditwrite 呼び出し行の最終引数になります。ターミネータコマンドは、呼び出し行の構文解析をいつ終了するかを auditwrite() に通知します。

制御コマンド

AW_WRITE

デフォルトの監査レコードまたは最後の AW_USERD コマンドが指定する監査レコードを監査トレールに書き込みます。待ち行列が有効な場合は、レコードは待ち行列に入り、待ち行列がフラッシュするとレコードが作成されます。

AW_APPEND

1 つ以上のレコード属性をレコードの終わりに添付します。AW_APPEND は、監査レコードのマルチショット構成で使用されます。属性は、AW_WRITE コマンドで auditwrite() が呼び出されるまでレコードバッファーに保管されます。 AW_APPEND コマンドでは、1 つ以上の属性コマンドを指定します。

AW_DEFAULTRD

デフォルトのレコード記述子を使用します。

AW_DISCARD

監査レコードの部分と、完全な監査レコードをすべて破棄します。

AW_DISCARDRD, int rd

rd が指定するレコード記述子を破棄します。rd に -1 を指定すると、デフォルトの rd が破棄されます。

AW_GETRD, int *rd

AW_USERD で使用する監査レコード記述子を取得します。

AW_PRESELECT,
au_mask_t *pmask

pmask に応じて、監査レコードを事前に選択します。通常、監査レコードは、実行環境の中で事前選択マスクを使用する auditwrite() によって事前選択されます。詳細については、「getaudit(2)」を参照してください。

AW_NOPRESELECT

AW_PRESELECT コマンドが指定する事前選択マスクに代わって、実行環境の事前選択マスクを使用します。

AW_QUEUE,
u_int hi_water

監査レコード待ち行列を有効にします。AW_QUEUE によって、auditwrite() はすべての監査レコードを待ち行列に入れます。待ち行列に入っているすべての監査レコードの合計バイト数が hi_water に達すると、待ち行列はフラッシュされます。AW_FLUSH を使えば待ち行列を自由にフラッシュできます。auditwrite() 監査レコード待ち行列をカーネル監査レコード待ち行列と混同しないようにしてください。auditwrite() 待ち行列は、ユーザーのアドレス空間で作成される個別の待ち行列です。auditwrite() 監査レコード待ち行列は、複数の監査レコードを 1 回の操作で書き込むようにすれば、システムコールのオーバーヘッドを最小限にできます。

AW_NOQUEUE

監査レコード待ち行列を解除します。待ち行列をフラッシュします。

AW_FLUSH

監査レコード待ち行列をフラッシュします。

AW_SAVERD, int *rd

保存領域の使用できるようにします。保存領域に格納されている属性は、レコードの内容の書き込みの前にレコードに付加されます。

AW_NOSAVE

保存領域を使用無効にします。

AW_SERVER

トラステッドサーバーオプションを有効にします。AW_SERVER コマンドは、呼び出し元プログラムがサーバであり、完全な監査レコードを生成する必要があることを auditwrite() に通知します。auditwrite() は、ヘッダ属性とトレーラ属性をすべてのレコードに追加します。監査ポリシーによっては、シーケンス属性とグループ属性も追加されます。監査ポリシーの詳細は、「audit(2)」を参照してください。

AW_NOSERVER

トラステッドサーバーオプションを無効にします。

AW_USERD, int rd

AW_GETRD で取得したレコード記述子を使用します。

属性コマンド

属性コマンドは、監査レコードを構成する属性を記述します。属性コマンドは、AW_APPEND 制御コマンドか AW_WRITE 制御コマンド 1 つだけで指定します。

AW_ARG, char n, char *text
u_long v

指定されたシステムコール引数情報を監査レコードに配置します。n は引数番号を示します。text は引数を記述する文字列を示します。v は引数の値を示します。

AW_ATTR, mode_t mode, uid_t uid, gid_t gid, dev_t dev, ino_t ino
dev_t rdev

指定されたファイルシステムオブジェクトの属性情報を監査レコードに配置します。この情報は stat(2) システムコールを使って取得できます。

AW_CLEARANCE
bclear_t *clear

指定された認可上限を監査レコードに配置します。このシステム上で機密ラベルが有効でない場合、 auditon(2) からの該当する監査ポリシー (slabel) が有効でない場合は、コマンドは無視されます。

AW_DATA, char unit_print, char unit_type, char unit_count
caddr_t p

指定された任意のデータを監査レコードに配置します。unit_print は、監査トレールを読み込むプログラムによってデータをどのように印刷するかを記述します。unit_print は次の値をとることができます。

AWD_BINARY




AWD_OCTAL




AWD_DECIMAL




AWD_HEX




AWD_STRING




unit_typeは、p 内のデータ型を記述します。unit_type は次の値をとることができます。

AWD_BYTE




AWD_CHAR




AWD_SHORT




AWD_INT




AWD_LONG




unit_count は、p の中に unit_type の要素がいくつ存在するかを記述します。p は、書き込まれるデータを指すアドレスです。

AW_EVENT
char *event_str

監査レコードに関連する監査イベントを指定します。各監査レコードに関連づけられるイベントは 1 つだけです。イベントが指定されていない監査レコードに書き込もうとすると、auditwrite() はエラーを返します。event_str は、audit_event(4) に定義される有効なユーザーレベルの監査イベント文字列です。

(AW_EVENT は、他社製のアプリケーションイベントに使用されます。他のイベントの場合は、できるだけAW_EVENTNUM を使用します。AW_EVENT は、文字列検索のために追加オーバーヘッドを引き起こすからです。)

AW_EVENTNUM
int event

AW_EVENTNUM は AW_EVENT に似ていますが、引数としてイベント文字列の代わりに有効な event 番号をとります。他社製の追加機器間で互換性を保つために、 登録されたイベントだけがこの属性コマンドを使用します。event は、audit_event(4) と </usr/include/bsm/audit_uevent.h> に定義されている有効な監査イベントです。監査イベント文字列の詳細は、「audit_event(4)」を参照してください。

AW_EXEC_ARGS
char **argv

指定されたコマンド行引数を監査レコード内に配置します。配列の終わりには NULL のポインタが付きます(フォーマットは呼び出し元の C プログラムが argv に使用するフォーマットと同じです)。auditon(2) からの該当する監査ポリシー (argv) がこのシステム上で有効でない場合は、この呼び出しは無視されます。

AW_EXEC_ENV
char **envp

指定されたコマンド行環境を監査レコード内に配置します。配列の終わりには NULL のポインタが付きます(このフォーマットは呼び出し元の C プログラムが envp 使用するフォーマットと同じです)。auditon(2) らの該当する監査ポリシー (arge) がこのシステム上で有効でない場合は、この呼び出しは無視されます。

AW_EXIT, int status
int errno

指定されたプログラムの終了ステータス情報を監査レコード内に配置します。status は、呼び出し元プログラムの終了ステータスを示します。errno は、プログラム終了の原因を示すシステムエラー番号または内部エラー番号を示します。

AW_GROUPS, int num
gid_t *groups

配列 groups の要素をフォーマットして監査レコード内に配置します。num は配列内の要素数を指定し、</usr/include/sys/param.h> に定義される NGROUPS_UMIN と NGROUPS_UMAX の間の数でなければなりません。監査ポリシーが [auditconfig(1M) を参照 ] 補足グループを組み込めるように設定されていない場合は、コマンドは無視されます。

AW_INADDR
struct in_addr *in_addr

指定されたインターネットアドレスを監査レコード内に配置します。

AW_IPC, char type, int id

指定されたプロセス間通信識別子を監査レコード内に配置します。type は次のいずれかの値をとります。AT_IPC_MSG、AT_IPC_SEM、AT_IPC_SHM、または AT_IPC_NULL。

AW_IPC_PERM
struct ipc_perm *perm

指定されたプロセス間通信識別子のアクセス権情報を監査レコード内に配置します。

AW_IPORT, u_short iport

指定された IP ポートを監査レコード内に配置します。

AW_LEVEL, blevel_t *level

指定されたレベルを監査レコード内に配置します。機密ラベルがこのシステム上で有効でない場合、auditon(2) からの該当する監査ポリシー (slabel) がこのシステム上で有効でない場合は、コマンドは無視されます。

AW_OPAQUE, caddr_t data
short byte_count

data が指している、長さが byte_count の隠されたデータを監査レコード内に配置します。

AW_PATH, char *path

指定されたパスを監査レコード内に配置します。パスの先頭にスラッシュ (/) が付いていない場合、パスには現在アクティブなルートで固定されます。

AW_PRIVILEGE, priv_set_t *priv_set
char settype

指定された特権セットを監査レコード内に配置します。settype は、次の値をとります。

AU_PRIV_UNKNOWN




AU_PRIV_FORCED




AU_PRIV_ALLOWED




AU_PRIV_EFFECTIVE




AU_PRIV_INHERITABLE




AU_PRIV_PERMITTED




AU_PRIV_SAVED




AW_PROCESS, au_id_t auid, uid_t euid, gid_t egid
uid_t ruid, gid_t rgid, pid_t pid, au_asid_t sid
au_tid_t *tid

指定されたプロセス情報を監査レコード内に配置します。AW_PROCESS 属性と AW_SUBJECT 属性は同じ情報を記録します。プロセスオブジェクトについての情報を記録するときは、AW_PROCESS 属性を使用します。プロセスサブジェクトについての情報を記録するときは、AW_SUBJECT 属性を使用します。

AW_RETURN, char number
u_int retval

属性は、監査イベントの成否を示します。この属性は、auditwrite() による事前選択に使用されます。また、auditreduce(1M) 事後選択プログラムがイベントの成否に応じて監査レコードを選択するときにも使用されます。

number は、イベントの成否を示します。イベントの失敗はゼロ以外の number 値によって示されます。正の値は praudit(1M) によって errno 値として解釈されます。対応するエラー文字列が印刷されます。負の値は、監査イベントに固有の一般的な失敗を示します。イベントの成功は、ゼロの number 値によって示されます。retval は、成功または失敗した関数やプログラムの戻り値または状態値を示します。

AW_SLABEL, bslabel_t *label

指定された機密レベルを監査レコード内に配置します。このシステム上で機密レベルが有効でない場合、auditon(2) からの該当する監査ポリシー (slabel) が有効でない場合は、コマンドは無視されます。

AW_SOCKET, struct socket *s

指定されたソケット情報を監査レコード内に配置します。

AW_SUBJECT, au_id_t auid, uid_t euid, gid_t egid
uid_t ruid, gid_t rgid, pid_t pid, au_aside_t sid
au_tid_t *tid

指定されたサブジェクト情報を監査レコード内に配置します。AW_PROCESS 属性と AW_SUBJECT 属性は同じ情報を記録します。プロセスオブジェクトについての情報を記録するときは、AW_PROCESS 属性を使用します。プロセスサブジェクトについての情報を記録するときは、AW_SUBJECT 属性を使用します。

AW_TEXT, char *text

指定された NULL で終わる文字列 text を監査レコード内に配置します。

AW_USEOFPRIV, char flag
priv_t priv

特権を使用しようとしたことを示すフラグと特権を 1 つずつ監査レコード内 に配置します。flag は、試行の成功 (1) または失敗 (0) を示します。priv は、使用を試みた特権を示します。

AW_XATOM
char *atom_string

指定された X アトム文字列を監査レコード内に配置します。

AW_XCOLORMAP, u_long xid
uid_t creator_uid

指定された X カラーマップ情報を監査レコード内に配置します。

AW_XCLIENT
u_long clientid

指定された X クライアント ID を監査レコード内に配置します。

AW_XCURSOR, u_long xid
uid_t creator_uid

指定された X カーソル情報を監査レコード内に配置します。

AW_XFONT, u_long xid
uid_t creator_uid

指定された X フォント情報を監査レコード内に配置します。

AW_XGC, u_long xid
uid_t creator_uid

指定された X gc 情報を監査レコード内に配置します。

AW_XPIXMAP, u_long xid
uid_t creator_uid

指定された X ピクセルマッピング情報を監査レコード内に配置します。

AW_XPROPERTY, u_long xid, uid_t creator_uid,
char *atom_name

指定された X プロパティ情報を監査レコード内に配置します。

AW_XSELECT, char *property_string, char *property_type,
char *window_data

指定された X 選択情報を監査レコード内に配置します。

AW_XWINDOW, u_long xid,
uid_t creator_uid

指定された X ウィンドウ情報を監査レコード内に配置します。

ターミネーターコマンド

ターミネータコマンド AW_END は、auditwrite() 呼び出し行の最後の引数になります。

属性

次の属性の説明については、attributes(5) のマニュアルページを参照してください。

属性タイプ	属性値
使用条件	SUNWcsu
MT レベル	MT- 安全

戻り値

auditwrite() コマンドは次の値を返します。

0

正常終了

-1

エラー終了時に aw_errno を設定してエラーを示します。

エラー

エラーが検出されると、監査レコード全体または監査レコードの一部が直ちに監査トレールに書き込まれます。この中には待ち行列に入っているレコードも含まれます。 また、LOG_ALERT メッセージが syslogd(1M) に送信され、auditwrite() 「処理エラー」監査レコードの監査トレールへの書き込みが試行されます。

aw_errnoに関連するエラー文字列の取得には、aw_strerror(3) またはaw_perror(3)が使用されます。

aw_errno は次の値をとります。

AW_ERR_ADDR_INVALID

指定されたアドレスが無効でした。

AW_ERR_ALLOC_FAIL

メモリを割り当てようとしましたが、失敗しました。

AW_ERR_AUDITON_FAIL

auditon(2) システムコールが失敗しました。原因については、「errno」を参照してください。

AW_ERR_AUDIT_FAIL

audit(2) システムコールが失敗しました。原因については、「errno」を参照してください。

AW_ERR_CMD_INCOMPLETE

必要なコマンドが省略されています。このイベントは、AW_APPEND が属性コマンドなしに指定された場合、またはこの逆の場合に発生します。

AW_ERR_CMD_INVALID

指定されたコマンドは有効なコマンドではありません。

AW_ERR_CMD_IN_EFFECT

AW_QUEUE などのコマンドがすでに有効であるか、AW_SAVERD が指定されています。

AW_ERR_CMD_NOT_IN_EFFECT

有効でないコマンドを逆行させようとしました。

AW_ERR_CMD_TOO_MANY

複数の制御コマンドが指定されています。

AW_ERR_EVENT_ID_INVALID

引き渡されたイベント ID 文字列は有効ではありません。

AW_ERR_EVENT_ID_NOT_SET

有効なイベント ID を指定せずに監査レコードを作成しようとしました。このときには、イベント ID は NULL 値に設定され、レコードはエラー処理手続の一環として作成されます。

AW_ERR_GETAUDIT_FAIL

getaudit(2) システムコールが失敗しました。原因については、「errno」を参照してください。

AW_ERR_QUEUE_SIZE_INVALID

指定された待ち行列のサイズが、システムが指定する最大監査レコードサイズより大きくなっています。

AW_ERR_RD_INVALID

指定されたレコード記述子が無効です。

AW_ERR_REC_TOO_BIG

システムが指定する最大監査レコードサイズより大きい監査レコードを作成しようとしました。

AW_ERR_NO_PLABEL

現在のプロセスのプロセスラベルを取得できなかったため、完全なレコードを生成できませんでした。

使用例

有効な例

/* Single-shot record construction:
 * Construct an audit record and write the record to the audit trail.
 * Uses the default audit record.
 */
 
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string1, AW_TEXT, "hello", AW_WRITE, AW_END);
 
/* Multi-shot construction:
 * Construct an audit record piecemeal and write the record.
 * Uses the default audit record.
 */
 
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string2, AW_APPEND, AW_END);
(void) auditwrite(AW_TEXT, "part 1", AW_APPEND, AW_END);
(void) auditwrite(AW_TEXT, "part 2", AW_APPEND, AW_END);
(void) auditwrite(AW_RETURN, 0, 0, AW_APPEND, AW_END);
(void) auditwrite(AW_WRITE, AW_END);
 
/* Multi-shot record construction:
 * Decide upon the return token value when it occurs.
 */
 
(void) auditwrite(AW_EVENTNUM, AUE_ftpd, AW_APPEND, AW_END);
(void) auditwrite(AW_TEXT, "Read access attempt", AW_APPEND, AW_END);
 
if (access_decision() == FALSE) {
        succ_or_fail = -1;
        reason = get_reason;
} else {
        succ_or_fail = 0;
        reason = 0;
}
 
(void) auditwrite(AW_TEXT, "more text", AW_RETURN, succ_or_fail, reason, AW_APPEND, AW_END);
(void) auditwrite(AW_WRITE, AW_END);
/* Queueing:
 * Turn on queueing, queue two records, then turn off queueing. Queue is flushed
 * automatically when queuing is turned off.
 */
 
(void) auditwrite(AW_QUEUE, 1024, AW_END);
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string3, AW_RETURN, 0, 0, AW_WRITE, AW_END);
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string4, AW_RETURN, 0, 0, AW_WRITE, AW_END);
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string5, AW_RETURN, 0, 0, AW_APPEND, AW_END);
(void) auditwrite(AW_NOQUEUE, AW_END);

無効な例

/*
 * Invalid command combinations:
 * Only one control command may be specified.
 */
(void) auditwrite(AW_EVENTNUM, valid_event_str, AW_TEXT, "text", AW_DISCARD, AW_WRITE, AW_END);

/*
 * No control command specified
 */
(void) auditwrite(AW_TEXT, "text", AW_END);

ファイル

/etc/security/audit_event

監査イベント文字列と監査イベント番号を対応付けるのに使用されます

関連項目

Trusted Solaris 7 リファレンスマニュアル

auditreduce(1M), praudit(1M), audit(2), getaudit(2), stat(2), audit_event(4), auditconfig(1M), auditon(2)

Trusted Solaris 開発ガイド

SunOS 5.7 リファレンスマニュアル

attributes(5)

注意事項

サブジェクトが指定されないとき、auditwrite() は、現在のプロセスのサブジェクト、グループ、(該当する監査ポリシーに応じて) 機密ラベル、 情報ラベル属性を生成しようとします。この試みはサーバーにとって意味のあることです。処理中のプロセスの AUID、UID、機密ラベル、情報ラベル、グループを取得する取り決めを行い、それらを auditwrite() に指定しなければ、記録された値がサーバープロセスの値になるからです。サーバーのプログラマは、auditwrite() を使用するときにはこの点を考慮に入れるとともに、auditwrite() を特別に要求してこの問題の解決を図る必要があります。

イベント番号 2048 から 32767 の監査レコードを作成するには、呼び出し元プロセスは有効な特権セットの中に PRIV_PROC_AUDIT_TCB を持っていなくてはなりません。イベント番号が 32768 から 65535 の場合は、呼び出し元プロセスは有効な特権セットの中に PRIV_PROC_AUDIT_APPL を持っていなくてはなりません。有効なユーザーレベルのイベント番号はこれらのイベント番号セットだけです。

Trusted Solaris 7  最終更新日 1999 年 12 月 31 日

名前 | 形式 | 機能説明 | パラメタ | 属性 | 戻り値 | エラー | 使用例 | ファイル | 関連項目 | 注意事項