SecAssessment.h   [plain text]


/*
 * Copyright (c) 2011 Apple Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * 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
 * http://www.opensource.apple.com/apsl/ 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
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
#ifndef _H_SECASSESSMENT
#define _H_SECASSESSMENT

#include <CoreFoundation/CoreFoundation.h>

#ifdef __cplusplus
extern "C" {
#endif


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


/*!
 * CF-standard type function
 */
CFTypeID SecAssessmentGetTypeID();


/*!
 * Primary operation codes. 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.
 * @constant kSecAssessmentOperationTypeInstall Value denoting the operation of installing
 *	software into the system.
 * @constant kSecAssessmentOperationTypeExecute Value denoting the operation of running or executing
 *	code on the system.
 */
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
		operation.
	
	@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.
	
	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
		behavior.
	@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 form 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.
	@constant kSecAssessmentContextKeyEdit A CFArray of SecCertificateRefs describing the
		certificate chain of a CMS-type signature as pulled from 'path' by the caller.
		The first certificate is the signing certificate. The certificates provided must be
		sufficient to construct a valid certificate chain.
 */
extern const CFStringRef kSecAssessmentContextKeyCertificates; // certificate chain as provided by caller

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)

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.

	Assessment result keys (dictionary keys returned on success):

	@param assessment A SecAssessmentRef created with SecAssessmentCreate.
	@param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
		behavior.
	@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).

	@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 SecAssessmentUpdate
	Make changes to the system policy configuration.
	
	@param path CFURL describing the file central to an operation - the program
		to be executed, archive to be installed, plugin to be loaded, etc.
		Pass NULL if the requested operation has no file subject.
	@param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
		behavior.
	@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 True on success. Returns False on failure (and sets *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 kSecAssessmentUpdateOperationAddFile Request to add rules governing operations on the 'path'
		argument.
	@constant kSecAssessmentUpdateOperationRemoveFile Request to remove rules governing operations on the
		'path' argument.
 */
extern const CFStringRef kSecAssessmentContextKeyUpdate;		// proposed operation
extern const CFStringRef kSecAssessmentUpdateOperationAddFile;	// add to policy database
extern const CFStringRef kSecAssessmentUpdateOperationRemoveFile; // remove from policy database

extern const CFStringRef kSecAssessmentUpdateKeyPriority;		// rule priority
extern const CFStringRef kSecAssessmentUpdateKeyLabel;			// rule label

Boolean SecAssessmentUpdate(CFURLRef path,
	SecAssessmentFlags flags,
	CFDictionaryRef context,
	CFErrorRef *errors);


/*!
	@function SecAssessmentControl
	Miscellaneous system policy operations
	
 */
Boolean SecAssessmentControl(CFStringRef control, void *arguments, CFErrorRef *errors);


#ifdef __cplusplus
}
#endif

#endif //_H_SECASSESSMENT