lib/SecAssessment.h

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