1  /*
  2   * Copyright (c) 2006,2011-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  	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  #ifdef DARLING
 43  #include <CoreFoundation/CoreFoundation.h>
 44  #endif
 45  
 46  #ifdef __cplusplus
 47  extern "C" {
 48  #endif
 49  
 50  CF_ASSUME_NONNULL_BEGIN
 51  
 52  /*!
 53  	@function SecStaticCodeGetTypeID
 54  	Returns the type identifier of all SecStaticCode instances.
 55  */
 56  CFTypeID SecStaticCodeGetTypeID(void);
 57  
 58  
 59  /*!
 60  	@function SecStaticCodeCreateWithPath
 61  	Given a path to a file system object, create a SecStaticCode object representing
 62  	the code at that location, if possible. Such a SecStaticCode is not inherently
 63  	linked to running code in the system.
 64  	
 65  	It is possible to create a SecStaticCode object from an unsigned code object.
 66  	Most uses of such an object will return the errSecCSUnsigned error. However,
 67  	SecCodeCopyPath and SecCodeCopySigningInformation can be safely applied to such objects.
 68  
 69  	@param path A path to a location in the file system. Only file:// URLs are
 70  	currently supported. For bundles, pass a URL to the root directory of the
 71  	bundle. For single files, pass a URL to the file. If you pass a URL to the
 72  	main executable of a bundle, the bundle as a whole will be generally recognized.
 73  	Caution: Paths containing embedded // or /../ within a bundle's directory
 74  	may cause the bundle to be misconstrued. If you expect to submit such paths,
 75  	first clean them with realpath(3) or equivalent.
 76  	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 77  	@param staticCode On successful return, contains a reference to the StaticCode object
 78  	representing the code at path. Unchanged on error.
 79  	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 80  	CSCommon.h or certain other Security framework headers.
 81  */
 82  OSStatus SecStaticCodeCreateWithPath(CFURLRef path, SecCSFlags flags, SecStaticCodeRef * __nonnull CF_RETURNS_RETAINED staticCode);
 83  
 84  extern const CFStringRef kSecCodeAttributeArchitecture;
 85  extern const CFStringRef kSecCodeAttributeSubarchitecture;
 86  extern const CFStringRef kSecCodeAttributeUniversalFileOffset;
 87  extern const CFStringRef kSecCodeAttributeBundleVersion;
 88  
 89  /*!
 90  	@function SecStaticCodeCreateWithPathAndAttributes
 91  	Given a path to a file system object, create a SecStaticCode object representing
 92  	the code at that location, if possible. Such a SecStaticCode is not inherently
 93  	linked to running code in the system.
 94  	
 95  	It is possible to create a SecStaticCode object from an unsigned code object.
 96  	Most uses of such an object will return the errSecCSUnsigned error. However,
 97  	SecCodeCopyPath and SecCodeCopySigningInformation can be safely applied to such objects.
 98  
 99  	@param path A path to a location in the file system. Only file:// URLs are
100  	currently supported. For bundles, pass a URL to the root directory of the
101  	bundle. For single files, pass a URL to the file. If you pass a URL to the
102  	main executable of a bundle, the bundle as a whole will be generally recognized.
103  	Caution: Paths containing embedded // or /../ within a bundle's directory
104  	may cause the bundle to be misconstrued. If you expect to submit such paths,
105  	first clean them with realpath(3) or equivalent.
106  	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
107  	@param attributes A CFDictionary containing additional attributes of the code sought.
108  	@param staticCode On successful return, contains a reference to the StaticCode object
109  	representing the code at path. Unchanged on error.
110  	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
111  	CSCommon.h or certain other Security framework headers.
112  
113  	@constant kSecCodeAttributeArchitecture Specifies the Mach-O architecture of code desired.
114  	This can be a CFString containing a canonical architecture name ("i386" etc.), or a CFNumber
115  	specifying an architecture numerically (see mach/machine.h). This key is ignored if the code
116  	is not in Mach-O binary form. If the code is Mach-O but not universal ("thin"), the architecture
117  	specified must agree with the actual file contents.
118  	@constant kSecCodeAttributeSubarchitecture If the architecture is specified numerically
119  	(using the kSecCodeAttributeArchitecture key), specifies any sub-architecture by number.
120  	This key is ignored if no main architecture is specified; if it is specified by name; or
121  	if the code is not in Mach-O form.
122  	@constant kSecCodeAttributeUniversalFileOffset The offset of a Mach-O specific slice of a universal Mach-O file.
123  	@constant kSecCodeAttributeBundleVersion If the code sought is a deep framework bundle (Something.framework/Versions/...),
124      then select the specified framework version. This key is otherwise ignored.
125  */
126  OSStatus SecStaticCodeCreateWithPathAndAttributes(CFURLRef path, SecCSFlags flags, CFDictionaryRef attributes,
127  	SecStaticCodeRef * __nonnull CF_RETURNS_RETAINED staticCode);
128  
129  
130  /*!
131  	@function SecStaticCodeCheckValidity
132  	Performs static validation on the given SecStaticCode object. The call obtains and
133  	verifies the signature on the code object. It checks the validity of all
134  	sealed components (including resources, if any). It validates the code against
135  	a SecRequirement if one is given. The call succeeds if all these conditions
136  	are satisfactory. It fails otherwise.
137  	
138  	This call is only secure if the code is not subject to concurrent modification,
139  	and the outcome is only valid as long as the code is unmodified thereafter.
140  	Consider this carefully if the underlying file system has dynamic characteristics,
141  	such as a network file system, union mount, FUSE, etc.
142  
143  	@param staticCode The code object to be validated.
144  	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
145  	
146  	@constant kSecCSCheckAllArchitectures
147  	For multi-architecture (universal) Mach-O programs, validate all architectures
148  	included. By default, only the native architecture is validated.
149  	@constant kSecCSDoNotValidateExecutable
150  	Do not validate the contents of the main executable. This is normally done.
151  	@constant kSecCSDoNotValidateResources
152  	Do not validate the presence and contents of all bundle resources (if any).
153  	By default, a mismatch in any bundle resource causes validation to fail.
154  	@constant kSecCSCheckNestedCode
155  	For code in bundle form, locate and recursively check embedded code. Only code
156  	in standard locations is considered.
157  	@constant kSecCSStrictValidate
158  	For code in bundle form, perform additional checks to verify that the bundle
159  	is not structured in a way that would allow tampering, and reject any resource
160  	envelope that introduces weaknesses into the signature.
161  	@constant kSecCSSingleThreaded
162  	Perform all resource validation serially on a single thread instead of dispatching
163  	work in parallel.
164  	@constant kSecCSAllowNetworkAccess
165  	Enables network access for certificate trust evaluation performed while validating the
166  	bundle or its contents.
167  
168  	@param requirement On optional code requirement specifying additional conditions
169  	the staticCode object must satisfy to be considered valid. If NULL, no additional
170  	requirements are imposed.
171  	@param errors An optional pointer to a CFErrorRef variable. If the call fails
172  	(something other than errSecSuccess is returned), and this argument is non-NULL,
173  	a CFErrorRef is stored there further describing the nature and circumstances
174  	of the failure. The caller must CFRelease() this error object when done with it.
175  	@result If validation succeeds, errSecSuccess. If validation fails, an OSStatus value
176  	documented in CSCommon.h or certain other Security framework headers.
177  */
178  CF_ENUM(uint32_t) {
179  	kSecCSCheckAllArchitectures = 1 << 0,
180  	kSecCSDoNotValidateExecutable = 1 << 1,
181  	kSecCSDoNotValidateResources = 1 << 2,
182  	kSecCSBasicValidateOnly = kSecCSDoNotValidateExecutable | kSecCSDoNotValidateResources,
183  	kSecCSCheckNestedCode = 1 << 3,
184  	kSecCSStrictValidate = 1 << 4,
185  	kSecCSFullReport = 1 << 5,
186  	kSecCSCheckGatekeeperArchitectures = (1 << 6) | kSecCSCheckAllArchitectures,
187  	kSecCSRestrictSymlinks = 1 << 7,
188  	kSecCSRestrictToAppLike = 1 << 8,
189  	kSecCSRestrictSidebandData = 1 << 9,
190  	kSecCSUseSoftwareSigningCert = 1 << 10,
191  	kSecCSValidatePEH = 1 << 11,
192  	kSecCSSingleThreaded = 1 << 12,
193  	// NOTE: These values have gaps for internal usage.
194  	kSecCSAllowNetworkAccess CF_ENUM_AVAILABLE(11_3, 14_5) = 1 << 16,
195  	kSecCSFastExecutableValidation CF_ENUM_AVAILABLE(11_3, 14_5) = 1 << 17,
196  };
197  
198  OSStatus SecStaticCodeCheckValidity(SecStaticCodeRef staticCode, SecCSFlags flags,
199  	SecRequirementRef __nullable requirement);
200  
201  OSStatus SecStaticCodeCheckValidityWithErrors(SecStaticCodeRef staticCode, SecCSFlags flags,
202  	SecRequirementRef __nullable requirement, CFErrorRef *errors);
203  
204  CF_ASSUME_NONNULL_END
205  
206  #ifdef __cplusplus
207  }
208  #endif
209  
210  #endif //_H_SECSTATICCODE