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 * Encapsulation which describes an Image4 identifier. An identifier expresses 31 * the four character code in a signing request as well as the constraint that 32 * the environment places on it. 33 * 34 * Identifiers are not created directly; they are always provided to the caller 35 * by other API and exist within the context of an environment. 36 */ 37 #ifndef __IMAGE4_API_IDENTIFIER_H 38 #define __IMAGE4_API_IDENTIFIER_H 39 40 #include <image4/image4.h> 41 #include <image4/types.h> 42 #include <image4/coprocessor.h> 43 44 __BEGIN_DECLS 45 OS_ASSUME_NONNULL_BEGIN 46 OS_ASSUME_PTR_ABI_SINGLE_BEGIN 47 48 #pragma mark Types 49 /*! 50 * @typedef image4_identifier_constraint_t 51 * An enumeration expressing the type of constraint the identifier places on the 52 * environment. 53 * 54 * @const IMAGE4_IDENTIFIER_CONSTRAINT_EQ 55 * The identifier must match the value in the manifest. 56 * 57 * @const IMAGE4_IDENTIFIER_CONSTRAINT_LT 58 * The identifier must be less than the value in the manifest. 59 * 60 * @const IMAGE4_IDENTIFIER_CONSTRAINT_LE 61 * The identifier must be less than or equal to the value in the manifest. 62 * 63 * @const IMAGE4_IDENTIFIER_CONSTRAINT_GT 64 * The identifier must be greater than the value in the manifest. 65 * 66 * @const IMAGE4_IDENTIFIER_CONSTRAINT_GE 67 * The identifier must be greater than or equal the value in the manifest. 68 * 69 * @const IMAGE4_IDENTIFIER_CONSTRAINT_NE 70 * The identifier must not be equal to the value in the manifest. 71 * 72 * @const IMAGE4_IDENTIFIER_CONSTRAINT_UN 73 * The identifier is not constrained at all. 74 * 75 * @const IMAGE4_IDENTIFIER_CONSTRAINT_NA 76 * The identifier's constraints are not known, or the identifier does not 77 * represent a constraint. 78 */ 79 OS_CLOSED_ENUM(image4_identifier_constraint, uint64_t, 80 IMAGE4_IDENTIFIER_CONSTRAINT_EQ, 81 IMAGE4_IDENTIFIER_CONSTRAINT_LT, 82 IMAGE4_IDENTIFIER_CONSTRAINT_LE, 83 IMAGE4_IDENTIFIER_CONSTRAINT_GT, 84 IMAGE4_IDENTIFIER_CONSTRAINT_GE, 85 IMAGE4_IDENTIFIER_CONSTRAINT_NE, 86 IMAGE4_IDENTIFIER_CONSTRAINT_UN, 87 IMAGE4_IDENTIFIER_CONSTRAINT_NA, 88 ); 89 90 #pragma mark API 91 /*! 92 * @function image4_identifier_get_constraint 93 * Obtain the constraint for the identifier. 94 * 95 * @param id4 96 * The identifier to query. 97 * 98 * @result 99 * The constraint which the environment places on the identifier. 100 */ 101 IMAGE4_API_AVAILABLE_SPRING_2024 102 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 103 image4_identifier_constraint_t 104 image4_identifier_get_constraint(const image4_identifier_t *id4); 105 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_constraint); 106 107 /*! 108 * @function image4_identifier_get_constraint 109 * Obtain a C string representation of the constraint for the identifier. 110 * 111 * @param id4 112 * The identifier to query. 113 * 114 * @result 115 * The C string representation of the constraint which the identifier places on 116 * the environment. 117 */ 118 IMAGE4_API_AVAILABLE_SPRING_2024 119 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 120 const char * 121 image4_identifier_get_constraint_cstr(const image4_identifier_t *id4); 122 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_constraint_cstr); 123 124 /*! 125 * @function image4_identifier_get_fourcc 126 * Obtain the four character code for the identifier. 127 * 128 * @param id4 129 * The identifier to query. 130 * 131 * @result 132 * The four character code which represents the identifier in a manifest. 133 */ 134 IMAGE4_API_AVAILABLE_SPRING_2024 135 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 136 uint32_t 137 image4_identifier_get_fourcc(const image4_identifier_t *id4); 138 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_fourcc); 139 140 /*! 141 * @function image4_identifier_get_fourcc_cstr 142 * Obtain the C string representation of the four character code for the 143 * identifier. 144 * 145 * @param id4 146 * The identifier to query. 147 * 148 * @result 149 * The C string representation of the four character code which represents the 150 * identifier in a manifest. 151 */ 152 IMAGE4_API_AVAILABLE_SPRING_2024 153 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 154 const char * 155 image4_identifier_get_fourcc_cstr(const image4_identifier_t *id4); 156 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_fourcc_cstr); 157 158 OS_ASSUME_PTR_ABI_SINGLE_END 159 OS_ASSUME_NONNULL_END 160 __END_DECLS 161 162 #endif // __IMAGE4_API_IDENTIFIER_H 163