SecCodeSigner.h
1 /* 2 * Copyright (c) 2006-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 SecCodeSigner 26 SecCodeSigner represents an object that can sign code. 27 */ 28 #ifndef _H_SECCODESIGNER 29 #define _H_SECCODESIGNER 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 #include <Security/CSCommon.h> 36 37 /*! 38 @typedef SecCodeSignerRef 39 This is the type of a reference to a code requirement. 40 */ 41 #ifdef BRIDGED_SECCODESIGNER 42 typedef struct CF_BRIDGED_TYPE(id) __SecCodeSigner *SecCodeSignerRef; /* code signing object */ 43 #else 44 typedef struct __SecCodeSigner *SecCodeSignerRef; /* code signing object */ 45 #endif 46 47 48 /*! 49 @function SecCodeGetTypeID 50 Returns the type identifier of all SecCodeSigner instances. 51 */ 52 CFTypeID SecCodeSignerGetTypeID(void); 53 54 55 /*! 56 The following CFString constants can be used as keys in the parameters argument 57 of SecCodeSignerCreate to specify various modes and options of the signing operation. 58 Passing any keys not specified here may lead to undefined behavior and is not supported. 59 The same applies to passing objects of types not explicitly allowed here. 60 61 @constant kSecCodeSignerDetached Determines where the signature is written. 62 If this key is absent, the code being signed is modified to contain the signature, 63 replacing any signature already embedded there. 64 If the value is kCFNull, the signature is written to the system-wide detached 65 signature database. (You must have root privileges to write there.) 66 If the value of this key is a CFURL, the signature is written to a file at that location, 67 replacing any data there. 68 If the value is a CFMutableData, the signature is appended to that data. 69 @constant kSecCodeSignerDryRun A boolean value. If present and true, the actual writing 70 of the signature is inhibited, and the code is not modified, but all operations 71 leading up to this are performed normally, including the cryptographic access to 72 the signing identity (if any). 73 @constant kSecCodeSignerFlags A CFNumber specifying which flags to set in the code signature. 74 Note that depending on circumstances, this value may be augmented or modified 75 as part of the signing operation. 76 @constant kSecCodeSignerIdentifier If present, a CFString that explicitly specifies 77 the unique identifier string sealed into the code signature. If absent, the identifier 78 is derived implicitly from the code being signed. 79 @constant kSecCodeSignerIdentifierPrefix If the unique identifier string of the code signature 80 is implicitly generated, and the resulting string does not contain any "." (dot) 81 characters, then the (string) value of this parameter is prepended to the identifier. 82 By convention, the prefix is usually of the form "com.yourcompany.", but any value 83 is acceptable. If the kSecCodeSignerIdentifier parameter is specified, this parameter 84 is ineffective (but still allowed). 85 @constant kSecCodeSignerIdentity A SecIdentityRef describing the signing identity 86 to use for signing code. This is a mandatory parameter for signing operations. 87 Its value must be either a SecIdentityRef specifying a cryptographic identity 88 valid for Code Signing, or the special value kCFNull to indicate ad-hoc signing. 89 @constant kSecCodeSignerOperation The type of operation to be performed. Valid values 90 are kSecCodeSignerOperationSign to sign code, and kSecCodeSignerOperationRemove 91 to remove any existing signature from code. The default operation is to sign code. 92 @constant kSecCodeSignerPageSize An integer value explicitly specifying the page size 93 used to sign the main executable. This must be a power of two. A value of zero indicates 94 infinite size (no paging). 95 Only certain page sizes are allowed in most circumstances, and specifying an inappropriate 96 size will lead to spurious verification failures. This is for expert use only. 97 @constant kSecCodeSignerRequirements Specifies the internal requirements to be sealed into 98 the code signature. Must be either a CFData containing the binary (compiled) form of 99 a requirements set (SuperBlob), or a CFString containing a valid text form to be 100 compiled into binary form. Default requirements are automatically generated if this 101 parameter is omitted, and defaults may be applied to particular requirement types 102 that are not specified; but any requirement type you specify is sealed exactly as 103 specified. 104 @constant kSecCodeSignerResourceRules A CFDictionary containing resource scanning rules 105 determining what resource files are sealed into the signature (and in what way). 106 A situation-dependent default is applied if this parameter is not specified. 107 @constant kSecCodeSignerSDKRoot A CFURLRef indicating an alterate directory root 108 where signing operations should find subcomponents (libraries, frameworks, modules, etc.). 109 The default is the host system root "/". 110 @constant kSecCodeSignerSigningTime Specifies what date and time is sealed into the 111 code signature's CMS data. Can be either a CFDate object specifying a date, or 112 the value kCFNull indicating that no date should be included in the signature. 113 If not specified, the current date is chosen and sealed. 114 Since an ad-hoc signature has no CMS data, this argument is ineffective 115 for ad-hoc signing operations. 116 @constant kSecCodeSignerRequireTimestamp A CFBoolean indicating (if kCFBooleanTrue) that 117 the code signature should be certified by a timestamp authority service. This option 118 requires access to a timestamp server (usually over the Internet). If requested and 119 the timestamp server cannot be contacted or refuses service, the signing operation fails. 120 The timestamp value is not under the caller's control. 121 If the value is kCFBooleanFalse, no timestamp service is contacted and the resulting signature 122 has no certified timestamp. 123 If this key is omitted, a default is used that may vary from release to release. 124 Note that when signing multi-architectural ("fat") programs, each architecture will 125 be signed separately, and thus each architecture will have a slightly different timestamp. 126 @constant kSecCodeSignerTimestampServer A CFURL specifying which timestamp authority service 127 to contact for timestamping if requested by the kSecCodeSignerRequireTimestamp argument. 128 If omitted (and timestamping is performed), a system-defined default value is used, referring 129 to an Apple-operated timestamp service. Note that this service may not freely serve all requests. 130 @constant kSecCodeSignerTimestampAuthentication A SecIdentityRef describing the identity 131 used to authenticate to the timestamp authority server, if the server requires client-side 132 (SSL/TLS) authentication. This will not generally be the identity used to sign the actual 133 code, depending on the requirements of the timestamp authority service used. 134 If omitted, the timestamp server is contacted using unauthenticated HTTP requests. 135 @constant kSecCodeSignerTimestampOmitCertificates A CFBoolean indicating (if kCFBooleanTrue) 136 that the timestamp embedded in the signature, if requested, not contain the full certificate chain 137 of the timestamp service used. This will make for a marginally smaller signature, but may not 138 verify correctly unless all such certificates are available (through the keychain system) 139 on the verifying system. 140 The default is to embed enough certificates to ensure proper verification of Apple-generated 141 timestamp signatures. 142 @constant kSecCodeSignerRuntimeVersion A CFString indicating the version of runtime hardening policies 143 that the process should be opted into. The string should be of the form "x", "x.x", or "x.x.x" where 144 x is a number between 0 and 255. This parameter is optional. If the signer specifies 145 kSecCodeSignatureRuntime but does not provide this parameter, the runtime version will be the SDK 146 version built into the Mach-O. 147 148 */ 149 extern const CFStringRef kSecCodeSignerApplicationData; 150 extern const CFStringRef kSecCodeSignerDetached; 151 extern const CFStringRef kSecCodeSignerDigestAlgorithm; 152 extern const CFStringRef kSecCodeSignerDryRun; 153 extern const CFStringRef kSecCodeSignerEntitlements; 154 extern const CFStringRef kSecCodeSignerFlags; 155 extern const CFStringRef kSecCodeSignerIdentifier; 156 extern const CFStringRef kSecCodeSignerIdentifierPrefix; 157 extern const CFStringRef kSecCodeSignerIdentity; 158 extern const CFStringRef kSecCodeSignerPageSize; 159 extern const CFStringRef kSecCodeSignerRequirements; 160 extern const CFStringRef kSecCodeSignerResourceRules; 161 extern const CFStringRef kSecCodeSignerSDKRoot; 162 extern const CFStringRef kSecCodeSignerSigningTime; 163 extern const CFStringRef kSecCodeSignerTimestampAuthentication; 164 extern const CFStringRef kSecCodeSignerRequireTimestamp; 165 extern const CFStringRef kSecCodeSignerTimestampServer; 166 extern const CFStringRef kSecCodeSignerTimestampOmitCertificates; 167 extern const CFStringRef kSecCodeSignerPreserveMetadata; 168 extern const CFStringRef kSecCodeSignerTeamIdentifier; 169 extern const CFStringRef kSecCodeSignerPlatformIdentifier; 170 extern const CFStringRef kSecCodeSignerRuntimeVersion; 171 extern const CFStringRef kSecCodeSignerPreserveAFSC; 172 extern const CFStringRef kSecCodeSignerOmitAdhocFlag; 173 extern const CFStringRef kSecCodeSignerEditCpuType; 174 extern const CFStringRef kSecCodeSignerEditCpuSubtype; 175 extern const CFStringRef kSecCodeSignerEditCMS; 176 177 enum { 178 kSecCodeSignerPreserveIdentifier = 1 << 0, // preserve signing identifier 179 kSecCodeSignerPreserveRequirements = 1 << 1, // preserve internal requirements (including DR) 180 kSecCodeSignerPreserveEntitlements = 1 << 2, // preserve entitlements 181 kSecCodeSignerPreserveResourceRules = 1 << 3, // preserve resource rules (and thus resources) 182 kSecCodeSignerPreserveFlags = 1 << 4, // preserve signing flags 183 kSecCodeSignerPreserveTeamIdentifier = 1 << 5, // preserve team identifier flags 184 kSecCodeSignerPreserveDigestAlgorithm = 1 << 6, // preserve digest algorithms used 185 kSecCodeSignerPreservePEH = 1 << 7, // preserve pre-encryption hashes 186 kSecCodeSignerPreserveRuntime = 1 << 8, // preserve the runtime version 187 }; 188 189 190 /*! 191 @function SecCodeSignerCreate 192 Create a (new) SecCodeSigner object to be used for signing code. 193 194 @param parameters An optional CFDictionary containing parameters that influence 195 signing operations with the newly created SecCodeSigner. If NULL, defaults 196 are applied to all parameters; note however that some parameters do not have 197 useful defaults, and will need to be set before signing is attempted. 198 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 199 The kSecCSRemoveSignature flag requests that any existing signature be stripped 200 from the target code instead of signing. The kSecCSEditSignature flag 201 requests editing of existing signatures, which only works with a very 202 limited set of options. 203 @param staticCode On successful return, a SecStaticCode object reference representing 204 the file system origin of the given SecCode. On error, unchanged. 205 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in 206 CSCommon.h or certain other Security framework headers. 207 */ 208 enum { 209 kSecCSRemoveSignature = 1 << 0, // strip existing signature 210 kSecCSSignPreserveSignature = 1 << 1, // do not (re)sign if an embedded signature is already present 211 kSecCSSignNestedCode = 1 << 2, // recursive (deep) signing 212 kSecCSSignOpaque = 1 << 3, // treat all files as resources (no nest scan, no flexibility) 213 kSecCSSignV1 = 1 << 4, // sign ONLY in V1 form 214 kSecCSSignNoV1 = 1 << 5, // do not include V1 form 215 kSecCSSignBundleRoot = 1 << 6, // include files in bundle root 216 kSecCSSignStrictPreflight = 1 << 7, // fail signing operation if signature would fail strict validation 217 kSecCSSignGeneratePEH = 1 << 8, // generate pre-encryption hashes 218 kSecCSSignGenerateEntitlementDER = 1 << 9, // generate entitlement DER 219 kSecCSEditSignature = 1 << 10, // edit existing signature 220 }; 221 222 #ifdef BRIDGED_SECCODESIGNER 223 OSStatus SecCodeSignerCreate(CFDictionaryRef parameters, SecCSFlags flags, 224 SecCodeSignerRef * __nonnull CF_RETURNS_RETAINED signer); 225 #else 226 OSStatus SecCodeSignerCreate(CFDictionaryRef parameters, SecCSFlags flags, 227 SecCodeSignerRef *signer); 228 #endif 229 230 /*! 231 @function SecCodeSignerAddSignature 232 Create a code signature and add it to the StaticCode object being signed. 233 234 @param signer A SecCodeSigner object containing all the information required 235 to sign code. 236 @param code A valid SecStaticCode object reference representing code files 237 on disk. This code will be signed, and will ordinarily be modified to contain 238 the resulting signature data. 239 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. 240 @param errors An optional pointer to a CFErrorRef variable. If the call fails 241 (and something other than errSecSuccess is returned), and this argument is non-NULL, 242 a CFErrorRef is stored there further describing the nature and circumstances 243 of the failure. The caller must CFRelease() this error object when done with it. 244 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in 245 CSCommon.h or certain other Security framework headers. 246 */ 247 OSStatus SecCodeSignerAddSignature(SecCodeSignerRef signer, 248 SecStaticCodeRef code, SecCSFlags flags); 249 250 OSStatus SecCodeSignerAddSignatureWithErrors(SecCodeSignerRef signer, 251 SecStaticCodeRef code, SecCSFlags flags, CFErrorRef *errors); 252 253 254 #ifdef __cplusplus 255 } 256 #endif 257 258 #endif //_H_SECCODESIGNER