1/* 2 * Copyright (c) 2011 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 73extern CFStringRef kSecAssessmentContextQuarantineFlags; 74 75 76/*! 77 Operational flags for SecAssessment calls 78 79 @type SecAssessmentFlags A mask of flag bits passed to SecAssessment calls to influence their 80 operation. 81 82 @constant kSecAssessmentDefaultFlags Pass this to indicate that default behavior is desired. 83 @constant kSecAssessmentFlagIgnoreCache Do not use cached information; always perform a full 84 evaluation of system policy. This may be substantially slower. 85 @constant kSecAssessmentFlagNoCache Do not save any evaluation outcome in the system caches. 86 Any content already there is left undisturbed. Independent of kSecAssessmentFlagIgnoreCache. 87 @constant kSecAssessmentFlagEnforce Perform normal operations even if assessments have been 88 globally bypassed (which would usually approve anything). 89 @constant kSecAssessmentAllowWeak Allow signatures that contain known weaknesses, such as an 90 insecure resource envelope. 91 @constant kSecAssessmentIgnoreWhitelist Do not search the weak signature whitelist. 92 93 Flags common to multiple calls are assigned from high-bit down. Flags for particular calls 94 are assigned low-bit up, and are documented with that call. 95 */ 96typedef uint64_t SecAssessmentFlags; 97enum { 98 kSecAssessmentDefaultFlags = 0, // default behavior 99 100 kSecAssessmentFlagDirect = 1 << 30, // in-process evaluation 101 kSecAssessmentFlagAsynchronous = 1 << 29, // request asynchronous operation 102 kSecAssessmentFlagIgnoreCache = 1 << 28, // do not search cache 103 kSecAssessmentFlagNoCache = 1 << 27, // do not populate cache 104 kSecAssessmentFlagEnforce = 1 << 26, // force on (disable bypass switches) 105 kSecAssessmentFlagAllowWeak = 1 << 25, // allow weak signatures 106 kSecAssessmentFlagIgnoreWhitelist = 1 << 24, // do not search weak signature whitelist 107}; 108 109 110/*! 111 @function SecAssessmentCreate 112 Ask the system for its assessment of a proposed operation. 113 114 @param path CFURL describing the file central to the operation - the program 115 to be executed, archive to be installed, plugin to be loaded, etc. 116 @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default 117 behavior. 118 @param context Optional CFDictionaryRef containing additional information bearing 119 on the requested assessment. 120 @param errors Standard CFError argument for reporting errors. Note that declining to permit 121 the proposed operation is not an error. Inability to arrive at a judgment is. 122 @result On success, a SecAssessment object that can be queried for its outcome. 123 On error, NULL (with *errors set). 124 125 Option flags: 126 127 @constant kSecAssessmentFlagRequestOrigin Request additional work to produce information on 128 the originator (signer) of the object being discussed. 129 130 Context keys: 131 132 @constant kSecAssessmentContextKeyOperation Type of operation (see overview above). This defaults 133 to the kSecAssessmentOperationTypeExecute. 134 */ 135extern CFStringRef kSecAssessmentAssessmentVerdict; // CFBooleanRef: master result - allow or deny 136extern CFStringRef kSecAssessmentAssessmentOriginator; // CFStringRef: describing the signature originator 137extern CFStringRef kSecAssessmentAssessmentAuthority; // CFDictionaryRef: authority used to arrive at result 138extern CFStringRef kSecAssessmentAssessmentSource; // CFStringRef: primary source of authority 139extern CFStringRef kSecAssessmentAssessmentFromCache; // present if result is from cache 140extern CFStringRef kSecAssessmentAssessmentWeakSignature; // present if result attributable to signature weakness 141extern CFStringRef kSecAssessmentAssessmentCodeSigningError; // error code returned by code signing API 142extern CFStringRef kSecAssessmentAssessmentAuthorityRow; // (internal) 143extern CFStringRef kSecAssessmentAssessmentAuthorityOverride; // (internal) 144extern CFStringRef kSecAssessmentAssessmentAuthorityOriginalVerdict; // (internal) 145 146extern CFStringRef kDisabledOverride; // AuthorityOverride value for "Gatekeeper is disabled" 147 148enum { 149 kSecAssessmentFlagRequestOrigin = 1 << 0, // request origin information (slower) 150}; 151 152SecAssessmentRef SecAssessmentCreate(CFURLRef path, 153 SecAssessmentFlags flags, 154 CFDictionaryRef context, 155 CFErrorRef *errors); 156 157 158/*! 159 @function SecAssessmentCopyResult 160 161 Extract results from a completed assessment and return them as a CFDictionary. 162 163 @param assessment A SecAssessmentRef created with SecAssessmentCreate. 164 @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default 165 behavior. 166 @errors Standard CFError argument for reporting errors. Note that declining to permit 167 the proposed operation is not an error. Inability to form a judgment is. 168 @result On success, a CFDictionary describing the outcome and various corroborating 169 data as requested by flags. The caller owns this dictionary and should release it 170 when done with it. On error, NULL (with *errors set). 171 172 Assessment result keys (dictionary keys returned on success): 173 174 @constant kSecAssessmentAssessmentVerdict A CFBoolean value indicating whether the system policy 175 allows (kCFBooleanTrue) or denies (kCFBooleanFalse) the proposed operation. 176 @constant kSecAssessmentAssessmentAuthority A CFDictionary describing what sources of authority 177 were used to arrive at this result. 178 @constant kSecAssessmentAssessmentOriginator A human-readable CFString describing the originator 179 of the signature securing the subject of the verdict. Requires kSecAssessmentFlagRequireOrigin. 180 May be missing anyway if no reliable source of origin can be determined. 181 */ 182CFDictionaryRef SecAssessmentCopyResult(SecAssessmentRef assessment, 183 SecAssessmentFlags flags, 184 CFErrorRef *errors); 185 186 187/*! 188 @function SecAssessmentCopyUpdate 189 Make changes to the system policy configuration. 190 191 @param path CFTypeRef describing the subject of the operation. Depending on the operation, 192 this may be a CFURL denoting a (single) file or bundle; a SecRequirement describing 193 a group of files; a CFNumber denoting an existing rule by rule number, or NULL to perform 194 global changes. 195 @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default 196 behavior. 197 @param context Required CFDictionaryRef containing information bearing 198 on the requested assessment. Must at least contain the kSecAssessmentContextKeyEdit key. 199 @param errors Standard CFError argument for reporting errors. Note that declining to permit 200 the proposed operation is not an error. Inability to form a judgment is. 201 @result Returns On success, a CFDictionary containing information pertaining to the completed operation. 202 Caller must CFRelease it when done. On failure, NULL, with *errors set if provided. 203 204 Note: The SecAssessmentUpdate variant does not return data. It returns True on success, or False on error. 205 206 Context keys and values: 207 208 @constant kSecAssessmentContextKeyEdit Required context key describing the kind of change 209 requested to the system policy configuration. Currently understood values: 210 @constant kSecAssessmentUpdateOperationAdd Add a new rule to the assessment rule database. 211 @constant kSecAssessmentUpdateOperationRemove Remove rules from the rule database. 212 @constant kSecAssessmentUpdateOperationEnable (Re)enable rules in the rule database. 213 @constant kSecAssessmentUpdateOperationDisable Disable rules in the rule database. 214 @constant kSecAssessmentUpdateOperationFind Locate and return rules from the rule database. 215 This operation does not change the database, and does not require authorization or privileges. 216 217 @constant kSecAssessmentUpdateKeyAuthorization A CFData containing the external form of a 218 system AuthorizationRef used to authorize the change. The call will automatically generate 219 a suitable authorization if this is missing; however, if the request is on behalf of 220 another client, an AuthorizationRef should be created there and passed along here. 221 @constant kSecAssessmentUpdateKeyPriority CFNumber denoting a (floating point) priority 222 for the rule(s) being processed. 223 @constant kSecAssessmentUpdateKeyLabel CFString denoting a label string applied to the rule(s) 224 being processed. 225 @constant kSecAssessmentUpdateKeyExpires CFDate denoting an (absolute, future) expiration date 226 for rule(s) being processed. 227 @constant kSecAssessmentUpdateKeyAllow CFBoolean denoting whether a new rule allows or denies 228 assessment. The default is to allow; set to kCFBooleanFalse to create a negative (denial) rule. 229 @constant kSecAssessmentUpdateKeyRemarks CFString containing a colloquial description or comment 230 about a newly created rule. This is mean to be human readable and is not used when evaluating rules. 231 232 Keys returned as the result of a successful kSecAssessmentUpdateOperationFind operation: 233 234 @constant kSecAssessmentRuleKeyID A CFNumber uniquely identifying a rule. 235 @constant kSecAssessmentRuleKeyPriority A CFNumber indicating the rule's priority. 236 This is a floating point number. Higher values indicate higher priority. 237 @constant kSecAssessmentRuleKeyAllow A CFBoolean indicating whether the rule allows (true) or denies (false) the operation. 238 @constant kSecAssessmentRuleKeyLabel An optional CFString labeling the rule. Multiple rules may have the same label; 239 this can be used to group rules. Labels are not presented to the user. The label has no effect on evaluation. 240 @constant kSecAssessmentRuleKeyRemarks An optional CFString containing user-readable text characterizing the rule's meaning. 241 The remark has no effect on the evaluation. 242 @constant kSecAssessmentRuleKeyRequirement A CFString containing the (text form of) the code requirement governing the rule's match. 243 @constant kSecAssessmentRuleKeyType A CFString denoting the type of operation governed by the rule. 244 One of the kSecAssessmentOperationType* constants. 245 @constant kSecAssessmentRuleKeyExpires A CFDate indicating when the rule expires. Absent if the rule does not expire. Expired rules are never returned. 246 @constant kSecAssessmentRuleKeyDisabled A CFNumber; non zero if temporarily disabled. Optional. 247 @constant kSecAssessmentRuleKeyBookmark A CFData with the bookmark to the rule. Optional. 248 */ 249extern CFStringRef kSecAssessmentContextKeyUpdate; // proposed operation 250extern CFStringRef kSecAssessmentUpdateOperationAdd; // add rule to policy database 251extern CFStringRef kSecAssessmentUpdateOperationRemove; // remove rule from policy database 252extern CFStringRef kSecAssessmentUpdateOperationEnable; // enable rule(s) in policy database 253extern CFStringRef kSecAssessmentUpdateOperationDisable; // disable rule(s) in policy database 254extern CFStringRef kSecAssessmentUpdateOperationFind; // extract rule(s) from the policy database 255 256extern CFStringRef kSecAssessmentUpdateKeyAuthorization; // [CFData] external form of governing authorization 257 258extern CFStringRef kSecAssessmentUpdateKeyPriority; // rule priority 259extern CFStringRef kSecAssessmentUpdateKeyLabel; // rule label 260extern CFStringRef kSecAssessmentUpdateKeyExpires; // rule expiration 261extern CFStringRef kSecAssessmentUpdateKeyAllow; // rule outcome (allow/deny) 262extern CFStringRef kSecAssessmentUpdateKeyRemarks; // rule remarks (human readable) 263 264extern CFStringRef kSecAssessmentUpdateKeyRow; // rule identifier (CFNumber; add only) 265extern CFStringRef kSecAssessmentUpdateKeyCount; // count of changed rules (CFNumber) 266extern CFStringRef kSecAssessmentUpdateKeyFound; // set of found rules (CFArray of CFDictionaries) 267 268extern CFStringRef kSecAssessmentRuleKeyID; // rule content returned: rule ID 269extern CFStringRef kSecAssessmentRuleKeyPriority; // rule content returned: rule priority (floating point) 270extern CFStringRef kSecAssessmentRuleKeyAllow; // rule content returned: rule allows (boolean) 271extern CFStringRef kSecAssessmentRuleKeyLabel; // rule content returned: rule label (string; optional) 272extern CFStringRef kSecAssessmentRuleKeyRemarks; // rule content returned: rule remarks (string; optional) 273extern CFStringRef kSecAssessmentRuleKeyRequirement; // rule content returned: rule code requirement (string) 274extern CFStringRef kSecAssessmentRuleKeyType; // rule content returned: rule type (string) 275extern CFStringRef kSecAssessmentRuleKeyExpires; // rule content returned: rule expiration (CFDate; optional) 276extern CFStringRef kSecAssessmentRuleKeyDisabled; // rule content returned: rule disabled (CFNumber; nonzero means temporarily disabled) 277extern CFStringRef kSecAssessmentRuleKeyBookmark; // rule content returned: bookmark data (CFBookmark; optional) 278 279CFDictionaryRef SecAssessmentCopyUpdate(CFTypeRef target, 280 SecAssessmentFlags flags, 281 CFDictionaryRef context, 282 CFErrorRef *errors); 283 284Boolean SecAssessmentUpdate(CFTypeRef target, 285 SecAssessmentFlags flags, 286 CFDictionaryRef context, 287 CFErrorRef *errors); 288 289 290/*! 291 @function SecAssessmentControl 292 Miscellaneous system policy operations. 293 294 @param control A CFString indicating which operation is requested. 295 @param arguments Arguments to the operation as documented for control. 296 @param errors Standard CFErrorRef * argument to report errors. 297 @result Returns True on success. Returns False on failure (and sets *errors). 298 */ 299Boolean SecAssessmentControl(CFStringRef control, void *arguments, CFErrorRef *errors); 300 301 302#ifdef __cplusplus 303} 304#endif 305 306#endif //_H_SECASSESSMENT 307