--- /dev/null	Mon Aug 31 13:42:47 2020
+++ new/usr/src/man/man9f/credentials.9f	Mon Aug 31 13:42:47 2020
@@ -0,0 +1,201 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 Nexenta by DDN, Inc. All rights reserved.
+.\"
+.Dd Aug 21, 2020
+.Dt CREDENTIALS 9F
+.Os
+.Sh NAME
+.Nm credentials ,
+.Nm CRED ,
+.Nm crdup ,
+.Nm crfree ,
+.Nm crget ,
+.Nm crhold ,
+.Nm kcred ,
+.Nm zone_kcred
+.Nd Functions for obtaining credentials in the kernel
+.Sh SYNOPSIS
+.In sys/cred.h
+.Ft "cred_t *"
+.Fo CRED
+.Fc
+.Ft "cred_t *"
+.Fo crdup
+.Fa "cred_t *cr"
+.Fc
+.Ft "void"
+.Fo crfree
+.Fa "cred_t *cr"
+.Fc
+.Ft "cred_t *"
+.Fo crget
+.Fc
+.Ft "void"
+.Fo crhold
+.Fa "cred_t *cr"
+.Fc
+.Ft "cred_t *"
+.Fo zone_kcred
+.Fc
+.Vt cred_t *kcred
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+This interface is still evolving in illumos.
+API and ABI stability is not guaranteed.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa cr
+pointer to the user credential structure.
+.El
+.Sh 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.
+.Pp
+Most users do not need to create new credentials.
+Instead, users should generally use the credentials of the executing context.
+.Pp
+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.
+.Pp
+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
+.Fn crdup
+or
+.Fn crhold
+to ensure that the credentials remain valid.
+.Ss Fn CRED
+The
+.Fn CRED
+function returns the credential of the calling thread.
+Its contents depend on the calling context (user, kernel, interrupt).
+.Ss Fn crdup
+.Fn crdup
+returns a newly-allocated copy of
+.Fa cr
+with reference count of 1.
+It sleeps until the allocation succeeds.
+.Ss Fn crfree
+.Fn crfree
+releases a reference to
+.Fa cr .
+If this is the last reference, the credential is destroyed.
+.Ss Fn crhold
+.Fn crhold
+takes a reference to
+.Fa cr .
+.Ss Va kcred
+.Va kcred
+is the root credential of the global zone.
+Its UIDs and GIDs are all 0.
+It has the following privilege sets by default:
+.Bd -literal -offset indent
+E: basic,proc_secflags
+I: basic,proc_secflags
+P: basic,proc_secflags
+L: all
+.Ed
+.Pp
+.Dv NET_MAC_AWARE
+is set in the credential's flags.
+It is not marked privilege-aware.
+.Pp
+.Va kcred
+will never be freed by the system.
+.Ss Fn zone_kcred
+The
+.Fn 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.
+.Ss Fn crget
+The
+.Fn crget
+function returns a copy of
+.Fn 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
+.Fn crfree .
+It sleeps until the allocation succeeds.
+.Ss Considerations
+.Va kcred
+and
+.Fn 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.
+.Pp
+If the output of
+.Fn 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.
+.Pp
+.Va kcred ,
+.Fn zone_kcred ,
+and
+.Fn CRED
+are not suitable for modfication by the caller.
+Callers must use
+.Fn crdup
+to create a copy of these credentials that are suitable for modification.
+.Pp
+Callers of
+.Fn zone_kcred
+and
+.Fn 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
+.Em zone->zone_kcred
+explicitly.
+.Sh CONTEXT
+These functions can be called from
+.Sy user
+and
+.Sy kernel
+contexts.
+.Sh RETURN VALUES
+.Fn zone_kcred
+and
+.Fn CRED
+return a pointer to a
+.Vt cred_t
+that should not be modified.
+.Pp
+.Fn crget
+and
+.Fn crdup
+return a pointer to a newly allocated
+.Vt cred_t .
+.Pp
+.Fn zone_kcred ,
+.Fn CRED ,
+.Fn crdup ,
+and
+.Fn crget
+can never fail, and always return a valid credential.
+.Sh SEE ALSO
+.Xr ddi_cred 9f
