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