OSX/libsecurity_codesigning/lib/SecStaticCode.h

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