From c8ea0e30834a32a861b4b11d028f0c23dfefffc0 Mon Sep 17 00:00:00 2001 From: rwatson Date: Tue, 23 Jul 2002 13:09:24 +0000 Subject: Update ucred.9 to talk a bit more about correct use of credentials, including documenting that ucreds must not be pulled out of thin air, when to use td_cred vs. p_ucred, how to avoid race conditions in credential updates, and why to use p_ucred when targetting a thread or process in an access control operation involving two processes. Reviewed by: julian, jhb (earlier revision) --- share/man/man9/ucred.9 | 66 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 8 deletions(-) (limited to 'share') diff --git a/share/man/man9/ucred.9 b/share/man/man9/ucred.9 index a952631..e69e275 100644 --- a/share/man/man9/ucred.9 +++ b/share/man/man9/ucred.9 @@ -144,15 +144,65 @@ structure. returns 0 if the credential has a reference count greater than 1; otherwise, 1 is returned. .Sh USAGE NOTES -In general in a system call, -you should always use the +As of +.Fx 5.0 , +the .Vt ucred -associated with the -thread doing the work rather than that of the process attached to it, -As that associated with the thread is guaranteed to be safely accessed -under SMP, and will remain stable for the duration of the call, even -in the face of a multithreaded application changing the process credentials -from another thread. +structure contains extensible fields. +This means that the correct protocol must always be followed to create +a fresh and writable credential structure: new credentials must always +be derived from existing credentials using +.Fn crget +and +.Fn crcopy . +.Pp +In the common case, credentials required for access control decisions are +used in a read-only manner. +In these circumstances, the thread credential +.Va td_ucred +should be used, as it requires no locking to access safely, and remains stable +for the duration of the call even in the face of a multi-threaded +application changing the process credentials from another thread. +Primitives such as +.Xr suser 9 +will assume the use of +.Va td_ucred +unless explicitly specified using +.Xr suser_cred 9 . +.Pp +During a process credential update, the process lock must be held across +check and update, to prevent race conditions. +The process credential, +.Va td->td_proc->p_ucred , +must be used both for check and update. +If a process credential is updated during a system call and checks against +the thread credential are to be made later during the same system call, +the thread credential must also be refreshed from the process credential +so as to prevent use of a stale value. +To avoid this scenario, it is recommended that system calls updating the +process credential by designed to avoid other authorization functions. +.Pp +If temporarily elevated privileges are required for a thread, the thread +credential can by replaced for the duration of an activity, or for +the remainder of the system call. +However, as a thread credential is often shared, appropriate care should be +taken to make sure modifications are made to a writable credential +through the use of +.Fn crget +and +.Fn crcopy . +.Pp +Caution should be exercised when checking authorization for a thread or +process perform an operation on another thread or process. +As a result of temporary elevation, the target thread credential should +.Em never +be used as the target credential in an access control decision: the process +credential associated with the thread, +.Va td->td_proc->p_ucred , +should be used instead. +For example, +.Xr p_candebug 9 +accepts a target process, not a target thread, for access control purposes. .Sh SEE ALSO .Xr uihold 9 .Sh AUTHORS -- cgit v1.1