1 /*
2 * Copyright (c) 2000-2007 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 /*
29 * @OSF_COPYRIGHT@
30 */
31 /*
32 * Mach Operating System
33 * Copyright (c) 1991,1990,1989 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: ipc/ipc_object.h
66 * Author: Rich Draves
67 * Date: 1989
68 *
69 * Definitions for IPC objects, for which tasks have capabilities.
70 */
71
72 #ifndef _IPC_IPC_OBJECT_H_
73 #define _IPC_IPC_OBJECT_H_
74
75 #include <os/atomic_private.h>
76 #include <mach/kern_return.h>
77 #include <mach/message.h>
78 #include <kern/locks.h>
79 #include <kern/macro_help.h>
80 #include <kern/assert.h>
81 #include <kern/zalloc.h>
82 #include <ipc/ipc_types.h>
83 #include <libkern/OSAtomic.h>
84
85 __BEGIN_DECLS __ASSUME_PTR_ABI_SINGLE_BEGIN
86 #pragma GCC visibility push(hidden)
87
88 typedef natural_t ipc_object_refs_t; /* for ipc/ipc_object.h */
89 typedef natural_t ipc_object_bits_t;
90 typedef natural_t ipc_object_type_t;
91
92 __options_closed_decl(ipc_object_copyout_flags_t, uint32_t, {
93 IPC_OBJECT_COPYOUT_FLAGS_NONE = 0x0,
94 IPC_OBJECT_COPYOUT_FLAGS_PINNED = 0x1,
95 IPC_OBJECT_COPYOUT_FLAGS_NO_LABEL_CHECK = 0x2,
96 });
97
98 __options_closed_decl(ipc_object_copyin_flags_t, uint16_t, {
99 IPC_OBJECT_COPYIN_FLAGS_NONE = 0x0,
100 IPC_OBJECT_COPYIN_FLAGS_ALLOW_IMMOVABLE_SEND = 0x1, /* Dest port contains an immovable send right */
101 IPC_OBJECT_COPYIN_FLAGS_ALLOW_DEAD_SEND_ONCE = 0x2,
102 IPC_OBJECT_COPYIN_FLAGS_DEADOK = 0x4,
103 IPC_OBJECT_COPYIN_FLAGS_ALLOW_REPLY_MAKE_SEND_ONCE = 0x8, /* Port is a reply port. */
104 IPC_OBJECT_COPYIN_FLAGS_ALLOW_REPLY_MOVE_SEND_ONCE = 0x10, /* Port is a reply port. */
105 IPC_OBJECT_COPYIN_FLAGS_ALLOW_IMMOVABLE_RECEIVE = 0x20,
106 IPC_OBJECT_COPYIN_FLAGS_ALLOW_CONN_IMMOVABLE_RECEIVE = 0x40, /* Port is a libxpc connection port. */
107 });
108
109 /*
110 * The ipc_object is used to both tag and reference count these two data
111 * structures, and (Noto Bene!) pointers to either of these or the
112 * ipc_object at the head of these are freely cast back and forth; hence
113 * the ipc_object MUST BE FIRST in the ipc_common_data.
114 *
115 * If the RPC implementation enabled user-mode code to use kernel-level
116 * data structures (as ours used to), this peculiar structuring would
117 * avoid having anything in user code depend on the kernel configuration
118 * (with which lock size varies).
119 */
120 struct ipc_object {
121 ipc_object_bits_t _Atomic io_bits;
122 ipc_object_refs_t _Atomic io_references;
123 } __attribute__((aligned(8)));
124
125 /*
126 * Legacy defines. Should use IPC_OBJECT_NULL, etc...
127 */
128 #define IO_NULL ((ipc_object_t) 0)
129 #define IO_DEAD ((ipc_object_t) ~0UL)
130 #define IO_VALID(io) (((io) != IO_NULL) && ((io) != IO_DEAD))
131
132 /*
133 * IPC steals the high-order bits from the kotype to use
134 * for its own purposes. This allows IPC to record facts
135 * about ports that aren't otherwise obvious from the
136 * existing port fields. In particular, IPC can optionally
137 * mark a port for no more senders detection. Any change
138 * to IO_BITS_PORT_INFO must be coordinated with bitfield
139 * definitions in ipc_port.h.
140 *
141 * Note that the io_bits can be read atomically without
142 * holding the object lock (for example to read the kobject type).
143 * As such updates to this field need to use the io_bits_or()
144 * or io_bits_andnot() functions.
145 */
146 #define IO_BITS_PORT_INFO 0x0000f000 /* stupid port tricks */
147 #define IO_BITS_KOTYPE 0x000003ff /* used by the object */
148 #define IO_BITS_KOLABEL 0x00000400 /* The kobject has a label */
149 #define IO_BITS_OTYPE 0x7fff0000 /* determines a zone */
150 #define IO_BITS_ACTIVE 0x80000000 /* is object alive? */
151
152 #define io_bits(io) atomic_load_explicit(&(io)->io_bits, memory_order_relaxed)
153
154 static inline void
io_bits_or(ipc_object_t io,ipc_object_bits_t bits)155 io_bits_or(ipc_object_t io, ipc_object_bits_t bits)
156 {
157 /*
158 * prevent any possibility for the compiler to tear the update,
159 * the update still requires the io lock to be held.
160 */
161 os_atomic_store(&io->io_bits, io_bits(io) | bits, relaxed);
162 }
163
164 static inline void
io_bits_andnot(ipc_object_t io,ipc_object_bits_t bits)165 io_bits_andnot(ipc_object_t io, ipc_object_bits_t bits)
166 {
167 /*
168 * prevent any possibility for the compiler to tear the update,
169 * the update still requires the io lock to be held.
170 */
171 os_atomic_store(&io->io_bits, io_bits(io) & ~bits, relaxed);
172 }
173
174 #define io_active(io) ((io_bits(io) & IO_BITS_ACTIVE) != 0)
175
176 #define io_otype(io) ((io_bits(io) & IO_BITS_OTYPE) >> 16)
177 #define io_kotype(io) (io_bits(io) & IO_BITS_KOTYPE)
178 #define io_is_kobject(io) (io_kotype(io) != 0)
179 #define io_is_kolabeled(io) ((io_bits(io) & IO_BITS_KOLABEL) != 0)
180 #define io_makebits(otype) (IO_BITS_ACTIVE | ((otype) << 16))
181
182 /*
183 * Object types: ports, port sets, kernel-loaded ports
184 */
185 #define IOT_PORT 0
186 #define IOT_PORT_SET 1
187 #define IOT_NUMBER 2 /* number of types used */
188
189 extern zone_t __single ipc_object_zones[IOT_NUMBER];
190
191 #define io_alloc(otype, flags) \
192 zalloc_flags(ipc_object_zones[otype], flags)
193
194 /*
195 * Here we depend on all ipc_objects being an ipc_wait_queue
196 */
197 #define io_waitq(io) \
198 (&__container_of(io, struct ipc_object_waitq, iowq_object)->iowq_waitq)
199 #define io_from_waitq(waitq) \
200 (&__container_of(waitq, struct ipc_object_waitq, iowq_waitq)->iowq_object)
201
202 #define io_lock(io) ipc_object_lock(io)
203 #define io_lock_try(io) ipc_object_lock_try(io)
204 #define io_unlock(io) ipc_object_unlock(io)
205 #define io_lock_held(io) assert(waitq_held(io_waitq(io)))
206 #define io_lock_held_kdp(io) waitq_held(io_waitq(io))
207 #define io_lock_allow_invalid(io) ipc_object_lock_allow_invalid(io)
208
209 #define io_reference(io) ipc_object_reference(io)
210 #define io_release(io) ipc_object_release(io)
211 #define io_release_safe(io) ipc_object_release_safe(io)
212 #define io_release_live(io) ipc_object_release_live(io)
213
214 /*
215 * Retrieve a label for use in a kernel call that takes a security
216 * label as a parameter. If necessary, io_getlabel acquires internal
217 * (not io_lock) locks, and io_unlocklabel releases them.
218 */
219
220 struct label;
221 extern struct label *io_getlabel(ipc_object_t obj);
222 #define io_unlocklabel(obj)
223
224 /*
225 * Exported interfaces
226 */
227
228 extern void ipc_object_lock(
229 ipc_object_t object);
230
231 extern bool ipc_object_lock_allow_invalid(
232 ipc_object_t object) __result_use_check;
233
234 extern bool ipc_object_lock_try(
235 ipc_object_t object);
236
237 extern void ipc_object_unlock(
238 ipc_object_t object);
239
240 extern void ipc_object_deallocate_register_queue(void);
241
242 /* Take a reference to an object */
243 extern void ipc_object_reference(
244 ipc_object_t object);
245
246 /* Release a reference to an object */
247 extern void ipc_object_release(
248 ipc_object_t object);
249
250 extern void ipc_object_release_safe(
251 ipc_object_t object);
252
253 /* Release a reference to an object that isn't the last one */
254 extern void ipc_object_release_live(
255 ipc_object_t object);
256
257 /* Look up an object in a space */
258 extern kern_return_t ipc_object_translate(
259 ipc_space_t space,
260 mach_port_name_t name,
261 mach_port_right_t right,
262 ipc_object_t *objectp);
263
264 /* Look up two objects in a space, locking them in the order described */
265 extern kern_return_t ipc_object_translate_two(
266 ipc_space_t space,
267 mach_port_name_t name1,
268 mach_port_right_t right1,
269 ipc_object_t *objectp1,
270 mach_port_name_t name2,
271 mach_port_right_t right2,
272 ipc_object_t *objectp2);
273
274 /* Validate an object as belonging to the correct zone */
275 extern void ipc_object_validate(
276 ipc_object_t object);
277
278 /* Allocate a dead-name entry */
279 extern kern_return_t
280 ipc_object_alloc_dead(
281 ipc_space_t space,
282 mach_port_name_t *namep);
283
284 /* Allocate an object */
285 extern kern_return_t ipc_object_alloc(
286 ipc_space_t space,
287 ipc_object_type_t otype,
288 mach_port_type_t type,
289 mach_port_urefs_t urefs,
290 mach_port_name_t *namep,
291 ipc_object_t *objectp);
292
293 /* Allocate an object, with a specific name */
294 extern kern_return_t ipc_object_alloc_name(
295 ipc_space_t space,
296 ipc_object_type_t otype,
297 mach_port_type_t type,
298 mach_port_urefs_t urefs,
299 mach_port_name_t name,
300 ipc_object_t *objectp,
301 void (^finish_init)(ipc_object_t object));
302
303 /* Convert a send type name to a received type name */
304 extern mach_msg_type_name_t ipc_object_copyin_type(
305 mach_msg_type_name_t msgt_name);
306
307 /* Copyin a capability from a space */
308 extern kern_return_t ipc_object_copyin(
309 ipc_space_t space,
310 mach_port_name_t name,
311 mach_msg_type_name_t msgt_name,
312 ipc_object_t *objectp,
313 mach_port_context_t context,
314 mach_msg_guard_flags_t *guard_flags,
315 ipc_object_copyin_flags_t copyin_flags);
316
317 /* Copyin a naked capability from the kernel */
318 extern void ipc_object_copyin_from_kernel(
319 ipc_object_t object,
320 mach_msg_type_name_t msgt_name);
321
322 /* Destroy a naked capability */
323 extern void ipc_object_destroy(
324 ipc_object_t object,
325 mach_msg_type_name_t msgt_name);
326
327 /* Destroy a naked destination capability */
328 extern void ipc_object_destroy_dest(
329 ipc_object_t object,
330 mach_msg_type_name_t msgt_name);
331
332 /* Insert a send right into an object already in the current space */
333 extern kern_return_t ipc_object_insert_send_right(
334 ipc_space_t space,
335 mach_port_name_t name,
336 mach_msg_type_name_t msgt_name);
337
338 /* Copyout a capability, placing it into a space */
339 extern kern_return_t ipc_object_copyout(
340 ipc_space_t space,
341 ipc_object_t object,
342 mach_msg_type_name_t msgt_name,
343 ipc_object_copyout_flags_t flags,
344 mach_port_context_t *context,
345 mach_msg_guard_flags_t *guard_flags,
346 mach_port_name_t *namep);
347
348 /* Copyout a capability with a name, placing it into a space */
349 extern kern_return_t ipc_object_copyout_name(
350 ipc_space_t space,
351 ipc_object_t object,
352 mach_msg_type_name_t msgt_name,
353 mach_port_name_t name);
354
355 /* Translate/consume the destination right of a message */
356 extern void ipc_object_copyout_dest(
357 ipc_space_t space,
358 ipc_object_t object,
359 mach_msg_type_name_t msgt_name,
360 mach_port_name_t *namep);
361
362 #pragma GCC visibility pop
363 __ASSUME_PTR_ABI_SINGLE_BEGIN __END_DECLS
364
365 #endif /* _IPC_IPC_OBJECT_H_ */
366