1/* 2 * Copyright (c) 2006-2007 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 SecCodePriv 26 SecCodePriv is the private counter-part to SecCode. Its contents are not 27 official API, and are subject to change without notice. 28*/ 29#ifndef _H_SECCODEPRIV 30#define _H_SECCODEPRIV 31 32#include <Security/SecCode.h> 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38 39/* 40 * Private constants for SecCodeCopySigningInformation. 41 * These are returned with the 42 */ 43extern const CFStringRef kSecCodeInfoCodeDirectory; /* Internal */ 44extern const CFStringRef kSecCodeInfoCodeOffset; /* Internal */ 45extern const CFStringRef kSecCodeInfoResourceDirectory; /* Internal */ 46 47 48/*! 49 @function SecCodeGetStatus 50 Retrieves the dynamic status for a SecCodeRef. 51 52 The dynamic status of a code can change at any time; the value returned is a snapshot 53 in time that is inherently stale by the time it is received by the caller. However, 54 since the status bits can only change in certain ways, some information is indefinitely 55 valid. For example, an indication of invalidity (kSecCodeStatusValid bit off) is permanent 56 since the valid bit cannot be set once clear, while an indication of validity (bit set) 57 may already be out of date. 58 Use this call with caution; it is usually wiser to call the validation API functions 59 and let then consider the status as part of their holistic computation. However, 60 SecCodeGetStatus is useful at times to capture persistent (sticky) status configurations. 61 62 @param code A valid SecCode object reference representing code running 63 on the system. 64 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 65 @param status Upon successful return, contains the dynamic status of code as 66 determined by its host. 67 68 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in 69 CSCommon.h or certain other Security framework headers. 70 */ 71OSStatus SecCodeGetStatus(SecCodeRef code, SecCSFlags flags, SecCodeStatus *status); 72 73 74/*! 75 @function SecCodeSetStatus 76 Change the dynamic status of a SecCodeRef. 77 78 @param code A valid SecCode object reference representing code running 79 on the system. 80 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 81 @param status Upon successful return, contains the dynamic status of code as 82 determined by its host. 83 84 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in 85 CSCommon.h or certain other Security framework headers. 86 */ 87typedef uint32_t SecCodeStatusOperation; 88enum { 89 kSecCodeOperationNull = 0, 90 kSecCodeOperationInvalidate = 1, 91 kSecCodeOperationSetHard = 2, 92 kSecCodeOperationSetKill = 3, 93}; 94 95OSStatus SecCodeSetStatus(SecCodeRef code, SecCodeStatusOperation operation, 96 CFDictionaryRef arguments, SecCSFlags flags); 97 98 99/*! 100 @function SecCodeCopyInternalRequirement 101 For a given Code or StaticCode object, retrieves a particular kind of internal 102 requirement that was sealed during signing. 103 104 This function will always fail for unsigned code. Requesting a type of internal 105 requirement that was not given during signing is not an error. 106 107 Specifying a type of kSecDesignatedRequirementType is not the same as calling 108 SecCodeCopyDesignatedRequirement. This function will only return an explicit 109 Designated Requirement if one was specified during signing. SecCodeCopyDesignatedRequirement 110 will synthesize a suitable Designated Requirement if one was not given explicitly. 111 112 @param code The Code or StaticCode object to be interrogated. For a Code 113 argument, its StaticCode is processed as per SecCodeCopyStaticCode. 114 @param type A SecRequirementType specifying which internal requirement is being 115 requested. 116 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 117 @param requirement On successful return, contains a copy of the internal requirement 118 of the given type included in the given code. If the code has no such internal 119 requirement, this argument is set to NULL (with no error). 120 @result On success, errSecSuccess. On error, an OSStatus value 121 documented in CSCommon.h or certain other Security framework headers. 122*/ 123OSStatus SecCodeCopyInternalRequirement(SecStaticCodeRef code, SecRequirementType type, 124 SecCSFlags flags, SecRequirementRef *requirement); 125 126 127/*! 128 @function SecCodeCreateWithPID 129 Asks the kernel to return a SecCode object for a process identified 130 by a UNIX process id (pid). This is a shorthand for asking SecGetRootCode() 131 for a guest whose "pid" attribute has the given pid value. 132 133 This is a deprecated convenience function. 134 Call SecCodeCopyGuestWithAttributes instead. 135 136 @param pid A process id for an existing UNIX process on the system. 137 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 138 @param process On successful return, a SecCode object reference identifying 139 the requesteed process. 140 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in 141 CSCommon.h or certain other Security framework headers. 142*/ 143OSStatus SecCodeCreateWithPID(pid_t pid, SecCSFlags flags, SecCodeRef *process) 144 AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6; 145 146 147/* 148 @function SecCodeSetDetachedSignature 149 For a given Code or StaticCode object, explicitly specify the detached signature 150 data used to verify it. 151 This call unconditionally overrides any signature embedded in the Code and any 152 previously specified detached signature; only the signature data specified here 153 will be used from now on for this Code object. If NULL data is specified, the 154 code object is returned to its natural signing state (before a detached 155 signature was first attached to it). 156 Any call to this function voids all cached validations for the Code object. 157 Validations will be performed again as needed in the future. This call does not, 158 by itself, perform or trigger any validations. 159 Please note that it is possible to have multiple Code objects for the same static 160 or dynamic code entity in the system. This function only attaches signature data 161 to the particular SecStaticCodeRef involved. It is your responsibility to understand 162 the object graph and pick the right one(s). 163 164 @param code A Code or StaticCode object whose signature information is to be changed. 165 @param signature A CFDataRef containing the signature data to be used for validating 166 the given Code. This must be exactly the data previously generated as a detached 167 signature by the SecCodeSignerAddSignature API or the codesign(1) command with 168 the -D/--detached option. 169 If signature is NULL, discards any previously set signature data and reverts 170 to using the embedded signature, if any. If not NULL, the data is retained and used 171 for future validation operations. 172 The data may be retained or copied. Behavior is undefined if this object 173 is modified after this call before it is replaced through another call to this 174 function). 175 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 176 */ 177OSStatus SecCodeSetDetachedSignature(SecStaticCodeRef code, CFDataRef signature, 178 SecCSFlags flags); 179 180 181#ifdef __cplusplus 182} 183#endif 184 185#endif //_H_SECCODE 186