1 /* 2 * Copyright (c) 2006 Apple Computer, 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 29 30 /* 31 * [SPN] Support for _POSIX_SPAWN 32 * 33 * This file contains internal data structures which are externally represented 34 * as opaque void pointers to prevent introspection. This permits us to 35 * change the underlying implementation of the code to maintain it or to 36 * support new features, as needed, without the consumer needing to recompile 37 * their code because of structure size changes or data reorganization. 38 */ 39 40 #ifndef _SYS_SPAWN_INTERNAL_H_ 41 #define _SYS_SPAWN_INTERNAL_H_ 42 43 #include <sys/_types.h> /* __offsetof(), __darwin_size_t */ 44 #include <sys/param.h> 45 #include <sys/syslimits.h> /* PATH_MAX */ 46 #include <sys/spawn.h> 47 #include <mach/machine.h> 48 #include <mach/port.h> 49 #include <mach/exception_types.h> 50 #include <mach/coalition.h> /* COALITION_NUM_TYPES */ 51 #include <mach/task_policy.h> 52 #include <os/overflow.h> 53 54 /* 55 * Safely compute the size in bytes of a structure, '_type', whose last 56 * element, '_member', is a zero-sized array meant to hold 'x' bytes. 57 * 58 * If the size calculation overflows a size_t value, this macro returns 0. 59 */ 60 #define PS_ACTION_SIZE(x, _type, _member_type) ({\ 61 size_t _ps_count = (size_t)x; \ 62 size_t _ps_size = 0; \ 63 /* (count * sizeof(_member_type)) + sizeof(_type) */ \ 64 if (os_mul_and_add_overflow(_ps_count, \ 65 sizeof(_member_type), \ 66 sizeof(_type), \ 67 &_ps_size)) { \ 68 _ps_size = 0; \ 69 } \ 70 _ps_size; }) 71 72 /* 73 * Allowable posix_spawn() port action types 74 */ 75 typedef enum { 76 PSPA_SPECIAL = 0, 77 PSPA_EXCEPTION = 1, 78 PSPA_AU_SESSION = 2, 79 PSPA_IMP_WATCHPORTS = 3, 80 PSPA_REGISTERED_PORTS = 4, 81 PSPA_PTRAUTH_TASK_PORT = 5, 82 } pspa_t; 83 84 /* 85 * Internal representation of one port to be set on posix_spawn(). 86 * Currently this is limited to setting special and exception ports, 87 * but could be extended to other inheritable port types. 88 */ 89 typedef struct _ps_port_action { 90 pspa_t port_type; 91 exception_mask_t mask; 92 mach_port_name_t new_port; 93 exception_behavior_t behavior; 94 thread_state_flavor_t flavor; 95 int which; 96 } _ps_port_action_t; 97 98 /* 99 * A collection of port actions to take on the newly spawned process. 100 */ 101 typedef struct _posix_spawn_port_actions { 102 int pspa_alloc; 103 int pspa_count; 104 _ps_port_action_t pspa_actions[]; 105 } *_posix_spawn_port_actions_t; 106 107 /* 108 * Returns size in bytes of a _posix_spawn_port_actions holding x elements. 109 */ 110 #define PS_PORT_ACTIONS_SIZE(x) \ 111 PS_ACTION_SIZE(x, struct _posix_spawn_port_actions, _ps_port_action_t) 112 113 #define NBINPREFS 4 114 115 /* 116 * Mapping of opaque data pointer to a MAC policy (specified by name). 117 */ 118 typedef struct _ps_mac_policy_extension { 119 char policyname[128]; 120 union { 121 /* Address of the user space data passed into kernel space */ 122 uint64_t data; 123 /* In kernel space, offset into the pool of all extensions' data */ 124 uint64_t dataoff; 125 }; 126 uint64_t datalen; 127 } _ps_mac_policy_extension_t; 128 129 /* 130 * A collection of extra data passed to MAC policies for the newly spawned process. 131 */ 132 typedef struct _posix_spawn_mac_policy_extensions { 133 int psmx_alloc; 134 int psmx_count; 135 _ps_mac_policy_extension_t psmx_extensions[]; 136 } *_posix_spawn_mac_policy_extensions_t; 137 138 /* 139 * Returns size in bytes of a _posix_spawn_mac_policy_extensions holding x elements. 140 */ 141 #define PS_MAC_EXTENSIONS_SIZE(x) \ 142 PS_ACTION_SIZE(x, struct _posix_spawn_mac_policy_extensions, _ps_mac_policy_extension_t) 143 144 #define PS_MAC_EXTENSIONS_INIT_COUNT 2 145 146 /* 147 * Coalition posix spawn attributes 148 */ 149 struct _posix_spawn_coalition_info { 150 struct { 151 uint64_t psci_id; 152 uint32_t psci_role; 153 uint32_t psci_reserved1; 154 uint64_t psci_reserved2; 155 } psci_info[COALITION_NUM_TYPES]; 156 }; 157 158 /* 159 * UID/GID attributes 160 */ 161 struct _posix_spawn_posix_cred_info { 162 uint32_t pspci_flags; /* spawn persona flags */ 163 uid_t pspci_uid; /* alternate posix/unix UID */ 164 gid_t pspci_gid; /* alternate posix/unix GID */ 165 uint32_t pspci_ngroups; /* alternate advisory groups */ 166 gid_t pspci_groups[NGROUPS]; 167 uid_t pspci_gmuid; /* group membership UID */ 168 char pspci_login[MAXLOGNAME + 1]; 169 }; 170 171 #define POSIX_SPAWN_POSIX_CRED_UID 0x00010000 172 #define POSIX_SPAWN_POSIX_CRED_GID 0x00020000 173 #define POSIX_SPAWN_POSIX_CRED_GROUPS 0x00040000 174 #define POSIX_SPAWN_POSIX_CRED_LOGIN 0x00080000 175 176 /* 177 * Persona attributes 178 */ 179 struct _posix_spawn_persona_info { 180 uid_t pspi_id; /* persona ID (unix UID) */ 181 uint32_t pspi_flags; /* spawn persona flags */ 182 uid_t pspi_uid; /* alternate posix/unix UID */ 183 gid_t pspi_gid; /* alternate posix/unix GID */ 184 uint32_t pspi_ngroups; /* alternate advisory groups */ 185 gid_t pspi_groups[NGROUPS]; 186 uid_t pspi_gmuid; /* group membership UID */ 187 }; 188 189 #define POSIX_SPAWN_PERSONA_FLAGS_NONE 0x0 190 #define POSIX_SPAWN_PERSONA_FLAGS_OVERRIDE 0x1 /* noop, the only option */ 191 #define POSIX_SPAWN_PERSONA_FLAGS_VERIFY 0x2 /* noop, unimplemented */ 192 193 #define POSIX_SPAWN_PERSONA_ALL_FLAGS \ 194 (POSIX_SPAWN_PERSONA_FLAGS_OVERRIDE \ 195 | POSIX_SPAWN_PERSONA_FLAGS_VERIFY \ 196 ) 197 198 #define POSIX_SPAWN_PERSONA_UID POSIX_SPAWN_POSIX_CRED_UID 199 #define POSIX_SPAWN_PERSONA_GID POSIX_SPAWN_POSIX_CRED_GID 200 #define POSIX_SPAWN_PERSONA_GROUPS POSIX_SPAWN_POSIX_CRED_GROUPS 201 202 203 /* 204 * A posix_spawnattr structure contains all of the attribute elements that 205 * can be set, as well as any metadata whose validity is signalled by the 206 * presence of a bit in the flags field. All fields are initialized to the 207 * appropriate default values by posix_spawnattr_init(). 208 * 209 * Fields must be added at the end of this, but before extensions array 210 * pointers. 211 */ 212 213 typedef struct _posix_spawnattr { 214 short psa_flags; /* spawn attribute flags */ 215 short flags_padding; /* get the flags to be int aligned */ 216 sigset_t psa_sigdefault; /* signal set to default */ 217 sigset_t psa_sigmask; /* signal set to mask */ 218 pid_t psa_pgroup; /* pgroup to spawn into */ 219 cpu_type_t psa_binprefs[NBINPREFS]; /* cpu affinity prefs*/ 220 int psa_pcontrol; /* process control bits on resource starvation */ 221 int psa_apptype; /* app type and process spec behav */ 222 uint64_t psa_cpumonitor_percent; /* CPU usage monitor percentage */ 223 uint64_t psa_cpumonitor_interval; /* CPU usage monitor interval, in seconds */ 224 uint64_t psa_reserved; 225 226 short psa_jetsam_flags; /* jetsam flags */ 227 short short_padding; /* Padding for alignment issues */ 228 int psa_priority; /* jetsam relative importance */ 229 int psa_memlimit_active; /* jetsam memory limit (in MB) when process is active */ 230 int psa_memlimit_inactive; /* jetsam memory limit (in MB) when process is inactive */ 231 232 uint64_t psa_qos_clamp; /* QoS Clamp to set on the new process */ 233 task_role_t psa_darwin_role; /* PRIO_DARWIN_ROLE to set on the new process */ 234 int psa_thread_limit; /* thread limit */ 235 236 uint64_t psa_max_addr; /* Max valid VM address */ 237 bool psa_no_smt; 238 bool psa_tecs; 239 int psa_platform; /* Plaform for the binary */ 240 241 cpu_subtype_t psa_subcpuprefs[NBINPREFS]; /* subcpu affinity prefs*/ 242 uint32_t psa_options; /* More options to be passed to posix_spawn */ 243 uint32_t psa_port_soft_limit; /* port space soft limit */ 244 uint32_t psa_port_hard_limit; /* port space hard limit */ 245 uint32_t psa_filedesc_soft_limit; /* file descriptor soft limit */ 246 uint32_t psa_filedesc_hard_limit; /* file descriptor hard limit */ 247 uint32_t psa_crash_behavior; /* crash behavior flags */ 248 uint64_t psa_crash_behavior_deadline; /* crash behavior deadline */ 249 uint8_t psa_launch_type; /* type of launch for launch constraint enforcement */ 250 251 /* For exponential backoff */ 252 uint32_t psa_crash_count; 253 uint32_t psa_throttle_timeout; 254 255 /* 256 * NOTE: Extensions array pointers must stay at the end so that 257 * everything above this point stays the same size on different bitnesses 258 * see <rdar://problem/12858307> 259 */ 260 _posix_spawn_port_actions_t psa_ports; /* special/exception ports */ 261 _posix_spawn_mac_policy_extensions_t psa_mac_extensions; /* MAC policy-specific extensions. */ 262 struct _posix_spawn_coalition_info *psa_coalition_info; /* coalition info */ 263 struct _posix_spawn_persona_info *psa_persona_info; /* spawn new process into given persona */ 264 struct _posix_spawn_posix_cred_info *psa_posix_cred_info; /* posix creds: uid/gid/groups */ 265 char *psa_subsystem_root_path; /* pass given path in apple strings */ 266 } *_posix_spawnattr_t; 267 268 /* 269 * Jetsam flags eg: psa_jetsam_flags 270 */ 271 #define POSIX_SPAWN_JETSAM_SET 0x8000 272 273 #define POSIX_SPAWN_JETSAM_USE_EFFECTIVE_PRIORITY 0x01 274 #define POSIX_SPAWN_JETSAM_HIWATER_BACKGROUND 0x02 /* to be deprecated */ 275 #define POSIX_SPAWN_JETSAM_MEMLIMIT_FATAL 0x04 /* to be deprecated */ 276 277 /* 278 * Additional flags available for use with 279 * the posix_spawnattr_setjetsam_ext() call 280 */ 281 #define POSIX_SPAWN_JETSAM_MEMLIMIT_ACTIVE_FATAL 0x04 /* if set, limit is fatal when the process is active */ 282 #define POSIX_SPAWN_JETSAM_MEMLIMIT_INACTIVE_FATAL 0x08 /* if set, limit is fatal when the process is inactive */ 283 284 285 /* 286 * Flags set based on posix_spawnattr_set_jetsam_ttr_np(). 287 * Indicate relaunch behavior of process when jetsammed 288 */ 289 /* Mask and bucket counts for relaunch behavior */ 290 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_BUCKETS (0x3) 291 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_MASK (0x30) 292 293 /* Actual buckets based on behavior data */ 294 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_HIGH (0x30) 295 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_MED (0x20) 296 #define POSIX_SPAWN_JETSAM_RELAUNCH_BEHAVIOR_LOW (0x10) 297 298 /* 299 * Deprecated posix_spawn psa_flags values 300 * 301 * POSIX_SPAWN_OSX_TALAPP_START 0x0400 302 * POSIX_SPAWN_IOS_RESV1_APP_START 0x0400 303 * POSIX_SPAWN_IOS_APPLE_DAEMON_START 0x0800 304 * POSIX_SPAWN_IOS_APP_START 0x1000 305 * POSIX_SPAWN_OSX_WIDGET_START 0x0800 306 * POSIX_SPAWN_OSX_DBCLIENT_START 0x0800 307 * POSIX_SPAWN_OSX_RESVAPP_START 0x1000 308 */ 309 310 /* 311 * Deprecated posix_spawn psa_apptype values 312 * 313 * POSIX_SPAWN_PROCESS_TYPE_APPLEDAEMON 0x00000001 314 * POSIX_SPAWN_PROCESS_TYPE_UIAPP 0x00000002 315 * POSIX_SPAWN_PROCESS_TYPE_ADAPTIVE 0x00000004 316 * POSIX_SPAWN_PROCESS_TYPE_TAL 0x00000001 317 * POSIX_SPAWN_PROCESS_TYPE_WIDGET 0x00000002 318 * POSIX_SPAWN_PROCESS_TYPE_DELAYIDLESLEEP 0x10000000 319 * 320 * POSIX_SPAWN_PROCESS_FLAG_IMPORTANCE_DONOR 0x00000010 321 * POSIX_SPAWN_PROCESS_FLAG_ADAPTIVE 0x00000020 322 * POSIX_SPAWN_PROCESS_FLAG_START_BACKGROUND 0x00000040 323 * POSIX_SPAWN_PROCESS_FLAG_START_LIGHT_THROTTLE 0x00000080 324 */ 325 326 /* 327 * posix_spawn psa_apptype process type settings. 328 * when POSIX_SPAWN_PROC_TYPE is set, old psa_apptype bits are ignored 329 */ 330 #define POSIX_SPAWN_PROCESS_TYPE_NORMAL 0x00000000 331 #define POSIX_SPAWN_PROCESS_TYPE_DEFAULT POSIX_SPAWN_PROCESS_TYPE_NORMAL 332 333 #define POSIX_SPAWN_PROC_TYPE_MASK 0x00000F00 334 335 #define POSIX_SPAWN_PROC_TYPE_APP_DEFAULT 0x00000100 336 #define POSIX_SPAWN_PROC_TYPE_APP_TAL 0x00000200 /* unused */ 337 338 #define POSIX_SPAWN_PROC_TYPE_DAEMON_STANDARD 0x00000300 339 #define POSIX_SPAWN_PROC_TYPE_DAEMON_INTERACTIVE 0x00000400 340 #define POSIX_SPAWN_PROC_TYPE_DAEMON_BACKGROUND 0x00000500 341 #define POSIX_SPAWN_PROC_TYPE_DAEMON_ADAPTIVE 0x00000600 342 343 #define POSIX_SPAWN_PROC_TYPE_DRIVER 0x00000700 344 345 #define POSIX_SPAWN_PROC_CLAMP_NONE 0x00000000 346 #define POSIX_SPAWN_PROC_CLAMP_UTILITY 0x00000001 347 #define POSIX_SPAWN_PROC_CLAMP_BACKGROUND 0x00000002 348 #define POSIX_SPAWN_PROC_CLAMP_MAINTENANCE 0x00000003 349 #define POSIX_SPAWN_PROC_CLAMP_LAST 0x00000004 350 351 #define POSIX_SPAWN_ENTITLEMENT_DRIVER "com.apple.private.spawn-driver" 352 /* Setting to indicate no change to darwin role */ 353 #define POSIX_SPAWN_DARWIN_ROLE_NONE 0x00000000 354 /* Other possible values are specified by PRIO_DARWIN_ROLE in sys/resource.h */ 355 356 /* Other posix spawn options passed through psa_options */ 357 __options_decl(posix_spawn_options, uint32_t, { 358 PSA_OPTION_NONE = 0, 359 PSA_OPTION_PLUGIN_HOST_DISABLE_A_KEYS = 0x1, 360 PSA_OPTION_ALT_ROSETTA = 0x2, 361 }); 362 363 /* 364 * Allowable posix_spawn() file actions 365 */ 366 typedef enum { 367 PSFA_OPEN = 0, 368 PSFA_CLOSE = 1, 369 PSFA_DUP2 = 2, 370 PSFA_INHERIT = 3, 371 PSFA_FILEPORT_DUP2 = 4, 372 PSFA_CHDIR = 5, 373 PSFA_FCHDIR = 6 374 } psfa_t; 375 376 377 /* 378 * A posix_spawn() file action record for a single action 379 * 380 * Notes: We carry around the full open arguments for both the open 381 * and the close to permit the use of a single array of action 382 * elements to be associated with a file actions object. 383 * 384 * A possible future optimization would be to break this into 385 * a variable sized vector list to save space (i.e. a separate 386 * string area, allocation of least amount of path buffer per 387 * open action, etc.). 388 */ 389 typedef struct _psfa_action { 390 psfa_t psfaa_type; /* file action type */ 391 union { 392 int psfaa_filedes; /* fd to operate on */ 393 mach_port_name_t psfaa_fileport; /* fileport to operate on */ 394 }; 395 union { 396 struct { 397 int psfao_oflag; /* open flags to use */ 398 mode_t psfao_mode; /* mode for open */ 399 char psfao_path[PATH_MAX]; /* path to open */ 400 } psfaa_openargs; 401 struct { 402 int psfad_newfiledes; /* new file descriptor to use */ 403 } psfaa_dup2args; 404 struct { 405 char psfac_path[PATH_MAX]; /* path to chdir */ 406 } psfaa_chdirargs; 407 }; 408 } _psfa_action_t; 409 410 411 /* 412 * Internal representation of posix_spawn() file actions structure 413 * 414 * Notes: This is implemented as a structure followed by an array of 415 * file action records. The psfa_act_alloc value is the number 416 * of elements allocated in this array, and the psfa_act_count is 417 * the number of elements currently in use (to permit some form 418 * of preallocation, e.g. a power of 2 growth for reallocation, 419 * etc.). 420 * 421 * A possible future optimization would keep a size value and 422 * a structure base reference pointer to permit copyin to the 423 * kernel directly as a single blob, without damaging relative 424 * internal pointer math. It's probably better that this be a 425 * long long rather than a true pointer, to make it invariant 426 * for 32 vs. 64 bt programming SPIs. 427 */ 428 typedef struct _posix_spawn_file_actions { 429 int psfa_act_alloc; /* available actions space */ 430 int psfa_act_count; /* count of defined actions */ 431 _psfa_action_t psfa_act_acts[]; /* actions array (uses c99) */ 432 } *_posix_spawn_file_actions_t; 433 434 /* 435 * Calculate the size of a structure, given the number of elements that it is 436 * capable of containing. 437 */ 438 #define PSF_ACTIONS_SIZE(x) \ 439 PS_ACTION_SIZE(x, struct _posix_spawn_file_actions, _psfa_action_t) 440 441 /* 442 * Initial count of actions in a struct _posix_spawn_file_actions after it is 443 * first allocated; this should be non-zero, since we expect that one would not 444 * have been allocated unless there was an intent to use it. 445 */ 446 #define PSF_ACTIONS_INIT_COUNT 2 447 448 /* 449 * Structure defining the true third argument to the posix_spawn() system call 450 * entry point; we wrap it and pass a descriptor so that we can know the 451 * copyin size ahead of time, and deal with copying in variant lists of things 452 * as single monolithic units, instead of many individual elements. This is a 453 * performance optimization. 454 */ 455 struct _posix_spawn_args_desc { 456 __darwin_size_t attr_size; /* size of attributes block */ 457 _posix_spawnattr_t attrp; /* pointer to block */ 458 __darwin_size_t file_actions_size; /* size of file actions block */ 459 _posix_spawn_file_actions_t 460 file_actions; /* pointer to block */ 461 __darwin_size_t port_actions_size; /* size of port actions block */ 462 _posix_spawn_port_actions_t 463 port_actions; /* pointer to port block */ 464 __darwin_size_t mac_extensions_size; 465 _posix_spawn_mac_policy_extensions_t 466 mac_extensions; /* pointer to policy-specific 467 * attributes */ 468 __darwin_size_t coal_info_size; 469 struct _posix_spawn_coalition_info *coal_info; /* pointer to coalition info */ 470 471 __darwin_size_t persona_info_size; 472 struct _posix_spawn_persona_info *persona_info; 473 474 __darwin_size_t posix_cred_info_size; 475 struct _posix_spawn_posix_cred_info *posix_cred_info; 476 477 __darwin_size_t subsystem_root_path_size; 478 char *subsystem_root_path; 479 }; 480 481 #ifdef KERNEL 482 #include <sys/appleapiopts.h> 483 #ifdef __APPLE_API_PRIVATE 484 485 #if __DARWIN_ALIGN_NATURAL 486 #pragma options align=natural 487 #endif 488 489 struct user32__posix_spawn_args_desc { 490 uint32_t attr_size; /* size of attributes block */ 491 uint32_t attrp; /* pointer to block */ 492 uint32_t file_actions_size; /* size of file actions block */ 493 uint32_t file_actions; /* pointer to block */ 494 uint32_t port_actions_size; /* size of port actions block */ 495 uint32_t port_actions; /* pointer to block */ 496 uint32_t mac_extensions_size; 497 uint32_t mac_extensions; 498 uint32_t coal_info_size; 499 uint32_t coal_info; 500 uint32_t persona_info_size; 501 uint32_t persona_info; 502 uint32_t posix_cred_info_size; 503 uint32_t posix_cred_info; 504 uint32_t subsystem_root_path_size; 505 uint32_t subsystem_root_path; 506 }; 507 508 struct user__posix_spawn_args_desc { 509 user_size_t attr_size; /* size of attributes block */ 510 user_addr_t attrp; /* pointer to block */ 511 user_size_t file_actions_size; /* size of file actions block */ 512 user_addr_t file_actions; /* pointer to block */ 513 user_size_t port_actions_size; /* size of port actions block */ 514 user_addr_t port_actions; /* pointer to block */ 515 user_size_t mac_extensions_size; /* size of MAC-specific attrs. */ 516 user_addr_t mac_extensions; /* pointer to block */ 517 user_size_t coal_info_size; 518 user_addr_t coal_info; 519 user_size_t persona_info_size; 520 user_addr_t persona_info; 521 user_size_t posix_cred_info_size; 522 user_addr_t posix_cred_info; 523 user_size_t subsystem_root_path_size; 524 user_addr_t subsystem_root_path; 525 }; 526 527 528 #if __DARWIN_ALIGN_NATURAL 529 #pragma options align=reset 530 #endif 531 532 #endif /* __APPLE_API_PRIVATE */ 533 #endif /* KERNEL */ 534 535 #endif /* _SYS_SPAWN_INTERNAL_H_ */ 536