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 | |
84 | typedef natural_t ipc_object_refs_t; /* for ipc/ipc_object.h */ |
85 | typedef natural_t ipc_object_bits_t; |
86 | typedef 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 | */ |
99 | struct 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 | */ |
110 | struct { |
111 | ipc_object_bits_t ; |
112 | #ifdef __LP64__ |
113 | natural_t ; /* 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 | |
153 | extern zone_t ipc_object_zones[IOT_NUMBER]; |
154 | |
155 | #define io_alloc(otype) \ |
156 | ((ipc_object_t) zalloc(ipc_object_zones[(otype)])) |
157 | |
158 | extern 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 | |
196 | static inline void |
197 | io_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 | |
215 | static inline void |
216 | io_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 | |
245 | struct label; |
246 | extern 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 */ |
254 | extern void ipc_object_reference( |
255 | ipc_object_t object); |
256 | |
257 | /* Release a reference to an object */ |
258 | extern void ipc_object_release( |
259 | ipc_object_t object); |
260 | |
261 | /* Look up an object in a space */ |
262 | extern 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 */ |
269 | extern 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 */ |
279 | extern kern_return_t |
280 | ipc_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 */ |
285 | extern kern_return_t ipc_object_alloc_dead_name( |
286 | ipc_space_t space, |
287 | mach_port_name_t name); |
288 | |
289 | /* Allocate an object */ |
290 | extern 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 */ |
299 | extern 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 */ |
308 | extern 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 */ |
312 | extern 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 */ |
319 | extern 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 */ |
324 | extern void ipc_object_destroy( |
325 | ipc_object_t object, |
326 | mach_msg_type_name_t msgt_name); |
327 | |
328 | /* Destroy a naked destination capability */ |
329 | extern 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 */ |
334 | extern 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 */ |
342 | extern 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 */ |
350 | extern 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 */ |
357 | extern 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 | |