1/* 2 * Copyright (c) 2011-2014 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_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. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23#ifndef _H_SECASSESSMENT 24#define _H_SECASSESSMENT 25 26#include <CoreFoundation/CoreFoundation.h> 27 28#ifdef __cplusplus 29extern "C" { 30#endif 31 32 33/*! 34 * @type SecAccessmentRef An assessment being performed. 35 */ 36typedef struct _SecAssessment *SecAssessmentRef; 37 38 39/*! 40 * CF-standard type function 41 */ 42CFTypeID SecAssessmentGetTypeID(); 43 44 45/* 46 * Notifications sent when the policy authority database changes. 47 * (Should move to /usr/include/notify_keys.h eventually.) 48 */ 49#define kNotifySecAssessmentMasterSwitch "com.apple.security.assessment.masterswitch" 50#define kNotifySecAssessmentUpdate "com.apple.security.assessment.update" 51#define kNotifySecAssessmentRecordingChange "com.apple.security.assessment.UIRecordRejectDidChangeNotification" 52 53 54/*! 55 * Primary operation types. These are operations the system policy can express 56 * opinions on. They are not operations *on* the system configuration itself. 57 * (For those, see SecAssessmentUpdate below.) 58 * 59 * @constant kSecAssessmentContextKeyOperation Context key describing the type of operation 60 * being contemplated. The default varies depending on the API call used. 61 * @constant kSecAssessmentOperationTypeExecute Value denoting the operation of running or executing 62 * code on the system. 63 * @constant kSecAssessmentOperationTypeInstall Value denoting the operation of installing 64 * software into the system. 65 * @constant kSecAssessmentOperationTypeOpenDocument Value denoting the operation of opening 66 * (in the LaunchServices sense) of documents. 67 */ 68extern CFStringRef kSecAssessmentContextKeyOperation; // proposed operation 69extern CFStringRef kSecAssessmentOperationTypeExecute; // .. execute code 70extern CFStringRef kSecAssessmentOperationTypeInstall; // .. install software 71extern CFStringRef kSecAssessmentOperationTypeOpenDocument; // .. LaunchServices-level document open 72 73 74/*! 75 Operational flags for SecAssessment calls 76 77 @type SecAssessmentFlags A mask of flag bits passed to SecAssessment calls to influence their 78 operation. 79 80 @constant kSecAssessmentDefaultFlags Pass this to indicate that default behavior is desired. 81 @constant kSecAssessmentFlagIgnoreCache Do not use cached information; always perform a full 82 evaluation of system policy. This may be substantially slower. 83 @constant kSecAssessmentFlagNoCache Do not save any evaluation outcome in the system caches. 84 Any content already there is left undisturbed. Independent of kSecAssessmentFlagIgnoreCache. 85 @constant kSecAssessmentFlagEnforce Perform normal operations even if assessments have been 86 globally bypassed (which would usually approve anything). 87 @constant kSecAssessmentAllowWeak Allow signatures that contain known weaknesses, such as an 88 insecure resource envelope. 89 @constant kSecAssessmentIgnoreWhitelist Do not search the weak signature whitelist. 90 91 Flags common to multiple calls are assigned from high-bit down. Flags for particular calls 92 are assigned low-bit up, and are documented with that call. 93 */ 94typedef uint64_t SecAssessmentFlags; 95enum { 96 kSecAssessmentDefaultFlags = 0, // default behavior 97 98 kSecAssessmentFlagDirect = 1 << 30, // in-process evaluation 99 kSecAssessmentFlagAsynchronous = 1 << 29, // request asynchronous operation 100 kSecAssessmentFlagIgnoreCache = 1 << 28, // do not search cache 101 kSecAssessmentFlagNoCache = 1 << 27, // do not populate cache 102 kSecAssessmentFlagEnforce = 1 << 26, // force on (disable bypass switches) 103 kSecAssessmentFlagAllowWeak = 1 << 25, // allow weak signatures 104 kSecAssessmentFlagIgnoreWhitelist = 1 << 24, // do not search weak signature whitelist 105}; 106 107 108/*! 109 @function SecAssessmentCreate 110 Ask the system for its assessment of a proposed operation. 111 112 @param path CFURL describing the file central to the operation - the program 113 to be executed, archive to be installed, plugin to be loaded, etc. 114 @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default 115 behavior. 116 @param context Optional CFDictionaryRef containing additional information bearing 117 on the requested assessment. 118 @param errors Standard CFError argument for reporting errors. Note that declining to permit 119 the proposed operation is not an error. Inability to arrive at a judgment is. 120 @result On success, a SecAssessment object that can be queried for its outcome. 121 On error, NULL (with *errors set). 122 123 Option flags: 124 125 @constant kSecAssessmentFlagRequestOrigin Request additional work to produce information on 126 the originator (signer) of the object being discussed. 127 128 Context keys: 129 130 @constant kSecAssessmentContextKeyOperation Type of operation (see overview above). This defaults 131 to the kSecAssessmentOperationTypeExecute. 132 */ 133extern CFStringRef kSecAssessmentContextKeyFeedback; // feedback reporting block 134typedef Boolean (^SecAssessmentFeedback)(CFStringRef type, CFDictionaryRef information); 135extern CFStringRef kSecAssessmentFeedbackProgress; // progress reporting feedback 136extern CFStringRef kSecAssessmentFeedbackInfoCurrent; // info key: current work progress 137extern CFStringRef kSecAssessmentFeedbackInfoTotal; // info key: total expected work 138 139extern CFStringRef kSecAssessmentAssessmentVerdict; // CFBooleanRef: master result - allow or deny 140extern CFStringRef kSecAssessmentAssessmentOriginator; // CFStringRef: describing the signature originator 141extern CFStringRef kSecAssessmentAssessmentAuthority; // CFDictionaryRef: authority used to arrive at result 142extern CFStringRef kSecAssessmentAssessmentSource; // CFStringRef: primary source of authority 143extern CFStringRef kSecAssessmentAssessmentFromCache; // present if result is from cache 144extern CFStringRef kSecAssessmentAssessmentWeakSignature; // present if result attributable to signature weakness 145extern CFStringRef kSecAssessmentAssessmentCodeSigningError; // error code returned by code signing API 146extern CFStringRef kSecAssessmentAssessmentAuthorityRow; // (internal) 147extern CFStringRef kSecAssessmentAssessmentAuthorityOverride; // (internal) 148extern CFStringRef kSecAssessmentAssessmentAuthorityOriginalVerdict; // (internal) 149 150extern CFStringRef kDisabledOverride; // AuthorityOverride value for "Gatekeeper is disabled" 151 152enum { 153 kSecAssessmentFlagRequestOrigin = 1 << 0, // request origin information (slower) 154}; 155 156SecAssessmentRef SecAssessmentCreate(CFURLRef path, 157 SecAssessmentFlags flags, 158 CFDictionaryRef context, 159 CFErrorRef *errors); 160 161 162/*! 163 @function SecAssessmentCopyResult 164 165 Extract results from a completed assessment and return them as a CFDictionary. 166 167 @param assessment A SecAssessmentRef created with SecAssessmentCreate. 168 @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default 169 behavior. 170 @errors Standard CFError argument for reporting errors. Note that declining to permit 171 the proposed operation is not an error. Inability to form a judgment is. 172 @result On success, a CFDictionary describing the outcome and various corroborating 173 data as requested by flags. The caller owns this dictionary and should release it 174 when done with it. On error, NULL (with *errors set). 175 176 Assessment result keys (dictionary keys returned on success): 177 178 @constant kSecAssessmentAssessmentVerdict A CFBoolean value indicating whether the system policy 179 allows (kCFBooleanTrue) or denies (kCFBooleanFalse) the proposed operation. 180 @constant kSecAssessmentAssessmentAuthority A CFDictionary describing what sources of authority 181 were used to arrive at this result. 182 @constant kSecAssessmentAssessmentOriginator A human-readable CFString describing the originator 183 of the signature securing the subject of the verdict. Requires kSecAssessmentFlagRequireOrigin. 184 May be missing anyway if no reliable source of origin can be determined. 185 */ 186CFDictionaryRef SecAssessmentCopyResult(SecAssessmentRef assessment, 187 SecAssessmentFlags flags, 188 CFErrorRef *errors); 189 190 191/*! 192 @function SecAssessmentCopyUpdate 193 Make changes to the system policy configuration. 194 195 @param path CFTypeRef describing the subject of the operation. Depending on the operation, 196 this may be a CFURL denoting a (single) file or bundle; a SecRequirement describing 197 a group of files; a CFNumber denoting an existing rule by rule number, or NULL to perform 198 global changes. 199 @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default 200 behavior. 201 @param context Required CFDictionaryRef containing information bearing 202 on the requested assessment. Must at least contain the kSecAssessmentContextKeyEdit key. 203 @param errors Standard CFError argument for reporting errors. Note that declining to permit 204 the proposed operation is not an error. Inability to form a judgment is. 205 @result Returns On success, a CFDictionary containing information pertaining to the completed operation. 206 Caller must CFRelease it when done. On failure, NULL, with *errors set if provided. 207 208 Note: The SecAssessmentUpdate variant does not return data. It returns True on success, or False on error. 209 210 Context keys and values: 211 212 @constant kSecAssessmentContextKeyEdit Required context key describing the kind of change 213 requested to the system policy configuration. Currently understood values: 214 @constant kSecAssessmentUpdateOperationAdd Add a new rule to the assessment rule database. 215 @constant kSecAssessmentUpdateOperationRemove Remove rules from the rule database. 216 @constant kSecAssessmentUpdateOperationEnable (Re)enable rules in the rule database. 217 @constant kSecAssessmentUpdateOperationDisable Disable rules in the rule database. 218 @constant kSecAssessmentUpdateOperationFind Locate and return rules from the rule database. 219 This operation does not change the database, and does not require authorization or privileges. 220 221 @constant kSecAssessmentUpdateKeyAuthorization A CFData containing the external form of a 222 system AuthorizationRef used to authorize the change. The call will automatically generate 223 a suitable authorization if this is missing; however, if the request is on behalf of 224 another client, an AuthorizationRef should be created there and passed along here. 225 @constant kSecAssessmentUpdateKeyPriority CFNumber denoting a (floating point) priority 226 for the rule(s) being processed. 227 @constant kSecAssessmentUpdateKeyLabel CFString denoting a label string applied to the rule(s) 228 being processed. 229 @constant kSecAssessmentUpdateKeyExpires CFDate denoting an (absolute, future) expiration date 230 for rule(s) being processed. 231 @constant kSecAssessmentUpdateKeyAllow CFBoolean denoting whether a new rule allows or denies 232 assessment. The default is to allow; set to kCFBooleanFalse to create a negative (denial) rule. 233 @constant kSecAssessmentUpdateKeyRemarks CFString containing a colloquial description or comment 234 about a newly created rule. This is mean to be human readable and is not used when evaluating rules. 235 236 Keys returned as the result of a successful kSecAssessmentUpdateOperationFind operation: 237 238 @constant kSecAssessmentRuleKeyID A CFNumber uniquely identifying a rule. 239 @constant kSecAssessmentRuleKeyPriority A CFNumber indicating the rule's priority. 240 This is a floating point number. Higher values indicate higher priority. 241 @constant kSecAssessmentRuleKeyAllow A CFBoolean indicating whether the rule allows (true) or denies (false) the operation. 242 @constant kSecAssessmentRuleKeyLabel An optional CFString labeling the rule. Multiple rules may have the same label; 243 this can be used to group rules. Labels are not presented to the user. The label has no effect on evaluation. 244 @constant kSecAssessmentRuleKeyRemarks An optional CFString containing user-readable text characterizing the rule's meaning. 245 The remark has no effect on the evaluation. 246 @constant kSecAssessmentRuleKeyRequirement A CFString containing the (text form of) the code requirement governing the rule's match. 247 @constant kSecAssessmentRuleKeyType A CFString denoting the type of operation governed by the rule. 248 One of the kSecAssessmentOperationType* constants. 249 @constant kSecAssessmentRuleKeyExpires A CFDate indicating when the rule expires. Absent if the rule does not expire. Expired rules are never returned. 250 @constant kSecAssessmentRuleKeyDisabled A CFNumber; non zero if temporarily disabled. Optional. 251 @constant kSecAssessmentRuleKeyBookmark A CFData with the bookmark to the rule. Optional. 252 */ 253extern CFStringRef kSecAssessmentContextKeyUpdate; // proposed operation 254extern CFStringRef kSecAssessmentUpdateOperationAdd; // add rule to policy database 255extern CFStringRef kSecAssessmentUpdateOperationRemove; // remove rule from policy database 256extern CFStringRef kSecAssessmentUpdateOperationEnable; // enable rule(s) in policy database 257extern CFStringRef kSecAssessmentUpdateOperationDisable; // disable rule(s) in policy database 258extern CFStringRef kSecAssessmentUpdateOperationFind; // extract rule(s) from the policy database 259 260extern CFStringRef kSecAssessmentUpdateKeyAuthorization; // [CFData] external form of governing authorization 261 262extern CFStringRef kSecAssessmentUpdateKeyPriority; // rule priority 263extern CFStringRef kSecAssessmentUpdateKeyLabel; // rule label 264extern CFStringRef kSecAssessmentUpdateKeyExpires; // rule expiration 265extern CFStringRef kSecAssessmentUpdateKeyAllow; // rule outcome (allow/deny) 266extern CFStringRef kSecAssessmentUpdateKeyRemarks; // rule remarks (human readable) 267 268extern CFStringRef kSecAssessmentUpdateKeyRow; // rule identifier (CFNumber; add only) 269extern CFStringRef kSecAssessmentUpdateKeyCount; // count of changed rules (CFNumber) 270extern CFStringRef kSecAssessmentUpdateKeyFound; // set of found rules (CFArray of CFDictionaries) 271 272extern CFStringRef kSecAssessmentRuleKeyID; // rule content returned: rule ID 273extern CFStringRef kSecAssessmentRuleKeyPriority; // rule content returned: rule priority (floating point) 274extern CFStringRef kSecAssessmentRuleKeyAllow; // rule content returned: rule allows (boolean) 275extern CFStringRef kSecAssessmentRuleKeyLabel; // rule content returned: rule label (string; optional) 276extern CFStringRef kSecAssessmentRuleKeyRemarks; // rule content returned: rule remarks (string; optional) 277extern CFStringRef kSecAssessmentRuleKeyRequirement; // rule content returned: rule code requirement (string) 278extern CFStringRef kSecAssessmentRuleKeyType; // rule content returned: rule type (string) 279extern CFStringRef kSecAssessmentRuleKeyExpires; // rule content returned: rule expiration (CFDate; optional) 280extern CFStringRef kSecAssessmentRuleKeyDisabled; // rule content returned: rule disabled (CFNumber; nonzero means temporarily disabled) 281extern CFStringRef kSecAssessmentRuleKeyBookmark; // rule content returned: bookmark data (CFBookmark; optional) 282 283CFDictionaryRef SecAssessmentCopyUpdate(CFTypeRef target, 284 SecAssessmentFlags flags, 285 CFDictionaryRef context, 286 CFErrorRef *errors); 287 288Boolean SecAssessmentUpdate(CFTypeRef target, 289 SecAssessmentFlags flags, 290 CFDictionaryRef context, 291 CFErrorRef *errors); 292 293 294/*! 295 @function SecAssessmentControl 296 Miscellaneous system policy operations. 297 298 @param control A CFString indicating which operation is requested. 299 @param arguments Arguments to the operation as documented for control. 300 @param errors Standard CFErrorRef * argument to report errors. 301 @result Returns True on success. Returns False on failure (and sets *errors). 302 */ 303Boolean SecAssessmentControl(CFStringRef control, void *arguments, CFErrorRef *errors); 304 305 306#ifdef __cplusplus 307} 308#endif 309 310#endif //_H_SECASSESSMENT 311