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 Software.Distribution@CS.CMU.EDU
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
88typedef natural_t ipc_object_refs_t; /* for ipc/ipc_object.h */
89typedef natural_t ipc_object_bits_t;
90typedef 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 */
120struct 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
154static inline void
155io_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
164static inline void
165io_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
189extern 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) ({ \
203 ipc_object_t __io = (io); \
204 ipc_object_lock(__io, io_otype(__io)); \
205})
206#define io_unlock(io) ipc_object_unlock(io)
207#define io_lock_held(io) assert(waitq_held(io_waitq(io)))
208#define io_lock_held_kdp(io) waitq_held(io_waitq(io))
209#define io_lock_allow_invalid(io) ipc_object_lock_allow_invalid(io)
210
211#define io_reference(io) ipc_object_reference(io)
212#define io_release(io) ipc_object_release(io)
213#define io_release_safe(io) ipc_object_release_safe(io)
214#define io_release_live(io) ipc_object_release_live(io)
215
216/*
217 * Retrieve a label for use in a kernel call that takes a security
218 * label as a parameter. If necessary, io_getlabel acquires internal
219 * (not io_lock) locks, and io_unlocklabel releases them.
220 */
221
222struct label;
223extern struct label *io_getlabel(ipc_object_t obj);
224#define io_unlocklabel(obj)
225
226/*
227 * Exported interfaces
228 */
229
230extern void ipc_object_lock(
231 ipc_object_t object,
232 ipc_object_type_t type);
233
234extern void ipc_object_lock_check_aligned(
235 ipc_object_t object,
236 ipc_object_type_t type);
237
238extern bool ipc_object_lock_allow_invalid(
239 ipc_object_t object) __result_use_check;
240
241extern bool ipc_object_lock_try(
242 ipc_object_t object,
243 ipc_object_type_t type);
244
245extern void ipc_object_unlock(
246 ipc_object_t object);
247
248extern void ipc_object_deallocate_register_queue(void);
249
250/* Take a reference to an object */
251extern void ipc_object_reference(
252 ipc_object_t object);
253
254/* Release a reference to an object */
255extern void ipc_object_release(
256 ipc_object_t object);
257
258extern void ipc_object_release_safe(
259 ipc_object_t object);
260
261/* Release a reference to an object that isn't the last one */
262extern void ipc_object_release_live(
263 ipc_object_t object);
264
265/* Look up an object in a space */
266extern kern_return_t ipc_object_translate(
267 ipc_space_t space,
268 mach_port_name_t name,
269 mach_port_right_t right,
270 ipc_object_t *objectp);
271
272/* Look up two objects in a space, locking them in the order described */
273extern kern_return_t ipc_object_translate_two(
274 ipc_space_t space,
275 mach_port_name_t name1,
276 mach_port_right_t right1,
277 ipc_object_t *objectp1,
278 mach_port_name_t name2,
279 mach_port_right_t right2,
280 ipc_object_t *objectp2);
281
282/* Validate an object as belonging to the correct zone */
283extern void ipc_object_validate(
284 ipc_object_t object,
285 ipc_object_type_t type);
286
287extern void ipc_object_validate_aligned(
288 ipc_object_t object,
289 ipc_object_type_t type);
290
291/* Allocate a dead-name entry */
292extern kern_return_t
293ipc_object_alloc_dead(
294 ipc_space_t space,
295 mach_port_name_t *namep);
296
297/* Allocate an object */
298extern kern_return_t ipc_object_alloc(
299 ipc_space_t space,
300 ipc_object_type_t otype,
301 mach_port_type_t type,
302 mach_port_urefs_t urefs,
303 mach_port_name_t *namep,
304 ipc_object_t *objectp);
305
306/* Allocate an object, with a specific name */
307extern kern_return_t ipc_object_alloc_name(
308 ipc_space_t space,
309 ipc_object_type_t otype,
310 mach_port_type_t type,
311 mach_port_urefs_t urefs,
312 mach_port_name_t name,
313 ipc_object_t *objectp,
314 void (^finish_init)(ipc_object_t object));
315
316/* Convert a send type name to a received type name */
317extern mach_msg_type_name_t ipc_object_copyin_type(
318 mach_msg_type_name_t msgt_name);
319
320/* Copyin a capability from a space */
321extern kern_return_t ipc_object_copyin(
322 ipc_space_t space,
323 mach_port_name_t name,
324 mach_msg_type_name_t msgt_name,
325 ipc_object_t *objectp,
326 mach_port_context_t context,
327 mach_msg_guard_flags_t *guard_flags,
328 ipc_object_copyin_flags_t copyin_flags);
329
330/* Copyin a naked capability from the kernel */
331extern void ipc_object_copyin_from_kernel(
332 ipc_object_t object,
333 mach_msg_type_name_t msgt_name);
334
335/* Destroy a naked capability */
336extern void ipc_object_destroy(
337 ipc_object_t object,
338 mach_msg_type_name_t msgt_name);
339
340/* Destroy a naked destination capability */
341extern void ipc_object_destroy_dest(
342 ipc_object_t object,
343 mach_msg_type_name_t msgt_name);
344
345/* Insert a send right into an object already in the current space */
346extern kern_return_t ipc_object_insert_send_right(
347 ipc_space_t space,
348 mach_port_name_t name,
349 mach_msg_type_name_t msgt_name);
350
351/* Copyout a capability, placing it into a space */
352extern kern_return_t ipc_object_copyout(
353 ipc_space_t space,
354 ipc_object_t object,
355 mach_msg_type_name_t msgt_name,
356 ipc_object_copyout_flags_t flags,
357 mach_port_context_t *context,
358 mach_msg_guard_flags_t *guard_flags,
359 mach_port_name_t *namep);
360
361/* Copyout a capability with a name, placing it into a space */
362extern kern_return_t ipc_object_copyout_name(
363 ipc_space_t space,
364 ipc_object_t object,
365 mach_msg_type_name_t msgt_name,
366 mach_port_name_t name);
367
368/* Translate/consume the destination right of a message */
369extern void ipc_object_copyout_dest(
370 ipc_space_t space,
371 ipc_object_t object,
372 mach_msg_type_name_t msgt_name,
373 mach_port_name_t *namep);
374
375#pragma GCC visibility pop
376__ASSUME_PTR_ABI_SINGLE_BEGIN __END_DECLS
377
378#endif /* _IPC_IPC_OBJECT_H_ */
379