lib/SecStaticCode.h

   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
  29         Normally, each SecCode has a specific SecStaticCode that holds its static signing
  30         data. Informally, that is the SecStaticCode the SecCode "was made from" (by its host).
  31         There is however no viable link in the other direction - given a SecStaticCode,
  32         it is not possible to find, enumerate, or control any SecCode that originated from it.
  33 */
  34 #ifndef _H_SECSTATICCODE
  35 #define _H_SECSTATICCODE
  36
  37 #include <Security/CSCommon.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43
  44 /*!
  45         @function SecStaticCodeGetTypeID
  46         Returns the type identifier of all SecStaticCode instances.
  47 */
  48 CFTypeID SecStaticCodeGetTypeID(void);
  49
  50
  51 /*!
  52         @function SecStaticCodeCreateWithPath
  53         Given a path to a file system object, create a SecStaticCode object representing
  54         the code at that location, if possible. Such a SecStaticCode is not inherently
  55         linked to running code in the system.
  56
  57         It is possible to create a SecStaticCode object from an unsigned code object.
  58         Most uses of such an object will return the errSecCSUnsigned error. However,
  59         SecCodeCopyPath and SecCodeCopySigningInformation can be safely applied to such objects.
  60
  61         @param path A path to a location in the file system. Only file:// URLs are
  62         currently supported. For bundles, pass a URL to the root directory of the
  63         bundle. For single files, pass a URL to the file. If you pass a URL to the
  64         main executable of a bundle, the bundle as a whole will be generally recognized.
  65         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  66         @param staticCode On successful return, contains a reference to the StaticCode object
  67         representing the code at path. Unchanged on error.
  68         @result Upon success, noErr. Upon error, an OSStatus value documented in
  69         CSCommon.h or certain other Security framework headers.
  70 */
  71 OSStatus SecStaticCodeCreateWithPath(CFURLRef path, SecCSFlags flags, SecStaticCodeRef *staticCode);
  72
  73
  74 /*!
  75         @function SecStaticCodeCheckValidity
  76         Performs static validation on the given SecStaticCode object. The call obtains and
  77         verifies the signature on the code object. It checks the validity of all
  78         sealed components (including resources, if any). It validates the code against
  79         a SecRequirement if one is given. The call succeeds if all these conditions
  80         are satisfactory. It fails otherwise.
  81
  82         This call is only secure if the code is not subject to concurrent modification,
  83         and the outcome is only valid as long as the code is unmodified thereafter.
  84         Consider this carefully if the underlying file system has dynamic characteristics,
  85         such as a network file system, union mount, FUSE, etc.
  86
  87         @param staticCode The code object to be validated.
  88         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  89
  90         @constant kSecCSCheckAllArchitectures
  91         For multi-architecture (universal) Mach-O programs, validate all architectures
  92         included. By default, only the native architecture is validated.
  93         @constant kSecCSNoDnotValidateExecutable
  94         Do not validate the contents of the main executable. This is normally done.
  95         @constant kSecCSNoNotValidateResources
  96         Do not validate the presence and contents of all bundle resources (if any).
  97         By default, a mismatch in any bundle resource causes validation to fail.
  98
  99         @param requirement On optional code requirement specifying additional conditions
 100         the staticCode object must satisfy to be considered valid. If NULL, no additional
 101         requirements are imposed.
 102         @param errors An optional pointer to a CFErrorRef variable. If the call fails
 103         (something other than noErr is returned), and this argument is non-NULL,
 104         a CFErrorRef is stored there further describing the nature and circumstances
 105         of the failure. The caller must CFRelease() this error object when done with it.
 106         @result If validation succeeds, noErr. If validation fails, an OSStatus value
 107         documented in CSCommon.h or certain other Security framework headers.
 108 */
 109 enum {
 110         kSecCSCheckAllArchitectures = 1 << 0,
 111         kSecCSDoNotValidateExecutable = 1 << 1,
 112         kSecCSDoNotValidateResources = 1 << 2,
 113         kSecCSBasicValidateOnly = kSecCSDoNotValidateExecutable | kSecCSDoNotValidateResources
 114 };
 115
 116 OSStatus SecStaticCodeCheckValidity(SecStaticCodeRef staticCode, SecCSFlags flags,
 117         SecRequirementRef requirement);
 118
 119 OSStatus SecStaticCodeCheckValidityWithErrors(SecStaticCodeRef staticCode, SecCSFlags flags,
 120         SecRequirementRef requirement, CFErrorRef *errors);
 121
 122
 123 #ifdef __cplusplus
 124 }
 125 #endif
 126
 127 #endif //_H_SECSTATICCODE