1 /*! 2 * @header 3 * Encapsulation which describes an Image4 identifier. An identifier expresses 4 * the four character code in a signing request as well as the constraint that 5 * the environment places on it. 6 * 7 * Identifiers are not created directly; they are always provided to the caller 8 * by other API and exist within the context of an environment. 9 */ 10 #ifndef __IMAGE4_API_IDENTIFIER_H 11 #define __IMAGE4_API_IDENTIFIER_H 12 13 #include <image4/image4.h> 14 #include <image4/types.h> 15 #include <image4/coprocessor.h> 16 17 __BEGIN_DECLS 18 OS_ASSUME_NONNULL_BEGIN 19 OS_ASSUME_PTR_ABI_SINGLE_BEGIN 20 21 #pragma mark Types 22 /*! 23 * @typedef image4_identifier_constraint_t 24 * An enumeration expressing the type of constraint the identifier places on the 25 * environment. 26 * 27 * @const IMAGE4_IDENTIFIER_CONSTRAINT_EQ 28 * The identifier must match the value in the manifest. 29 * 30 * @const IMAGE4_IDENTIFIER_CONSTRAINT_LT 31 * The identifier must be less than the value in the manifest. 32 * 33 * @const IMAGE4_IDENTIFIER_CONSTRAINT_LE 34 * The identifier must be less than or equal to the value in the manifest. 35 * 36 * @const IMAGE4_IDENTIFIER_CONSTRAINT_GT 37 * The identifier must be greater than the value in the manifest. 38 * 39 * @const IMAGE4_IDENTIFIER_CONSTRAINT_GE 40 * The identifier must be greater than or equal the value in the manifest. 41 * 42 * @const IMAGE4_IDENTIFIER_CONSTRAINT_NE 43 * The identifier must not be equal to the value in the manifest. 44 * 45 * @const IMAGE4_IDENTIFIER_CONSTRAINT_UN 46 * The identifier is not constrained at all. 47 * 48 * @const IMAGE4_IDENTIFIER_CONSTRAINT_NA 49 * The identifier's constraints are not known, or the identifier does not 50 * represent a constraint. 51 */ 52 OS_CLOSED_ENUM(image4_identifier_constraint, uint64_t, 53 IMAGE4_IDENTIFIER_CONSTRAINT_EQ, 54 IMAGE4_IDENTIFIER_CONSTRAINT_LT, 55 IMAGE4_IDENTIFIER_CONSTRAINT_LE, 56 IMAGE4_IDENTIFIER_CONSTRAINT_GT, 57 IMAGE4_IDENTIFIER_CONSTRAINT_GE, 58 IMAGE4_IDENTIFIER_CONSTRAINT_NE, 59 IMAGE4_IDENTIFIER_CONSTRAINT_UN, 60 IMAGE4_IDENTIFIER_CONSTRAINT_NA, 61 ); 62 63 #pragma mark API 64 /*! 65 * @function image4_identifier_get_constraint 66 * Obtain the constraint for the identifier. 67 * 68 * @param id4 69 * The identifier to query. 70 * 71 * @result 72 * The constraint which the environment places on the identifier. 73 */ 74 IMAGE4_API_AVAILABLE_SPRING_2024 75 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 76 image4_identifier_constraint_t 77 image4_identifier_get_constraint(const image4_identifier_t *id4); 78 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_constraint); 79 80 /*! 81 * @function image4_identifier_get_constraint 82 * Obtain a C string representation of the constraint for the identifier. 83 * 84 * @param id4 85 * The identifier to query. 86 * 87 * @result 88 * The C string representation of the constraint which the identifier places on 89 * the environment. 90 */ 91 IMAGE4_API_AVAILABLE_SPRING_2024 92 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 93 const char * 94 image4_identifier_get_constraint_cstr(const image4_identifier_t *id4); 95 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_constraint_cstr); 96 97 /*! 98 * @function image4_identifier_get_fourcc 99 * Obtain the four character code for the identifier. 100 * 101 * @param id4 102 * The identifier to query. 103 * 104 * @result 105 * The four character code which represents the identifier in a manifest. 106 */ 107 IMAGE4_API_AVAILABLE_SPRING_2024 108 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 109 uint32_t 110 image4_identifier_get_fourcc(const image4_identifier_t *id4); 111 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_fourcc); 112 113 /*! 114 * @function image4_identifier_get_fourcc_cstr 115 * Obtain the C string representation of the four character code for the 116 * identifier. 117 * 118 * @param id4 119 * The identifier to query. 120 * 121 * @result 122 * The C string representation of the four character code which represents the 123 * identifier in a manifest. 124 */ 125 IMAGE4_API_AVAILABLE_SPRING_2024 126 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 127 const char * 128 image4_identifier_get_fourcc_cstr(const image4_identifier_t *id4); 129 IMAGE4_XNU_AVAILABLE_DIRECT(image4_identifier_get_fourcc_cstr); 130 131 OS_ASSUME_PTR_ABI_SINGLE_END 132 OS_ASSUME_NONNULL_END 133 __END_DECLS 134 135 #endif // __IMAGE4_API_IDENTIFIER_H 136