1 // 2 // Entitlements.h 3 // CoreEntitlements 4 // 5 // 6 7 #ifndef CORE_ENTITLEMENTS_ENTITLEMENTS_H 8 #define CORE_ENTITLEMENTS_ENTITLEMENTS_H 9 10 #ifndef _CE_INDIRECT 11 #error "Please include <CoreEntitlements/CoreEntitlements.h> instead of this file" 12 #endif 13 14 #include <CoreEntitlements/Result.h> 15 #include <CoreEntitlements/Runtime.h> 16 17 __ptrcheck_abi_assume_single(); 18 19 /*! 20 * @enum CEVersion_t 21 * Represents the various versions supported by CoreEntitlements 22 */ 23 OS_ENUM(CEVersion, int64_t, 24 kCEVersionInvalid = 0, 25 kCEVersionZero = 1, 26 kCEVersionOne = 2); 27 28 /*! 29 * @struct CEValidationResult 30 * Contains the result of the call to CEValidate 31 */ 32 typedef struct { 33 CEVersion_t version; 34 const uint8_t *__ended_by(blob_end) blob; 35 const uint8_t * blob_end; 36 } CEValidationResult; 37 38 typedef struct { 39 bool allow_data_elements; 40 } CEValidationOptions; 41 42 /*! 43 * @function CEValidate 44 * Validates if the provided blob conforms to one of the entitlement specification understood by CoreEntitlements 45 * @param rt 46 * Active runtime 47 * @param result 48 * The validation result will be stored here 49 * @param blob 50 * Pointer to the start of the entitlements object 51 * @param blob_end 52 * Pointer to one byte past the end of the entitlements object 53 * @discussion 54 * This function will return kCENoError if the entitlements are valid 55 */ 56 CEError_t CEValidate(const CERuntime_t rt, CEValidationResult* result, const uint8_t *__ended_by(blob_end) blob, const uint8_t* blob_end) __result_use_check; 57 /*! 58 * @function CEValidateWithOptions 59 * Validates if the provided blob conforms to one of the entitlement specification understood by CoreEntitlements 60 * @param rt 61 * Active runtime 62 * @param options 63 * Options that modify how validation behaves 64 * @param result 65 * The validation result will be stored here 66 * @param blob 67 * Pointer to the start of the entitlements object 68 * @param blob_end 69 * Pointer to one byte past the end of the entitlements object 70 * @discussion 71 * This function will return kCENoError if the entitlements are valid 72 */ 73 CEError_t CEValidateWithOptions(const CERuntime_t rt, CEValidationOptions* options, CEValidationResult* result, const uint8_t *__ended_by(blob_end) blob, const uint8_t* blob_end) __result_use_check; 74 75 /*! 76 * @function CEAcquireManagedContext 77 * Creates and returns a managed query context for the validated blob against which you can perform queries 78 * @param rt 79 * Active runtime (must support allocation and deallocation) 80 * @param validationResult 81 * The validation result returned by CEValidate 82 * @param ctx 83 * Pointer to where the context is to be returned 84 * @note 85 * The returned managed context must be subsequently released with CEAcquireManagedContext 86 */ 87 CEError_t CEAcquireManagedContext(const CERuntime_t rt, CEValidationResult validationResult, CEQueryContext_t* ctx) __result_use_check; 88 89 /*! 90 @discussion 91 Releases the managed context 92 */ 93 CEError_t CEReleaseManagedContext(CEQueryContext_t* ctx); 94 95 /*! 96 * @enum CEQueryOpOpcode_t 97 * These are all the supported operations by the CoreEntitlements VM 98 */ 99 OS_ENUM(CEQueryOpOpcode, int64_t, 100 kCEOpNoop = 0, 101 kCEOpSelectKey = 1, 102 kCEOpSelectIndex = 2, 103 kCEOpMatchString = 3, 104 kCEOpMatchStringPrefix = 4, 105 kCEOpMatchBool = 5, 106 kCEOpStringValueAllowed = 6, 107 kCEOpMatchInteger = 7, 108 kCEOpStringPrefixValueAllowed = 8, 109 kCEOpSelectKeyWithPrefix = 9, 110 kCEOpIntegerValueAllowed = 10, 111 kCEOpMatchType = 11, 112 kCEOpMatchData = 12, 113 kCEOpMatchDataValueAllowed = 13, 114 kCEOpMaxOperation = 14, /* Sentinel value */ 115 kCEOpDynamic = 0x1LL << 62); 116 117 118 119 /*! 120 * @typedef CEQueryOperation_t 121 * Represents an operation within the DERQL interpreter 122 * The opcode specified _which_ operation to perform, while the parameters specify how to perform it. 123 * Operations are passed by value and may be safely reused. 124 */ 125 typedef struct CEQueryOperation { 126 CEQueryOpOpcode_t opcode; 127 union { 128 CEBuffer dynamicParameter; 129 CEStaticBuffer stringParameter; 130 int64_t numericParameter; 131 } parameters; 132 } CEQueryOperation_t; 133 134 typedef CEQueryOperation_t CEQuery_t[]; 135 136 extern const CEQueryOperation_t* CESelectKeyOperation; 137 extern const CEQueryOperation_t* CESelectValueOperation; 138 139 /*! 140 * @typedef CEPrepareOptions_t 141 * Containts the options you may pass in to CEPrepareQuery. 142 */ 143 typedef struct CEPrepareOptions { 144 /* 145 If materialize is true dynamic ops are turned into static ones 146 */ 147 bool materialize; 148 /* 149 Controls if CEPrepareQuery should fail on keys in dynamic operations that are too long 150 */ 151 bool failOnOversizedParameters; 152 } CEPrepareOptions_t; 153 154 /*! 155 * @function CEContextQuery 156 * Performs a query on the passed in CEQueryContext_t 157 * 158 * @param ctx 159 * The context on which to perform the query 160 * 161 * @param query 162 * The sequence of operations to execute 163 * 164 * @param queryLength 165 * The number of operations in the query 166 * 167 * @returns 168 * This function will return kCENoError if the query is satisfiable, otherwise kCEQueryCannotBeSatisfied. 169 * 170 * @note 171 * As stated previously, the query only succeeds if it is satisfiable by the context, meaning that the operations executed in the passed in order 172 * leave the VM in the valid state. An invalid state may arise from a variety of situations, like trying to select a value for a key that doesn't exist, 173 * or a failing string matching operations. 174 */ 175 CEError_t CEContextQuery(CEQueryContext_t ctx, const CEQueryOperation_t *__counted_by(queryLength) query, size_t queryLength) __result_use_check; 176 177 /*! 178 * @function CEPrepareQuery 179 * Prepares the query for execution by materializing dynamic operations if needed 180 * 181 * @params options 182 * Options to control how the query should be prepared 183 * 184 * @param query 185 * The sequence of operations to prepare 186 * 187 * @param queryLength 188 * The number of operations in the query 189 */ 190 CEError_t CEPrepareQuery(CEPrepareOptions_t options, CEQueryOperation_t *__counted_by(queryLength) query, size_t queryLength); 191 192 /*! 193 * @function CEContextIsSubset 194 * Checks if the subset <-> superset relation holds between two context. 195 * The logic relations used to establish that relation correspond to the normal profile-validation rules. 196 * 197 * @param subset 198 * The context that is meant to a subset 199 * 200 * @param superset 201 * The context that is meant to be a superset 202 * 203 * @returns 204 * This function will return kCENoError if the relation holds, otherwise kCEQueryCannotBeSatisfied. 205 */ 206 CEError_t CEContextIsSubset(CEQueryContext_t subset, CEQueryContext_t superset); 207 208 #include <CoreEntitlements/QueryHelpers.h> 209 210 #endif 211