SecAssessment.h   [plain text]

 * Copyright (c) 2011 Apple Inc. All Rights Reserved.
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * and read it before using this
 * file.
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * Please see the License for the specific language governing rights and
 * limitations under the License.

#include <CoreFoundation/CoreFoundation.h>

#ifdef __cplusplus
extern "C" {

 * @type SecAccessmentRef An assessment being performed.
typedef struct _SecAssessment *SecAssessmentRef;

 * CF-standard type function
CFTypeID SecAssessmentGetTypeID();

 * Notifications sent when the policy authority database changes.
 * (Should move to /usr/include/notify_keys.h eventually.)
#define kNotifySecAssessmentMasterSwitch ""
#define kNotifySecAssessmentUpdate ""

 * Primary operation types. These are operations the system policy can express
 * opinions on. They are not operations *on* the system configuration itself.
 * (For those, see SecAssessmentUpdate below.)
 * @constant kSecAssessmentContextKeyOperation Context key describing the type of operation
 *	being contemplated. The default varies depending on the API call used.
 * @constant kSecAssessmentOperationTypeExecute Value denoting the operation of running or executing
 *	code on the system.
 * @constant kSecAssessmentOperationTypeInstall Value denoting the operation of installing
 *	software into the system.
 * @constant kSecAssessmentOperationTypeOpenDocument Value denoting the operation of opening
 *	(in the LaunchServices sense) of documents.
extern const CFStringRef kSecAssessmentContextKeyOperation;	// proposed operation
extern const CFStringRef kSecAssessmentOperationTypeExecute;	// .. execute code
extern const CFStringRef kSecAssessmentOperationTypeInstall;	// .. install software
extern const CFStringRef kSecAssessmentOperationTypeOpenDocument; // .. LaunchServices-level document open

	Operational flags for SecAssessment calls
	@type SecAssessmentFlags A mask of flag bits passed to SecAssessment calls to influence their
	@constant kSecAssessmentDefaultFlags Pass this to indicate that default behavior is desired.
	@constant kSecAssessmentFlagIgnoreCache Do not use cached information; always perform a full
		evaluation of system policy. This may be substantially slower.
	@constant kSecAssessmentFlagNoCache Do not save any evaluation outcome in the system caches.
		Any content already there is left undisturbed. Independent of kSecAssessmentFlagIgnoreCache.
	@constant kSecAssessmentFlagEnforce Perform normal operations even if assessments have been
		globally bypassed (which would usually approve anything).
	Flags common to multiple calls are assigned from high-bit down. Flags for particular calls
	are assigned low-bit up, and are documented with that call.
typedef uint64_t SecAssessmentFlags;
enum {
	kSecAssessmentDefaultFlags = 0,					// default behavior

	kSecAssessmentFlagDirect = 1 << 30,				// in-process evaluation
	kSecAssessmentFlagAsynchronous = 1 << 29,		// request asynchronous operation
	kSecAssessmentFlagIgnoreCache = 1 << 28,		// do not search cache
	kSecAssessmentFlagNoCache = 1 << 27,			// do not populate cache
	kSecAssessmentFlagEnforce = 1 << 26,			// force on (disable bypass switches)

	@function SecAssessmentCreate
	Ask the system for its assessment of a proposed operation.
	@param path CFURL describing the file central to the operation - the program
		to be executed, archive to be installed, plugin to be loaded, etc.
	@param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
	@param context Optional CFDictionaryRef containing additional information bearing
		on the requested assessment.
	@param errors Standard CFError argument for reporting errors. Note that declining to permit
		the proposed operation is not an error. Inability to arrive at a judgment is.
	@result On success, a SecAssessment object that can be queried for its outcome.
		On error, NULL (with *errors set).
	Option flags:
	@constant kSecAssessmentFlagRequestOrigin Request additional work to produce information on
		the originator (signer) of the object being discussed.

	Context keys:

	@constant kSecAssessmentContextKeyOperation Type of operation (see overview above). This defaults
		to the kSecAssessmentOperationTypeExecute.
extern const CFStringRef kSecAssessmentAssessmentVerdict;		// CFBooleanRef: master result - allow or deny
extern const CFStringRef kSecAssessmentAssessmentOriginator;	// CFStringRef: describing the signature originator
extern const CFStringRef kSecAssessmentAssessmentAuthority;	// CFDictionaryRef: authority used to arrive at result
extern const CFStringRef kSecAssessmentAssessmentSource;		// CFStringRef: primary source of authority
extern const CFStringRef kSecAssessmentAssessmentFromCache;	// present if result is from cache
extern const CFStringRef kSecAssessmentAssessmentAuthorityRow; // (internal)
extern const CFStringRef kSecAssessmentAssessmentAuthorityOverride; // (internal)

extern const CFStringRef kDisabledOverride;					// AuthorityOverride value for "Gatekeeper is disabled"

enum {
	kSecAssessmentFlagRequestOrigin = 1 << 0,		// request origin information (slower)

SecAssessmentRef SecAssessmentCreate(CFURLRef path,
	SecAssessmentFlags flags,
	CFDictionaryRef context,
	CFErrorRef *errors);

	@function SecAssessmentCopyResult

	Extract results from a completed assessment and return them as a CFDictionary.

	@param assessment A SecAssessmentRef created with SecAssessmentCreate.
	@param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
	@errors Standard CFError argument for reporting errors. Note that declining to permit
		the proposed operation is not an error. Inability to form a judgment is.
	@result On success, a CFDictionary describing the outcome and various corroborating
		data as requested by flags. The caller owns this dictionary and should release it
		when done with it. On error, NULL (with *errors set).

	Assessment result keys (dictionary keys returned on success):

	@constant kSecAssessmentAssessmentVerdict A CFBoolean value indicating whether the system policy
		allows (kCFBooleanTrue) or denies (kCFBooleanFalse) the proposed operation.
	@constant kSecAssessmentAssessmentAuthority A CFDictionary describing what sources of authority
		were used to arrive at this result.
	@constant kSecAssessmentAssessmentOriginator A human-readable CFString describing the originator
		of the signature securing the subject of the verdict. Requires kSecAssessmentFlagRequireOrigin.
		May be missing anyway if no reliable source of origin can be determined.
CFDictionaryRef SecAssessmentCopyResult(SecAssessmentRef assessment,
	SecAssessmentFlags flags,
	CFErrorRef *errors);

	@function SecAssessmentCopyUpdate
	Make changes to the system policy configuration.
	@param path CFTypeRef describing the subject of the operation. Depending on the operation,
		this may be a CFURL denoting a (single) file or bundle; a SecRequirement describing
		a group of files; a CFNumber denoting an existing rule by rule number, or NULL to perform
		global changes.
	@param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
	@param context Required CFDictionaryRef containing information bearing
		on the requested assessment. Must at least contain the kSecAssessmentContextKeyEdit key.
	@param errors Standard CFError argument for reporting errors. Note that declining to permit
		the proposed operation is not an error. Inability to form a judgment is.
	@result Returns On success, a CFDictionary containing information pertaining to the completed operation.
		Caller must CFRelease it when done. On failure, NULL, with *errors set if provided.
	Note: The SecAssessmentUpdate variant does not return data. It returns True on success, or False on error.
	Context keys and values:

	@constant kSecAssessmentContextKeyEdit Required context key describing the kind of change
		requested to the system policy configuration. Currently understood values:
	@constant kSecAssessmentUpdateOperationAdd Add a new rule to the assessment rule database.
	@constant kSecAssessmentUpdateOperationRemove Remove rules from the rule database.
	@constant kSecAssessmentUpdateOperationEnable (Re)enable rules in the rule database.
	@constant kSecAssessmentUpdateOperationDisable Disable rules in the rule database.
	@constant kSecAssessmentUpdateOperationFind Locate and return rules from the rule database.
		This operation does not change the database, and does not require authorization or privileges.
	@constant kSecAssessmentUpdateKeyAuthorization A CFData containing the external form of a
		system AuthorizationRef used to authorize the change. The call will automatically generate
		a suitable authorization if this is missing; however, if the request is on behalf of
		another client, an AuthorizationRef should be created there and passed along here.
	@constant kSecAssessmentUpdateKeyPriority CFNumber denoting a (floating point) priority
		for the rule(s) being processed.
	@constant kSecAssessmentUpdateKeyLabel CFString denoting a label string applied to the rule(s)
		being processed.
	@constant kSecAssessmentUpdateKeyExpires CFDate denoting an (absolute, future) expiration date
		for rule(s) being processed.
	@constant kSecAssessmentUpdateKeyAllow CFBoolean denoting whether a new rule allows or denies
		assessment. The default is to allow; set to kCFBooleanFalse to create a negative (denial) rule.
	@constant kSecAssessmentUpdateKeyRemarks CFString containing a colloquial description or comment
		about a newly created rule. This is mean to be human readable and is not used when evaluating rules.
	Keys returned as the result of a successful kSecAssessmentUpdateOperationFind operation:
	@constant kSecAssessmentRuleKeyID A CFNumber uniquely identifying a rule.
	@constant kSecAssessmentRuleKeyPriority A CFNumber indicating the rule's priority.
		This is a floating point number. Higher values indicate higher priority.
	@constant kSecAssessmentRuleKeyAllow A CFBoolean indicating whether the rule allows (true) or denies (false) the operation.
	@constant kSecAssessmentRuleKeyLabel An optional CFString labeling the rule. Multiple rules may have the same label;
		this can be used to group rules. Labels are not presented to the user. The label has no effect on evaluation.
	@constant kSecAssessmentRuleKeyRemarks An optional CFString containing user-readable text characterizing the rule's meaning.
		The remark has no effect on the evaluation.
	@constant kSecAssessmentRuleKeyRequirement A CFString containing the (text form of) the code requirement governing the rule's match.
	@constant kSecAssessmentRuleKeyType A CFString denoting the type of operation governed by the rule.
		One of the kSecAssessmentOperationType* constants.
	@constant kSecAssessmentRuleKeyExpires A CFDate indicating when the rule expires. Absent if the rule does not expire. Expired rules are never returned.
	@constant kSecAssessmentRuleKeyDisabled A CFNumber; non zero if temporarily disabled. Optional.
	@constant kSecAssessmentRuleKeyBookmark A CFData with the bookmark to the rule. Optional.
extern const CFStringRef kSecAssessmentContextKeyUpdate;		// proposed operation
extern const CFStringRef kSecAssessmentUpdateOperationAdd;		// add rule to policy database
extern const CFStringRef kSecAssessmentUpdateOperationRemove;	// remove rule from policy database
extern const CFStringRef kSecAssessmentUpdateOperationEnable;	// enable rule(s) in policy database
extern const CFStringRef kSecAssessmentUpdateOperationDisable;	// disable rule(s) in policy database
extern const CFStringRef kSecAssessmentUpdateOperationFind;	// extract rule(s) from the policy database

extern const CFStringRef kSecAssessmentContextKeyCertificates; // obsolete
extern const CFStringRef kSecAssessmentUpdateKeyAuthorization;	// [CFData] external form of governing authorization

extern const CFStringRef kSecAssessmentUpdateKeyPriority;		// rule priority
extern const CFStringRef kSecAssessmentUpdateKeyLabel;			// rule label
extern const CFStringRef kSecAssessmentUpdateKeyExpires;		// rule expiration
extern const CFStringRef kSecAssessmentUpdateKeyAllow;			// rule outcome (allow/deny)
extern const CFStringRef kSecAssessmentUpdateKeyRemarks;		// rule remarks (human readable)

extern const CFStringRef kSecAssessmentUpdateKeyRow;			// rule identifier (CFNumber; add only)
extern const CFStringRef kSecAssessmentUpdateKeyCount;			// count of changed rules (CFNumber)
extern const CFStringRef kSecAssessmentUpdateKeyFound;			// set of found rules (CFArray of CFDictionaries)

extern const CFStringRef kSecAssessmentRuleKeyID;				// rule content returned: rule ID
extern const CFStringRef kSecAssessmentRuleKeyPriority;			// rule content returned: rule priority (floating point)
extern const CFStringRef kSecAssessmentRuleKeyAllow;			// rule content returned: rule allows (boolean)
extern const CFStringRef kSecAssessmentRuleKeyLabel;			// rule content returned: rule label (string; optional)
extern const CFStringRef kSecAssessmentRuleKeyRemarks;			// rule content returned: rule remarks (string; optional)
extern const CFStringRef kSecAssessmentRuleKeyRequirement;		// rule content returned: rule code requirement (string)
extern const CFStringRef kSecAssessmentRuleKeyType;				// rule content returned: rule type (string)
extern const CFStringRef kSecAssessmentRuleKeyExpires;			// rule content returned: rule expiration (CFDate; optional)
extern const CFStringRef kSecAssessmentRuleKeyDisabled;			// rule content returned: rule disabled (CFNumber; nonzero means temporarily disabled)
extern const CFStringRef kSecAssessmentRuleKeyBookmark;			// rule content returned: bookmark data (CFBookmark; optional)
CFDictionaryRef SecAssessmentCopyUpdate(CFTypeRef target,
	SecAssessmentFlags flags,
	CFDictionaryRef context,
	CFErrorRef *errors);

Boolean SecAssessmentUpdate(CFTypeRef target,
	SecAssessmentFlags flags,
	CFDictionaryRef context,
	CFErrorRef *errors);

	@function SecAssessmentControl
	Miscellaneous system policy operations.
	@param control A CFString indicating which operation is requested.
	@param arguments Arguments to the operation as documented for control.
	@param errors Standard CFErrorRef * argument to report errors.
	@result Returns True on success. Returns False on failure (and sets *errors).
Boolean SecAssessmentControl(CFStringRef control, void *arguments, CFErrorRef *errors);

#ifdef __cplusplus