1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
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
|
