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)

1 files changed, 58 insertions, 8 deletions

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