bsd/sys/persona.h

   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 enum {
  35         PERSONA_INVALID = 0,
  36         PERSONA_GUEST   = 1,
  37         PERSONA_MANAGED = 2,
  38         PERSONA_PRIV    = 3,
  39         PERSONA_SYSTEM  = 4,
  40
  41         PERSONA_TYPE_MAX = PERSONA_SYSTEM,
  42 };
  43
  44 #define PERSONA_ID_NONE ((uid_t)-1)
  45
  46 struct kpersona_info {
  47         uint32_t persona_info_version;
  48
  49         uid_t    persona_id; /* overlaps with UID */
  50         int      persona_type;
  51         gid_t    persona_gid;
  52         uint32_t persona_ngroups;
  53         gid_t    persona_groups[NGROUPS];
  54         uid_t    persona_gmuid;
  55         char     persona_name[MAXLOGNAME + 1];
  56
  57         /* TODO: MAC policies?! */
  58 };
  59
  60 #define PERSONA_INFO_V1       1
  61 #define PERSONA_INFO_V1_SIZE  (sizeof(struct kpersona_info))
  62
  63
  64 #define PERSONA_OP_ALLOC    1
  65 #define PERSONA_OP_DEALLOC  2
  66 #define PERSONA_OP_GET      3
  67 #define PERSONA_OP_INFO     4
  68 #define PERSONA_OP_PIDINFO  5
  69 #define PERSONA_OP_FIND     6
  70
  71 #ifndef KERNEL
  72 /*
  73  * user space persona interface
  74  */
  75
  76 /*
  77  * kpersona_alloc: Allocate a new in-kernel persona
  78  *
  79  * Parameters:
  80  *       info: Pointer to persona info structure describing the
  81  *             attributes of the persona to create / allocate.
  82  *
  83  *         id: output: set to the ID of the created persona
  84  *
  85  * Note:
  86  *      The 'persona_id' field of the 'info' parameter is ignored.
  87  *
  88  * Return:
  89  *        != 0: ERROR
  90  *        == 0: Success
  91  */
  92 int kpersona_alloc(struct kpersona_info *info, uid_t *id);
  93
  94 /*
  95  * kpersona_dealloc: delete / destroy an in-kernel persona
  96  *
  97  * Parameters:
  98  *         id: the ID of the persona to destroy
  99  *
 100  * Return:
 101  *        < 0: ERROR
 102  *          0: Success
 103  */
 104 int kpersona_dealloc(uid_t id);
 105
 106
 107 /*
 108  * kpersona_get: retrieve the persona with which the current thread is running
 109  *
 110  * Parameters:
 111  *         id: output: will be filled with current thread's persona
 112  *             (or current processes persona) on success.
 113  *
 114  * Return:
 115  *        < 0: Thread is not running under any persona
 116  *          0: Success (uuid is filled with running persona UUID)
 117  */
 118 int kpersona_get(uid_t *id);
 119
 120
 121 /*
 122  * kpersona_info: gather info about the given persona
 123  *
 124  * Parameters:
 125  *         id: ID of the persona to investigate
 126  *
 127  *       info: output: filled in with persona attributes on success.
 128  *
 129  * Return:
 130  *        < 0: ERROR
 131  *          0: Success
 132  */
 133 int kpersona_info(uid_t id, struct kpersona_info *info);
 134
 135
 136 /*
 137  * kpersona_pidinfo: gather persona info about the given PID
 138  *
 139  * Parameters:
 140  *        pid: PID of the process whose persona info we're to return
 141  *
 142  *       info: output: filled in with persona attributes on success.
 143  *
 144  * Return:
 145  *        < 0: ERROR
 146  *          0: Success
 147  */
 148 int kpersona_pidinfo(pid_t pid, struct kpersona_info *info);
 149
 150
 151 /*
 152  * kpersona_find: lookup the kernel's UUID of a persona
 153  *
 154  * Parameters:
 155  *       name: Local login name of the persona.
 156  *             Set this to NULL to find personas by 'uid'.
 157  *
 158  *        uid: UID of the persona.
 159  *             Set this to -1 to find personas by 'name'
 160  *
 161  *         id: output: the ID(s) matching the input parameters
 162  *      idlen: input - size of 'id' buffer (in number of IDs)
 163  *             output - the total required size of the 'id' buffer
 164  *                      (in number of IDs) - may be larger than input size
 165  * Note:
 166  *      At least one of 'name' or 'uid' must be set.
 167  *
 168  * Return:
 169  *         < 0: ERROR
 170  *        >= 0: The number of IDs found to match the input parameters
 171  */
 172 int kpersona_find(const char *name, uid_t uid, uid_t *id, size_t *idlen);
 173 #endif /* !KERNEL */
 174
 175 #ifdef KERNEL_PRIVATE
 176 /* XNU + kext private interface */
 177 #include <sys/cdefs.h>
 178 #include <sys/kauth.h>
 179 #include <libkern/libkern.h>
 180 #include <os/refcnt.h>
 181
 182 #ifdef PERSONA_DEBUG
 183 #include <os/log.h>
 184 #define persona_dbg(fmt, ...) \
 185         os_log(OS_LOG_DEFAULT, "[%4d] %s:  " fmt "\n", \
 186                current_proc() ? current_proc()->p_pid : -1, \
 187                __func__, ## __VA_ARGS__)
 188 #else
 189 #define persona_dbg(fmt, ...) do { } while (0)
 190 #endif
 191
 192 /*
 193  * Persona
 194  */
 195 #ifdef XNU_KERNEL_PRIVATE
 196 /* only XNU proper needs to see the persona structure */
 197 struct persona {
 198         os_refcnt_t  pna_refcount;
 199         int32_t      pna_valid;
 200
 201         uid_t        pna_id;
 202         int          pna_type;
 203         char         pna_login[MAXLOGNAME + 1];
 204
 205         kauth_cred_t pna_cred;
 206         uid_t        pna_pgid;
 207
 208         int          pna_cred_locked; /* set upon first adoption */
 209
 210         LIST_ENTRY(persona) pna_list;
 211
 212         /* this could go away if we used a coalition */
 213         LIST_HEAD(, proc)   pna_members;
 214
 215         lck_mtx_t    pna_lock;
 216
 217         /*
 218          * We can add things here such as PID maps, UID maps, etc.
 219          */
 220 #ifdef PERSONA_DEBUG
 221         char         pna_desc[128];
 222 #endif
 223 };
 224
 225 #define persona_lock(persona)     lck_mtx_lock(&(persona)->pna_lock)
 226 #define persona_unlock(persona)   lck_mtx_unlock(&(persona)->pna_lock)
 227 #define persona_try_lock(persona) lck_mtx_try_lock(&(persona)->pna_lock)
 228
 229 #define persona_lock_assert_held(persona) \
 230         LCK_MTX_ASSERT(&(persona)->pna_lock, LCK_MTX_ASSERT_OWNED)
 231
 232 #ifdef PERSONA_DEBUG
 233 static inline const char *
 234 persona_desc(struct persona *persona, int locked)
 235 {
 236         if (!persona) {
 237                 return "<none>";
 238         }
 239
 240         if (persona->pna_desc[0] != 0) {
 241                 return persona->pna_desc;
 242         }
 243
 244         if (!locked) {
 245                 persona_lock(persona);
 246         }
 247         if (persona->pna_desc[0] != 0) {
 248                 goto out_unlock;
 249         }
 250
 251         char *p = &persona->pna_desc[0];
 252         char *end = p + sizeof(persona->pna_desc) - 1;
 253
 254         *end = 0;
 255         p += snprintf(p, end - p, "%s/%d:%d",
 256             persona->pna_login,
 257             kauth_cred_getuid(persona->pna_cred),
 258             kauth_cred_getgid(persona->pna_cred));
 259
 260         if (p <= end) {
 261                 *p = 0;
 262         }
 263 out_unlock:
 264         if (!locked) {
 265                 persona_unlock(persona);
 266         }
 267
 268         return persona->pna_desc;
 269 }
 270 #else /* !PERSONA_DEBUG */
 271 static inline const char *
 272 persona_desc(struct persona *persona, int locked)
 273 {
 274         (void)persona;
 275         (void)locked;
 276         return "<persona>";
 277 }
 278 #endif
 279
 280 #else /* !XNU_KERNEL_PRIVATE */
 281 /* kexts should only see an opaque persona structure */
 282 struct persona;
 283 #endif
 284
 285 __BEGIN_DECLS
 286
 287 #ifndef _KAUTH_CRED_T
 288 #define _KAUTH_CRED_T
 289 typedef struct ucred *kauth_cred_t;
 290 #endif  /* !_KAUTH_CRED_T */
 291
 292 /* returns the persona ID for the given pesona structure */
 293 uid_t persona_get_id(struct persona *persona);
 294
 295 /* returns the type of the persona (see enum above: PERSONA_GUEST, etc.) */
 296 int persona_get_type(struct persona *persona);
 297
 298 /* returns ref on kauth_cred_t that must be dropped via kauth_cred_unref() */
 299 kauth_cred_t persona_get_cred(struct persona *persona);
 300
 301 /* returns a reference that must be released with persona_put() */
 302 struct persona *persona_lookup(uid_t id);
 303
 304 /*
 305  * returns non-zero on error, on success returns 0 and updates 'plen' to
 306  * total found (could be more than original value of 'plen')
 307  */
 308 int persona_find(const char *login, uid_t uid,
 309     struct persona **persona, size_t *plen);
 310
 311 /* returns a reference to the persona tied to the current thread */
 312 struct persona *current_persona_get(void);
 313
 314 /* get a reference to a persona structure */
 315 struct persona *persona_get(struct persona *persona);
 316
 317 /* release a reference to a persona structure */
 318 void persona_put(struct persona *persona);
 319
 320 #ifdef XNU_KERNEL_PRIVATE
 321
 322 #if CONFIG_PERSONAS
 323 #include <sys/proc_internal.h>
 324
 325 /*
 326  * In-kernel persona API
 327  */
 328 extern uint32_t g_max_personas;
 329 extern struct persona *g_system_persona;
 330
 331 void personas_bootstrap(void);
 332
 333 struct persona *persona_alloc(uid_t id, const char *login,
 334     int type, int *error);
 335
 336 int persona_init_begin(struct persona *persona);
 337 void persona_init_end(struct persona *persona, int error);
 338
 339 struct persona *persona_lookup_and_invalidate(uid_t id);
 340
 341 static inline int
 342 proc_has_persona(proc_t p)
 343 {
 344         if (p && p->p_persona) {
 345                 return 1;
 346         }
 347         return 0;
 348 }
 349
 350 static inline uid_t
 351 persona_id_from_proc(proc_t p)
 352 {
 353         if (p && p->p_persona) {
 354                 return p->p_persona->pna_id;
 355         }
 356         return PERSONA_ID_NONE;
 357 }
 358
 359 int persona_proc_inherit(proc_t child, proc_t parent);
 360
 361 int persona_proc_adopt_id(proc_t p, uid_t id,
 362     kauth_cred_t auth_override);
 363 int persona_proc_adopt(proc_t p, struct persona *persona,
 364     kauth_cred_t auth_override);
 365 int persona_proc_drop(proc_t p);
 366
 367 int persona_set_cred(struct persona *persona, kauth_cred_t cred);
 368 int persona_set_cred_from_proc(struct persona *persona, proc_t proc);
 369
 370 uid_t persona_get_uid(struct persona *persona);
 371
 372 int persona_set_gid(struct persona *persona, gid_t gid);
 373 gid_t persona_get_gid(struct persona *persona);
 374
 375 int persona_set_groups(struct persona *persona, gid_t *groups, unsigned ngroups, uid_t gmuid);
 376 int persona_get_groups(struct persona *persona, unsigned *ngroups, gid_t *groups, unsigned groups_sz);
 377
 378 uid_t persona_get_gmuid(struct persona *persona);
 379
 380 int persona_get_login(struct persona *persona, char login[MAXLOGNAME + 1]);
 381
 382 /* returns a reference that must be released with persona_put() */
 383 struct persona *persona_proc_get(pid_t pid);
 384
 385 #else /* !CONFIG_PERSONAS */
 386
 387 static inline int
 388 proc_has_persona(__unused proc_t p)
 389 {
 390         return 0;
 391 }
 392
 393 static inline uid_t
 394 persona_id_from_proc(__unused proc_t p)
 395 {
 396         return PERSONA_ID_NONE;
 397 }
 398
 399 #endif /* CONFIG_PERSONAS */
 400 #endif /* XNU_KERNEL_PRIVATE */
 401 __END_DECLS
 402
 403 #endif /* KERNEL_PRIVATE */
 404
 405 #endif /* PRIVATE */
 406 #endif /* _SYS_PERSONA_H_ */