AU_MASK(3)

💅 au_mask — bestie's guide to audit mask conversions ✨

okay so this page is from the Library Functions Manual, and it lives in section 3 (au_mask(3)) — it's the glow-up guide to the au_preselect, getauditflagsbin and getauditflagschar girlies. buckle up 🎀

---

🌸 NAME 🌸

au_preselect, getauditflagsbin, getauditflagschar — the trio that converts between the string and numeric values of audit masks. literally the translators of the audit world 🫶

---

🦋 LIBRARY 🦋

Basic Security Module Library — libbsm, and you link it with -lbsm. iconic. 💖

---

✨ SYNOPSIS ✨

#include <bsm/libbsm.h>

int
au_preselect(au_event_t event, au_mask_t *mask_p, int sorf, int flag);

int
getauditflagsbin(char *auditstr, au_mask_t *masks);

int
getauditflagschar(char *auditstr, au_mask_t *masks, int verbose);

no cap, that's the whole vibe check right there 👑

---

💜 DESCRIPTION 💜

these interfaces are here to support processing of an audit mask — that's a thing of type au_mask_t, iykyk — and they handle the conversion between numeric and text formats, plus figuring out whether or not a mask actually matches an event. three jobs, all slaying. 🔥

🧚 au_preselect()

this one calculates whether or not the audit event passed via event is matched by the audit mask passed via mask_p.

the sorf argument tells it whether or not to consider the event as a success — if the AU_PRS_SUCCESS flag is set — or failure — if the AU_PRS_FAILURE flag is set.

and then the flag argument accepts extra arguments that influence the behavior of au_preselect(), specifically:

• AU_PRS_REREAD — causes the event to be re-looked up rather than read from the cache 👀
• AU_PRS_USECACHE — forces use of the cache ⚡

🍓 getauditflagsbin()

converts a string representation of an audit mask — passed via a character string that auditstr points to — and returns the resulting mask, if it's valid, via *masks. love that for us 💅

🌈 getauditflagschar()

takes the audit event mask passed via *masks and converts it to a character string in a buffer pointed to by auditstr. 🎀

⚠️ bestie please read the "BUGS" section about how to provide a buffer of sufficient size. this is not a drill 😭

if the verbose flag is set, the class description string retrieved from audit_class(5) gets used; otherwise it's the two-character class name. two modes, both valid, we stan. ✨

---

🎀 IMPLEMENTATION NOTES 🎀

au_preselect() makes implicit use of various audit database routines, and it may influence the behavior of simultaneous or interleaved processing of those databases by other code. so like… it's not just vibing in its own lane, it's lowkey touching shared state. noted. 💀

---

👑 RETURN VALUES 👑

au_preselect()

• returns 0 on success
• returns -1 if there's a failure looking up the event type or other database access — in which case errno will be set to indicate the error
• returns 1 if the event is matched; 0 if it's not

getauditflagsbin() and getauditflagschar()

• return the value 0 if successful
• otherwise the value -1 is returned and the global variable errno is set to indicate the error

periodt. 📌

---

🔍 SEE ALSO 🔍

• libbsm(3)
• audit_class(5)

---

⭐ 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 real main-character origin story ngl 💖

---

🫶 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. absolute icons, all three of them. 👑

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

---

💀 BUGS 💀

• the errno variable may not always be properly set in the event of an error. 🙈 like, it might, but don't count on it.
• getauditflagschar() does not provide a way to indicate how long the character buffer is, in order to detect overflow. 😭 as a result, the caller must always provide a buffer of sufficient length for any possible mask — which may be calculated as three times the number of non-zero bits in the mask argument in the event non-verbose class names are used, and is not trivially predictable for verbose class names. this API should be replaced with a more robust one. 🚩

🚨 fr fr, do the math before you pass that buffer. this is the dangerous part of the page.

---

okay that's the whole thing! stay safe out there with your audit masks, bestie 💜✨

— cute little sign-off: this page came from Debian, dated April 19, 2005, and yeah the header said AU_MASK(3) at the top and the same down at the bottom. mwah 💋🌸