Tribblix: manual page: credentials.9f

CREDENTIALS(9F) Kernel Functions for Drivers CREDENTIALS(9F)

NAME

credentials, CRED, crdup, crfree, crget, crhold, kcred, zone_kcred -
Functions for obtaining credentials in the kernel

SYNOPSIS

#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

INTERFACE LEVEL

Volatile - This interface is still evolving in illumos. API and ABI
stability is not guaranteed.

PARAMETERS

cr pointer to the user credential structure.

DESCRIPTION

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
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.

Considerations

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.

CONTEXT

These functions can be called from user and kernel contexts.

RETURN VALUES

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.