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