1/* 2 * Copyright (c) 2006 Apple Computer, 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 SecStaticCode represents the Code Signing identity of code in the file system. 27 This includes applications, tools, frameworks, plugins, scripts, and so on. 28 Note that arbitrary files will be considered scripts of unknown provenance; 29 and thus it is possible to handle most files as if they were code, though that is 30 not necessarily a good idea. 31 32 Normally, each SecCode has a specific SecStaticCode that holds its static signing 33 data. Informally, that is the SecStaticCode the SecCode "was made from" (by its host). 34 There is however no viable link in the other direction - given a SecStaticCode, 35 it is not possible to find, enumerate, or control any SecCode that originated from it. 36 There might not be any at a given point in time; or there might be many. 37*/ 38#ifndef _H_SECSTATICCODE 39#define _H_SECSTATICCODE 40 41#include <Security/CSCommon.h> 42 43#ifdef __cplusplus 44extern "C" { 45#endif 46 47 48/*! 49 @function SecStaticCodeGetTypeID 50 Returns the type identifier of all SecStaticCode instances. 51*/ 52CFTypeID SecStaticCodeGetTypeID(void); 53 54 55/*! 56 @function SecStaticCodeCreateWithPath 57 Given a path to a file system object, create a SecStaticCode object representing 58 the code at that location, if possible. Such a SecStaticCode is not inherently 59 linked to running code in the system. 60 61 It is possible to create a SecStaticCode object from an unsigned code object. 62 Most uses of such an object will return the errSecCSUnsigned error. However, 63 SecCodeCopyPath and SecCodeCopySigningInformation can be safely applied to such objects. 64 65 @param path A path to a location in the file system. Only file:// URLs are 66 currently supported. For bundles, pass a URL to the root directory of the 67 bundle. For single files, pass a URL to the file. If you pass a URL to the 68 main executable of a bundle, the bundle as a whole will be generally recognized. 69 Caution: Paths containing embedded // or /../ within a bundle's directory 70 may cause the bundle to be misconstrued. If you expect to submit such paths, 71 first clean them with realpath(3) or equivalent. 72 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 73 @param attributes A CFDictionary containing additional attributes of the code sought. 74 @param staticCode On successful return, contains a reference to the StaticCode object 75 representing the code at path. Unchanged on error. 76 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in 77 CSCommon.h or certain other Security framework headers. 78 79 @constant kSecCodeAttributeArchitecture Specifies the Mach-O architecture of code desired. 80 This can be a CFString containing a canonical architecture name ("i386" etc.), or a CFNumber 81 specifying an architecture numerically (see mach/machine.h). This key is ignored if the code 82 is not in Mach-O binary form. If the code is Mach-O but not universal ("thin"), the architecture 83 specified must agree with the actual file contents. 84 @constant kSecCodeAttributeSubarchitecture If the architecture is specified numerically 85 (using the kSecCodeAttributeArchitecture key), specifies any sub-architecture by number. 86 This key is ignored if no main architecture is specified; if it is specified by name; or 87 if the code is not in Mach-O form. 88 @constant kSecCodeAttributeUniversalFileOffset The offset of a Mach-O specific slice of a universal Mach-O file. 89*/ 90extern const CFStringRef kSecCodeAttributeArchitecture; 91extern const CFStringRef kSecCodeAttributeSubarchitecture; 92extern const CFStringRef kSecCodeAttributeUniversalFileOffset; 93extern const CFStringRef kSecCodeAttributeBundleVersion; 94 95OSStatus SecStaticCodeCreateWithPath(CFURLRef path, SecCSFlags flags, SecStaticCodeRef *staticCode); 96 97OSStatus SecStaticCodeCreateWithPathAndAttributes(CFURLRef path, SecCSFlags flags, CFDictionaryRef attributes, 98 SecStaticCodeRef *staticCode); 99 100 101/*! 102 @function SecStaticCodeCheckValidity 103 Performs static validation on the given SecStaticCode object. The call obtains and 104 verifies the signature on the code object. It checks the validity of all 105 sealed components (including resources, if any). It validates the code against 106 a SecRequirement if one is given. The call succeeds if all these conditions 107 are satisfactory. It fails otherwise. 108 109 This call is only secure if the code is not subject to concurrent modification, 110 and the outcome is only valid as long as the code is unmodified thereafter. 111 Consider this carefully if the underlying file system has dynamic characteristics, 112 such as a network file system, union mount, FUSE, etc. 113 114 @param staticCode The code object to be validated. 115 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 116 117 @constant kSecCSCheckAllArchitectures 118 For multi-architecture (universal) Mach-O programs, validate all architectures 119 included. By default, only the native architecture is validated. 120 @constant kSecCSNoDnotValidateExecutable 121 Do not validate the contents of the main executable. This is normally done. 122 @constant kSecCSNoNotValidateResources 123 Do not validate the presence and contents of all bundle resources (if any). 124 By default, a mismatch in any bundle resource causes validation to fail. 125 @constant kSecCSCheckNestedCode 126 For code in bundle form, locate and recursively check embedded code. Only code 127 in standard locations is considered. 128 @constant kSecCSStrictValidate 129 For code in bundle form, perform additional checks to verify that the bundle 130 is not structured in a way that would allow tampering, and reject any resource 131 envelope that introduces weaknesses into the signature. 132 133 @param requirement On optional code requirement specifying additional conditions 134 the staticCode object must satisfy to be considered valid. If NULL, no additional 135 requirements are imposed. 136 @param errors An optional pointer to a CFErrorRef variable. If the call fails 137 (something other than errSecSuccess is returned), and this argument is non-NULL, 138 a CFErrorRef is stored there further describing the nature and circumstances 139 of the failure. The caller must CFRelease() this error object when done with it. 140 @result If validation succeeds, errSecSuccess. If validation fails, an OSStatus value 141 documented in CSCommon.h or certain other Security framework headers. 142*/ 143enum { 144 kSecCSCheckAllArchitectures = 1 << 0, 145 kSecCSDoNotValidateExecutable = 1 << 1, 146 kSecCSDoNotValidateResources = 1 << 2, 147 kSecCSBasicValidateOnly = kSecCSDoNotValidateExecutable | kSecCSDoNotValidateResources, 148 kSecCSCheckNestedCode = 1 << 3, 149 kSecCSStrictValidate = 1 << 4, 150}; 151 152OSStatus SecStaticCodeCheckValidity(SecStaticCodeRef staticCode, SecCSFlags flags, 153 SecRequirementRef requirement); 154 155OSStatus SecStaticCodeCheckValidityWithErrors(SecStaticCodeRef staticCode, SecCSFlags flags, 156 SecRequirementRef requirement, CFErrorRef *errors); 157 158 159#ifdef __cplusplus 160} 161#endif 162 163#endif //_H_SECSTATICCODE 164