1 /*
2 * Copyright (c) 2015 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28 #ifndef _SYS_PERSONA_H_
29 #define _SYS_PERSONA_H_
30
31 #ifdef PRIVATE
32 #include <sys/param.h>
33
34 #ifdef KERNEL
35 __enum_decl(persona_type_t, int, {
36 #else /* !KERNEL */
37 enum {
38 #endif /* KERNEL */
39 PERSONA_INVALID = 0,
40 PERSONA_GUEST = 1,
41 PERSONA_MANAGED = 2,
42 PERSONA_PRIV = 3,
43 PERSONA_SYSTEM = 4,
44 PERSONA_DEFAULT = 5,
45 PERSONA_SYSTEM_PROXY = 6,
46 PERSONA_SYS_EXT = 7,
47 PERSONA_ENTERPRISE = 8,
48
49 PERSONA_TYPE_MAX = PERSONA_ENTERPRISE,
50 #ifdef KERNEL
51 });
52 #else /* !KERNEL */
53 };
54 #endif /* KERNEL */
55
56 #define PERSONA_ID_NONE ((uid_t)-1)
57
58 struct kpersona_info {
59 uint32_t persona_info_version;
60
61 uid_t persona_id; /* overlaps with UID */
62 int persona_type;
63 gid_t persona_gid;
64 uint32_t persona_ngroups;
65 gid_t persona_groups[NGROUPS];
66 uid_t persona_gmuid;
67 char persona_name[MAXLOGNAME + 1];
68
69 /* TODO: MAC policies?! */
70 };
71
72 #define PERSONA_INFO_V1 1
73 #define PERSONA_INFO_V1_SIZE (sizeof(struct kpersona_info))
74
75
76 #define PERSONA_OP_ALLOC 1
77 #define PERSONA_OP_PALLOC 2
78 #define PERSONA_OP_DEALLOC 3
79 #define PERSONA_OP_GET 4
80 #define PERSONA_OP_INFO 5
81 #define PERSONA_OP_PIDINFO 6
82 #define PERSONA_OP_FIND 7
83 #define PERSONA_OP_GETPATH 8
84 #define PERSONA_OP_FIND_BY_TYPE 9
85
86 #define PERSONA_MGMT_ENTITLEMENT "com.apple.private.persona-mgmt"
87
88 #ifndef KERNEL
89 /*
90 * user space persona interface
91 */
92
93 /*
94 * kpersona_alloc: Allocate a new in-kernel persona
95 *
96 * Parameters:
97 * info: Pointer to persona info structure describing the
98 * attributes of the persona to create / allocate.
99 *
100 * id: output: set to the ID of the created persona
101 *
102 * Note:
103 * The 'persona_id' field of the 'info' parameter is ignored.
104 *
105 * Return:
106 * != 0: ERROR
107 * == 0: Success
108 */
109 int kpersona_alloc(struct kpersona_info *info, uid_t *id);
110
111 /*
112 * kpersona_palloc: Allocate a new in-kernel persona with a directory
113 * pathname
114 *
115 * Parameters:
116 * info: Pointer to persona info structure describing the
117 * attributes of the persona to create / allocate.
118 *
119 * path: Pointer to directory name that stores persona specific
120 * data. Assumes path buffer length = MAXPATHLEN and is a
121 * null-terminated string.
122 *
123 * id: output: set to the ID of the created persona
124 *
125 * Note:
126 * The 'persona_id' field of the 'info' parameter is ignored.
127 *
128 * Return:
129 * != 0: ERROR
130 * == 0: Success
131 */
132 int kpersona_palloc(struct kpersona_info *info, uid_t *id, char path[MAXPATHLEN]);
133
134 /*
135 * kpersona_dealloc: delete / destroy an in-kernel persona
136 *
137 * Parameters:
138 * id: the ID of the persona to destroy
139 *
140 * Return:
141 * < 0: ERROR
142 * 0: Success
143 */
144 int kpersona_dealloc(uid_t id);
145
146 /*
147 * kpersona_get: retrieve the persona with which the current thread is running
148 *
149 * To find the proc's persona id use kpersona_pidinfo
150 *
151 * Parameters:
152 * id: output: will be filled with the persona id from the voucher adopted
153 * on the current thread. If that voucher contains no persona information
154 * or there is no such voucher, then it defaults to the proc's persona id.
155 *
156 * Return:
157 * < 0: Thread is not running under any persona
158 * 0: Success (uuid is filled with running persona UUID)
159 */
160 int kpersona_get(uid_t *id);
161
162 /*
163 * kpersona_get_path: retrieve the given persona's path
164 *
165 * Parameters:
166 * id: ID of the persona
167 *
168 * path: output: filled in with path on success.
169 * Assumes path buffer length = MAXPATHLEN
170 *
171 * Return:
172 * < 0: Error
173 * 0: Success
174 */
175 int kpersona_getpath(uid_t id, char path[MAXPATHLEN]);
176
177 /*
178 * kpersona_info: gather info about the given persona
179 *
180 * Parameters:
181 * id: ID of the persona to investigate
182 * If set to 0, it uses persona id from the voucher adopted on the current
183 * thread. If that voucher contains no persona information or there is no
184 * such voucher, then it defaults to the proc's persona id.
185 *
186 * info: output: filled in with persona attributes on success.
187 *
188 * Return:
189 * < 0: ERROR
190 * 0: Success
191 */
192 int kpersona_info(uid_t id, struct kpersona_info *info);
193
194 /*
195 * kpersona_pidinfo: gather persona info about the given PID
196 *
197 * Parameters:
198 * pid: PID of the process whose persona info we're to return
199 *
200 * info: output: filled in with persona attributes on success.
201 *
202 * Return:
203 * < 0: ERROR
204 * 0: Success
205 */
206 int kpersona_pidinfo(pid_t pid, struct kpersona_info *info);
207
208 /*
209 * kpersona_find: lookup the kernel's UUID of a persona
210 *
211 * Parameters:
212 * name: Local login name of the persona.
213 * Set this to NULL to find personas by 'uid'.
214 *
215 * uid: UID of the persona.
216 * Set this to -1 to find personas by 'name'
217 *
218 * id: output: the ID(s) matching the input parameters
219 * This can be NULL
220 *
221 * idlen: input - size of 'id' buffer (in number of IDs)
222 * output - the total required size of the 'id' buffer
223 * (in number of IDs) - may be larger than input size
224 * Note:
225 * At least one of 'name' or 'uid' must be set.
226 *
227 * Return:
228 * < 0: ERROR
229 * >= 0: The number of IDs found to match the input parameters
230 */
231 int kpersona_find(const char *name, uid_t uid, uid_t *id, size_t *idlen);
232
233 /*
234 * kpersona_find_by_type: lookup the persona ids by type
235 *
236 * Parameters:
237 * persona_type: Type of persona id (see enum)
238 *
239 * id: output: the ID(s) matching the input parameters
240 * This can be NULL
241 *
242 * idlen: input - size of 'id' buffer (in number of IDs)
243 * output - the total required size of the 'id' buffer
244 * (in number of IDs) - may be larger than input size
245 * Return:
246 * < 0: ERROR
247 * >= 0: The number of IDs found to match the input parameters
248 */
249 int kpersona_find_by_type(int persona_type, uid_t *id, size_t *idlen);
250 #endif /* !KERNEL */
251
252 #ifdef KERNEL_PRIVATE
253 /* XNU + kext private interface */
254 #include <sys/cdefs.h>
255 #include <sys/kauth.h>
256 #include <libkern/libkern.h>
257 #include <os/refcnt.h>
258
259 #ifdef PERSONA_DEBUG
260 #include <os/log.h>
261 #define persona_dbg(fmt, ...) \
262 os_log(OS_LOG_DEFAULT, "[%4d] %s: " fmt "\n", \
263 current_proc() ? proc_getpid(current_proc()) : -1, \
264 __func__, ## __VA_ARGS__)
265 #else
266 #define persona_dbg(fmt, ...) do { } while (0)
267 #endif
268
269 /*
270 * Persona
271 */
272 #ifdef XNU_KERNEL_PRIVATE
273 /* only XNU proper needs to see the persona structure */
274 struct persona {
275 os_refcnt_t pna_refcount;
276 int32_t pna_valid;
277
278 uid_t pna_id;
279 persona_type_t pna_type;
280 char pna_login[MAXLOGNAME + 1];
281 char *pna_path;
282
283 kauth_cred_t XNU_PTRAUTH_SIGNED_PTR("persona.pna_cred") pna_cred;
284 uid_t pna_pgid;
285
286 int pna_cred_locked; /* set upon first adoption */
287
288 LIST_ENTRY(persona) pna_list;
289
290 /* this could go away if we used a coalition */
291 LIST_HEAD(, proc) pna_members;
292
293 lck_mtx_t pna_lock;
294
295 /*
296 * We can add things here such as PID maps, UID maps, etc.
297 */
298 #ifdef PERSONA_DEBUG
299 char pna_desc[128];
300 #endif
301 };
302
303 #define persona_lock(persona) lck_mtx_lock(&(persona)->pna_lock)
304 #define persona_unlock(persona) lck_mtx_unlock(&(persona)->pna_lock)
305 #define persona_try_lock(persona) lck_mtx_try_lock(&(persona)->pna_lock)
306
307 #define persona_lock_assert_held(persona) \
308 LCK_MTX_ASSERT(&(persona)->pna_lock, LCK_MTX_ASSERT_OWNED)
309
310 #ifdef PERSONA_DEBUG
311 static inline const char *
persona_desc(struct persona * persona,int locked)312 persona_desc(struct persona *persona, int locked)
313 {
314 if (!persona) {
315 return "<none>";
316 }
317
318 if (persona->pna_desc[0] != 0) {
319 return persona->pna_desc;
320 }
321
322 if (!locked) {
323 persona_lock(persona);
324 }
325 if (persona->pna_desc[0] != 0) {
326 goto out_unlock;
327 }
328
329 char *p = &persona->pna_desc[0];
330 char *end = p + sizeof(persona->pna_desc) - 1;
331
332 *end = 0;
333 p += scnprintf(p, end - p, "%s/%d:%d",
334 persona->pna_login,
335 kauth_cred_getuid(persona->pna_cred),
336 kauth_cred_getgid(persona->pna_cred));
337
338 if (p <= end) {
339 *p = 0;
340 }
341 out_unlock:
342 if (!locked) {
343 persona_unlock(persona);
344 }
345
346 return persona->pna_desc;
347 }
348 #else /* !PERSONA_DEBUG */
349 static inline const char *
persona_desc(struct persona * persona,int locked)350 persona_desc(struct persona *persona, int locked)
351 {
352 (void)persona;
353 (void)locked;
354 return "<persona>";
355 }
356 #endif
357
358 #else /* !XNU_KERNEL_PRIVATE */
359 /* kexts should only see an opaque persona structure */
360 struct persona;
361 #endif
362
363 __BEGIN_DECLS
364
365 #ifndef _KAUTH_CRED_T
366 #define _KAUTH_CRED_T
367 typedef struct ucred *kauth_cred_t;
368 #endif /* !_KAUTH_CRED_T */
369
370 /* returns the persona ID for the given pesona structure */
371 uid_t persona_get_id(struct persona *persona);
372
373 /* returns the type of the persona (see enum above: PERSONA_GUEST, etc.) */
374 int persona_get_type(struct persona *persona);
375
376 /* returns ref on kauth_cred_t that must be dropped via kauth_cred_unref() */
377 kauth_cred_t persona_get_cred(struct persona *persona);
378
379 /* returns a reference that must be released with persona_put() */
380 struct persona *persona_lookup(uid_t id);
381
382 /*
383 * Search for personas based on name or uid
384 *
385 * Parameters:
386 * name: Local login name of the persona.
387 * Set this to NULL to find personas by 'uid'.
388 *
389 * uid: UID of the persona.
390 * Set this to -1 to find personas by 'name'
391 *
392 * persona: output - array of persona pointers. Each non-NULL value
393 * must* be released with persona_put. This can be NULL.
394 *
395 * plen: input - size of 'persona' buffer (in number of pointers)
396 * output - the total required size of the 'persona' buffer (could be larger than input value)
397 *
398 * Return:
399 * 0: Success
400 * != 0: failure (BSD errno value ESRCH or EINVAL)
401 */
402 int persona_find(const char *login, uid_t uid,
403 struct persona **persona, size_t *plen);
404
405 /* returns a reference that must be released with persona_put() */
406 struct persona *persona_proc_get(pid_t pid);
407
408 /* returns the persona id tied to the current thread (also uses adopted voucher) */
409 uid_t current_persona_get_id(void);
410
411 /* returns a reference to the persona tied to the current thread (also uses adopted voucher) */
412 struct persona *current_persona_get(void);
413
414 /* get a reference to a persona structure */
415 struct persona *persona_get(struct persona *persona);
416
417 /* release a reference to a persona structure */
418 void persona_put(struct persona *persona);
419
420 /*
421 * Search for personas of a given type, 'persona_type'.
422 *
423 * Parameters:
424 * persona_type: Type of persona (see enum)
425 *
426 * persona: output - array of persona pointers. Each non-NULL value
427 * must* be released with persona_put. This can be NULL.
428 *
429 * plen: input - size of 'persona' buffer (in number of pointers)
430 * output - the total required size of the 'persona' buffer (could be larger than input value)
431 *
432 * Return:
433 * 0: Success
434 * != 0: failure (BSD errno value ESRCH or EINVAL)
435 */
436 int persona_find_by_type(persona_type_t persona_type, struct persona **persona,
437 size_t *plen);
438
439 #ifdef XNU_KERNEL_PRIVATE
440
441 #if CONFIG_PERSONAS
442 #include <sys/proc_internal.h>
443
444 /*
445 * In-kernel persona API
446 */
447 extern const uint32_t g_max_personas;
448
449 struct persona *persona_alloc(uid_t id, const char *login,
450 persona_type_t type, char *path, int *error);
451
452 int persona_init_begin(struct persona *persona);
453 void persona_init_end(struct persona *persona, int error);
454
455 struct persona *persona_lookup_and_invalidate(uid_t id);
456 int persona_verify_and_set_uniqueness(struct persona *persona);
457 boolean_t persona_is_unique(struct persona *persona);
458
459 static inline int
proc_has_persona(proc_t p)460 proc_has_persona(proc_t p)
461 {
462 if (p && p->p_persona) {
463 return 1;
464 }
465 return 0;
466 }
467
468 static inline uid_t
persona_id_from_proc(proc_t p)469 persona_id_from_proc(proc_t p)
470 {
471 if (p && p->p_persona) {
472 return p->p_persona->pna_id;
473 }
474 return PERSONA_ID_NONE;
475 }
476
477 int persona_proc_inherit(proc_t child, proc_t parent);
478
479 int persona_proc_adopt_id(proc_t p, uid_t id,
480 kauth_cred_t auth_override);
481 int persona_proc_adopt(proc_t p, struct persona *persona,
482 kauth_cred_t auth_override);
483 int persona_proc_drop(proc_t p);
484
485 int persona_set_cred(struct persona *persona, kauth_cred_t cred);
486 int persona_set_cred_from_proc(struct persona *persona, proc_t proc);
487
488 uid_t persona_get_uid(struct persona *persona);
489
490 int persona_set_gid(struct persona *persona, gid_t gid);
491 gid_t persona_get_gid(struct persona *persona);
492
493 int persona_set_groups(struct persona *persona, gid_t *groups, size_t ngroups, uid_t gmuid);
494 int persona_get_groups(struct persona *persona, size_t *ngroups, gid_t *groups, size_t groups_sz);
495
496 uid_t persona_get_gmuid(struct persona *persona);
497
498 int persona_get_login(struct persona *persona, char login[MAXLOGNAME + 1]);
499
500 /* returns a reference that must be released with persona_put() */
501 struct persona *persona_proc_get(pid_t pid);
502
503 int persona_find_all(const char *login, uid_t uid, persona_type_t persona_type,
504 struct persona **persona, size_t *plen);
505
506 #else /* !CONFIG_PERSONAS */
507
508 static inline int
proc_has_persona(__unused proc_t p)509 proc_has_persona(__unused proc_t p)
510 {
511 return 0;
512 }
513
514 static inline uid_t
persona_id_from_proc(__unused proc_t p)515 persona_id_from_proc(__unused proc_t p)
516 {
517 return PERSONA_ID_NONE;
518 }
519
520 #endif /* CONFIG_PERSONAS */
521 #endif /* XNU_KERNEL_PRIVATE */
522 __END_DECLS
523
524 #endif /* KERNEL_PRIVATE */
525
526 #endif /* PRIVATE */
527 #endif /* _SYS_PERSONA_H_ */
528