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  	kSecAssessmentTicketFlagLegacyListCheck = 1 << 1, // Check the DeveloperID Legacy list
325  };
326  Boolean SecAssessmentTicketRegister(CFDataRef ticketData, CFErrorRef *errors);
327  Boolean SecAssessmentRegisterPackageTicket(CFURLRef packageURL, CFErrorRef* errors) API_AVAILABLE(macos(10.14.6));
328  Boolean SecAssessmentTicketLookup(CFDataRef hash, SecCSDigestAlgorithm hashType, SecAssessmentTicketFlags flags, double *date, CFErrorRef *errors);
329  Boolean SecAssessmentLegacyCheck(CFDataRef hash, SecCSDigestAlgorithm hashType, CFStringRef teamID, CFErrorRef *errors);
330  
331  #ifdef __cplusplus
332  }
333  #endif
334  
335  #endif //_H_SECASSESSMENT