sys/ucred.h Kernel.framework

@struct ucred @brief In-kernel credential structure. @discussion Note that this structure should not be used outside the kernel, nor should it or copies of it be exported outside. A credential has a relatively simple lifetime, with 3 phases: 1. construction 2. publication 3. death Construction ~~~~~~~~~~~~ The construction phase happens via various MACF hooks, typically with the "associate" or "update" suffix. During this phase, the credential structure is completely private, and can't be looked up. All "associate" and "update" callouts are made serially (so no locking is required for clients to ensure atomicity of updates) and keeping references on the cred is forbidden. Publication ~~~~~~~~~~~ Once the credential has been constructed, it is being published on its owning structure (typically the proc) and added into a uniquing hash table. After this point, the credential becomes a refcounted immutable "value type" data structure. MACF clients which have set labels are not allowed to modify this label pointer anymore (though their label itself might be mutable or contain caches). It means that while a client holds a reference on a credential, it can consult labels without further synchronization or references. Death ~~~~~ Credentials are managed under the smr_kauth_cred domain, and retired according to the <kern/smr.h> rules. Once it is safe for the credential to be freed, callbacks will clean up the resources the credential holds onto via the MACF cred_label_destroy() hook. It means that under an smr_kauth_cred critical section, clients can consult labels without further synchronization or references, even after the credential hit a "0" refcount. KPIs to interact with this data structure live in <sys/kauth.h>