1 /*
2 * Copyright (c) 2023 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 #ifndef _IPC_IPC_POLICY_H_
30 #define _IPC_IPC_POLICY_H_
31
32 #include <kern/assert.h>
33 #include <ipc/port.h>
34 #include <ipc/ipc_types.h>
35 #include <ipc/ipc_port.h>
36
37
38 __BEGIN_DECLS __ASSUME_PTR_ABI_SINGLE_BEGIN
39 #pragma GCC visibility push(hidden)
40
41 /*!
42 * @file <ipc/ipc_policy.h>
43 *
44 * @description
45 * This file exports interfaces that implement various security policies
46 * for Mach IPC.
47 */
48
49
50 #pragma mark compile time globals and configurations
51
52 /*!
53 * @const IPC_HAS_LEGACY_MACH_MSG_TRAP
54 * Whether the legacy mach_msg_trap() is (somewhat) supported
55 */
56 #if XNU_TARGET_OS_OSX
57 #define IPC_HAS_LEGACY_MACH_MSG_TRAP 1
58 #else
59 #define IPC_HAS_LEGACY_MACH_MSG_TRAP 0
60 #endif /* XNU_TARGET_OS_OSX */
61
62 /*!
63 * @const IPC_KOBJECT_DESC_MAX
64 * The maximum number of inline descriptors
65 * allowed in an incoming MACH64_SEND_KOBJECT_CALL message.
66 */
67 #define IPC_KOBJECT_DESC_MAX 3
68 /*!
69 * @const IPC_KOBJECT_RDESC_MAX
70 * The maximum number of inline descriptors
71 * allowed in a reply to a MACH64_SEND_KOBJECT_CALL message.
72 */
73 #define IPC_KOBJECT_RDESC_MAX 32
74
75 /*!
76 * @const IPC_KMSG_MAX_BODY_SPACE
77 * Maximum size of ipc kmsg body sizes (not including trailer or aux).
78 */
79 #define IPC_KMSG_MAX_BODY_SPACE ((64 * 1024 * 1024 * 3) / 4 - MAX_TRAILER_SIZE)
80
81 /*!
82 * @const IPC_KMSG_MAX_AUX_DATA_SPACE
83 * Maximum size for the auxiliary data of an IPC kmsg.
84 */
85 #define IPC_KMSG_MAX_AUX_DATA_SPACE 1024
86
87 /*!
88 * @const IPC_KMSG_MAX_OOL_PORT_COUNT
89 * The maximum number of ports that can be sent at once in a message.
90 */
91 #define IPC_KMSG_MAX_OOL_PORT_COUNT 16383
92
93 /*!
94 * @const IPC_POLICY_ENHANCED_V0
95 * This policy represents platform binaries, hardened-runtime and
96 * everything below it.
97 */
98 #define IPC_POLICY_ENHANCED_V0 \
99 (IPC_SPACE_POLICY_ENHANCED | IPC_SPACE_POLICY_ENHANCED_V0)
100
101 /*!
102 * @const IPC_POLICY_ENHANCED_V1
103 * This policy represents ES features exposed to 3P in FY2024 release.
104 */
105 #define IPC_POLICY_ENHANCED_V1 \
106 (IPC_SPACE_POLICY_ENHANCED | IPC_SPACE_POLICY_ENHANCED_V1)
107
108 /*!
109 * @const IPC_POLICY_ENHANCED_V2
110 * This policy represents ES features exposed to 3P in FY2025 release.
111 */
112 #define IPC_POLICY_ENHANCED_V2 \
113 (IPC_SPACE_POLICY_ENHANCED | IPC_SPACE_POLICY_ENHANCED_V2)
114
115 #pragma mark policy tunables
116
117 __options_decl(ipc_control_port_options_t, uint32_t, {
118 ICP_OPTIONS_NONE = 0x00,
119
120 /* policy for IPC_SPACE_POLICY_{PLATFORM,HARDENED} */
121 ICP_OPTIONS_PINNED_1P_SOFT = 0x01,
122 ICP_OPTIONS_PINNED_1P_HARD = 0x02,
123 ICP_OPTIONS_IMMOVABLE_1P_HARD = 0x04,
124
125 /* policy for other processes */
126 ICP_OPTIONS_PINNED_3P_SOFT = 0x08,
127 ICP_OPTIONS_PINNED_3P_HARD = 0x10,
128 ICP_OPTIONS_IMMOVABLE_3P_HARD = 0x20,
129 });
130
131 /*!
132 * @brief
133 * Policy for task and thread control ports.
134 */
135 extern ipc_control_port_options_t ipc_control_port_options;
136
137 /*!
138 * @brief
139 * Whether service port defense in depth is enabled.
140 */
141 extern bool service_port_defense_enabled;
142
143 /*!
144 * @brief
145 * Whether out-of-line port array descriptor
146 * restrictions are enabled.
147 */
148 extern bool ool_port_array_enforced;
149
150 #pragma mark policy utils
151
152 /*!
153 * @brief
154 * Denote that a path is unreachable.
155 *
156 * @discussion
157 * If this codepath is ever reached, it will reliably panic,
158 * even on release kernels.
159 */
160 #define ipc_unreachable(reason) mach_assert_abort(reason)
161
162 /*!
163 * @brief
164 * Performs an invariant check that stays on release kernels.
165 */
166 #define ipc_release_assert(expr) release_assert(expr)
167
168
169 #pragma mark policy options
170
171
172 /*!
173 * @brief
174 * Convert mach_msg policy options (originally derived from the current_task space) back into the space namespace
175 *
176 * @param opts the options to convert
177 *
178 * @return the options for the space
179 */
180 extern ipc_space_policy_t ipc_convert_msg_options_to_space(
181 mach_msg_option64_t opts);
182
183 /*!
184 * @brief
185 * Computes the IPC policy for a given task.
186 *
187 * @param task the current task
188 */
189 extern ipc_space_policy_t ipc_policy_for_task(
190 task_t task);
191
192 /*!
193 * @brief
194 * Derive the current policy flags for the current process.
195 *
196 * @discussion
197 * This function will derive the proper in-kernel mach_msg options
198 * from user specified flags and the current context.
199 *
200 * @param task the current task
201 * @param user_flags flags passed in from userspace
202 */
203 extern mach_msg_option64_t ipc_current_msg_options(
204 task_t task,
205 mach_msg_option64_t user_flags);
206
207 /*!
208 * @brief
209 * Preflight send options for invalid combinations
210 *
211 * @discussion
212 * If the send options have "obviously" incorrect parameters,
213 * then a mach port guard exception (@c kGUARD_EXC_INVALID_OPTIONS) is raised.
214 *
215 * @param opts the mach_msg() options, after sanitization
216 * via @c ipc_current_msg_options().
217 * @returns
218 * - MACH_MSG_SUCCESS success,
219 * - MACH_SEND_INVALID_OPTIONS
220 * for failure cases if MACH64_MACH_MSG2 is set
221 * - KERN_NOT_SUPPORTED for failure cases if MACH64_MACH_MSG2 is not set
222 */
223 extern mach_msg_return_t ipc_preflight_msg_option64(
224 mach_msg_option64_t opts);
225
226 /*!
227 * @brief
228 * Determines whether ipc policies should be applied
229 *
230 * @discussion
231 * This checks whether the current policy level matches the policy level
232 * of this particular feature, but this helper also allows for various
233 * ways for a task to be opted out of ipc security policies, such as if
234 * they have the IPC_SPACE_POLICY_SIMULATED, *_TRANSLATED, or *_OPTED_OUT flags.
235 *
236 * @param current_policy the policy level for the task/space that we are enforcing on
237 * @param requested_level the policy level that is required to be opted into this enforcement
238 *
239 * @returns
240 * - true if the current policy level matches the requested policy
241 * level for this feature, and the task is not opted out
242 * - false otherwise
243 */
244 extern bool ipc_should_apply_policy(
245 const ipc_space_policy_t current_policy,
246 const ipc_space_policy_t requested_level);
247
248
249 #pragma mark legacy trap policies
250 #if IPC_HAS_LEGACY_MACH_MSG_TRAP
251
252 /*!
253 * @brief
254 * Whether the current task is allowed to use the legacy @c mach_msg_trap().
255 *
256 * @description
257 * If using the legacy mach_msg_trap() is disallowed, this will raise
258 * a mach port guard exception (@c kGUARD_EXC_INVALID_OPTIONS).
259 *
260 * @discussion
261 * Nothing should be locked.
262 *
263 * @param msgid the message ID of the message being sent
264 * with the legacy interface.
265 * @param opts the mach_msg() options passed to the legacy interface,
266 * after sanitization via @c ipc_current_msg_options().
267 * @returns
268 * - MACH_MSG_SUCCESS success,
269 * - KERN_NOT_SUPPORTED for failure cases.
270 */
271 extern mach_msg_return_t ipc_policy_allow_legacy_send_trap(
272 mach_msg_id_t msgid,
273 mach_msg_option64_t opts);
274
275
276 #endif /* IPC_HAS_LEGACY_MACH_MSG_TRAP */
277 #pragma mark policy array
278
279 /*!
280 * @brief
281 * Decides the policy around receive right movability.
282 *
283 * @const IPC_MOVE_POLICY_NEVER
284 * Such ports are born in the IO_STATE_IN_SPACE_IMMOVABLE state.
285 * Moving or arming port-destroyed notification on such rights
286 * is disallowed.
287 *
288 * @const IPC_MOVE_POLICY_ONCE
289 * Such ports are born in the IO_STATE_IN_SPACE state.
290 *
291 * Arming port destroyed notification on such ports is allowed,
292 * and they will move to IO_STATE_IN_SPACE_IMMOVABLE after their first move.
293 *
294 * Their state will remain IO_STATE_IN_SPACE_IMMOVABLE after a port-destroyed
295 * notification fires.
296 *
297 * @const IPC_MOVE_POLICY_ONCE_OR_AFTER_PD
298 * Such ports are born in the IO_STATE_IN_SPACE state.
299 *
300 * This behaves like @c IPC_MOVE_POLICY_ONCE, but resets to IO_STATE_IN_SPACE
301 * after a port-destroyed notification is delivered.
302 *
303 * @const IPC_MOVE_POLICY_ALWAYS
304 * The port is always movable.
305 */
306 __enum_decl(ipc_move_policy_t, uint32_t, {
307 IPC_MOVE_POLICY_NEVER,
308 IPC_MOVE_POLICY_ONCE,
309 IPC_MOVE_POLICY_ONCE_OR_AFTER_PD,
310 IPC_MOVE_POLICY_ALWAYS,
311 });
312
313 /*!
314 * @brief
315 * Type for port policies
316 */
317 typedef const struct ipc_object_policy {
318 const char *pol_name;
319
320 /** see iko_op_stable */
321 unsigned long pol_kobject_stable : 1;
322 /** see iko_op_permanent */
323 unsigned long pol_kobject_permanent : 1;
324
325 /** whether the port is movable */
326 ipc_move_policy_t pol_movability : 2;
327
328
329 /** `mach_port_request_notification` protections */
330
331 /**
332 * allow arming a `MACH_NOTIFY_PORT_DESTROYED` notification
333 * on this receive right
334 */
335 unsigned long pol_notif_port_destroy : 1;
336 /**
337 * allow arming a `MACH_NOTIFY_NO_SENDERS` notification
338 * on this receive right
339 */
340 unsigned long pol_notif_no_senders : 1;
341 /**
342 * allow arming a `MACH_NOTIFY_DEAD_NAME/MACH_NOTIFY_SEND_POSSIBLE`
343 * notification on this receive right
344 */
345 unsigned long pol_notif_dead_name : 1;
346
347
348 /** whether the port requires incoming messages to use an IOT_REPLY_PORT properly */
349 unsigned long pol_enforce_reply_semantics : 1;
350
351 /**
352 * whether send rights created on this port are movable,
353 * immovable ports still allow "movement" via MAKE_SEND(_ONCE)
354 */
355 unsigned long pol_movable_send : 1;
356
357 /** required entitlement for platform restrictions binaries to create this port */
358 const char *pol_construct_entitlement;
359
360 /** see iko_op_no_senders */
361 void (*pol_kobject_no_senders)(
362 ipc_port_t port,
363 mach_port_mscount_t mscount);
364
365 /** destroys the label for this port */
366 void (*pol_label_free)(
367 ipc_object_label_t label);
368 } *ipc_object_policy_t;
369
370 /*!
371 * @brief
372 * Array of policies per port type.
373 */
374 extern struct ipc_object_policy ipc_policy_array[IOT_UNKNOWN];
375
376 /*!
377 * @brief
378 * Returns the policy for a given type/object/port/...
379 */
380 __attribute__((overloadable, always_inline, const))
381 static inline ipc_object_policy_t
ipc_policy(ipc_object_type_t otype)382 ipc_policy(ipc_object_type_t otype)
383 {
384 ipc_release_assert(otype < IOT_UNKNOWN);
385 return &ipc_policy_array[otype];
386 }
387
388 __attribute__((overloadable, always_inline, const))
389 static inline ipc_object_policy_t
ipc_policy(ipc_object_label_t label)390 ipc_policy(ipc_object_label_t label)
391 {
392 return ipc_policy(label.io_type);
393 }
394
395 __attribute__((overloadable, always_inline, const))
396 static inline ipc_object_policy_t
ipc_policy(ipc_object_t object)397 ipc_policy(ipc_object_t object)
398 {
399 return ipc_policy(object->io_type);
400 }
401
402 __attribute__((overloadable, always_inline, const))
403 static inline ipc_object_policy_t
ipc_policy(ipc_port_t port)404 ipc_policy(ipc_port_t port)
405 {
406 return ipc_policy(ip_type(port));
407 }
408
409
410 #pragma mark ipc policy telemetry [temporary]
411
412 /* The bootarg to disable ALL ipc policy violation telemetry */
413 extern bool ipcpv_telemetry_enabled;
414
415 /* Enables reply port/voucher/persona debugging code */
416 extern bool enforce_strict_reply;
417
418 extern bool bootstrap_port_telemetry_enabled;
419
420 /*!
421 * @brief
422 * Identifier of the type of ipc policy violation in a CA telemetry event
423 *
424 * Currently we only send reply port related violations to CA. This enum can
425 * be extended to report more violations in the future.
426 */
427 __enum_closed_decl(ipc_policy_violation_id_t, uint8_t, {
428 IPCPV_VIOLATION_NONE, /* 0, denote no violations */
429
430 /* Kobject Reply Port and Move Reply Port violators Start */
431 IPCPV_REPLY_PORT_SEMANTICS, /* 1, normal reply port semantics violator */
432 /* [2-5] were previously used; should be avoided to avoid telemetry confusion */
433 __UNUSED2, /* previously used, should be avoided */
434 __UNUSED3, /* previously used, should be avoided */
435 __UNUSED4, /* previously used, should be avoided */
436 __UNUSED5, /* previously used, should be avoided */
437 /* services opted out of reply port semantics previously should have fixed their violations */
438 IPCPV_REPLY_PORT_SEMANTICS_OPTOUT, /* 6 */
439 /* Kobject Reply Port and Move Reply Port Violators End */
440
441 /* Service Port Defense Violators Start */
442 __UNUSED10, /* 7 */
443 IPCPV_SERVICE_PORT_PD_NOTIFICATION, /* 8, for future telemetry */
444 /* Service Port Defense Violators End */
445
446 /*
447 * [9-12] were previously used for OOL port array restrictions;
448 * these should be avoided to avoid telemetry confusion
449 */
450 __UNUSED6, /* 9 previously used, should be avoided */
451 __UNUSED7, /* 10 previously used, should be avoided */
452 __UNUSED8, /* 11 previously used, should be avoided */
453 __UNUSED9, /* 12 previously used, should be avoided */
454 /* OOL ports array violators End */
455
456 /* Bootstrap port reply port semantics violators Start */
457 IPCPV_BOOTSTRAP_PORT, /* 13 */
458 /* Bootstrap port reply port semantics violators End */
459
460 _IPCPV_VIOLATION_COUNT,
461 });
462
463 /*!
464 * @brief
465 * Record ipc policy violations into a buffer for sending to CA at a later time.
466 *
467 * @discussion
468 * The ipc telemetry lock is not locked.
469 *
470 * @param violation_id type of ipc policy violation
471 * @param service_port service port involved in violation, if any
472 * @param aux_data additional data to include in the CA event:
473 * violator msgh_id for reply port defense
474 */
475 extern void ipc_stash_policy_violations_telemetry(
476 ipc_policy_violation_id_t violation_id,
477 ipc_port_t service_port,
478 int aux_data);
479
480 #if DEBUG || DEVELOPMENT
481 /*!
482 * @brief
483 * Helper function to record the total number of ipcpv violation occured.
484 * Telemetry count should be 0 in presub testing as we shouldn't emit any
485 * telemetry for known issue.
486 */
487 extern void ipc_inc_telemetry_count(void);
488 #endif /* DEBUG || DEVELOPMENT */
489
490 /*!
491 * @brief
492 * Check if the ipc space has emitted a certain type of telemetry.
493 *
494 * @param is ipc space in question
495 * @param type ipc policy violation type
496 */
497 __attribute__((always_inline))
498 static inline bool
ipc_space_has_telemetry_type(ipc_space_t is,uint8_t type)499 ipc_space_has_telemetry_type(ipc_space_t is, uint8_t type)
500 {
501 if (!ipcpv_telemetry_enabled) {
502 return true;
503 }
504
505 #if DEBUG || DEVELOPMENT
506 ipc_inc_telemetry_count();
507 #endif
508
509 return (os_atomic_or_orig(&is->is_telemetry, type, relaxed) & type) != 0;
510 }
511
512 #pragma mark MACH_SEND_MSG policies
513
514 /*!
515 * @brief
516 * Validation function that runs after the message header bytes have been copied
517 * from user, but before any other content or right is copied in.
518 *
519 * @discussion
520 * Nothing should be locked.
521 *
522 * @param hdr the user message header bytes, before anything
523 * else has been copied in.
524 * @param dsc_count the number of inline descriptors for the user message.
525 * @param opts the mach_msg() options, after sanitization
526 * via @c ipc_current_msg_options().
527 *
528 * @returns
529 * - MACH_MSG_SUCCESS the message passed validation
530 * - MACH_SEND_TOO_LARGE
531 * a MACH64_SEND_KOBJECT_CALL had too many descriptors.
532 * - MACH_MSG_VM_KERNEL the message would use more than ipc_kmsg_max_vm_space
533 * of kernel wired memory.
534 */
535 extern mach_msg_return_t ipc_validate_kmsg_header_schema_from_user(
536 mach_msg_user_header_t *hdr,
537 mach_msg_size_t dsc_count,
538 mach_msg_option64_t opts);
539
540 /*!
541 * @brief
542 * Validation function that runs after the message bytes has been copied from
543 * user, but before any right is copied in.
544 *
545 * @discussion
546 * Nothing should be locked.
547 *
548 * @param kdata the "kernel data" part of the incoming message.
549 * the descriptors data is copied in "kernel" format.
550 * @param send_uctx the IPC kmsg send context for the current send operation.
551 * @param opts the mach_msg() options, after sanitization
552 * via @c ipc_current_msg_options().
553 *
554 * @returns
555 * - MACH_MSG_SUCCESS the message passed validation
556 * - MACH_SEND_TOO_LARGE
557 * a MACH64_SEND_KOBJECT_CALL had too many descriptors.
558 * - MACH_MSG_VM_KERNEL the message would use more than ipc_kmsg_max_vm_space
559 * of kernel wired memory.
560 */
561 extern mach_msg_return_t ipc_validate_kmsg_schema_from_user(
562 mach_msg_header_t *kdata,
563 mach_msg_send_uctx_t *send_uctx,
564 mach_msg_option64_t opts);
565
566 /*!
567 * @brief
568 * Validation function that runs after the rights in the message header have
569 * been copied in.
570 *
571 * @discussion
572 * Nothing should be locked.
573 *
574 * @param hdr the copied in message header.
575 * @param send_uctx the IPC kmsg send context for the current send operation.
576 * @param opts the mach_msg() options, after sanitization
577 * via @c ipc_current_msg_options().
578 * @returns
579 * - MACH_MSG_SUCCESS the message passed validation
580 * - MACH_SEND_INVALID_OPTIONS
581 * some options are incompatible with the destination
582 * of the message. a kGUARD_EXC_INVALID_OPTIONS guard
583 * will be raised.
584 * - MACH_SEND_MSG_FILTERED
585 * the message failed a filtering check.
586 * a kGUARD_EXC_MSG_FILTERED guard might be raised.
587 */
588 extern mach_msg_return_t ipc_validate_kmsg_header_from_user(
589 mach_msg_header_t *hdr,
590 mach_msg_send_uctx_t *send_uctx,
591 mach_msg_option64_t opts);
592
593
594 #pragma mark port type policies and callouts
595
596 /*!
597 * @brief
598 * Frees a label value according to the port type callout.
599 *
600 * @param label The label to destroy.
601 */
602 static inline void
ipc_port_label_free(ipc_object_label_t label)603 ipc_port_label_free(ipc_object_label_t label)
604 {
605 if (label.iol_pointer) {
606 ipc_policy(label)->pol_label_free(label);
607 }
608 }
609
610 #pragma mark send immovability
611
612 /*!
613 * @brief
614 * Returns whether an entry for this port should be marked as immovable send
615 *
616 * @param curr_task The task where the new entry is being created/copied out
617 * @param port The port that the entry is being created/copied out for
618 * @param label The label associated with `port`
619 *
620 * @returns
621 * - true The send right entry should be marked as immovable
622 * - false The send right entry should not be marked as immovable
623 */
624 extern bool ipc_should_mark_immovable_send(
625 task_t curr_task,
626 ipc_port_t port,
627 ipc_object_label_t label);
628
629 /*!
630 * @brief
631 * Determine whether we need to protect this port from being stashed as a naked
632 * send right in the kernel. We disallow this if the port is supposed to be immovable send
633 * as this would allow userspace to bypass the immovable send checks and move the send
634 * right to another process.
635 *
636 * @param port The port that we want to protect
637 *
638 * @returns
639 * - true The port is allowed to be stashed
640 * - false The port is immovable send and should not be stashed
641 */
642 extern bool ipc_can_stash_naked_send(
643 ipc_port_t port);
644
645
646 #pragma mark entry init
647
648 /*!
649 * @brief
650 * Initialize the security fields/flags on a new right entry created through the
651 * new port creation path. This right could be any port or port set right.
652 *
653 * @param space The space this entry is being created in
654 * @param object The *initialized* port/portset object that is getting a new entry
655 * @param type The type of this entry (send, send-once, receive, deadname, portset)
656 * @param entry Pointer to the entry that is being initialized
657 * @param urefs Number of refs this entry will be initialized to
658 * @param name The name this entry will occupy in the space
659 */
660 extern void ipc_entry_init(
661 ipc_space_t space,
662 ipc_object_t object,
663 mach_port_type_t type,
664 ipc_entry_t entry,
665 mach_port_urefs_t urefs,
666 mach_port_name_t name);
667
668
669 #pragma mark receive immovability
670
671 /*!
672 * @brief
673 * Returns whether the receive right of a port is allowed to move out
674 * of an ipc space.
675 *
676 * Condition: Space is write-locked and active. Port is not locked.
677 *
678 * @param space The ipc space to copyin from
679 * @param port The port whose receive right is being moved
680 *
681 * @returns
682 * - true The receive right can move out of the space
683 * - false The receive right can not move out of the space
684 */
685 extern bool ipc_move_receive_allowed(
686 ipc_space_t space,
687 ipc_port_t port,
688 mach_port_name_t name);
689
690
691 #pragma mark policy guard violations
692
693 /*!
694 * @brief
695 * Marks the thread with AST_MACH_EXCEPTION for mach port guard violation.
696 *
697 * @discussion
698 * Also saves exception info in thread structure.
699 *
700 * @param target The port target of the exception (often a port name)
701 * @param payload A 64bit value that will be put in the guard "subcode".
702 * @param reason A valid mach_port_guard_exception_codes value.
703 */
704 __cold
705 extern void mach_port_guard_exception(
706 uint32_t target,
707 uint64_t payload,
708 unsigned reason);
709
710 /*!
711 * @brief
712 * Deliver a soft or hard immovable guard exception.
713 *
714 * @param space The space causing the immovable exception.
715 * The guard isn't delivered if it isn't the current space.
716 * @param name The name of the port in @c space violating immovability.
717 * @param port The port violating immovability (must be pol_movable_send).
718 */
719 __cold
720 extern void mach_port_guard_exception_immovable(
721 ipc_space_t space,
722 mach_port_name_t name,
723 mach_port_t port,
724 mach_msg_type_name_t disp,
725 ipc_entry_t entry);
726
727 /*!
728 * @brief
729 * Deliver a soft or hard mod_refs guard exception.
730 *
731 * @param space The space causing the pinned exception.
732 * The guard isn't delivered if it isn't the current space,
733 * or the task disables guards on pinned violations.
734 * @param name The name of the entry in @c space violating pinned rules.
735 * @param payload A valid @c MPG_FLAGS_MOD_REFS_PINNED_* value.
736 */
737 __cold
738 extern void mach_port_guard_exception_pinned(
739 ipc_space_t space,
740 mach_port_name_t name,
741 uint64_t payload);
742
743 #pragma mark exception port policy
744
745 /*!
746 * @brief
747 * Check whether the port can be a valid exception port for a given task.
748 *
749 * @param task The task registering an exception port.
750 * @param port The port being registered as exception port.
751 */
752 extern bool ipc_is_valid_exception_port(
753 task_t task,
754 ipc_port_t port);
755
756 #pragma mark notification policies
757
758 /*!
759 * @brief
760 * Check if requesting a port destroyed notification on pd_port is allowed.
761 *
762 * @discussion
763 * pd_port is locked and active.
764 * This function must raise a guard exception along every error path
765 *
766 * @param pd_port the port to be reaped after destroy
767 * @param notify_port the notify port that pd_port will be sent to after deat
768 *
769 * @returns
770 * - KERN_SUCCESS port destroyed notification is allowed to be requested
771 * on this pd_port with this notify_port
772 * - KERN_FAILURE pd_port already has a pd notification
773 * - KERN_INVALID_RIGHT some violation in the security policy
774 */
775 extern kern_return_t ipc_allow_register_pd_notification(
776 ipc_port_t pd_port,
777 ipc_port_t notify_port);
778
779 #pragma GCC visibility pop
780 __ASSUME_PTR_ABI_SINGLE_END __END_DECLS
781
782 #endif /* _IPC_IPC_POLICY_H_ */
783