| CREDENTIALS(9F) | Kernel Functions for Drivers | CREDENTIALS(9F) |
credentials, CRED,
crdup, crfree,
crget, crhold,
kcred, zone_kcred —
Functions for obtaining credentials in the
kernel
#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
Volatile - This interface is still evolving in illumos. API and ABI stability is not guaranteed.
Some kernel interfaces require a credential as an argument. This page documents the credentials available in the system, as well as interfaces for creating new credentials.
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()The 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.
kcred is the root credential of the global zone. Its UIDs and GIDs are all 0. It has the following privilege sets by default:
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()The 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()The 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.
kcred and
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 modification 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.
These functions can be called from user and kernel contexts.
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 22, 2023 | OmniOS |