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