1  /*
  2   * Copyright (c) 2006,2011-2012,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  
 24  /*!
 25  	@header SecStaticCode
 26  	SecStaticCodePriv is the private counter-part to SecStaticCode. Its contents are not
 27  	official API, and are subject to change without notice.
 28  */
 29  #ifndef _H_SECSTATICCODEPRIV
 30  #define _H_SECSTATICCODEPRIV
 31  
 32  #include <Security/SecStaticCode.h>
 33  
 34  #ifdef __cplusplus
 35  extern "C" {
 36  #endif
 37  
 38  /*
 39   Private SecStaticCodeCreate* SecCS flags.
 40   */
 41  CF_ENUM(uint32_t) {
 42  	kSecCSForceOnlineNotarizationCheck = 1 << 0,
 43  };
 44  
 45  
 46  /*
 47  	@function SecCodeSetCallback
 48  	For a given Code or StaticCode object, specify a block that is invoked at certain
 49  	stages of a validation operation. The block is only invoked for validations of this
 50  	particular object. Note that validation outcomes are cached in the API object, and
 51  	repeated validations will not generally result in the same set of callbacks.
 52  	Only one callback can be active for each API object. A new call to SecCodeSetCallback
 53  	replaces the previous callback.
 54  	
 55  	@param code A Code or StaticCode object whose validation should be monitored.
 56  	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 57  	@param old A pointer to a block pointer that receives any previously registered callback.
 58  		Pass NULL if you are not interested in any previous value.
 59  	@param callback A block to be synchronously invoked at certain stages of API operation.
 60  		Pass NULL to disable callbacks for this code object. The block must be available to
 61  		be invoked, possibly repeatedly, for as long as the code object exists or it is superseded
 62  		by another call to this API, whichever happens earlier.
 63  		From your block, return NULL to continue normal operation. Return a CFTypeRef object of
 64  		suitable value for the reported stage to intervene.
 65   */
 66  OSStatus SecStaticCodeSetCallback(SecStaticCodeRef code, SecCSFlags flag, SecCodeCallback *olds, SecCodeCallback callback);
 67  
 68  	
 69  /*
 70   	@function SecStaticCodeSetValidationConditions
 71   	Set various parameters that modify the evaluation of a signature.
 72   	This is an internal affordance used by Gatekeeper to implement checkfix evaluation.
 73   	It is not meant to be a generally useful mechanism.
 74   
 75   	@param code A Code or StaticCode object whose validation should be modified.
 76   	@param conditions A dictionary containing one or more validation conditions. Must not be NULL.
 77   */
 78  OSStatus SecStaticCodeSetValidationConditions(SecStaticCodeRef code, CFDictionaryRef conditions);
 79  	
 80  	
 81  /*
 82  	@function SecStaticCodeCancelValidation
 83   	Ask for an ongoing static validation using this (static) code object to be canceled as soon as feasible.
 84   	if no validation is pending, this does nothing.
 85   	Since validation is synchronous, this call must be made from another thread.
 86   	This call will return immediately. If a validation operation is terminated due to it,
 87   	it will fail with the errSecCSVetoed error.
 88   
 89  	@param code A Code or StaticCode object whose validation should be modified.
 90  	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 91   */
 92  OSStatus SecStaticCodeCancelValidation(SecStaticCodeRef code, SecCSFlags flags);
 93  
 94  /*
 95   @function SecStaticCodeEnableOnlineNotarizationCheck
 96   Sets a flag on the object to allow an online notarization check once for the lifetime of the object during
 97   the next validation.
 98  
 99   @param code A StaticCode object whose validation should be modified.
100   @param enable Whether to enable or disable online notarization checks.
101   */
102  OSStatus SecStaticCodeEnableOnlineNotarizationCheck(SecStaticCodeRef code, Boolean enable) __SPI_AVAILABLE(macos(11.3));
103  
104  /*
105      @function SecStaticCodeValidateResource
106      For a SecStaticCodeRef, check that the resource at the provided path is part of the signature and unaltered.
107      This call will fail if the file is not in the bundle, missing from the bundle, optional, or signed
108      into the bundle in a way that it cannot be fully verified.
109  
110      @param code A SecStaticCode object for the outer bundle.
111      @param resourcePath A CFStringRef containing the absolute path to a sealed resource file.
112          This path will be checked and must be to something within the code object's base path.
113      @param flags Flags to use during validation, see SecStaticCodeCheckValidity
114      @param errors An optional pointer to a CFErrorRef variable. If the call fails
115          (something other than errSecSuccess is returned), and this argument is non-NULL,
116          a CFErrorRef is stored there further describing the nature and circumstances
117          of the failure. The caller must CFRelease() this error object when done with it.
118  
119      @result noErr if the file at resourcePath validates as a resource of the bundle represented by code. Can return a
120          variety of errors from CSCommon.h or other Security framework headers, but notable errors are:
121  
122          errSecParam if the resource is not within the code object.
123          errSecCSResourcesNotFound if the resources in the bundle could not be loaded.
124          errSecCSResourcesNotSealed if the requested resource was found but cannot be verified.
125          errSecCSBadResource if the resource couldn't be found or was altered.
126          errSecCSSignatureFailed if the executable resource was found and was altered.
127   */
128  OSStatus SecStaticCodeValidateResourceWithErrors(SecStaticCodeRef code, CFURLRef resourcePath, SecCSFlags flags, CFErrorRef *errors) __SPI_AVAILABLE(macos(11.3));
129  
130  #ifdef __cplusplus
131  }
132  #endif
133  
134  #endif //_H_SECSTATICCODEPRIV