AU_OPEN(3)

💅 AU_OPEN(3) — Library Functions Manual, but make it cute 🎀

✨ NAME ✨

au_close, au_close_buffer, au_close_token, au_open, au_write — create and commit audit records, bestie. That's the whole vibe.

📚 LIBRARY 📚

Basic Security Module Library (libbsm, -lbsm) — link it, gorgeous.

🧾 SYNOPSIS 🧾

#include <bsm/libbsm.h>

int
au_open(void);

int
au_write(int d, token_t *tok);

int
au_close(int d, int keep, short event);

int
au_close_buffer(int d, short event, u_char *buffer, size_t *buflen);

int
au_close_token(token_t *tok, u_char *buffer, size_t *buflen);

🛠️ DESCRIPTION 🛠️

Okay so these interfaces let applications allocate audit records, construct a record using a series of tokens, and commit the audit record to the system event log. There's also an extension API to commit the record to an in-memory buffer instead of the system audit log — flexible icon behavior. 💖

• au_open() — allocates a new audit record descriptor. Fresh descriptor, no cap.
• au_write() — adds a token to an allocated audit descriptor. When a token has been successfully added to a record, the caller no longer owns the token memory, and does not need to free it directly via a call to au_free_token(3) — do not free it yourself, bestie. 😭
• au_close() — used to commit an audit record to the system audit log, or abandon the record. Either way, all resources associated with the record will be released. The keep argument determines the behavior: a value of AU_TO_WRITE causes the record to be committed; a value of AU_TO_NO_WRITE causes it to be abandoned. When the audit record is committed, a BSM header will be inserted before tokens added to the record, using the event identifier passed via event, and a trailer added to the end. Committing a record to the system audit log requires privilege. privilege check, periodt. 👑
• au_close_buffer() — writes the resulting record to an in-memory buffer of size *buflen; it will write back the filled buffer length into the same variable. The argument event is the event identifier to use in the record header. 🫶
• au_close_token() — generates the BSM stream output for a single token, tok, in the passed buffer buffer. The initial buffer size and resulting data size are passed via *buflen. The au_close_token() function will free the token before returning. token cleanup slay. ✨

🎯 RETURN VALUES 🎯

• au_open() — returns a non-negative audit record descriptor number on success, or a negative value on failure, along with error information in errno.
• au_write(), au_close(), au_close_buffer(), and au_close_token() — return 0 on success, or a negative value on failure, along with error information in errno.

👀 SEE ALSO 👀

• audit_submit(3)
• libbsm(3)

🕰️ HISTORY 🕰️

The OpenBSM implementation was created by McAfee Research, the security division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. It was subsequently adopted by the TrustedBSD Project as the foundation for the OpenBSM distribution. a whole origin story. 🌸

👑 AUTHORS 👑

This software was created by Robert Watson, Wayne Salamon, and Suresh Krishnaswamy for McAfee Research, the security research division of McAfee, Inc., under contract to Apple Computer, Inc. 💜

The Basic Security Module (BSM) interface to audit records and audit event stream format were defined by Sun Microsystems.

💀 BUGS 💀

Currently, au_open() does not reserve kernel resources necessary to commit the record to the trail; on systems supporting au_close(), the call will block until resources are available to commit the record. However, this leads to the possibility of an action being permitted without the record being guaranteed to go to disk. Ideally, au_open() would reserve resources necessary to commit any submitted record, releasing them on au_close().

mwah 💋 this AU_OPEN(3) page is from Debian, dated March 4, 2006 — periodt, bestie. 🫶