| CREDENTIALS(9F) | Kernel Functions for Drivers | CREDENTIALS(9F) |
credentials, CRED,
crdup, crfree,
crget, crhold,
kcred, zone_kcred —
#include <sys/cred.h>
cred_t *
CRED();
cred_t *
crdup(cred_t *cr);
void
crfree(cred_t *cr);
cred_t *
crget();
void
crhold(cred_t *cr);
cred_t *
zone_kcred();
cred_t *kcred
Most users do not need to create new credentials. Instead, users should generally use the credentials of the executing context.
This interface is primarily intended for services that must perform operations on behalf of multiple remotely authenticated users, whose authentication context is unrelated to the context of the executing thread or process. Drivers MUST NOT create new credentials. Drivers should use the provided credential.
For functions that do not return new credentials, if the
credentials will be used outside of their context (i.e. if the output of
zone_kcred() is referenced outside of the zone), then one should use
crdup() or crhold() to
ensure that the credentials remain valid.
CRED()CRED() function returns the credential of the
calling thread. Its contents depend on the calling context (user, kernel,
interrupt).
crdup()crdup() returns a newly-allocated copy of
cr with reference count of 1. It sleeps until the
allocation succeeds.
crfree()crfree() releases a reference to
cr. If this is the last reference, the credential is
destroyed.
crhold()crhold() takes a reference to cr.
E: basic,proc_secflags I: basic,proc_secflags P: basic,proc_secflags L: all
NET_MAC_AWARE is set in the credential's
flags. It is not marked privilege-aware.
kcred will never be freed by the system.
zone_kcred()zone_kcred() function returns the root credential of
the zone to which the calling thread belongs. This cred is derived from the
global kcred, minus any privileges denied to the zone.
crget()crget() function returns a copy of
zone_kcred() suitable for modification by the caller.
This is useful for obtaining a default, well-initialized credential in the
appropriate zone context, that is free of privileges or limitations of the
originating thread. It must be freed with crfree(). It
sleeps until the allocation succeeds.
zone_kcred() are not
privilege-aware, and have all IDs set to 0. This causes their Limit set to be
used in place of the Effective and Permitted sets, which significantly expands
their privileges.
If the output of crget() is not later
marked as privilege aware, and its UID is not set to a non-zero value, then
its Limit set will be used in place of its Effective and Permitted sets,
significantly expanding its privileges. Callers should either mark the
credential as privilege-aware, reduce the Limit set appropriately, or ensure
that they intend for zero-uid users to have expanded privileges.
kcred, zone_kcred(),
and CRED() are not suitable for modfication by the
caller. Callers must use crdup() to create a copy of
these credentials that are suitable for modification.
Callers of zone_kcred() and
crget() must take care to ensure that the calling
thread is executing in the context of the appropriate zone. If the thread is
performing work on behalf of a different zone, or if one is uncertain of the
zone context of the calling thread, then one should find the appropriate
zone by other means, and reference zone->zone_kcred
explicitly.
zone_kcred() and CRED() return a
pointer to a cred_t that should not be modified.
crget() and
crdup() return a pointer to a newly allocated
cred_t.
zone_kcred(),
CRED(), crdup(), and
crget() can never fail, and always return a valid
credential.
| August 21, 2020 | illumos |