OSX/libsecurity_codesigning/lib/SecAssessment.h

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