AU_TOKEN(3)

💅 AU_TOKEN(3) — the token-making chapter of your fave manual

okay bestie, welcome to AU_TOKEN(3), a page from the Library Functions Manual 💖 this is the libbsm glow-up guide — literally all the routines for generating BSM audit tokens, and we're gonna go through every single one together, no skips, no cap 🫶

---

✨ NAME ✨

so these are the icons, the whole squad of token-building functions — au_to_arg32, au_to_arg64, au_to_arg, au_to_attr64, au_to_data, au_to_exit, au_to_groups, au_to_newgroups, au_to_in_addr, au_to_in_addr_ex, au_to_ip, au_to_ipc, au_to_ipc_perm, au_to_iport, au_to_opaque, au_to_file, au_to_text, au_to_path, au_to_process32, au_to_process64, au_to_process, au_to_process32_ex, au_to_process64_ex, au_to_process_ex, au_to_return32, au_to_return64, au_to_return, au_to_seq, au_to_sock_inet32, au_to_sock_inet128, au_to_sock_inet, au_to_socket_ex, au_to_subject32, au_to_subject64, au_to_subject, au_to_subject32_ex, au_to_subject64_ex, au_to_subject_ex, au_to_me, au_to_exec_args, au_to_exec_env, au_to_header, au_to_header32, au_to_header64, au_to_header_ex, au_to_header32_ex, au_to_trailer, au_to_zonename.

and what do they all do? they're the routines for generating BSM audit tokens 💅 periodt.

---

🎀 LIBRARY 🎀

Basic Security Module Library — the one and only libbsm, link it with -lbsm 🦋

---

🌸 SYNOPSIS 🌸

first step always: bring the header in, bestie

#include <bsm/libbsm.h>

and now, the full cast, character for character 👑

token_t *
au_to_arg32(char n, const char *text, u_int32_t v);

token_t *
au_to_arg64(char n, const char *text, u_int64_t v);

token_t *
au_to_arg(char n, const char *text, u_int32_t v);

token_t *
au_to_attr32(struct vattr *attr);

token_t *
au_to_attr64(struct vattr *attr);

token_t *
au_to_attr(struct vattr *attr);

token_t *
au_to_data(char unit_print, char unit_type, char unit_count,
    const char *p);

token_t *
au_to_exit(int retval, int err);

token_t *
au_to_groups(int *groups);

token_t *
au_to_newgroups(u_int16_t n, gid_t *groups);

token_t *
au_to_in_addr(struct in_addr *internet_addr);

token_t *
au_to_in_addr_ex(struct in6_addr *internet_addr);

token_t *
au_to_ip(struct ip *ip);

token_t *
au_to_ipc(char type, int id);

token_t *
au_to_ipc_perm(struct ipc_perm *perm);

token_t *
au_to_iport(u_int16_t iport);

token_t *
au_to_opaque(const char *data, u_int16_t bytes);

token_t *
au_to_file(const char *file, struct timeval tm);

token_t *
au_to_text(const char *text);

token_t *
au_to_path(const char *text);

token_t *
au_to_process32(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);

token_t *
au_to_process64(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);

token_t *
au_to_process32_ex(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_addr_t *tid);

token_t *
au_to_process64_ex(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_addr_t *tid);

token_t *
au_to_return32(char status, u_int32_t ret);

token_t *
au_to_return64(char status, u_int64_t ret);

token_t *
au_to_return(char status, u_int32_t ret);

token_t *
au_to_seq(long audit_count);

token_t *
au_to_sock_inet32(struct sockaddr_in *so);

token_t *
au_to_sock_inet128(struct sockaddr_in6 *so);

token_t *
au_to_sock_int(struct sockaddr_in *so);

token_t *
au_to_socket_ex(u_short so_domain, u_short so_type,
    struct sockaddr *sa_local, struct sockaddr *sa_remote);

token_t *
au_to_subject32(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);

token_t *
au_to_subject64(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);

token_t *
au_to_subject(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);

token_t *
au_to_subject32_ex(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_addr_t *tid);

token_t *
au_to_subject64_ex(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_addr_t *tid);

token_t *
au_to_subject_ex(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_addr_t *tid);

token_t *
au_to_me(void);

token_t *
au_to_exec_args(char **argv);

token_t *
au_to_exec_env(char **envp);

token_t *
au_to_header(int rec_size, au_event_t e_type, au_emod_t emod);

token_t *
au_to_header32(int rec_size, au_event_t e_type, au_emod_t emod);

token_t *
au_to_header64(int rec_size, au_event_t e_type, au_emod_t e_mod);

token_t *
au_to_header_ex(int rec_size, au_event_t e_type, au_emod_t e_mod);

token_t *
au_to_header32_ex(int rec_size, au_event_t e_type, au_emod_t e_mod);

token_t *
au_to_trailer(int rec_size);

token_t *
au_to_zonename(const char *zonename);

yes, au_to_header64, au_to_header_ex and au_to_header32_ex really do name that last parameter e_mod instead of emod — we don't make the rules, we just report them 💀

---

💖 DESCRIPTION 💖

okay so here's the vibe: these interfaces support the allocation of BSM audit tokens, which get represented by token_t, for all kinds of data types ✨ like. that's the whole job. you got a thing, you want it to be an audit token, you call one of these bad boys.

now the one thing you CANNOT skip, bestie, listen to me 👇

au_errno_to_bsm(3) must be used to convert local errno(2) errors into BSM error numbers before they're passed to au_to_return(), au_to_return32(), and au_to_return64(). like, that's not optional, that's the whole assignment 🚨

---

🌈 RETURN VALUES 🌈

• Success — you get a pointer to a token_t 🎉 and that allocated token_t can be freed whenever you're done with it via a call to au_free_token(3) 💜
• Failure — you get NULL, and an error condition comes back via errno 😭

---

🦋 SEE ALSO 🦋

au_errno_to_bsm(3), libbsm(3) — go read those next, iykyk 📚

---

👑 HISTORY 👑

so the OpenBSM implementation was created by McAfee Research — that's the security division of McAfee Inc. — under contract to Apple Computer, Inc., back in 2004 🕰️ and then it was subsequently adopted by the TrustedBSD Project as the foundation for the OpenBSM distribution. main character origin story tbh 💅

---

⭐ 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 plus the audit event stream format were defined by Sun Microsystems 🌸 iconic, honestly.

---

okay that's the whole page, you ate that 🍓 this was AU_TOKEN(3) from the Debian build, dated April 19, 2005 — logged off, tokenized, and out 💖✨