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  * Primary operation codes. These are operations the system policy can express
  47  * opinions on. They are not operations *on* the system configuration itself.
  48  * (For those, see SecAssessmentUpdate below.)
  49  *
  50  * @constant kSecAssessmentContextKeyOperation Context key describing the type of operation
  51  *      being contemplated.
  52  * @constant kSecAssessmentOperationTypeInstall Value denoting the operation of installing
  53  *      software into the system.
  54  * @constant kSecAssessmentOperationTypeExecute Value denoting the operation of running or executing
  55  *      code on the system.
  56  */
  57 extern const CFStringRef kSecAssessmentContextKeyOperation;     // proposed operation
  58 extern const CFStringRef kSecAssessmentOperationTypeExecute;    // .. execute code
  59 extern const CFStringRef kSecAssessmentOperationTypeInstall;    // .. install software
  60 extern const CFStringRef kSecAssessmentOperationTypeOpenDocument; // .. LaunchServices-level document open
  61
  62
  63 /*!
  64         Operational flags for SecAssessment calls
  65
  66         @type SecAssessmentFlags A mask of flag bits passed to SecAssessment calls to influence their
  67                 operation.
  68
  69         @constant kSecAssessmentDefaultFlags Pass this to indicate that default behavior is desired.
  70         @constant kSecAssessmentFlagIgnoreCache Do not use cached information; always perform a full
  71                 evaluation of system policy. This may be substantially slower.
  72         @constant kSecAssessmentFlagNoCache Do not save any evaluation outcome in the system caches.
  73                 Any content already there is left undisturbed. Independent of kSecAssessmentFlagIgnoreCache.
  74
  75         Flags common to multiple calls are assigned from high-bit down. Flags for particular calls
  76         are assigned low-bit up, and are documented with that call.
  77  */
  78 typedef uint64_t SecAssessmentFlags;
  79 enum {
  80         kSecAssessmentDefaultFlags = 0,                                 // default behavior
  81
  82         kSecAssessmentFlagDirect = 1 << 30,                             // in-process evaluation
  83         kSecAssessmentFlagAsynchronous = 1 << 29,               // request asynchronous operation
  84         kSecAssessmentFlagIgnoreCache = 1 << 28,                // do not search cache
  85         kSecAssessmentFlagNoCache = 1 << 27,                    // do not populate cache
  86         kSecAssessmentFlagEnforce = 1 << 26,                    // force on (disable bypass switches)
  87 };
  88
  89
  90 /*!
  91         @function SecAssessmentCreate
  92         Ask the system for its assessment of a proposed operation.
  93
  94         @param path CFURL describing the file central to the operation - the program
  95                 to be executed, archive to be installed, plugin to be loaded, etc.
  96         @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
  97                 behavior.
  98         @param context Optional CFDictionaryRef containing additional information bearing
  99                 on the requested assessment.
 100         @param errors Standard CFError argument for reporting errors. Note that declining to permit
 101                 the proposed operation is not an error. Inability to form a judgment is.
 102         @result On success, a SecAssessment object that can be queried for its outcome.
 103                 On error, NULL (with *errors set).
 104
 105         Option flags:
 106
 107         @constant kSecAssessmentFlagRequestOrigin Request additional work to produce information on
 108                 the originator (signer) of the object being discussed.
 109
 110         Context keys:
 111
 112         @constant kSecAssessmentContextKeyOperation Type of operation (see overview above). This defaults
 113                 to the kSecAssessmentOperationTypeExecute.
 114         @constant kSecAssessmentContextKeyEdit A CFArray of SecCertificateRefs describing the
 115                 certificate chain of a CMS-type signature as pulled from 'path' by the caller.
 116                 The first certificate is the signing certificate. The certificates provided must be
 117                 sufficient to construct a valid certificate chain.
 118  */
 119 extern const CFStringRef kSecAssessmentContextKeyCertificates; // certificate chain as provided by caller
 120
 121 extern const CFStringRef kSecAssessmentAssessmentVerdict;               // CFBooleanRef: master result - allow or deny
 122 extern const CFStringRef kSecAssessmentAssessmentOriginator;    // CFStringRef: describing the signature originator
 123 extern const CFStringRef kSecAssessmentAssessmentAuthority;     // CFDictionaryRef: authority used to arrive at result
 124 extern const CFStringRef kSecAssessmentAssessmentSource;                // CFStringRef: primary source of authority
 125 extern const CFStringRef kSecAssessmentAssessmentFromCache;     // present if result is from cache
 126 extern const CFStringRef kSecAssessmentAssessmentAuthorityRow; // (internal)
 127 extern const CFStringRef kSecAssessmentAssessmentAuthorityOverride; // (internal)
 128
 129 enum {
 130         kSecAssessmentFlagRequestOrigin = 1 << 0,               // request origin information (slower)
 131 };
 132
 133 SecAssessmentRef SecAssessmentCreate(CFURLRef path,
 134         SecAssessmentFlags flags,
 135         CFDictionaryRef context,
 136         CFErrorRef *errors);
 137
 138
 139 /*!
 140         @function SecAssessmentCopyResult
 141
 142         Extract results from a completed assessment and return them as a CFDictionary.
 143
 144         Assessment result keys (dictionary keys returned on success):
 145
 146         @param assessment A SecAssessmentRef created with SecAssessmentCreate.
 147         @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
 148                 behavior.
 149         @errors Standard CFError argument for reporting errors. Note that declining to permit
 150                 the proposed operation is not an error. Inability to form a judgment is.
 151         @result On success, a CFDictionary describing the outcome and various corroborating
 152                 data as requested by flags. The caller owns this dictionary and should release it
 153                 when done with it. On error, NULL (with *errors set).
 154
 155         @constant kSecAssessmentAssessmentVerdict A CFBoolean value indicating whether the system policy
 156                 allows (kCFBooleanTrue) or denies (kCFBooleanFalse) the proposed operation.
 157         @constant kSecAssessmentAssessmentAuthority A CFDictionary describing what sources of authority
 158                 were used to arrive at this result.
 159         @constant kSecAssessmentAssessmentOriginator A human-readable CFString describing the originator
 160                 of the signature securing the subject of the verdict. Requires kSecAssessmentFlagRequireOrigin.
 161                 May be missing anyway if no reliable source of origin can be determined.
 162  */
 163 CFDictionaryRef SecAssessmentCopyResult(SecAssessmentRef assessment,
 164         SecAssessmentFlags flags,
 165         CFErrorRef *errors);
 166
 167
 168 /*!
 169         @function SecAssessmentUpdate
 170         Make changes to the system policy configuration.
 171
 172         @param path CFURL describing the file central to an operation - the program
 173                 to be executed, archive to be installed, plugin to be loaded, etc.
 174                 Pass NULL if the requested operation has no file subject.
 175         @param flags Operation flags and options. Pass kSecAssessmentDefaultFlags for default
 176                 behavior.
 177         @param context Required CFDictionaryRef containing information bearing
 178                 on the requested assessment. Must at least contain the kSecAssessmentContextKeyEdit key.
 179         @param errors Standard CFError argument for reporting errors. Note that declining to permit
 180                 the proposed operation is not an error. Inability to form a judgment is.
 181         @result Returns True on success. Returns False on failure (and sets *error).
 182
 183         Context keys and values:
 184
 185         @constant kSecAssessmentContextKeyEdit Required context key describing the kind of change
 186                 requested to the system policy configuration. Currently understood values:
 187         @constant kSecAssessmentUpdateOperationAddFile Request to add rules governing operations on the 'path'
 188                 argument.
 189         @constant kSecAssessmentUpdateOperationRemoveFile Request to remove rules governing operations on the
 190                 'path' argument.
 191  */
 192 extern const CFStringRef kSecAssessmentContextKeyUpdate;                // proposed operation
 193 extern const CFStringRef kSecAssessmentUpdateOperationAddFile;  // add to policy database
 194 extern const CFStringRef kSecAssessmentUpdateOperationRemoveFile; // remove from policy database
 195
 196 extern const CFStringRef kSecAssessmentUpdateKeyPriority;               // rule priority
 197 extern const CFStringRef kSecAssessmentUpdateKeyLabel;                  // rule label
 198
 199 Boolean SecAssessmentUpdate(CFURLRef path,
 200         SecAssessmentFlags flags,
 201         CFDictionaryRef context,
 202         CFErrorRef *errors);
 203
 204
 205 /*!
 206         @function SecAssessmentControl
 207         Miscellaneous system policy operations
 208
 209  */
 210 Boolean SecAssessmentControl(CFStringRef control, void *arguments, CFErrorRef *errors);
 211
 212
 213 #ifdef __cplusplus
 214 }
 215 #endif
 216
 217 #endif //_H_SECASSESSMENT