diff options
Diffstat (limited to 'usr/src/man/man9f')
| -rw-r--r-- | usr/src/man/man9f/Makefile | 20 | ||||
| -rw-r--r-- | usr/src/man/man9f/credentials.9f | 201 |
2 files changed, 219 insertions, 2 deletions
diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile index 82b64823b1..a61f028374 100644 --- a/usr/src/man/man9f/Makefile +++ b/usr/src/man/man9f/Makefile @@ -13,7 +13,7 @@ # Copyright 2017, Richard Lowe # Copyright 2014 Garrett D'Amore <garrett@damore> # Copyright 2019 Joyent, Inc. -# Copyright 2016 Nexenta Systems, Inc. +# Copyright 2020 Nexenta by DDN, Inc. All rights reserved. # Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org> # @@ -70,6 +70,7 @@ MANFILES= ASSERT.9f \ copyin.9f \ copymsg.9f \ copyout.9f \ + credentials.9f \ csx_AccessConfigurationRegister.9f \ csx_CS_DDI_Info.9f \ csx_ConvertSize.9f \ @@ -556,6 +557,7 @@ MANFILES= ASSERT.9f \ MANLINKS= AVL_NEXT.9f \ AVL_PREV.9f \ + CRED.9f \ SIZEOF_PTR.9f \ SIZEOF_STRUCT.9f \ STRUCT_BUF.9f \ @@ -690,6 +692,9 @@ MANLINKS= AVL_NEXT.9f \ avl_remove.9f \ avl_swap.9f \ bcanputnext.9f \ + crdup.9f \ + crfree.9f \ + crget.9f \ crgetgid.9f \ crgetgroups.9f \ crgetngroups.9f \ @@ -699,6 +704,7 @@ MANLINKS= AVL_NEXT.9f \ crgetsuid.9f \ crgetuid.9f \ crgetzoneid.9f \ + crhold.9f \ csx_Get16.9f \ csx_Get32.9f \ csx_Get64.9f \ @@ -971,6 +977,7 @@ MANLINKS= AVL_NEXT.9f \ inl.9f \ intro.9f \ inw.9f \ + kcred.9f \ kmem_cache_alloc.9f \ kmem_cache_destroy.9f \ kmem_cache_free.9f \ @@ -1312,7 +1319,8 @@ MANLINKS= AVL_NEXT.9f \ vsprintf.9f \ vzcmn_err.9f \ wr.9f \ - zcmn_err.9f + zcmn_err.9f \ + zone_kcred.9f assert.9f := LINKSRC = ASSERT.9f @@ -1485,6 +1493,14 @@ cv_timedwait_sig.9f := LINKSRC = condvar.9f cv_wait.9f := LINKSRC = condvar.9f cv_wait_sig.9f := LINKSRC = condvar.9f +CRED.9f := LINKSRC = credentials.9f +crdup.9f := LINKSRC = credentials.9f +crfree.9f := LINKSRC = credentials.9f +crget.9f := LINKSRC = credentials.9f +crhold.9f := LINKSRC = credentials.9f +kcred.9f := LINKSRC = credentials.9f +zone_kcred.9f := LINKSRC = credentials.9f + csx_Get16.9f := LINKSRC = csx_Get8.9f csx_Get32.9f := LINKSRC = csx_Get8.9f csx_Get64.9f := LINKSRC = csx_Get8.9f diff --git a/usr/src/man/man9f/credentials.9f b/usr/src/man/man9f/credentials.9f new file mode 100644 index 0000000000..89d2138c95 --- /dev/null +++ b/usr/src/man/man9f/credentials.9f @@ -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 |