1 /*
2 * Copyright (c) 2022 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * The contents of this file constitute Original Code as defined in and
7 * are subject to the Apple Public Source License Version 1.1 (the
8 * "License"). You may not use this file except in compliance with the
9 * License. Please obtain a copy of the License at
10 * http://www.apple.com/publicsource and read it before using this file.
11 *
12 * This Original Code and all software distributed under the License are
13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
17 * License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * @APPLE_LICENSE_HEADER_END@
21 */
22
23 #ifndef _SYS_CODE_SIGNING_H_
24 #define _SYS_CODE_SIGNING_H_
25
26 #include <sys/cdefs.h>
27 __BEGIN_DECLS
28
29 typedef uint32_t code_signing_monitor_type_t;
30 enum {
31 CS_MONITOR_TYPE_NONE = 0,
32 CS_MONITOR_TYPE_PPL = 1,
33
34 };
35
36 typedef uint32_t code_signing_config_t;
37 enum {
38 CS_CONFIG_UNRESTRICTED_DEBUGGING = (1 << 0),
39 CS_CONFIG_ALLOW_ANY_SIGNATURE = (1 << 1),
40 CS_CONFIG_ENFORCEMENT_DISABLED = (1 << 2),
41 CS_CONFIG_GET_OUT_OF_MY_WAY = (1 << 3),
42 CS_CONFIG_CSM_ENABLED = (1 << 31),
43 };
44
45 #ifdef KERNEL_PRIVATE
46 /* All definitions for XNU and kernel extensions */
47
48 #include <mach/boolean.h>
49 #include <mach/kern_return.h>
50 #include <img4/firmware.h>
51
52 /* Availability macros for KPI functions */
53 #define XNU_SUPPORTS_CSM_TYPE 1
54 #define XNU_SUPPORTS_CSM_APPLE_IMAGE4 1
55 #define XNU_SUPPORTS_PROFILE_GARBAGE_COLLECTION 1
56 #define XNU_SUPPORTS_COMPILATION_SERVICE 1
57 #define XNU_SUPPORTS_LOCAL_SIGNING 1
58 #define XNU_SUPPORTS_CE_ACCELERATION 1
59
60 /* Local signing public key size */
61 #define XNU_LOCAL_SIGNING_KEY_SIZE 97
62
63 #if XNU_KERNEL_PRIVATE
64
65 #include <sys/code_signing_internal.h>
66 #include <libkern/img4/interface.h>
67
68 #if PMAP_CS_INCLUDE_CODE_SIGNING
69 #if XNU_LOCAL_SIGNING_KEY_SIZE != PMAP_CS_LOCAL_SIGNING_KEY_SIZE
70 #error "XNU local signing key size and PMAP_CS local signing key size differ!"
71 #endif
72 #endif /* PMAP_CS_INCLUDE_CODE_SIGNING */
73
74 /* Common developer mode state variable */
75 extern bool *developer_mode_enabled;
76
77 /**
78 * AppleImage4 does not provide an API to convert an object specification index to an
79 * actual object specification. Since this particular function is used across different
80 * places, it makes sense to keep it in a shared header file.
81 *
82 * This function may be called in contexts where printing is not possible, so do NOT
83 * leave a print statement here under any ciscumstances.
84 */
85 static inline const img4_runtime_object_spec_t*
image4_get_object_spec_from_index(img4_runtime_object_spec_index_t obj_spec_index)86 image4_get_object_spec_from_index(
87 img4_runtime_object_spec_index_t obj_spec_index)
88 {
89 const img4_runtime_object_spec_t *obj_spec = NULL;
90
91 switch (obj_spec_index) {
92 case IMG4_RUNTIME_OBJECT_SPEC_INDEX_SUPPLEMENTAL_ROOT:
93 obj_spec = IMG4_RUNTIME_OBJECT_SPEC_SUPPLEMENTAL_ROOT;
94 break;
95
96 case IMG4_RUNTIME_OBJECT_SPEC_INDEX_LOCAL_POLICY:
97 obj_spec = IMG4_RUNTIME_OBJECT_SPEC_LOCAL_POLICY;
98 break;
99
100 default:
101 break;
102 }
103
104 return obj_spec;
105 }
106
107 /**
108 * Perform any initialization required for managing code signing state on the system.
109 * This is called within XNU itself and doesn't need to be exported to anything external.
110 */
111 void
112 code_signing_init(void);
113
114 #endif /* XNU_KERNEL_PRIVATE */
115
116 /**
117 * Query the system to understand the code signing configuration of the system. This
118 * includes information on what monitor environment is available on the system as well
119 * as what the state of the system looks like with the provided boot-args.
120 */
121 void
122 code_signing_configuration(
123 code_signing_monitor_type_t *monitor_type,
124 code_signing_config_t *config);
125
126 /**
127 * Enable developer mode on the system. When the system contains a monitor environment,
128 * developer mode is turned on by trapping into the appropriate monitor environment.
129 */
130 void
131 enable_developer_mode(void);
132
133 /**
134 * Disable developer mode on the system. When the system contains a monitor environment,
135 * developer mode is turned off by trapping into the appropriate monitor environment.
136 */
137 void
138 disable_developer_mode(void);
139
140 /**
141 * Query the current state of developer mode on the system. This call never traps into
142 * the monitor environment because XNU can directly read the monitors memory.
143 */
144 bool
145 developer_mode_state(void);
146
147 /**
148 * Wrapper function which is exposed to kernel extensions. This can be used to trigger
149 * a call to the garbage collector for going through and unregistring all unused profiles
150 * on the system.
151 */
152 void
153 garbage_collect_provisioning_profiles(void);
154
155 /**
156 * Set the CDHash which is currently being used by the compilation service. This CDHash
157 * is compared against when validating the signature of a compilation service library.
158 */
159 void
160 set_compilation_service_cdhash(
161 const uint8_t *cdhash);
162
163 /**
164 * Match a CDHash against the currently stored CDHash for the compilation service.
165 */
166 bool
167 match_compilation_service_cdhash(
168 const uint8_t *cdhash);
169
170 /**
171 * Set the local signing key which is currently being used on the system. This key is used
172 * to validate any signatures which are signed on device.
173 */
174 void
175 set_local_signing_public_key(
176 const uint8_t public_key[XNU_LOCAL_SIGNING_KEY_SIZE]);
177
178 /**
179 * Get the local signing key which is currently being used on the system. This API is
180 * mostly used by kernel extensions which validate code signatures on the platform.
181 */
182 uint8_t*
183 get_local_signing_public_key(void);
184
185 /**
186 * Unrestrict a particular CDHash for local signing, allowing it to be loaded and run on
187 * the system. This is only required to be done for main binaries, since libraries do not
188 * need to be unrestricted.
189 */
190 void
191 unrestrict_local_signing_cdhash(
192 const uint8_t *cdhash);
193
194 /**
195 * The kernel or the monitor environments allocate some data which is used by AppleImage4
196 * for storing critical system information such as nonces. AppleImage4 uses this API to
197 * get access to this data while abstracting the implementation underneath.
198 */
199 void*
200 kernel_image4_storage_data(
201 size_t *allocated_size);
202
203 /**
204 * AppleImage4 uses this API to store the specified nonce into the nonce storage. This API
205 * abstracts away the kernel or monitor implementation used.
206 */
207 void
208 kernel_image4_set_nonce(
209 const img4_nonce_domain_index_t ndi,
210 const img4_nonce_t *nonce);
211
212 /**
213 * AppleImage4 uses this API to roll a specified nonce on the next boot. This API abstracts
214 * away the kernel or monitor implementation used.
215 */
216 void
217 kernel_image4_roll_nonce(
218 const img4_nonce_domain_index_t ndi);
219
220 /**
221 * AppleImage4 uses this API to copy a specified nonce from the nonce storage. This API
222 * abstracts away the kernel or monitor implementation used.
223 *
224 * We need this API since the nonces use a lock to protect against concurrency, and the
225 * lock can only be taken within the monitor environment, if any.
226 */
227 errno_t
228 kernel_image4_copy_nonce(
229 const img4_nonce_domain_index_t ndi,
230 img4_nonce_t *nonce_out);
231
232 /**
233 * AppleImage4 uses this API to perform object execution on a particular object type. This
234 * API abstracts away the kernel or monitor implementation used.
235 */
236 errno_t
237 kernel_image4_execute_object(
238 img4_runtime_object_spec_index_t obj_spec_index,
239 const img4_buff_t *payload,
240 const img4_buff_t *manifest);
241
242 /**
243 * AppleImage4 uses this API to copy the contents of an executed object. This API abstracts
244 * away the kernel or monitor implementation used.
245 */
246 errno_t
247 kernel_image4_copy_object(
248 img4_runtime_object_spec_index_t obj_spec_index,
249 vm_address_t object_out,
250 size_t *object_length);
251
252 /**
253 * AppleImage4 uses this API to get a pointer to the structure which is used for exporting
254 * monitor locked down data to the rest of the system.
255 */
256 const void*
257 kernel_image4_get_monitor_exports(void);
258
259 /**
260 * AppleImage4 uses this API to let the monitor environment know the release type for the
261 * the current boot. Under some circumstances, the monitor isn't able to gauge this on its
262 * own.
263 */
264 errno_t
265 kernel_image4_set_release_type(
266 const char *release_type);
267
268 /**
269 * AppleImage4 uses this API to let the monitor know when a nonce domain is shadowing the
270 * AP boot nonce. Since this information is queried from the NVRAM, the monitor cant know
271 * this on its own.
272 */
273 errno_t
274 kernel_image4_set_bnch_shadow(
275 const img4_nonce_domain_index_t ndi);
276
277 /**
278 * AMFI uses this API to obtain the OSEntitlements object which is associated with the
279 * main binary mapped in for a process.
280 *
281 * This API is considered safer for resolving the OSEntitlements than through the cred
282 * structure on the process because the system maintains a strong binding in the linkage
283 * chain from the process structure through the pmap, which ultimately contains the
284 * code signing monitors address space information for the process.
285 */
286 kern_return_t
287 csm_resolve_os_entitlements_from_proc(
288 const proc_t process,
289 const void **os_entitlements);
290
291 #if CODE_SIGNING_MONITOR
292
293 /**
294 * Check to see if the monitor is currently enforcing code signing protections or
295 * not. Even when this is disabled, certains artifacts are still protected by the
296 * monitor environment.
297 */
298 bool
299 csm_enabled(void);
300
301 /**
302 * This function is used to initialize the state of the locks for managing provisioning
303 * profiles on the system. It should be called by the kernel bootstrap thread during the
304 * early kernel initialization.
305 */
306 void
307 csm_initialize_provisioning_profiles(void);
308
309 /**
310 * Register a provisioning profile with the monitor environment available on the
311 * system. This function will allocate its own memory for managing the profile and
312 * the caller is allowed to free their own allocation.
313 */
314 kern_return_t
315 csm_register_provisioning_profile(
316 const uuid_t profile_uuid,
317 const void *profile,
318 const size_t profile_size);
319
320 /**
321 * Associate a registered profile with a code signature object which is managed by
322 * the monitor environment. This incrementes the reference count on the profile object
323 * managed by the monitor, preventing the profile from being unregistered.
324 */
325 kern_return_t
326 csm_associate_provisioning_profile(
327 void *monitor_sig_obj,
328 const uuid_t profile_uuid);
329
330 /**
331 * Disassociate an associated profile with a code signature object which is managed by
332 * the monitor environment. This decrements the refernce count on the profile object
333 * managed by the monitor, potentially allowing it to be unregistered in case no other
334 * signatures hold a reference count to it.
335 */
336 kern_return_t
337 csm_disassociate_provisioning_profile(
338 void *monitor_sig_obj);
339
340 /**
341 * Trigger the provisioning profile garbage collector to go through each registered
342 * profile on the system and unregister it in case it isn't being used.
343 */
344 void
345 csm_free_provisioning_profiles(void);
346
347 /**
348 * Acquire the largest size for a code signature which the monitor will allocate on
349 * its own. Anything larger than this size needs to be page-allocated and aligned and
350 * will be locked down by the monitor upon registration.
351 */
352 vm_size_t
353 csm_signature_size_limit(void);
354
355 /**
356 * Register a code signature with the monitor environment. The monitor will either
357 * allocate its own memory for the code signature, or it will lockdown the memory which
358 * is given to it. In either case, the signature will be read-only for the kernel.
359 *
360 * If the monitor doesn't enforce code signing, then this function will return the
361 * KERN_SUCCESS condition.
362 */
363 kern_return_t
364 csm_register_code_signature(
365 const vm_address_t signature_addr,
366 const vm_size_t signature_size,
367 const vm_offset_t code_directory_offset,
368 const char *signature_path,
369 void **monitor_sig_obj,
370 vm_address_t *monitor_signature_addr);
371
372 /**
373 * Unregister a code signature previously registered with the monitor environment.
374 * This will free (or unlock) the signature memory held by the monitor.
375 *
376 * If the monitor doesn't enforce code signing, then this function will return the
377 * error KERN_NOT_SUPPORTED.
378 */
379 kern_return_t
380 csm_unregister_code_signature(
381 void *monitor_sig_obj);
382
383 /**
384 * Verify a code signature previously registered with the monitor. After verification,
385 * the signature can be used for making code signature associations with address spaces.
386 *
387 * If the monitor doesn't enforce code signing, then this function will return the
388 * KERN_SUCCESS condition.
389 */
390 kern_return_t
391 csm_verify_code_signature(
392 void *monitor_sig_obj);
393
394 /**
395 * Perform 2nd stage reconstitution through the monitor. This unlocks any unused parts
396 * of the code signature, which can then be freed by the kernel. This isn't strictly
397 * required, but it helps in conserving system memory.
398 *
399 * If the monitor doesn't enforce code signing, then this function will return the
400 * error KERN_NOT_SUPPORTED.
401 */
402 kern_return_t
403 csm_reconstitute_code_signature(
404 void *monitor_sig_obj,
405 vm_address_t *unneeded_addr,
406 vm_size_t *unneeded_size);
407
408 /**
409 * Associate a code signature with an address space for a specified region with the
410 * monitor environment. The code signature can only be associated if it has been
411 * verified before.
412 */
413 kern_return_t
414 csm_associate_code_signature(
415 pmap_t pmap,
416 void *monitor_sig_obj,
417 const vm_address_t region_addr,
418 const vm_size_t region_size,
419 const vm_offset_t region_offset);
420
421 /**
422 * Associate a JIT region with an address space in the monitor environment. An address
423 * space can only have a JIT region if it has the appropriate JIT entitlement.
424 */
425 kern_return_t
426 csm_associate_jit_region(
427 pmap_t pmap,
428 const vm_address_t region_addr,
429 const vm_size_t region_size);
430
431 /**
432 * Associate a debug region with an address space in the monitor environment. An address
433 * space can only have a debug region if it is currently being debugged.
434 */
435 kern_return_t
436 csm_associate_debug_region(
437 pmap_t pmap,
438 const vm_address_t region_addr,
439 const vm_size_t region_size);
440
441 /**
442 * Call out to the monitor to inform it that the address space needs to be debugged. The
443 * monitor will only allow the address space to be debugged if it has the appropriate
444 * entitlements.
445 */
446 kern_return_t
447 csm_allow_invalid_code(
448 pmap_t pmap);
449
450 /**
451 * Certain address spaces are exempt from code signing enforcement. This function can be
452 * used to check if the specified address space is such or not.
453 */
454 kern_return_t
455 csm_address_space_exempt(
456 const pmap_t pmap);
457
458 /**
459 * Instruct the monitor that an address space is about to be forked. The monitor can then
460 * do whatever it needs to do in order to prepare for the fork.
461 */
462 kern_return_t
463 csm_fork_prepare(
464 pmap_t old_pmap,
465 pmap_t new_pmap);
466
467 /**
468 * Get the signing identifier which is embedded within the code directory using the
469 * code signing monitor's abstract signature object.
470 */
471 kern_return_t
472 csm_acquire_signing_identifier(
473 const void *monitor_sig_obj,
474 const char **signing_id);
475
476 /**
477 * This API to associate an OSEntitlements objects with the code signing monitor's
478 * signature object. This binding is useful as it can be used to resolve the entitlement
479 * object which is used by the kernel for performing queries.
480 */
481 kern_return_t
482 csm_associate_os_entitlements(
483 void *monitor_sig_obj,
484 const void *os_entitlements);
485
486 /**
487 * Accelerate the CoreEntitlements context within the code signing monitor's memory
488 * in order to speed up all queries for entitlements going through CoreEntitlements.
489 */
490 kern_return_t
491 csm_accelerate_entitlements(
492 void *monitor_sig_obj,
493 CEQueryContext_t *ce_ctx);
494
495 kern_return_t
496 vm_map_entry_cs_associate(
497 vm_map_t map,
498 struct vm_map_entry *entry,
499 vm_map_kernel_flags_t vmk_flags);
500
501 kern_return_t
502 cs_associate_blob_with_mapping(
503 void *pmap,
504 vm_map_offset_t start,
505 vm_map_size_t size,
506 vm_object_offset_t offset,
507 void *blobs_p);
508
509 #endif /* CODE_SIGNING_MONITOR */
510
511 #endif /* KERNEL_PRIVATE */
512
513 __END_DECLS
514 #endif /* _SYS_CODE_SIGNING_H_ */
515