AU_OPEN(3)

💅 AU_OPEN(3) — create and commit audit records 💅

ok so this is a page from the Library Functions Manual — yes bestie, §3, the library-calls section — and it's the whole squad of audit-record functions: au_close, au_close_buffer, au_close_token, au_open, and au_write. They literally create and commit audit records. that's the vibe. 🎀

---

✨ LIBRARY ✨

Basic Security Module Library — that's libbsm, and you link it with -lbsm. 🫶

---

🌸 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 🦋

so these interfaces let your app allocate audit records, build a record out of a whole series of tokens, and then commit that record to the system event log. ✨ and there's a little bonus extension API too, which commits the record to an in-memory buffer instead of the system audit log — because sometimes you just wanna keep it in RAM, yk?

• au_open() — allocates a brand-new audit record descriptor. fresh out the box, no cap. 💅
• au_write() — adds a token to an audit descriptor you already allocated. big important thing here: once a token has been successfully added to a record, the caller no longer owns the token memory, so you do not need to free it yourself with a call to au_free_token(3). it's not yours anymore bestie, let it go. 🙈
• au_close() — commits an audit record to the system audit log, or abandons it. either way, all resources associated with the record get released. the keep argument decides which: a value of AU_TO_WRITE means the record gets committed, and AU_TO_NO_WRITE means it gets abandoned. when the record is committed, a BSM header gets inserted before the tokens you added (using the event identifier you pass in event), plus a trailer gets tacked on the end. 👑

heads up: committing a record to the system audit log requires privilege. the system said what it said. 🔥

• au_close_buffer() — writes the resulting record into an in-memory buffer of size *buflen, and it writes the filled buffer length right back into that same variable. multitasking icon. the event argument is the event identifier used in the record header. ⭐
• au_close_token() — generates the BSM stream output for a single token, tok, in the buffer you pass as buffer. the initial buffer size and the resulting data size both go through *buflen. and btw, au_close_token() will free the token before returning — so don't you dare double free it. 💀

---

🌈 RETURN VALUES 🌈

• au_open() — returns a non-negative audit record descriptor number on success, or a negative value on failure, with the error info tucked into errno. 😭
• au_write(), au_close(), au_close_buffer(), and au_close_token() — all return 0 on success, or a negative value on failure, again with the error info in errno.

---

🍓 SEE ALSO 🍓

• audit_submit(3)
• libbsm(3)

---

🧚 HISTORY 🧚

the OpenBSM implementation was created by McAfee Research — that's the security division of McAfee Inc. — under contract to Apple Computer, Inc., in 2004. ✨ then it got adopted by the TrustedBSD Project as the foundation for the OpenBSM distribution. glow-up fr fr. 💖

---

💜 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. 🫶

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

---

💀 BUGS 💀

ok so currently, au_open() does not reserve the kernel resources necessary to commit the record to the trail. on systems supporting au_close(), that call will just block until resources are available to commit the record. 😭

and here's the scary part: this leads to the possibility of an action being permitted without the record being guaranteed to go to disk. yikes. ideally, au_open() would reserve resources necessary to commit any submitted record, and release them on au_close(). that's the dream, but not the current reality. 🙈

---

okay that's the whole page bestie, go forth and audit responsibly 🦋💅✨

sign-off time: this lovely page came to you via Debian, dated March 4, 2006, and yes it's still serving looks. bye pookie! 💖