1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2020 Nexenta by DDN, Inc. All rights reserved. 13.\" 14.Dd Aug 21, 2020 15.Dt CREDENTIALS 9F 16.Os 17.Sh NAME 18.Nm credentials , 19.Nm CRED , 20.Nm crdup , 21.Nm crfree , 22.Nm crget , 23.Nm crhold , 24.Nm kcred , 25.Nm zone_kcred 26.Nd Functions for obtaining credentials in the kernel 27.Sh SYNOPSIS 28.In sys/cred.h 29.Ft "cred_t *" 30.Fo CRED 31.Fc 32.Ft "cred_t *" 33.Fo crdup 34.Fa "cred_t *cr" 35.Fc 36.Ft "void" 37.Fo crfree 38.Fa "cred_t *cr" 39.Fc 40.Ft "cred_t *" 41.Fo crget 42.Fc 43.Ft "void" 44.Fo crhold 45.Fa "cred_t *cr" 46.Fc 47.Ft "cred_t *" 48.Fo zone_kcred 49.Fc 50.Vt cred_t *kcred 51.Sh INTERFACE LEVEL 52.Sy Volatile - 53This interface is still evolving in illumos. 54API and ABI stability is not guaranteed. 55.Sh PARAMETERS 56.Bl -tag -width Fa 57.It Fa cr 58pointer to the user credential structure. 59.El 60.Sh DESCRIPTION 61Some kernel interfaces require a credential as an argument. 62This page documents the credentials available in the system, 63as well as interfaces for creating new credentials. 64.Pp 65Most users do not need to create new credentials. 66Instead, users should generally use the credentials of the executing context. 67.Pp 68This interface is primarily intended for services that must perform operations 69on behalf of multiple remotely authenticated users, whose authentication context 70is unrelated to the context of the executing thread or process. 71Drivers MUST NOT create new credentials. 72Drivers should use the provided credential. 73.Pp 74For functions that do not return new credentials, 75if the credentials will be used outside of their context 76(i.e. if the output of zone_kcred() is referenced outside of the zone), 77then one should use 78.Fn crdup 79or 80.Fn crhold 81to ensure that the credentials remain valid. 82.Ss Fn CRED 83The 84.Fn CRED 85function returns the credential of the calling thread. 86Its contents depend on the calling context (user, kernel, interrupt). 87.Ss Fn crdup 88.Fn crdup 89returns a newly-allocated copy of 90.Fa cr 91with reference count of 1. 92It sleeps until the allocation succeeds. 93.Ss Fn crfree 94.Fn crfree 95releases a reference to 96.Fa cr . 97If this is the last reference, the credential is destroyed. 98.Ss Fn crhold 99.Fn crhold 100takes a reference to 101.Fa cr . 102.Ss Va kcred 103.Va kcred 104is the root credential of the global zone. 105Its UIDs and GIDs are all 0. 106It has the following privilege sets by default: 107.Bd -literal -offset indent 108E: basic,proc_secflags 109I: basic,proc_secflags 110P: basic,proc_secflags 111L: all 112.Ed 113.Pp 114.Dv NET_MAC_AWARE 115is set in the credential's flags. 116It is not marked privilege-aware. 117.Pp 118.Va kcred 119will never be freed by the system. 120.Ss Fn zone_kcred 121The 122.Fn zone_kcred 123function returns the root credential of the zone to which the calling thread belongs. 124This cred is derived from the global kcred, minus any privileges denied to the zone. 125.Ss Fn crget 126The 127.Fn crget 128function returns a copy of 129.Fn zone_kcred 130suitable for modification by the caller. 131This is useful for obtaining a default, 132well-initialized credential in the appropriate zone context, 133that is free of privileges or limitations of the originating thread. 134It must be freed with 135.Fn crfree . 136It sleeps until the allocation succeeds. 137.Ss Considerations 138.Va kcred 139and 140.Fn zone_kcred 141are not privilege-aware, and have all IDs set to 0. 142This causes their Limit set to be used in place of the Effective and Permitted sets, 143which significantly expands their privileges. 144.Pp 145If the output of 146.Fn crget 147is not later marked as privilege aware, and its UID is not set to a non-zero value, 148then its Limit set will be used in place of its Effective and Permitted sets, 149significantly expanding its privileges. 150Callers should either mark the credential as privilege-aware, 151reduce the Limit set appropriately, 152or ensure that they intend for zero-uid users to have expanded privileges. 153.Pp 154.Va kcred , 155.Fn zone_kcred , 156and 157.Fn CRED 158are not suitable for modfication by the caller. 159Callers must use 160.Fn crdup 161to create a copy of these credentials that are suitable for modification. 162.Pp 163Callers of 164.Fn zone_kcred 165and 166.Fn crget 167must take care to ensure that the calling thread is 168executing in the context of the appropriate zone. 169If the thread is performing work on behalf of a different zone, 170or if one is uncertain of the zone context of the calling thread, 171then one should find the appropriate zone by other means, and reference 172.Em zone->zone_kcred 173explicitly. 174.Sh CONTEXT 175These functions can be called from 176.Sy user 177and 178.Sy kernel 179contexts. 180.Sh RETURN VALUES 181.Fn zone_kcred 182and 183.Fn CRED 184return a pointer to a 185.Vt cred_t 186that should not be modified. 187.Pp 188.Fn crget 189and 190.Fn crdup 191return a pointer to a newly allocated 192.Vt cred_t . 193.Pp 194.Fn zone_kcred , 195.Fn CRED , 196.Fn crdup , 197and 198.Fn crget 199can never fail, and always return a valid credential. 200.Sh SEE ALSO 201.Xr ddi_cred 9f 202