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