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 <mach/kern_return.h>
76#include <mach/message.h>
77#include <kern/locks.h>
78#include <kern/macro_help.h>
79#include <kern/assert.h>
80#include <kern/zalloc.h>
81#include <ipc/ipc_types.h>
82#include <libkern/OSAtomic.h>
83
84typedef natural_t ipc_object_refs_t; /* for ipc/ipc_object.h */
85typedef natural_t ipc_object_bits_t;
86typedef natural_t ipc_object_type_t;
87
88/*
89 * The ipc_object is used to both tag and reference count these two data
90 * structures, and (Noto Bene!) pointers to either of these or the
91 * ipc_object at the head of these are freely cast back and forth; hence
92 * the ipc_object MUST BE FIRST in the ipc_common_data.
93 *
94 * If the RPC implementation enabled user-mode code to use kernel-level
95 * data structures (as ours used to), this peculiar structuring would
96 * avoid having anything in user code depend on the kernel configuration
97 * (with which lock size varies).
98 */
99struct ipc_object {
100 ipc_object_bits_t io_bits;
101 ipc_object_refs_t io_references;
102 lck_spin_t io_lock_data;
103};
104
105/*
106 * If another object type needs to participate in io_kotype()-based
107 * dispatching, it must include a stub structure as the first
108 * element
109 */
110struct ipc_object_header {
111 ipc_object_bits_t io_bits;
112#ifdef __LP64__
113 natural_t io_padding; /* pad to natural boundary */
114#endif
115};
116
117/*
118 * Legacy defines. Should use IPC_OBJECT_NULL, etc...
119 */
120#define IO_NULL ((ipc_object_t) 0)
121#define IO_DEAD ((ipc_object_t) ~0UL)
122#define IO_VALID(io) (((io) != IO_NULL) && ((io) != IO_DEAD))
123
124/*
125 * IPC steals the high-order bits from the kotype to use
126 * for its own purposes. This allows IPC to record facts
127 * about ports that aren't otherwise obvious from the
128 * existing port fields. In particular, IPC can optionally
129 * mark a port for no more senders detection. Any change
130 * to IO_BITS_PORT_INFO must be coordinated with bitfield
131 * definitions in ipc_port.h.
132 */
133#define IO_BITS_PORT_INFO 0x0000f000 /* stupid port tricks */
134#define IO_BITS_KOTYPE 0x00000fff /* used by the object */
135#define IO_BITS_OTYPE 0x7fff0000 /* determines a zone */
136#define IO_BITS_ACTIVE 0x80000000 /* is object alive? */
137
138#define io_active(io) (((io)->io_bits & IO_BITS_ACTIVE) != 0)
139
140#define io_otype(io) (((io)->io_bits & IO_BITS_OTYPE) >> 16)
141#define io_kotype(io) ((io)->io_bits & IO_BITS_KOTYPE)
142
143#define io_makebits(active, otype, kotype) \
144 (((active) ? IO_BITS_ACTIVE : 0) | ((otype) << 16) | (kotype))
145
146/*
147 * Object types: ports, port sets, kernel-loaded ports
148 */
149#define IOT_PORT 0
150#define IOT_PORT_SET 1
151#define IOT_NUMBER 2 /* number of types used */
152
153extern zone_t ipc_object_zones[IOT_NUMBER];
154
155#define io_alloc(otype) \
156 ((ipc_object_t) zalloc(ipc_object_zones[(otype)]))
157
158extern void io_free(
159 unsigned int otype,
160 ipc_object_t object);
161
162/*
163 * Here we depend on the ipc_object being first within the kernel struct
164 * (ipc_port and ipc_pset).
165 */
166#define io_lock_init(io) \
167 lck_spin_init(&(io)->io_lock_data, &ipc_lck_grp, &ipc_lck_attr)
168#define io_lock_destroy(io) \
169 lck_spin_destroy(&(io)->io_lock_data, &ipc_lck_grp)
170#define io_lock(io) \
171 lck_spin_lock(&(io)->io_lock_data)
172#define io_lock_try(io) \
173 lck_spin_try_lock(&(io)->io_lock_data)
174#define io_lock_held_kdp(io) \
175 kdp_lck_spin_is_acquired(&(io)->io_lock_data)
176#define io_unlock(io) \
177 lck_spin_unlock(&(io)->io_lock_data)
178
179#define _VOLATILE_ volatile
180
181/* Sanity check the ref count. If it is 0, we may be doubly zfreeing.
182 * If it is larger than max int, it has been corrupted or leaked,
183 * probably by being modified into an address (this is architecture
184 * dependent, but it's safe to assume there cannot really be max int
185 * references unless some code is leaking the io_reference without leaking
186 * object). Saturate the io_reference on release kernel if it reaches
187 * max int to avoid use after free.
188 *
189 * NOTE: The 0 test alone will not catch double zfreeing of ipc_port
190 * structs, because the io_references field is the first word of the struct,
191 * and zfree modifies that to point to the next free zone element.
192 */
193#define IO_MAX_REFERENCES \
194 (unsigned)(~0 ^ (1 << (sizeof(int)*BYTE_SIZE - 1)))
195
196static inline void
197io_reference(ipc_object_t io) {
198 ipc_object_refs_t new_io_references;
199 ipc_object_refs_t old_io_references;
200
201 assert((io)->io_references > 0 &&
202 (io)->io_references < IO_MAX_REFERENCES);
203
204 do {
205 old_io_references = (io)->io_references;
206 new_io_references = old_io_references + 1;
207 if (old_io_references == IO_MAX_REFERENCES) {
208 break;
209 }
210 } while (OSCompareAndSwap(old_io_references, new_io_references,
211 &((io)->io_references)) == FALSE);
212}
213
214
215static inline void
216io_release(ipc_object_t io) {
217 ipc_object_refs_t new_io_references;
218 ipc_object_refs_t old_io_references;
219
220 assert((io)->io_references > 0 &&
221 (io)->io_references < IO_MAX_REFERENCES);
222
223 do {
224 old_io_references = (io)->io_references;
225 new_io_references = old_io_references - 1;
226 if (old_io_references == IO_MAX_REFERENCES) {
227 break;
228 }
229 } while (OSCompareAndSwap(old_io_references, new_io_references,
230 &((io)->io_references)) == FALSE);
231
232 /* If we just removed the last reference count */
233 if (1 == old_io_references) {
234 /* Free the object */
235 io_free(io_otype((io)), (io));
236 }
237}
238
239/*
240 * Retrieve a label for use in a kernel call that takes a security
241 * label as a parameter. If necessary, io_getlabel acquires internal
242 * (not io_lock) locks, and io_unlocklabel releases them.
243 */
244
245struct label;
246extern struct label *io_getlabel (ipc_object_t obj);
247#define io_unlocklabel(obj)
248
249/*
250 * Exported interfaces
251 */
252
253/* Take a reference to an object */
254extern void ipc_object_reference(
255 ipc_object_t object);
256
257/* Release a reference to an object */
258extern void ipc_object_release(
259 ipc_object_t object);
260
261/* Look up an object in a space */
262extern kern_return_t ipc_object_translate(
263 ipc_space_t space,
264 mach_port_name_t name,
265 mach_port_right_t right,
266 ipc_object_t *objectp);
267
268/* Look up two objects in a space, locking them in the order described */
269extern kern_return_t ipc_object_translate_two(
270 ipc_space_t space,
271 mach_port_name_t name1,
272 mach_port_right_t right1,
273 ipc_object_t *objectp1,
274 mach_port_name_t name2,
275 mach_port_right_t right2,
276 ipc_object_t *objectp2);
277
278/* Allocate a dead-name entry */
279extern kern_return_t
280ipc_object_alloc_dead(
281 ipc_space_t space,
282 mach_port_name_t *namep);
283
284/* Allocate a dead-name entry, with a specific name */
285extern kern_return_t ipc_object_alloc_dead_name(
286 ipc_space_t space,
287 mach_port_name_t name);
288
289/* Allocate an object */
290extern kern_return_t ipc_object_alloc(
291 ipc_space_t space,
292 ipc_object_type_t otype,
293 mach_port_type_t type,
294 mach_port_urefs_t urefs,
295 mach_port_name_t *namep,
296 ipc_object_t *objectp);
297
298/* Allocate an object, with a specific name */
299extern kern_return_t ipc_object_alloc_name(
300 ipc_space_t space,
301 ipc_object_type_t otype,
302 mach_port_type_t type,
303 mach_port_urefs_t urefs,
304 mach_port_name_t name,
305 ipc_object_t *objectp);
306
307/* Convert a send type name to a received type name */
308extern mach_msg_type_name_t ipc_object_copyin_type(
309 mach_msg_type_name_t msgt_name);
310
311/* Copyin a capability from a space */
312extern kern_return_t ipc_object_copyin(
313 ipc_space_t space,
314 mach_port_name_t name,
315 mach_msg_type_name_t msgt_name,
316 ipc_object_t *objectp);
317
318/* Copyin a naked capability from the kernel */
319extern void ipc_object_copyin_from_kernel(
320 ipc_object_t object,
321 mach_msg_type_name_t msgt_name);
322
323/* Destroy a naked capability */
324extern void ipc_object_destroy(
325 ipc_object_t object,
326 mach_msg_type_name_t msgt_name);
327
328/* Destroy a naked destination capability */
329extern void ipc_object_destroy_dest(
330 ipc_object_t object,
331 mach_msg_type_name_t msgt_name);
332
333/* Copyout a capability, placing it into a space */
334extern kern_return_t ipc_object_copyout(
335 ipc_space_t space,
336 ipc_object_t object,
337 mach_msg_type_name_t msgt_name,
338 boolean_t overflow,
339 mach_port_name_t *namep);
340
341/* Copyout a capability with a name, placing it into a space */
342extern kern_return_t ipc_object_copyout_name(
343 ipc_space_t space,
344 ipc_object_t object,
345 mach_msg_type_name_t msgt_name,
346 boolean_t overflow,
347 mach_port_name_t name);
348
349/* Translate/consume the destination right of a message */
350extern void ipc_object_copyout_dest(
351 ipc_space_t space,
352 ipc_object_t object,
353 mach_msg_type_name_t msgt_name,
354 mach_port_name_t *namep);
355
356/* Rename an entry in a space */
357extern kern_return_t ipc_object_rename(
358 ipc_space_t space,
359 mach_port_name_t oname,
360 mach_port_name_t nname);
361
362#endif /* _IPC_IPC_OBJECT_H_ */
363