VACCESS(9)

👑 VACCESS(9) — the kernel dev manual, but make it cute 👑

okay bestie, gather round, because we're about to talk about vaccess, aka the function that looks at a vnode and goes "hmm, are you allowed to do that?" and honestly? it's giving security model royalty. 💅

---

✨ NAME ✨

vaccess — generate an access control decision using vnode parameters 🎀

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/vnode.h>

int
vaccess(enum vtype type, mode_t file_mode, uid_t file_uid,
    gid_t file_gid, accmode_t accmode, struct ucred *cred,
    int *privused);

---

🦋 DESCRIPTION 🦋

So like, this call implements the logic for the Unix discretionary file security model that's common to so many file systems in FreeBSD. No cap, it's the blueprint. 🫶

It accepts:

• the vnode's type, type
• permissions via file_mode
• the owning UID, file_uid
• the owning GID, file_gid
• the desired access mode, accmode
• the requesting credential, cred
• and an optional call-by-reference int pointer that reports whether or not privilege was required for a successful evaluation of the call — that's privused

About privused, bestie, listen: the caller can set that pointer to NULL if she simply does not wish to be informed about privilege information. or, she can point it at an integer that will be set to 1 if privilege is used, and 0 otherwise. it's giving optional. it's giving your choice. 🙈

This call is intended to support implementations of VOP_ACCESS(9), which will use their own access methods to retrieve the vnode properties, and then invoke vaccess() to perform the actual check. Implementations of VOP_ACCESS(9) may choose to implement additional security mechanisms, and the results of those will be composed with the return value. so like, vaccess() is the main character but she's happy to share the spotlight. ✨

💜 the algorithm, aka how she decides 💜

The algorithm used by vaccess() selects a component of the file permission bits based on comparing the passed credential, file owner, and file group.

1. If the credential's effective UID matches the file owner → the owner component of the permission bits is selected. 👑
2. If the UID does not match → the credential's effective GID, followed by additional groups, are compared with the file group. If there is a match → the group component of the permission bits is selected.
3. If neither the credential UID nor GIDs match the passed file owner and group → the other component of the permission bits is selected.

Once the appropriate protections are selected for the current credential, the requested access mode — in combination with the vnode type — will be compared with the discretionary rights available for the credential. And if the rights granted by those discretionary protections are insufficient? then super-user privilege, if it's available for the credential, will also be considered. she checks every angle, fr fr. 🔥

---

⭐ RETURN VALUES ⭐

vaccess() will return 0 on success, or a non-zero error value on failure. simple. iconic. periodt.

---

💀 ERRORS 💀

• [EACCES] — Permission denied. An attempt was made to access a file in a way forbidden by its file access permissions. 🚫
• [EPERM] — Operation not permitted. An attempt was made to perform an operation limited to processes with appropriate privileges or to the owner of a file or other resource. 😭

---

🌈 SEE ALSO 🌈

vaccess_acl_nfs4(9), vaccess_acl_posix1e(9), vnode(9), VOP_ACCESS(9)

---

🎀 AUTHORS 🎀

This manual page and the current implementation of vaccess() were written by Robert Watson. thank you king, we are obsessed. 👑

---

and that's the whole vibe check, bestie — this page came out of the Debian edition of the Kernel Developer's Manual, dated September 18, 2009, and honestly it ate. go forth and access-control responsibly 💖✨🌸