| KAUTH(9) | Kernel Developer's Manual | KAUTH(9) |
kauth —
#include <sys/kauth.h>
kauth, or kernel authorization, is the subsystem
managing all authorization requests inside the kernel. It manages user
credentials and rights, and can be used to implement a system-wide security
policy. It allows external modules to plug-in the authorization process.
kauth introduces some new concepts, namely
“scopes” and “listeners”, which will be detailed
together with other useful information for kernel developers in this
document.
kauth types include the following:
kauth operates in various “scopes”, each
scope holding a group of “listeners”.
Each listener works as a callback for when an authorization request within the scope is made. When such a request is made, all listeners on the scope are passed common information such as the credentials of the request context, an identifier for the requested operation, and possibly other information as well.
Every listener examines the passed information and returns its decision regarding the requested operation. It can either return:
KAUTH_RESULT_ALLOWKAUTH_RESULT_DENYKAUTH_RESULT_DEFERFor an operation to be allowed, at least one listener has to
return KAUTH_RESULT_ALLOW while no other listener
returned KAUTH_RESULT_DENY.
Scopes manage listeners that operate in the same aspect of the system.
kauth exports a KPI that allows developers both of
NetBSD and third-party products to authorize requests,
access and modify credentials, create and remove scopes and listeners, and
perform other miscellaneous operations on credentials.
kauth provides a single authorization request routine,
which all authorization requests go through. This routine dispatches the
request to the listeners of the appropriate scope, together with four optional
user-data variables, and returns the augmented result.
It is declared as
int
kauth_authorize_action(kauth_scope_t
scope, kauth_cred_t cred,
kauth_action_t op, void *arg0,
void *arg1, void *arg2,
void *arg3)
An authorization request can return one of two possible values:
0
(zero)EPERMEach scope has its own authorization wrapper, to make it easy to call from various places by eliminating the need to specify the scope and/or cast values. The authorization wrappers are detailed in each scope's section.
kauth_authorize_action() has several
special cases, when it will always allow the request. These are for when the
request is issued by the kernel itself (indicated by the credentials being
either NOCRED or FSCRED), or
when there was no definitive decision from any of the listeners (i.e., it
was not explicitly allowed or denied) and no security model was loaded.
The authorization wrapper for this scope is declared as
int
kauth_authorize_generic(kauth_cred_t
cred, kauth_action_t op, void
*arg0)
The following operations are available for this scope:
KAUTH_GENERIC_ISSUSERUsing this request is strongly discouraged and should only be done as a temporary place-holder, as it is breaking the separation between the interface for authorization requests from the back-end implementation.
The authorization wrapper for this scope is declared as
int
kauth_authorize_system(kauth_cred_t
cred, kauth_action_t op, enum
kauth_system_req req, void *arg1,
void *arg2, void *arg3)
The following requests are available for this scope:
KAUTH_SYSTEM_ACCOUNTINGKAUTH_SYSTEM_CHROOTKAUTH_REQ_SYSTEM_CHROOT_CHROOTKAUTH_REQ_SYSTEM_CHROOT_FCHROOTKAUTH_SYSTEM_CPUreq can be any of the following:
KAUTH_REQ_SYSTEM_CPU_SETSTATEKAUTH_SYSTEM_DEBUGKAUTH_SYSTEM_DEVMAPPERKAUTH_SYSTEM_FILEHANDLEKAUTH_SYSTEM_FS_EXTATTRKAUTH_SYSTEM_FS_SNAPSHOTKAUTH_SYSTEM_FS_QUOTAarg1 is a struct mount * describing the file system mount in question. req can be one of the following:
KAUTH_REQ_SYSTEM_FS_QUOTA_GETarg2 is a uid_t with the user-id of the user whose quota information is to be retrieved.
KAUTH_REQ_SYSTEM_FS_QUOTA_ONOFFKAUTH_REQ_SYSTEM_FS_QUOTA_MANAGEarg2 is a uid_t with the user-id of the user whose quota/quota use is to be set.
KAUTH_REQ_SYSTEM_FS_QUOTA_NOLIMITKAUTH_SYSTEM_FS_RESERVEDSPACEKAUTH_SYSTEM_LFSKAUTH_REQ_SYSTEM_LFS_MARKVKAUTH_REQ_SYSTEM_LFS_BMAPVKAUTH_REQ_SYSTEM_LFS_SEGCLEANKAUTH_REQ_SYSTEM_LFS_SEGWAITKAUTH_REQ_SYSTEM_LFS_FCNTLKAUTH_SYSTEM_MAP_VA_ZEROKAUTH_SYSTEM_MODULEarg1 is the command.
KAUTH_SYSTEM_MKNODKAUTH_SYSTEM_MOUNTreq can be any of the following:
KAUTH_REQ_SYSTEM_MOUNT_DEVICEKAUTH_REQ_SYSTEM_MOUNT_GETKAUTH_REQ_SYSTEM_MOUNT_NEWarg1 is the struct vnode * on which the file system is to be mounted, arg2 is an int with the mount flags, and arg3 is a void * with file system specific data, if any.
KAUTH_REQ_SYSTEM_MOUNT_UNMOUNTarg1 is a struct mount * with the mount in question.
KAUTH_REQ_SYSTEM_MOUNT_UPDATEarg1 is the struct mount * of the existing mount, arg2 is an int with the new mount flags, and arg3 is a void * with file system specific data, if any.
KAUTH_REQ_SYSTEM_MOUNT_UMAPKAUTH_SYSTEM_MQUEUEKAUTH_SYSTEM_PSETreq can be any of the following:
KAUTH_REQ_SYSTEM_PSET_ASSIGNKAUTH_REQ_SYSTEM_PSET_BINDKAUTH_REQ_SYSTEM_PSET_CREATEKAUTH_REQ_SYSTEM_PSET_DESTROYKAUTH_SYSTEM_REBOOTKAUTH_SYSTEM_SETIDCOREKAUTH_SYSTEM_SEMAPHOREKAUTH_SYSTEM_SWAPCTLKAUTH_SYSTEM_SYSCTLKAUTH_REQ_SYSTEM_SYSCTL_ADDKAUTH_REQ_SYSTEM_SYSCTL_DELETEKAUTH_REQ_SYSTEM_SYSCTL_DESCKAUTH_REQ_SYSTEM_SYSCTL_MODIFYThis request might be deprecated in the future.
KAUTH_REQ_SYSTEM_SYSCTL_PRVTKAUTH_SYSTEM_SYSVIPCKAUTH_REQ_SYSTEM_SYSVIPC_BYPASSKAUTH_REQ_SYSTEM_SYSVIPC_SHM_LOCKKAUTH_REQ_SYSTEM_SYSVIPC_SHM_UNLOCKKAUTH_REQ_SYSTEM_SYSVIPC_MSGQ_OVERSIZEKAUTH_SYSTEM_TIMEKAUTH_REQ_SYSTEM_TIME_ADJTIMEKAUTH_REQ_SYSTEM_TIME_NTPADJTIMEKAUTH_REQ_SYSTEM_TIME_SYSTEMarg1 is a struct timespec * with the new time, arg2 is a struct timeval * with the delta from the current time, arg3 is a bool indicating whether the caller is a device context (e.g. /dev/clockctl) or not.
KAUTH_REQ_SYSTEM_TIME_RTCOFFSETKAUTH_REQ_SYSTEM_TIME_TIMECOUNTERSKAUTH_SYSTEM_VERIEXECKAUTH_REQ_SYSTEM_VERIEXEC_ACCESSKAUTH_REQ_SYSTEM_VERIEXEC_MODIFYThe authorization wrapper for this scope is declared as
int
kauth_authorize_process(kauth_cred_t
cred, kauth_action_t op, struct
proc *p, void *arg1, void
*arg2, void *arg3)
The following operations are available for this scope:
KAUTH_PROCESS_KTRACEIf arg1 is
KAUTH_REQ_PROCESS_KTRACE_PERSISTENT, this checks
if persistent tracing can be done. Persistent tracing maintains the
trace across a set-user-id/set-group-id
exec(3), and normally
requires privileged credentials.
KAUTH_PROCESS_PROCFSarg1 is the struct
pfsnode * for the target element in the target process, and
arg2 is the access type, which can be either
KAUTH_REQ_PROCESS_PROCFS_READ,
KAUTH_REQ_PROCESS_PROCFS_RW, or
KAUTH_REQ_PROCESS_PROCFS_WRITE, indicating
control, read,
read-write, or write access
respectively.
KAUTH_PROCESS_PTRACEarg1 is the ptrace(2) command.
KAUTH_PROCESS_CANSEEarg1 indicates the class of information
being viewed, and can be either of
KAUTH_REQ_PROCESS_CANSEE_ARGS,
KAUTH_REQ_PROCESS_CANSEE_ENTRY,
KAUTH_REQ_PROCESS_CANSEE_ENV, or
KAUTH_REQ_PROCESS_CANSEE_OPENFILES.
KAUTH_PROCESS_SCHEDULER_GETAFFINITYKAUTH_PROCESS_SCHEDULER_SETAFFINITYKAUTH_PROCESS_SCHEDULER_GETPARAMKAUTH_PROCESS_SCHEDULER_SETPARAMKAUTH_PROCESS_SIGNALp is the process the signal is being posted to, and arg1 is the signal number.
KAUTH_PROCESS_CORENAMEarg1 can be
KAUTH_REQ_PROCESS_CORENAME_GET or
KAUTH_REQ_PROCESS_CORENAME_SET, indicating
access to read or write the process' corename, respectively.
When modifying the corename, arg2 holds the new corename to be used.
KAUTH_PROCESS_FORKKAUTH_PROCESS_KEVENT_FILTERKAUTH_PROCESS_NICEKAUTH_PROCESS_RLIMITarg1 can be
KAUTH_REQ_PROCESS_RLIMIT_GET or
KAUTH_REQ_PROCESS_RLIMIT_SET, indicating access
to read or write the process' resource limits, respectively, or
KAUTH_REQ_PROCESS_RLIMIT_BYPASS to check if the
limit enforcement can be bypassed.
When modifying resource limits, arg2 is the new value to be used and arg3 indicates which resource limit is to be modified.
KAUTH_PROCESS_SETIDKAUTH_PROCESS_STOPFLAGarg1 indicates the flag, and can be
either P_STOPEXEC,
P_STOPEXIT, or
P_STOPFORK respectively.
The authorization wrapper for this scope is declared as
int
kauth_authorize_network(kauth_cred_t
cred, kauth_action_t op, enum
kauth_network_req req, void *arg1,
void *arg2, void *arg3)
The following operations are available for this scope:
KAUTH_NETWORK_ALTQreq indicates the ALTQ subsystem in question, and can be one of the following:
KAUTH_REQ_NETWORK_ALTQ_AFMAPKAUTH_REQ_NETWORK_ALTQ_BLUEKAUTH_REQ_NETWORK_ALTQ_CBQKAUTH_REQ_NETWORK_ALTQ_CDNRKAUTH_REQ_NETWORK_ALTQ_CONFKAUTH_REQ_NETWORK_ALTQ_FIFOQKAUTH_REQ_NETWORK_ALTQ_HFSCKAUTH_REQ_NETWORK_ALTQ_JOBSKAUTH_REQ_NETWORK_ALTQ_PRIQKAUTH_REQ_NETWORK_ALTQ_REDKAUTH_REQ_NETWORK_ALTQ_RIOKAUTH_REQ_NETWORK_ALTQ_WFQKAUTH_NETWORK_BINDreq allows to indicate the type of the request to structure listeners and callers easier. Supported request types:
KAUTH_REQ_NETWORK_BIND_PORTKAUTH_REQ_NETWORK_BIND_PRIVPORTKAUTH_NETWORK_FIREWALLreq indicates the sub-action, and can be one of the following:
KAUTH_REQ_NETWORK_FIREWALL_FWKAUTH_REQ_NETWORK_FIREWALL_NATKAUTH_NETWORK_INTERFACEarg1 is (optionally) the struct ifnet * associated with the interface. arg2 is (optionally) an int describing the interface-specific operation. arg3 is (optionally) a pointer to the interface-specific request structure. req indicates the sub-action, and can be one of the following:
KAUTH_REQ_NETWORK_INTERFACE_GETKAUTH_REQ_NETWORK_INTERFACE_GETPRIVKAUTH_REQ_NETWORK_INTERFACE_SETKAUTH_REQ_NETWORK_INTERFACE_SETPRIVKAUTH_REQ_NETWORK_INTERFACE_FIRMWARENote that unless the struct ifnet * for the interface was passed in arg1, there's no way to tell what structure arg3 is.
KAUTH_NETWORK_INTERFACE_BRIDGEreq can be one of the following:
KAUTH_REQ_NETWORK_INTERFACE_BRIDGE_GETPRIVKAUTH_REQ_NETWORK_INTERFACE_BRIDGE_SETPRIVKAUTH_NETWORK_INTERFACE_PPPreq can be one of the following:
KAUTH_REQ_NETWORK_INTERFACE_PPP_ADDKAUTH_NETWORK_INTERFACE_PVCKAUTH_REQ_NETWORK_INTERFACE_PVC_ADDKAUTH_NETWORK_INTERFACE_SLIPreq can be one of the following:
KAUTH_REQ_NETWORK_INTERFACE_SLIP_ADDKAUTH_NETWORK_INTERFACE_STRIPreq can be one of the following:
KAUTH_REQ_NETWORK_INTERFACE_STRIP_ADDKAUTH_NETWORK_INTERFACE_TUNreq can be one of the following:
KAUTH_REQ_NETWORK_INTERFACE_TUN_ADDKAUTH_NETWORK_IPSECKAUTH_REQ_NETWORK_IPSEC_BYPASSKAUTH_NETWORK_IPV6KAUTH_REQ_NETWORK_IPV6_HOPBYHOPKAUTH_REQ_NETWORK_IPV6_JOIN_MULTICASTKAUTH_NETWORK_FORWSRCRTKAUTH_NETWORK_NFSreq can be any of the following:
KAUTH_REQ_NETWORK_NFS_EXPORTKAUTH_REQ_NETWORK_NFS_SVCKAUTH_NETWORK_ROUTEarg1 is the struct rt_msghdr * for the request.
KAUTH_NETWORK_SMBreq can be one of the following:
KAUTH_REQ_NETWORK_SMB_SHARE_ACCESSarg1 is a struct smb_share * describing the SMB share, and arg2 is a mode_t with the desired access mode.
KAUTH_REQ_NETWORK_SMB_SHARE_CREATEarg1 is a struct smb_sharespec * describing the share to be created.
KAUTH_REQ_NETWORK_SMB_VC_ACCESSarg1 is a struct smb_vc * describing the SMB VC, and arg2 is a mode_t with the desired access mode.
KAUTH_REQ_NETWORK_SMB_VC_CREATEarg1 is a struct smb_vcspec * describing the VC to be created.
KAUTH_NETWORK_SOCKETreq allows to indicate the type of the request to structure listeners and callers easier. Supported request types:
KAUTH_REQ_NETWORK_SOCKET_RAWSOCKKAUTH_REQ_NETWORK_SOCKET_OPENKAUTH_REQ_NETWORK_SOCKET_CANSEEarg1 is a struct socket * describing the socket.
KAUTH_REQ_NETWORK_SOCKET_DROParg1 is a struct socket * describing the socket.
KAUTH_REQ_NETWORK_SOCKET_SETPRIVarg1 is a struct socket * describing the socket, arg2 is a u_long describing the socket option.
The authorization wrapper for this scope is declared as
int
kauth_authorize_machdep(kauth_cred_t
cred, kauth_action_t op, void
*arg0, void *arg1, void
*arg2, void *arg3)
The actions on this scope provide a set that may or may not affect all platforms. Below is a list of available actions, along with which platforms are affected by each.
KAUTH_MACHDEP_CACHEFLUSHKAUTH_MACHDEP_CPU_UCODE_APPLYKAUTH_MACHDEP_IOPERM_GETKAUTH_MACHDEP_IOPERM_SETKAUTH_MACHDEP_IOPLKAUTH_MACHDEP_LDT_GETKAUTH_MACHDEP_LDT_SETKAUTH_MACHDEP_MTRR_GETKAUTH_MACHDEP_MTRR_SETKAUTH_MACHDEP_NVRAMKAUTH_MACHDEP_PXGKAUTH_MACHDEP_UNMANAGEDMEMIn addition to the standard authorization wrapper:
int
kauth_authorize_device(kauth_cred_t
cred, kauth_action_t op, void
*arg0, void *arg1, void
*arg2, void *arg3)
this scope provides authorization wrappers for various device types.
int
kauth_authorize_device_tty(kauth_cred_t
cred, kauth_action_t op, struct
tty *tty)
Authorizes requests for terminal devices on the system. The third argument, tty, is the terminal device in question. It is passed to the listener as arg0. The second argument, op, is the action and can be one of the following:
KAUTH_DEVICE_TTY_OPENKAUTH_DEVICE_TTY_PRIVSETKAUTH_DEVICE_TTY_STIKAUTH_DEVICE_TTY_VIRTUALint
kauth_authorize_device_spec(kauth_cred_t
cred, enum kauth_device_req req,
struct vnode *vp)
Authorizes requests for special files, usually disk devices, but also direct memory access, on the system.
It passes KAUTH_DEVICE_RAWIO_SPEC as the
action to the listener, and accepts two arguments.
req, passed to the listener as
arg0, is access requested, and can be one of
KAUTH_REQ_DEVICE_RAWIO_SPEC_READ,
KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE, or
KAUTH_REQ_DEVICE_RAWIO_SPEC_RW, representing read,
write, or both read/write access respectively. vp is
the vnode of the special file in question, and is passed to the listener as
arg1.
Keep in mind that it is the responsibility of the security model
developer to check whether the underlying device is a disk or the system
memory, using iskmemdev():
if ((vp->v_type == VCHR) &&
iskmemdev(vp->v_un.vu_specinfo->si_rdev))
/* system memory access */
int
kauth_authorize_device_passthru(kauth_cred_t
cred, dev_t dev, u_long
mode, void *data)
Authorizes hardware passthru requests, or user commands passed directly to the hardware. These have the potential of resulting in direct disk and/or memory access.
It passes KAUTH_DEVICE_RAWIO_PASSTHRU as
the action to the listener, and accepts three arguments.
dev, passed as arg1 to the
listener, is the device for which the request is made.
mode, passed as arg0 to the
listener, is a generic representation of the access mode requested. It can
be one or more (binary-OR'd) of the following:
data, passed as arg2 to the listener, is device-specific data that may be associated with the request.
arg0 is an enum kauth_device_req with one of the following values:
KAUTH_REQ_DEVICE_BLUETOOTH_BCSP_ADDarg0 is an enum kauth_device_req with one of the following values:
KAUTH_REQ_DEVICE_BLUETOOTH_BTUART_ADDarg0 is the packet type. For
HCI_CMD_PKT packets, arg1
is the opcode, for HCI_EVENT_PKT packets,
arg1 is the event ID, and for
HCI_ACLDATA_PKT or
HCI_SCODATA_PKT packets,
arg1 is the connection handle.
arg0 is a struct hci_unit * describing the HCI unit, arg1 is a hci_cmd_hdr_t * describing the packet header.
arg0 is a struct hci_unit * describing the HCI unit, arg1 is a struct btreq * describing the request, and arg2 is a u_long describing the command.
The authorization wrapper for this scope is declared as
int
kauth_authorize_vnode(kauth_cred_t
cred, kauth_action_t action,
vnode_t *vp, vnode_t *dvp,
int fs_decision)
This scope is heavily used in file system code and can potentially affect system-wide performance. Therefore, there are several things developers should know when using it.
First, the action parameter is a bit-mask
and multiple actions can be binary-OR'd and authorized in a single call. Two
helper functions help generate the action value for a
couple of common cases: translating file system access to a
kauth action and checking access to a vnode.
The first,
kauth_mode_to_action(mode_t
access_mode), and returns a kauth_action_t
representing the desired access modes. Another function,
kauth_access_action(mode_t
access_mode, enum vtype v_type,
mode_t file_mode), returns a
kauth_action_t suitable for use in many file system
access(2) implementations. It
calls the aforementioned kauth_mode_to_action(), but
before returning also adds the KAUTH_VNODE_IS_EXEC
flag if needed. See below for the meaning of this flag and how its necessity
is determined.
Second, it is recommended to be very careful with adding listeners
on this scope. A special parameter, fs_decision,
allows different file systems to instrument different policies without
adding their own listener. This parameter is special because it also serves
as a fall-back decision when no
secmodel(9) is present to
prevent a fail-open scenario. It can take either an
errno(2) value or
“KAUTH_VNODE_REMOTEFS”, indicating that the file system on
which the authorization is made is remote and cannot provide us with a
fall-back decision. In this case, kauth can only
short-circuit the request but the file system will have the last word if
there is no definitive allow or deny decision.
The value of fs_decision can be hard-coded or determined by calling an internal function implementing a policy. For the latter case, genfs(9) provides a set of helper functions that implement common policies that file systems can use. The calling convention is as follows:
int error; error = kauth_authorize_vnode(..., genfs_can_foo(...));
Actions on the vnode scope are of two types: operations and flags. An operation is similar in concept to actions on other scopes in the sense that it represents an operation desired by the caller. A flag is an indicator of additional information about the vnode that a file system can set in order to allow the listener to make a more informed decision.
Actions include the following:
Flags include the following:
The macro FS_OBJECT_CAN_EXEC() can be
used to help determine if this flag should be set. This macro determines
a file system object to be executable if it is a directory (in which
case we say it is searchable) or if it has at least one executable bit
set in its mode.
Setting this flag helps a listener know that a vnode is executable and is used in implementing privileged access to files and directories while maintaining semantics that prevent execution until a file is marked as an executable. An example for using this in listener code is:
if (privileged) {
/* Always allow read/write; execute only if executable. */
if ((action & KAUTH_VNODE_EXECUTE) == 0 ||
(action & KAUTH_VNODE_IS_EXEC))
result = KAUTH_RESULT_ALLOW;
}
Finally, the vnode scope authorization wrapper returns
EACCES in case of an error, to maintain file
system semantics. File systems can override this value if needed.
kauth framework to provide
hooking to credential-related operations.
It is a “notify-only” scope, allowing hooking operations such as initialization of new credentials, credential inheritance during a fork, and copying and freeing of credentials. The main purpose for this scope is to give a security model a way to control the aforementioned operations, especially in cases where the credentials hold security model-private data.
Notifications are made using the following function, which is
internal to kauth:
int
kauth_cred_hook(kauth_cred_t
cred, kauth_action_t action,
void *arg0, void *arg1)
With the following actions:
KAUTH_CRED_COPYKAUTH_CRED_FORKcred are the credentials of the lwp context doing the fork, and arg0 and arg1 are both struct proc * of the parent and child processes, respectively.
KAUTH_CRED_CHROOTchange_root() (see
vfs(9) ).
Arg0 is the new struct cwdinfo * of the process.
KAUTH_CRED_FREEKAUTH_CRED_INITSince this is a notify-only scope, all listeners are required to
return KAUTH_RESULT_ALLOW.
kauth has a variety of accessor and mutator routines to
handle kauth_cred_t objects.
The following routines can be used to access and modify the user- and group-ids in a kauth_cred_t:
kauth_cred_getuid(kauth_cred_t
cred)kauth_cred_geteuid(kauth_cred_t
cred)kauth_cred_getsvuid(kauth_cred_t
cred)kauth_cred_setuid(kauth_cred_t
cred, uid_t uid)kauth_cred_seteuid(kauth_cred_t
cred, uid_t uid)kauth_cred_setsvuid(kauth_cred_t
cred, uid_t uid)kauth_cred_getgid(kauth_cred_t
cred)kauth_cred_getegid(kauth_cred_t
cred)kauth_cred_getsvgid(kauth_cred_t
cred)kauth_cred_setgid(kauth_cred_t
cred, gid_t gid)kauth_cred_setegid(kauth_cred_t
cred, gid_t gid)kauth_cred_setsvgid(kauth_cred_t
cred, gid_t gid)kauth_cred_getrefcnt(kauth_cred_t
cred)The following routines can be used to access and modify the group list in a kauth_cred_t:
kauth_cred_ismember_gid(kauth_cred_t
cred, gid_t gid, int
*resultp)If it is, resultp will be set to one, otherwise, to zero.
The return value is an error code, or zero for success.
kauth_cred_ngroups(kauth_cred_t
cred)kauth_cred_group(kauth_cred_t
cred, u_int idx)kauth_cred_setgroups(kauth_cred_t
cred, const gid_t *groups,
size_t ngroups, uid_t gmuid,
enum uio_seg seg)UIO_USERSPACE or
UIO_SYSSPACE indicating whether
groups is a user or kernel space address.
Any groups remaining will be set to an invalid value.
gmuid is unused for now, and to maintain interface compatibility with the Darwin KPI.
The return value is an error code, or zero for success.
kauth_cred_getgroups(kauth_cred_t
cred, gid_t *groups, size_t
ngroups, enum uio_seg seg)UIO_USERSPACE or
UIO_SYSSPACE indicating whether
groups is a user or kernel space address.
The return value is an error code, or zero for success.
kauth provides an interface to allow attaching
security-model private data to credentials.
The use of this interface has two parts that can be divided to direct and indirect control of the private-data. Directly controlling the private data is done by using the below routines, while the indirect control is often dictated by events such as process fork, and is handled by listening on the credentials scope (see above).
Attaching private data to credentials works by registering a key to serve as a unique identifier, distinguishing various sets of private data that may be associated with the credentials. Registering, and deregistering, a key is done by using these routines:
kauth_register_key(secmodel_t
sm, kauth_key_t *keyp)The function returns 0 on success and an error code (see errno(2)) on failure.
kauth_deregister_key(kauth_key_t
key)Once registered, private data may be manipulated by the following routines:
kauth_cred_setdata(kauth_cred_t
cred, kauth_key_t key, void
*data)kauth_cred_getdata(kauth_cred_t
cred, kauth_key_t key)Note that it is required to use the above routines every time the
private data is changed, i.e., using
kauth_cred_getdata() and later modifying the private
data should be accompanied by a call to
kauth_cred_setdata() with the “new”
private data.
kauth provides an interface for handling shared
credentials.
When a kauth_cred_t is first allocated, its reference count is set to 1. However, with time, its reference count can grow as more objects (processes, LWPs, files, etc.) reference it.
The following routines are available for managing credentials reference counting:
kauth_cred_hold(kauth_cred_t
cred)kauth_cred_free(kauth_cred_t
cred)If the reference count dropped to zero, the memory used by cred will be freed.
Credential inheritance happens during a fork(2), and is handled by the following function:
void
kauth_proc_fork(struct proc
*parent, struct proc *child)
When called, it references the parent's credentials from the
child, and calls the credentials scope's hook with the
KAUTH_CRED_FORK action to allow security
model-specific handling of the inheritance to take place.
The kauth_cred_t objects have their own memory management routines:
kauth_cred_alloc(void)The following routines are available for these cases:
kauth_uucred_to_cred(kauth_cred_t
cred, const struct uucred *uucred)This includes effective user- and group-ids, a number of groups, and a group list. The reference count is set to one.
Note that kauth will try to copy as
many groups as can be held inside a
kauth_cred_t.
kauth_cred_to_uucred(struct uucred
*uucred, const kauth_cred_t cred)This includes effective user- and group-ids, a number of groups, and a group list.
Note that kauth will try to copy as
many groups as can be held inside a struct
uucred.
kauth_cred_uucmp(kauth_cred_t
cred, struct uucred *uucred)Common values that will be compared are effective user- and group-ids, and the group list.
kauth are:
kauth_cred_clone(kauth_cred_t
cred1, kauth_cred_t cred2)kauth_cred_dup(kauth_cred_t
cred)What this routine does is call
kauth_cred_alloc() followed by a call to
kauth_cred_clone().
kauth_cred_copy(kauth_cred_t
cred)kauth_cred_dup(), except for a few
differences.
If cred already has a reference count of
one, it will be returned. Otherwise, a new
kauth_cred_t will be allocated and the credentials
from cred will be cloned to it. Last, a call to
kauth_cred_free() for cred
will be done.
kauth_cred_get(void)kauth provides routines to manage the creation and
deletion of scopes on the system.
Note that the built-in scopes, the “generic” scope and the “process” scope, can't be deleted.
kauth_register_scope(const char
*id, kauth_scope_callback_t cb,
void *cookie)kauth_deregister_scope(kauth_scope_t
scope)kauth are authorization callbacks that are
called during an authorization request in the scope which they belong to.
When an authorization request is made, all listeners associated with a scope are called to allow, deny, or defer the request.
It is enough for one listener to deny the request in order for the request to be denied; but all listeners are called during an authorization process none-the-less. All listeners are required to allow the request for it to be granted, and in a case where all listeners defer the request — leaving the decision for other listeners — the request is denied.
The following KPI is provided for the management of listeners:
kauth_listen_scope(const char
*id, kauth_scope_callback_t cb,
void *cookie)kauth_unlisten_scope(kauth_listener_t
listener)kauth provides no means for
synchronization within listeners. It is the programmer's responsibility to
make sure data used by the listener is properly locked during its use, as it
can be accessed simultaneously from the same listener called multiple times.
It is also the programmer's responsibility to do garbage collection after
the listener, possibly freeing any allocated data it used.
The common method to do the above is by having a reference count to each listener. On entry to the listener, this reference count should be raised; on exit, lowered.
During the removal of a listener, first
kauth_scope_unlisten() should be called to make sure
the listener code will not be entered in the future. Then, the code should
wait (possibly sleeping) until the reference count drops to zero. When that
happens, it is safe to do the final cleanup.
Listeners might sleep, so no locks can be held when calling an authorization wrapper.
if (suser(cred, &acflag) == 0) /* allow privileged operation */
Using the new interface, you must ask for a specific privilege explicitly. For example, checking whether it is possible to open a socket would look something like this:
if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET,
KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM,
IPPROTO_TCP) == 0)
/* allow opening the socket */
Note that the securelevel implications were also
integrated into the kauth framework so you don't
have to note anything special in the call to the authorization wrapper, but
rather just have to make sure the security model handles the request as you
expect it to.
To do that you can just grep(1) in the relevant security model directory and have a look at the code.
kauth provides a large set of both detailed and
more or less generic requests, it might be needed eventually to introduce more
scopes, actions, or requests.
Adding a new scope should happen only when an entire subsystem is introduced and it is assumed other parts of the kernel may want to interfere with its inner-workings. When a subsystem that has the potential of impacting the security of the system is introduced, existing security modules must be updated to also handle actions on the newly added scope.
New actions should be added when sets of operations not covered at all belong in an already existing scope.
Requests (or sub-actions) can be added as subsets of existing actions when an operation that belongs in an already covered area is introduced.
Note that all additions should include updates to this manual, the security models shipped with NetBSD, and the example skeleton security model.
The kernel authorization framework in NetBSD first appeared in NetBSD 4.0, and is a clean-room implementation based on Apple TN2127, available at http://developer.apple.com/technotes/tn2005/tn2127.html
kauth in NetBSD is still
under active development, it is likely that the ABI, and possibly the API,
will differ between NetBSD versions. Developers are to
take notice of this fact in order to avoid building code that expects one
version of the ABI and running it in a system with a different one.
Jason R. Thorpe
<thorpej@NetBSD.org>
provided guidance and answered questions about the Darwin
implementation.
| July 14, 2018 | NetBSD 9.2 |