1 /* 2 * Copyright © 2017-2024 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 * @header 30 * Common header for Image4 trust evaluation API. 31 */ 32 #ifndef __IMAGE4_API_H 33 #define __IMAGE4_API_H 34 35 /*! 36 * @const IMAGE4_API_VERSION 37 * The API version of the library. This version will be changed in accordance 38 * with new API introductions so that callers may submit code to the build that 39 * adopts those new APIs before the APIs land by using the following pattern: 40 * 41 * #if IMAGE4_API_VERSION >= 20221230 42 * image4_new_api(); 43 * #endif 44 * 45 * In this example, the library maintainer and API adopter agree on an API 46 * version of 20221230 ahead of time for the introduction of 47 * image4_new_api(). When a libdarwin with that API version is submitted, the 48 * project is rebuilt, and the new API becomes active. 49 * 50 * Breaking API changes will be both covered under this mechanism as well as 51 * individual preprocessor macros in this header that declare new behavior as 52 * required. 53 */ 54 #define IMAGE4_API_VERSION (20240503u) 55 56 /*! 57 * @const IMAGE4_RESTRICTED_API_VERSION 58 * The restricted API version of the library. Restricted interfaces are 59 * 60 * 1. likely to be hacks, 61 * 2. not guaranteed to function correctly in all contexts, and 62 * 3. subject to a pre-arranged contract for deprecation and removal. 63 * 64 * The availability documentation for each restricted API will indicate the 65 * expiration version. 66 */ 67 #define IMAGE4_RESTRICTED_API_VERSION (1002u) 68 69 #if __has_include(<os/base.h>) 70 #include <os/base.h> 71 #else 72 #include <image4/shim/base.h> 73 #endif 74 75 #if __has_include(<sys/types.h>) 76 #include <sys/types.h> 77 78 #if !defined(_ERRNO_T) 79 typedef int errno_t; 80 #endif // !defined(_ERRNO_T) 81 #else 82 #include <image4/shim/types.h> 83 #endif 84 85 #if __has_include(<TargetConditionals.h>) 86 #include <TargetConditionals.h> 87 #endif 88 89 #if __has_include(<os/availability.h>) 90 #include <os/availability.h> 91 #endif 92 93 #if __has_include(<sys/cdefs.h>) 94 #include <sys/cdefs.h> 95 #endif 96 97 #if !defined(__BEGIN_DECLS) 98 #if defined(__cplusplus) 99 #define __BEGIN_DECLS extern "C" { 100 #define __END_DECLS } 101 #else 102 #define __BEGIN_DECLS 103 #define __END_DECLS 104 #endif 105 #endif 106 107 #if !defined(__static_size) 108 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L && __GNUC__ 109 #define __static_size static 110 #define __static_size_const static const 111 #else 112 #define __static_size 113 #define __static_size_const 114 #endif 115 #endif // !defined(__static_size) 116 117 /*! 118 * @brief 119 * Pass -DIMAGE4_STRIP_AVAILABILITY=1 if the build environment is picking up a 120 * definition of API_AVAILABLE from somewhere, e.g. an old shim header or from 121 * inappropriately-injected header search paths. 122 */ 123 #if !defined(API_AVAILABLE) || IMAGE4_STRIP_AVAILABILITY 124 #undef API_AVAILABLE 125 #define API_AVAILABLE(...) 126 #endif 127 128 #if !defined(__ASSUME_PTR_ABI_SINGLE_BEGIN) 129 #if __has_include(<ptrcheck.h>) 130 #include <ptrcheck.h> 131 #define __ASSUME_PTR_ABI_SINGLE_BEGIN __ptrcheck_abi_assume_single() 132 #define __ASSUME_PTR_ABI_SINGLE_END __ptrcheck_abi_assume_unsafe_indexable() 133 #else 134 #define __ASSUME_PTR_ABI_SINGLE_BEGIN 135 #define __ASSUME_PTR_ABI_SINGLE_END 136 #endif 137 #endif 138 139 #if defined(__counted_by_or_null) 140 #define __static_array_or_null(_S) _Nullable __counted_by_or_null(_S) 141 #else 142 #define __counted_by_or_null(_S) 143 #define __static_array_or_null(_S) _Nullable _S 144 #endif 145 146 #if !defined(__sized_by_or_null) 147 #define __sized_by_or_null(_S) 148 #endif 149 150 #if XNU_KERNEL_PRIVATE 151 #if !defined(__IMAGE4_XNU_INDIRECT) 152 #error "Please include <libkern/image4/dlxk.h> instead of this header" 153 #endif 154 #endif 155 156 /*! 157 * @const IMAGE4_API_AVAILABLE_SPRING_2024 158 * APIs which first became available in the Spring 2024 set of releases. 159 */ 160 #define IMAGE4_API_AVAILABLE_SPRING_2024 \ 161 API_AVAILABLE( \ 162 macos(14.3), \ 163 ios(17.4), \ 164 tvos(17.4), \ 165 watchos(10.4), \ 166 bridgeos(8.3)) 167 168 /*! 169 * @const IMAGE4_API_AVAILABLE_FALL_2024 170 * APIs which first became available in the Fall 2024 set of releases. 171 */ 172 #define IMAGE4_API_AVAILABLE_FALL_2024 \ 173 API_AVAILABLE( \ 174 macos(15.0), \ 175 ios(18.0), \ 176 tvos(18.0), \ 177 watchos(11.0), \ 178 bridgeos(9.0)) 179 180 /*! 181 * @const IMAGE4_XNU_AVAILABLE_DIRECT 182 * API symbol which is available to xnu via the dlxk mechanism. 183 */ 184 #if XNU_KERNEL_PRIVATE || IMAGE4_DLXK_AVAILABILITY 185 #define IMAGE4_XNU_AVAILABLE_DIRECT(_s) typedef typeof(&_s) _ ## _s ## _dlxk_t 186 #else 187 #define IMAGE4_XNU_AVAILABLE_DIRECT(_s) 188 #endif 189 190 /*! 191 * @const IMAGE4_XNU_AVAILABLE_INDIRECT 192 * API symbol which is accessed through a macro and is available to xnu via the 193 * dlxk mechanism. 194 */ 195 #if XNU_KERNEL_PRIVATE || IMAGE4_DLXK_AVAILABILITY 196 #define IMAGE4_XNU_AVAILABLE_INDIRECT(_s) typedef typeof(&_s) _s ## _dlxk_t 197 #else 198 #define IMAGE4_XNU_AVAILABLE_INDIRECT(_s) 199 #endif 200 201 /*! 202 * @const IMAGE4_XNU_RETIRED_DIRECT 203 * API symbol which has been retired. 204 */ 205 #if XNU_KERNEL_PRIVATE || IMAGE4_DLXK_AVAILABILITY 206 #define IMAGE4_XNU_RETIRED_DIRECT(_s) typedef void * _ ## _s ## _dlxk_t 207 #else 208 #define IMAGE4_XNU_RETIRED_DIRECT(_s) 209 #endif 210 211 /*! 212 * @const IMAGE4_XNU_RETIRED_INDIRECT 213 * API symbol which has been retired. 214 */ 215 #if XNU_KERNEL_PRIVATE || IMAGE4_DLXK_AVAILABILITY 216 #define IMAGE4_XNU_RETIRED_INDIRECT(_s) typedef void * _s ## _dlxk_t 217 #else 218 #define IMAGE4_XNU_RETIRED_INDIRECT(_s) 219 #endif 220 221 /*! 222 * @const image4_call_restricted 223 * Calls a restricted API. 224 */ 225 #if IMAGE4_RESTRICTED_API 226 #define image4_call_restricted(_s, ...) image4_ ## _s(__VA_ARGS__) 227 #else 228 #define image4_call_restricted(_s, ...) \ 229 image4_ ## _s(IMAGE4_RESTRICTED_API_VERSION, ## __VA_ARGS__) 230 #endif 231 232 #endif // __IMAGE4_API_H 233