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