1 /*
2 * Copyright (c) 2000-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 * @OSF_COPYRIGHT@
30 */
31 /*
32 * Mach Operating System
33 * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
34 * All Rights Reserved.
35 *
36 * Permission to use, copy, modify and distribute this software and its
37 * documentation is hereby granted, provided that both the copyright
38 * notice and this permission notice appear in all copies of the
39 * software, derivative works or modified versions, and any portions
40 * thereof, and that both notices appear in supporting documentation.
41 *
42 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
43 * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
44 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
45 *
46 * Carnegie Mellon requests users of this software to return to
47 *
48 * Software Distribution Coordinator or [email protected]
49 * School of Computer Science
50 * Carnegie Mellon University
51 * Pittsburgh PA 15213-3890
52 *
53 * any improvements or extensions that they make and grant Carnegie Mellon
54 * the rights to redistribute these changes.
55 */
56 /*
57 * NOTICE: This file was modified by McAfee Research in 2004 to introduce
58 * support for mandatory and extensible security protections. This notice
59 * is included in support of clause 2.2 (b) of the Apple Public License,
60 * Version 2.0.
61 */
62 /*
63 */
64 /*
65 * File: mach/port.h
66 *
67 * Definition of a Mach port
68 *
69 * Mach ports are the endpoints to Mach-implemented communications
70 * channels (usually uni-directional message queues, but other types
71 * also exist).
72 *
73 * Unique collections of these endpoints are maintained for each
74 * Mach task. Each Mach port in the task's collection is given a
75 * [task-local] name to identify it - and the the various "rights"
76 * held by the task for that specific endpoint.
77 *
78 * This header defines the types used to identify these Mach ports
79 * and the various rights associated with them. For more info see:
80 *
81 * <mach/mach_port.h> - manipulation of port rights in a given space
82 * <mach/message.h> - message queue [and port right passing] mechanism
83 *
84 */
85
86 #ifndef _MACH_PORT_H_
87 #define _MACH_PORT_H_
88
89 #include <sys/cdefs.h>
90 #include <stdint.h>
91 #include <mach/boolean.h>
92 #include <mach/machine/vm_types.h>
93 #if XNU_KERNEL_PRIVATE
94 #include <ptrauth.h>
95 #endif /* XNU_KERNEL_PRIVATE */
96
97 /*
98 * mach_port_name_t - the local identity for a Mach port
99 *
100 * The name is Mach port namespace specific. It is used to
101 * identify the rights held for that port by the task whose
102 * namespace is implied [or specifically provided].
103 *
104 * Use of this type usually implies just a name - no rights.
105 * See mach_port_t for a type that implies a "named right."
106 *
107 */
108
109 typedef natural_t mach_port_name_t;
110 typedef mach_port_name_t *mach_port_name_array_t;
111
112 #ifdef KERNEL
113
114 /*
115 * mach_port_t - a named port right
116 *
117 * In the kernel, "rights" are represented [named] by pointers to
118 * the ipc port object in question. There is no port namespace for the
119 * rights to be collected.
120 *
121 * Actually, there is namespace for the kernel task. But most kernel
122 * code - including, but not limited to, Mach IPC code - lives in the
123 * limbo between the current user-level task and the "next" task. Very
124 * little of the kernel code runs in full kernel task context. So very
125 * little of it gets to use the kernel task's port name space.
126 *
127 * Because of this implementation approach, all in-kernel rights for
128 * a given port coalesce [have the same name/pointer]. The actual
129 * references are counted in the port itself. It is up to the kernel
130 * code in question to "just remember" how many [and what type of]
131 * rights it holds and handle them appropriately.
132 *
133 */
134
135 #ifndef MACH_KERNEL_PRIVATE
136 /*
137 * For kernel code that resides outside of Mach proper, we opaque the
138 * port structure definition.
139 */
140 struct ipc_port;
141
142 #endif /* MACH_KERNEL_PRIVATE */
143
144 typedef struct ipc_port *ipc_port_t;
145
146 #define IPC_PORT_NULL __unsafe_forge_single(ipc_port_t, NULL)
147 #define IPC_PORT_DEAD __unsafe_forge_single(ipc_port_t, ~0UL)
148 #define IPC_PORT_VALID(port) ipc_port_valid(port)
149
150 static inline boolean_t
ipc_port_valid(ipc_port_t port)151 ipc_port_valid(ipc_port_t port)
152 {
153 return port != IPC_PORT_DEAD && port;
154 }
155
156 typedef ipc_port_t mach_port_t;
157
158 /*
159 * Since the 32-bit and 64-bit representations of ~0 are different,
160 * explicitly handle MACH_PORT_DEAD
161 */
162
163 #define CAST_MACH_PORT_TO_NAME(x) ((mach_port_name_t)(uintptr_t)(x))
164 #define CAST_MACH_NAME_TO_PORT(x) ((x) == MACH_PORT_DEAD ? (mach_port_t)IPC_PORT_DEAD : (mach_port_t)(uintptr_t)(x))
165
166 #else /* KERNEL */
167
168 /*
169 * mach_port_t - a named port right
170 *
171 * In user-space, "rights" are represented by the name of the
172 * right in the Mach port namespace. Even so, this type is
173 * presented as a unique one to more clearly denote the presence
174 * of a right coming along with the name.
175 *
176 * Often, various rights for a port held in a single name space
177 * will coalesce and are, therefore, be identified by a single name
178 * [this is the case for send and receive rights]. But not
179 * always [send-once rights currently get a unique name for
180 * each right].
181 *
182 */
183
184 #include <sys/_types.h>
185 #include <sys/_types/_mach_port_t.h>
186
187 #endif /* KERNEL */
188
189 #if XNU_KERNEL_PRIVATE
190 #if __has_feature(ptrauth_calls)
191 #define __mach_port_array_auth \
192 __ptrauth(ptrauth_key_process_independent_data, 1, \
193 ptrauth_string_discriminator("mach_port_ool_t"))
194 #else
195 #define __mach_port_array_auth
196 #endif
197 typedef struct {
198 mach_port_t __mach_port_array_auth port;
199 } mach_port_ool_t;
200 typedef mach_port_ool_t *mach_port_array_t;
201 #else
202 typedef mach_port_t *mach_port_array_t;
203 #endif
204
205 /*
206 * MACH_PORT_NULL is a legal value that can be carried in messages.
207 * It indicates the absence of any port or port rights. (A port
208 * argument keeps the message from being "simple", even if the
209 * value is MACH_PORT_NULL.) The value MACH_PORT_DEAD is also a legal
210 * value that can be carried in messages. It indicates
211 * that a port right was present, but it died.
212 */
213
214 #if defined(XNU_KERNEL_PRIVATE) && defined(__cplusplus)
215 #define MACH_PORT_NULL NULL
216 #else
217 #define MACH_PORT_NULL 0 /* intentional loose typing */
218 #endif
219 #define MACH_PORT_DEAD ((mach_port_name_t) ~0)
220 #if MACH_KERNEL_PRIVATE
221 #define MACH_PORT_SPECIAL_DEFAULT ((mach_port_name_t)1)
222 #endif /* MACH_KERNEL_PRIVATE */
223 #define MACH_PORT_VALID(name) \
224 (((name) != MACH_PORT_NULL) && \
225 ((name) != MACH_PORT_DEAD))
226
227
228 /*
229 * For kernel-selected [assigned] port names, the name is
230 * comprised of two parts: a generation number and an index.
231 * This approach keeps the exact same name from being generated
232 * and reused too quickly [to catch right/reference counting bugs].
233 * The dividing line between the constituent parts is exposed so
234 * that efficient "mach_port_name_t to data structure pointer"
235 * conversion implementation can be made.
236 */
237
238 #define MACH_PORT_INDEX(name) ((name) >> 8)
239 #define MACH_PORT_GEN(name) (((name) & 0xff) << 24)
240 #define MACH_PORT_MAKE(index, gen) (((index) << 8) | ((gen) >> 24))
241
242 /*
243 * These are the different rights a task may have for a port.
244 * The MACH_PORT_RIGHT_* definitions are used as arguments
245 * to mach_port_allocate, mach_port_get_refs, etc, to specify
246 * a particular right to act upon. The mach_port_names and
247 * mach_port_type calls return bitmasks using the MACH_PORT_TYPE_*
248 * definitions. This is because a single name may denote
249 * multiple rights.
250 */
251
252 #if XNU_KERNEL_PRIVATE
253 __enum_closed_decl(mach_port_right_t, uint32_t, {
254 MACH_PORT_RIGHT_SEND = 0,
255 MACH_PORT_RIGHT_RECEIVE = 1,
256 MACH_PORT_RIGHT_SEND_ONCE = 2,
257 MACH_PORT_RIGHT_PORT_SET = 3,
258 MACH_PORT_RIGHT_DEAD_NAME = 4,
259 MACH_PORT_RIGHT_LABELH = 5, /* obsolete right */
260 MACH_PORT_RIGHT_NUMBER = 6, /* right not implemented */
261 });
262
263 #define MACH_PORT_RIGHT_VALID_TRANSLATE(right) \
264 ((right) >= MACH_PORT_RIGHT_SEND && (right) <= MACH_PORT_RIGHT_DEAD_NAME)
265 #else
266 typedef natural_t mach_port_right_t;
267
268 #define MACH_PORT_RIGHT_SEND ((mach_port_right_t) 0)
269 #define MACH_PORT_RIGHT_RECEIVE ((mach_port_right_t) 1)
270 #define MACH_PORT_RIGHT_SEND_ONCE ((mach_port_right_t) 2)
271 #define MACH_PORT_RIGHT_PORT_SET ((mach_port_right_t) 3)
272 #define MACH_PORT_RIGHT_DEAD_NAME ((mach_port_right_t) 4)
273 #define MACH_PORT_RIGHT_LABELH ((mach_port_right_t) 5) /* obsolete right */
274 #define MACH_PORT_RIGHT_NUMBER ((mach_port_right_t) 6) /* right not implemented */
275 #endif
276
277 #if XNU_KERNEL_PRIVATE
278 #define MACH_PORT_TYPE(right) ((1u) << ((right) + 16))
279
280 __options_closed_decl(mach_port_type_t, uint32_t, {
281 MACH_PORT_TYPE_NONE = 0,
282 MACH_PORT_TYPE_SEND = MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND),
283 MACH_PORT_TYPE_RECEIVE = MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE),
284 MACH_PORT_TYPE_SEND_ONCE = MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE),
285 MACH_PORT_TYPE_PORT_SET = MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET),
286 MACH_PORT_TYPE_DEAD_NAME = MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME),
287
288 /* Dummy type bits that mach_port_type/mach_port_names can return. */
289 MACH_PORT_TYPE_DNREQUEST = 0x80000000,
290 MACH_PORT_TYPE_SPREQUEST = 0x40000000,
291 MACH_PORT_TYPE_SPREQUEST_DELAYED = 0x20000000,
292 });
293 typedef mach_port_type_t *mach_port_type_array_t;
294 #else
295 #define MACH_PORT_TYPE(right) \
296 ((mach_port_type_t)(((mach_port_type_t) 1) \
297 << ((right) + ((mach_port_right_t) 16))))
298
299 typedef natural_t mach_port_type_t;
300 typedef mach_port_type_t *mach_port_type_array_t;
301
302 #define MACH_PORT_TYPE_NONE ((mach_port_type_t) 0L)
303 #define MACH_PORT_TYPE_SEND MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND)
304 #define MACH_PORT_TYPE_RECEIVE MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE)
305 #define MACH_PORT_TYPE_SEND_ONCE MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE)
306 #define MACH_PORT_TYPE_PORT_SET MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET)
307 #define MACH_PORT_TYPE_DEAD_NAME MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME)
308 #define MACH_PORT_TYPE_LABELH MACH_PORT_TYPE(MACH_PORT_RIGHT_LABELH) /* obsolete */
309 /* Dummy type bits that mach_port_type/mach_port_names can return. */
310 #define MACH_PORT_TYPE_DNREQUEST 0x80000000
311 #define MACH_PORT_TYPE_SPREQUEST 0x40000000
312 #define MACH_PORT_TYPE_SPREQUEST_DELAYED 0x20000000
313 #endif
314
315 /* Convenient combinations. */
316
317 #define MACH_PORT_TYPE_SEND_RECEIVE \
318 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_RECEIVE)
319 #define MACH_PORT_TYPE_SEND_RIGHTS \
320 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_SEND_ONCE)
321 #define MACH_PORT_TYPE_PORT_RIGHTS \
322 (MACH_PORT_TYPE_SEND_RIGHTS|MACH_PORT_TYPE_RECEIVE)
323 #define MACH_PORT_TYPE_PORT_OR_DEAD \
324 (MACH_PORT_TYPE_PORT_RIGHTS|MACH_PORT_TYPE_DEAD_NAME)
325 #define MACH_PORT_TYPE_ALL_RIGHTS \
326 (MACH_PORT_TYPE_PORT_OR_DEAD|MACH_PORT_TYPE_PORT_SET)
327
328 /* User-references for capabilities. */
329
330 typedef natural_t mach_port_urefs_t;
331 typedef integer_t mach_port_delta_t; /* change in urefs */
332
333 /* Attributes of ports. (See mach_port_get_receive_status.) */
334
335 typedef natural_t mach_port_seqno_t; /* sequence number */
336 typedef natural_t mach_port_mscount_t; /* make-send count */
337 typedef natural_t mach_port_msgcount_t; /* number of msgs */
338 typedef natural_t mach_port_rights_t; /* number of rights */
339
340 /*
341 * Are there outstanding send rights for a given port?
342 */
343 #define MACH_PORT_SRIGHTS_NONE 0 /* no srights */
344 #define MACH_PORT_SRIGHTS_PRESENT 1 /* srights */
345 typedef unsigned int mach_port_srights_t; /* status of send rights */
346
347 typedef struct mach_port_status {
348 mach_port_rights_t mps_pset; /* count of containing port sets */
349 mach_port_seqno_t mps_seqno; /* sequence number */
350 mach_port_mscount_t mps_mscount; /* make-send count */
351 mach_port_msgcount_t mps_qlimit; /* queue limit */
352 mach_port_msgcount_t mps_msgcount; /* number in the queue */
353 mach_port_rights_t mps_sorights; /* how many send-once rights */
354 boolean_t mps_srights; /* do send rights exist? */
355 boolean_t mps_pdrequest; /* port-deleted requested? */
356 boolean_t mps_nsrequest; /* no-senders requested? */
357 natural_t mps_flags; /* port flags */
358 } mach_port_status_t;
359
360 /* System-wide values for setting queue limits on a port */
361 #define MACH_PORT_QLIMIT_ZERO (0)
362 #define MACH_PORT_QLIMIT_BASIC (5)
363 #define MACH_PORT_QLIMIT_SMALL (16)
364 #define MACH_PORT_QLIMIT_LARGE (1024)
365 #define MACH_PORT_QLIMIT_KERNEL (65534)
366 #define MACH_PORT_QLIMIT_MIN MACH_PORT_QLIMIT_ZERO
367 #define MACH_PORT_QLIMIT_DEFAULT MACH_PORT_QLIMIT_BASIC
368 #define MACH_PORT_QLIMIT_MAX MACH_PORT_QLIMIT_LARGE
369
370 typedef struct mach_port_limits {
371 mach_port_msgcount_t mpl_qlimit; /* number of msgs */
372 } mach_port_limits_t;
373
374 /* Possible values for mps_flags (part of mach_port_status_t) */
375 #define MACH_PORT_STATUS_FLAG_TEMPOWNER 0x01
376 #define MACH_PORT_STATUS_FLAG_GUARDED 0x02
377 #define MACH_PORT_STATUS_FLAG_STRICT_GUARD 0x04
378 #define MACH_PORT_STATUS_FLAG_IMP_DONATION 0x08
379 #define MACH_PORT_STATUS_FLAG_REVIVE 0x10
380 #define MACH_PORT_STATUS_FLAG_TASKPTR 0x20
381 #define MACH_PORT_STATUS_FLAG_GUARD_IMMOVABLE_RECEIVE 0x40
382 #define MACH_PORT_STATUS_FLAG_NO_GRANT 0x80 /* Obsolete */
383
384 typedef struct mach_port_info_ext {
385 mach_port_status_t mpie_status;
386 mach_port_msgcount_t mpie_boost_cnt;
387 uint32_t reserved[6];
388 } mach_port_info_ext_t;
389
390 typedef struct mach_port_guard_info {
391 uint64_t mpgi_guard; /* guard value */
392 } mach_port_guard_info_t;
393
394 typedef integer_t *mach_port_info_t; /* varying array of natural_t */
395
396 /* Flavors for mach_port_get/set/assert_attributes() */
397 typedef int mach_port_flavor_t;
398 #define MACH_PORT_LIMITS_INFO 1 /* uses mach_port_limits_t */
399 #define MACH_PORT_RECEIVE_STATUS 2 /* uses mach_port_status_t */
400 #define MACH_PORT_DNREQUESTS_SIZE 3 /* info is int */
401 #define MACH_PORT_TEMPOWNER 4 /* indicates receive right will be reassigned to another task */
402 #define MACH_PORT_IMPORTANCE_RECEIVER 5 /* indicates recieve right accepts priority donation */
403 #define MACH_PORT_DENAP_RECEIVER 6 /* indicates receive right accepts de-nap donation */
404 #define MACH_PORT_INFO_EXT 7 /* uses mach_port_info_ext_t */
405 #define MACH_PORT_GUARD_INFO 8 /* asserts if the strict guard value is correct */
406 #define MACH_PORT_SERVICE_THROTTLED 9 /* info is an integer that indicates if service port is throttled or not */
407
408 #define MACH_PORT_LIMITS_INFO_COUNT ((natural_t) \
409 (sizeof(mach_port_limits_t)/sizeof(natural_t)))
410 #define MACH_PORT_RECEIVE_STATUS_COUNT ((natural_t) \
411 (sizeof(mach_port_status_t)/sizeof(natural_t)))
412 #define MACH_PORT_DNREQUESTS_SIZE_COUNT 1
413 #define MACH_PORT_INFO_EXT_COUNT ((natural_t) \
414 (sizeof(mach_port_info_ext_t)/sizeof(natural_t)))
415 #define MACH_PORT_GUARD_INFO_COUNT ((natural_t) \
416 (sizeof(mach_port_guard_info_t)/sizeof(natural_t)))
417 #define MACH_PORT_SERVICE_THROTTLED_COUNT 1
418
419 /*
420 * Structure used to pass information about port allocation requests.
421 * Must be padded to 64-bits total length.
422 */
423 typedef struct mach_port_qos {
424 unsigned int name:1; /* name given */
425 unsigned int prealloc:1; /* prealloced message */
426 boolean_t pad1:30;
427 natural_t len;
428 } mach_port_qos_t;
429
430 /*
431 * Structure used to pass information about the service port
432 */
433 #define MACH_SERVICE_PORT_INFO_STRING_NAME_MAX_BUF_LEN 255 /* Maximum length of the port string name buffer */
434
435 typedef struct mach_service_port_info {
436 char mspi_string_name[MACH_SERVICE_PORT_INFO_STRING_NAME_MAX_BUF_LEN]; /* Service port's string name */
437 uint8_t mspi_domain_type; /* Service port domain */
438 } mach_service_port_info_data_t;
439
440 #define MACH_SERVICE_PORT_INFO_COUNT ((char) \
441 (sizeof(mach_service_port_info_data_t)/sizeof(char)))
442
443 typedef struct mach_service_port_info * mach_service_port_info_t;
444
445 /*
446 * Platform binaries are not allowed to send OOL port array to any port.
447 *
448 * MACH_MSG_OOL_PORTS_DESCRIPTOR are allowed to be sent ONLY to receive
449 * rights that are explicitly allow to receive that descriptor.
450 *
451 * Such ports have a dedicated port type, and are created using the
452 * MPO_CONNECTION_PORT_WITH_PORT_ARRAY flag.
453 *
454 * Creation of such ports requires the binary to have the following entitlement.
455 */
456 #define MACH_PORT_CONNECTION_PORT_WITH_PORT_ARRAY "com.apple.developer.allow-connection-port-with-port-array"
457
458 /* Allows 1p process to create provisional reply port (to be rename to weak reply port) */
459 #define MACH_PORT_PROVISIONAL_REPLY_ENTITLEMENT "com.apple.private.allow-weak-reply-port"
460
461 /*
462 * Flags for mach_port_options (used for
463 * invocation of mach_port_construct).
464 * Indicates attributes to be set for the newly
465 * allocated port.
466 */
467
468 /* MPO options flags */
469 #define MPO_CONTEXT_AS_GUARD 0x01 /* Add guard to the port */
470 #define MPO_QLIMIT 0x02 /* Set qlimit for the port msg queue */
471 #define MPO_TEMPOWNER 0x04 /* Set the tempowner bit of the port */
472 #define MPO_IMPORTANCE_RECEIVER 0x08 /* Mark the port as importance receiver */
473 #define MPO_INSERT_SEND_RIGHT 0x10 /* Insert a send right for the port */
474 #define MPO_STRICT 0x20 /* Apply strict guarding for port */
475 #define MPO_DENAP_RECEIVER 0x40 /* Mark the port as App de-nap receiver */
476 #define MPO_IMMOVABLE_RECEIVE 0x80 /* Mark the port as immovable; protected by the guard context */
477 #define MPO_FILTER_MSG 0x100 /* Allow message filtering */
478 #define MPO_TG_BLOCK_TRACKING 0x200 /* Track blocking relationship for thread group during sync IPC */
479 #define MPO_ENFORCE_REPLY_PORT_SEMANTICS 0x2000 /* When talking to this port, local port of mach msg needs to follow reply port semantics.*/
480 /* This service port has requested security hardening */
481 #define MPO_STRICT_SERVICE_PORT (MPO_SERVICE_PORT | MPO_ENFORCE_REPLY_PORT_SEMANTICS)
482
483 #define MPO_OPTIONS_MASK \
484 (MPO_CONTEXT_AS_GUARD | \
485 MPO_QLIMIT | \
486 MPO_TEMPOWNER | \
487 MPO_IMPORTANCE_RECEIVER | \
488 MPO_INSERT_SEND_RIGHT | \
489 MPO_STRICT | \
490 MPO_DENAP_RECEIVER | \
491 MPO_IMMOVABLE_RECEIVE | \
492 MPO_FILTER_MSG | \
493 MPO_TG_BLOCK_TRACKING | \
494 MPO_ENFORCE_REPLY_PORT_SEMANTICS)
495
496 /* MPO port type flags */
497 #define MPO_MAKE_PORT_TYPE(a, b) (((a & 0x7) << 14) | ((b & 0x7) << 10))
498 #define MPO_PORT_TYPE_MASK MPO_MAKE_PORT_TYPE(0x7, 0x7) /* 0x1dc00 */
499 #if KERNEL_PRIVATE
500 __enum_closed_decl(mpo_flags_t, uint32_t, {
501 #else /* KERNEL_PRIVATE */
502 /* These need to be defined for libxpc and other clients who `#ifdef` */
503 #define MPO_PORT MPO_PORT
504 #define MPO_SERVICE_PORT MPO_SERVICE_PORT
505 #define MPO_CONNECTION_PORT MPO_CONNECTION_PORT
506 #define MPO_REPLY_PORT MPO_REPLY_PORT
507 #define MPO_PROVISIONAL_REPLY_PORT MPO_PROVISIONAL_REPLY_PORT
508 #define MPO_EXCEPTION_PORT MPO_EXCEPTION_PORT
509 #define MPO_CONNECTION_PORT_WITH_PORT_ARRAY MPO_CONNECTION_PORT_WITH_PORT_ARRAY
510 __options_decl(mpo_flags_t, uint32_t, {
511 #endif /* KERNEL_PRIVATE */
512 /* Your classic IOT_PORT, an uninteresting message queue */
513 MPO_PORT = MPO_MAKE_PORT_TYPE(0, 0), /* 0x0 */
514 /* Create a service port with the given name; should be used only by launchd */
515 MPO_SERVICE_PORT = MPO_MAKE_PORT_TYPE(0, 1), /* 0x400 */
516 /* Derive new peer connection port from a given service port */
517 MPO_CONNECTION_PORT = MPO_MAKE_PORT_TYPE(0, 2), /* 0x800 */
518 /* Designate port as a reply port */
519 MPO_REPLY_PORT = MPO_MAKE_PORT_TYPE(0, 4), /* 0x1000 */
520 /* Designate port as a provisional (fake) reply port */
521 MPO_PROVISIONAL_REPLY_PORT = MPO_MAKE_PORT_TYPE(1, 0), /* 0x4000 */
522 /* Used for hardened exceptions - immovable */
523 MPO_EXCEPTION_PORT = MPO_MAKE_PORT_TYPE(2, 0), /* 0x8000 */
524 /* Can receive OOL port array descriptors */
525 MPO_CONNECTION_PORT_WITH_PORT_ARRAY = MPO_MAKE_PORT_TYPE(4, 0), /* 0x10000 */
526 });
527 #define MPO_UNUSED_BITS ~(MPO_OPTIONS_MASK | MPO_PORT_TYPE_MASK)
528
529 /* Denotes an anonymous service */
530 #define MPO_ANONYMOUS_SERVICE (MACH_PORT_DEAD - 1)
531
532 /*
533 * Structure to define optional attributes for a newly
534 * constructed port.
535 */
536 typedef struct mach_port_options {
537 uint32_t flags;
538 mach_port_limits_t mpl; /* Message queue limit for port */
539 union {
540 uint64_t reserved[2]; /* Reserved */
541 mach_port_name_t work_interval_port; /* Work interval port */
542 #if KERNEL
543 uint32_t service_port_info32; /* Service port (MPO_SERVICE_PORT) */
544 uint64_t service_port_info64; /* Service port (MPO_SERVICE_PORT) */
545 #else
546 mach_service_port_info_t service_port_info; /* Service port (MPO_SERVICE_PORT) */
547 #endif
548 mach_port_name_t service_port_name; /* Service port (MPO_CONNECTION_PORT) */
549 };
550 }mach_port_options_t;
551
552 typedef mach_port_options_t *mach_port_options_ptr_t;
553
554 /* Mach Port Guarding definitions */
555
556 /*
557 * EXC_GUARD represents a guard violation for both
558 * mach ports and file descriptors. GUARD_TYPE_ is used
559 * to differentiate among them.
560 */
561 #define GUARD_TYPE_MACH_PORT 0x1
562
563 /*
564 * Reasons for exception for a guarded mach port
565 *
566 * Arguments are documented in doc/mach_ipc/guard_exceptions.md,
567 * please update when adding a new type.
568 *
569 * Note: these had been designed as bitfields,
570 * hence the weird spaced values,
571 * but are truly an enum, please add new values in the "holes".
572 */
573 enum mach_port_guard_exception_codes {
574 kGUARD_EXC_NONE = 0, /* never sent */
575 kGUARD_EXC_DESTROY = 1,
576 kGUARD_EXC_MOD_REFS = 2,
577 kGUARD_EXC_INVALID_OPTIONS = 3,
578 kGUARD_EXC_SET_CONTEXT = 4,
579 kGUARD_EXC_THREAD_SET_STATE = 5,
580 kGUARD_EXC_EXCEPTION_BEHAVIOR_ENFORCE = 6,
581 kGUARD_EXC_SERVICE_PORT_VIOLATION_FATAL = 7, /* unused, for future sp defense enablement */
582 kGUARD_EXC_UNGUARDED = 8,
583 kGUARD_EXC_KOBJECT_REPLY_PORT_SEMANTICS = 9,
584 kGUARD_EXC_REQUIRE_REPLY_PORT_SEMANTICS = 10,
585 kGUARD_EXC_INCORRECT_GUARD = 16,
586 kGUARD_EXC_IMMOVABLE = 32,
587 kGUARD_EXC_STRICT_REPLY = 64,
588 kGUARD_EXC_INVALID_NOTIFICATION_REQ = 65,
589 kGUARD_EXC_INVALID_MPO_ENTITLEMENT = 66,
590 kGUARD_EXC_DESCRIPTOR_VIOLATION = 67,
591 kGUARD_EXC_MSG_FILTERED = 128,
592 /* start of [optionally] non-fatal guards */
593 kGUARD_EXC_INVALID_RIGHT = 256,
594 kGUARD_EXC_INVALID_NAME = 512,
595 kGUARD_EXC_INVALID_VALUE = 1u << 10,
596 kGUARD_EXC_INVALID_ARGUMENT = 1u << 11, /* really kGUARD_EXC_ALREADY_GUARDED */
597 kGUARD_EXC_RIGHT_EXISTS = 1u << 12, /* unused */
598 kGUARD_EXC_KERN_NO_SPACE = 1u << 13, /* unused */
599 kGUARD_EXC_KERN_FAILURE = 1u << 14, /* really kGUARD_EXC_INVALID_PDREQUEST */
600 kGUARD_EXC_KERN_RESOURCE = 1u << 15, /* unused */
601 kGUARD_EXC_SEND_INVALID_REPLY = 1u << 16,
602 kGUARD_EXC_SEND_INVALID_VOUCHER = 1u << 17,
603 kGUARD_EXC_SEND_INVALID_RIGHT = 1u << 18,
604 kGUARD_EXC_RCV_INVALID_NAME = 1u << 19,
605 /* start of always non-fatal guards */
606 kGUARD_EXC_RCV_GUARDED_DESC = 0x00100000, /* for development only */
607 kGUARD_EXC_SERVICE_PORT_VIOLATION_NON_FATAL = 0x00100001, /* unused, for future sp defense enablement */
608 kGUARD_EXC_PROVISIONAL_REPLY_PORT = 0x00100002, /* unused */
609 kGUARD_EXC_OOL_PORT_ARRAY_CREATION = 0x00100003, /* unused */
610 kGUARD_EXC_MOVE_PROVISIONAL_REPLY_PORT = 0x00100004,
611 kGUARD_EXC_REPLY_PORT_SINGLE_SO_RIGHT = 0x00100005,
612 kGUARD_EXC_MOD_REFS_NON_FATAL = 1u << 21,
613 kGUARD_EXC_IMMOVABLE_NON_FATAL = 1u << 22, /* unused*/
614 };
615
616 #define MAX_FATAL_kGUARD_EXC_CODE kGUARD_EXC_MSG_FILTERED
617 #define MAX_OPTIONAL_kGUARD_EXC_CODE kGUARD_EXC_RCV_INVALID_NAME
618
619 #ifdef XNU_KERNEL_PRIVATE
620 /*
621 * Mach port guard payload construction helpers
622 *
623 * The order of the argument is the same as their position in
624 * the payload, with flag being the MSB and the last argument
625 * in the least siginificant end.
626 */
627 #define MPG_24BIT_MASK ((0x1ULL << 24) - 1)
628
629 /*
630 * +-------------+----------------+----------------------+
631 * |[63:56] flag | [55:32] unused | [31:0] a |
632 * +-------------+----------------+----------------------+
633 */
634 __header_always_inline __attribute__((overloadable))
635 uint64_t
MPG_PAYLOAD(uint8_t flag,uint32_t a)636 MPG_PAYLOAD(uint8_t flag, uint32_t a)
637 {
638 return ((uint64_t)flag << 56) | a;
639 }
640
641 /*
642 * +-------------+----------------+----------------------+
643 * |[63:56] flag | [55:32] a | [31:0] b |
644 * +-------------+----------------+----------------------+
645 */
646 __header_always_inline __attribute__((overloadable))
647 uint64_t
MPG_PAYLOAD(uint8_t flag,uint32_t a,uint32_t b)648 MPG_PAYLOAD(uint8_t flag, uint32_t a, uint32_t b)
649 {
650 return ((uint64_t)flag << 56) |
651 ((uint64_t)(a & MPG_24BIT_MASK) << 32) | b;
652 }
653
654 /*
655 * +-------------+----------------+-----------+----------+
656 * |[63:56] flag | [55:32] a | [31:16] b | [15:0] c |
657 * +-------------+----------------+-----------+----------+
658 */
659 __header_always_inline __attribute__((overloadable))
660 uint64_t
MPG_PAYLOAD(uint8_t flag,uint32_t a,uint16_t b,uint16_t c)661 MPG_PAYLOAD(uint8_t flag, uint32_t a, uint16_t b, uint16_t c)
662 {
663 return ((uint64_t)flag << 56) |
664 ((uint64_t)(a & MPG_24BIT_MASK) << 32) |
665 ((uint64_t)b << 16) |
666 c;
667 }
668 #endif /* XNU_KERNEL_PRIVATE */
669
670 /*
671 * Mach port guard flags.
672 */
673 #define MPG_FLAGS_NONE 0x00
674
675 /*
676 * These flags are used as bits in the subcode of kGUARD_EXC_STRICT_REPLY exceptions.
677 */
678 #define MPG_FLAGS_STRICT_REPLY_INVALID_VOUCHER 0x04
679 #define MPG_FLAGS_STRICT_REPLY_MISMATCHED_PERSONA 0x10
680
681 /*
682 * These flags are used as bits in the subcode of kGUARD_EXC_MOD_REFS exceptions.
683 */
684 #define MPG_FLAGS_MOD_REFS_PINNED_DEALLOC 0x01
685 #define MPG_FLAGS_MOD_REFS_PINNED_DESTROY 0x02
686 #define MPG_FLAGS_MOD_REFS_PINNED_COPYIN 0x03
687
688 /*
689 * These flags are used as bits in the subcode of kGUARD_EXC_INVALID_RIGHT exceptions.
690 */
691 #define MPG_FLAGS_INVALID_RIGHT_RECV 0x01 /* does not have receive right */
692 #define MPG_FLAGS_INVALID_RIGHT_DELTA 0x02 /* ipc_right_delta() */
693 #define MPG_FLAGS_INVALID_RIGHT_DESTRUCT 0x03 /* ipc_right_destruct() */
694 #define MPG_FLAGS_INVALID_RIGHT_COPYIN 0x04 /* ipc_right_copyin() */
695 #define MPG_FLAGS_INVALID_RIGHT_DEALLOC 0x05 /* ipc_right_dealloc() */
696 #define MPG_FLAGS_INVALID_RIGHT_DEALLOC_KERNEL 0x06 /* mach_port_deallocate_kernel() */
697 #define MPG_FLAGS_INVALID_RIGHT_TRANSLATE_PORT 0x07 /* port in ipc_object_translate_port_pset() */
698 #define MPG_FLAGS_INVALID_RIGHT_TRANSLATE_PSET 0x08 /* pset in ipc_object_translate_port_pset() */
699
700 /*
701 * These flags are used as bits in the subcode of kGUARD_EXC_INVALID_VALUE exceptions.
702 */
703 #define MPG_FLAGS_INVALID_VALUE_PEEK 0x01 /* mach_port_peek() */
704 #define MPG_FLAGS_INVALID_VALUE_DELTA 0x02 /* ipc_right_delta() */
705 #define MPG_FLAGS_INVALID_VALUE_DESTRUCT 0x03 /* ipc_right_destruct() */
706
707 /*
708 * These flags are used as bits in the subcode of kGUARD_EXC_KERN_FAILURE exceptions.
709 */
710 #define MPG_FLAGS_KERN_FAILURE_TASK 0x01 /* task other than launchd arm pd on service ports */
711 #define MPG_FLAGS_KERN_FAILURE_NOTIFY_TYPE 0x02 /* not using IOT_NOTIFICATION_PORT for pd notification */
712 #define MPG_FLAGS_KERN_FAILURE_NOTIFY_RECV 0x03 /* notification port not owned by launchd */
713 #define MPG_FLAGS_KERN_FAILURE_MULTI_NOTI 0x04 /* register multiple pd notification */
714
715 /*
716 * These flags are used as bits in the subcode of kGUARD_EXC_SEND_INVALID_RIGHT exceptions.
717 */
718 #define MPG_FLAGS_SEND_INVALID_RIGHT_PORT 0x01 /* ipc_kmsg_copyin_port_descriptor() */
719 #define MPG_FLAGS_SEND_INVALID_RIGHT_OOL_PORT 0x02 /* ipc_kmsg_copyin_ool_ports_descriptor() */
720 #define MPG_FLAGS_SEND_INVALID_RIGHT_GUARDED 0x03 /* ipc_kmsg_copyin_guarded_port_descriptor */
721
722 /*
723 * These flags are used as bits in the subcode of kGUARD_EXC_INVALID_OPTIONS exceptions.
724 */
725 #define MPG_FLAGS_INVALID_OPTIONS_OOL_DISP 0x01 /* ipc_kmsg_copyin_ool_ports_descriptor() */
726 #define MPG_FLAGS_INVALID_OPTIONS_OOL_ARRAYS 0x02 /* ipc_validate_kmsg_header_from_user() */
727 #define MPG_FLAGS_INVALID_OPTIONS_OOL_RIGHT 0x03 /* ipc_validate_kmsg_header_from_user() */
728
729 /*
730 * Flags for mach_port_guard_with_flags. These flags extend
731 * the attributes associated with a guarded port.
732 */
733 #define MPG_STRICT 0x01 /* Apply strict guarding for a port */
734 #define MPG_IMMOVABLE_RECEIVE 0x02 /* Receive right cannot be moved out of the space */
735
736 #if !__DARWIN_UNIX03 && !defined(_NO_PORT_T_FROM_MACH)
737 /*
738 * Mach 3.0 renamed everything to have mach_ in front of it.
739 * These types and macros are provided for backward compatibility
740 * but are deprecated.
741 */
742 typedef mach_port_t port_t;
743 typedef mach_port_name_t port_name_t;
744 typedef mach_port_name_t *port_name_array_t;
745
746 #define PORT_NULL ((port_t) 0)
747 #define PORT_DEAD ((port_t) ~0)
748 #define PORT_VALID(name) \
749 ((port_t)(name) != PORT_NULL && (port_t)(name) != PORT_DEAD)
750
751 #endif /* !__DARWIN_UNIX03 && !_NO_PORT_T_FROM_MACH */
752
753 #endif /* _MACH_PORT_H_ */
754