/* * Copyright (c) 2006-2010 Apple Inc. All Rights Reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /*! @header SecCodeSigner SecCodeSigner represents an object that can sign code. */ #ifndef _H_SECCODESIGNER #define _H_SECCODESIGNER #ifdef __cplusplus extern "C" { #endif #include <Security/CSCommon.h> /*! @typedef SecCodeSignerRef This is the type of a reference to a code requirement. */ typedef struct __SecCodeSigner *SecCodeSignerRef; /* code signing object */ /*! @function SecCodeGetTypeID Returns the type identifier of all SecCodeSigner instances. */ CFTypeID SecCodeSignerGetTypeID(void); /*! The following CFString constants can be used as keys in the parameters argument of SecCodeSignerCreate to specify various modes and options of the signing operation. Passing any keys not specified here may lead to undefined behavior and is not supported. The same applies to passing objects of types not explicitly allowed here. @constant kSecCodeSignerDetached Determines where the signature is written. If this key is absent, the code being signed is modified to contain the signature, replacing any signature already embedded there. If the value is kCFNull, the signature is written to the system-wide detached signature database. (You must have root privileges to write there.) If the value of this key is a CFURL, the signature is written to a file at that location, replacing any data there. If the value is a CFMutableData, the signature is appended to that data. @constant kSecCodeSignerDryRun A boolean value. If present and true, the actual writing of the signature is inhibited, and the code is not modified, but all operations leading up to this are performed normally, including the cryptographic access to the signing identity (if any). @constant kSecCodeSignerFlags A CFNumber specifying which flags to set in the code signature. Note that depending on circumstances, this value may be augmented or modified as part of the signing operation. @constant kSecCodeSignerIdentifier If present, a CFString that explicitly specifies the unique identifier string sealed into the code signature. If absent, the identifier is derived implicitly from the code being signed. @constant kSecCodeSignerIdentifierPrefix If the unique identifier string of the code signature is implicitly generated, and the resulting string does not contain any "." (dot) characters, then the (string) value of this parameter is prepended to the identifier. By convention, the prefix is usually of the form "com.yourcompany.", but any value is acceptable. If the kSecCodeSignerIdentifier parameter is specified, this parameter is ineffective (but still allowed). @constant kSecCodeSignerIdentity A SecIdentityRef describing the signing identity to use for signing code. This is a mandatory parameter for signing operations. Its value must be either a SecIdentityRef specifying a cryptographic identity valid for Code Signing, or the special value kCFNull to indicate ad-hoc signing. @constant kSecCodeSignerOperation The type of operation to be performed. Valid values are kSecCodeSignerOperationSign to sign code, and kSecCodeSignerOperationRemove to remove any existing signature from code. The default operation is to sign code. @constant kSecCodeSignerPageSize An integer value explicitly specifying the page size used to sign the main executable. This must be a power of two. A value of zero indicates infinite size (no paging). Only certain page sizes are allowed in most circumstances, and specifying an inappropriate size will lead to spurious verification failures. This is for expert use only. @constant kSecCodeSignerRequirements Specifies the internal requirements to be sealed into the code signature. Must be either a CFData containing the binary (compiled) form of a requirements set (SuperBlob), or a CFString containing a valid text form to be compiled into binary form. Default requirements are automatically generated if this parameter is omitted, and defaults may be applied to particular requirement types that are not specified; but any requirement type you specify is sealed exactly as specified. @constant kSecCodeSignerResourceRules A CFDictionary containing resource scanning rules determining what resource files are sealed into the signature (and in what way). A situation-dependent default is applied if this parameter is not specified. @constant kSecCodeSignerSDKRoot A CFURLRef indicating an alterate directory root where signing operations should find subcomponents (libraries, frameworks, modules, etc.). The default is the host system root "/". @constant kSecCodeSignerSigningTime Specifies what date and time is sealed into the code signature's CMS data. Can be either a CFDate object specifying a date, or the value kCFNull indicating that no date should be included in the signature. If not specified, the current date is chosen and sealed. Since an ad-hoc signature has no CMS data, this argument is ineffective for ad-hoc signing operations. @constant kSecCodeSignerRequireTimestamp A CFBoolean indicating (if kCFBooleanTrue) that the code signature should be certified by a timestamp authority service. This option requires access to a timestamp server (usually over the Internet). If requested and the timestamp server cannot be contacted or refuses service, the signing operation fails. The timestamp value is not under the caller's control. If the value is kCFBooleanFalse, no timestamp service is contacted and the resulting signature has no certified timestamp. If this key is omitted, a default is used that may vary from release to release. Note that when signing multi-architectural ("fat") programs, each architecture will be signed separately, and thus each architecture will have a slightly different timestamp. @constant kSecCodeSignerTimestampServer A CFURL specifying which timestamp authority service to contact for timestamping if requested by the kSecCodeSignerRequireTimestamp argument. If omitted (and timestamping is performed), a system-defined default value is used, referring to an Apple-operated timestamp service. Note that this service may not freely serve all requests. @constant kSecCodeSignerTimestampAuthentication A SecIdentityRef describing the identity used to authenticate to the timestamp authority server, if the server requires client-side (SSL/TLS) authentication. This will not generally be the identity used to sign the actual code, depending on the requirements of the timestamp authority service used. If omitted, the timestamp server is contacted using unauthenticated HTTP requests. @constant kSecCodeSignerTimestampOmitCertificates A CFBoolean indicating (if kCFBooleanTrue) that the timestamp embedded in the signature, if requested, not contain the full certificate chain of the timestamp service used. This will make for a marginally smaller signature, but may not verify correctly unless all such certificates are available (through the keychain system) on the verifying system. The default is to embed enough certificates to ensure proper verification of Apple-generated timestamp signatures. */ extern const CFStringRef kSecCodeSignerApplicationData; extern const CFStringRef kSecCodeSignerDetached; extern const CFStringRef kSecCodeSignerDigestAlgorithm; extern const CFStringRef kSecCodeSignerDryRun; extern const CFStringRef kSecCodeSignerEntitlements; extern const CFStringRef kSecCodeSignerFlags; extern const CFStringRef kSecCodeSignerIdentifier; extern const CFStringRef kSecCodeSignerIdentifierPrefix; extern const CFStringRef kSecCodeSignerIdentity; extern const CFStringRef kSecCodeSignerPageSize; extern const CFStringRef kSecCodeSignerRequirements; extern const CFStringRef kSecCodeSignerResourceRules; extern const CFStringRef kSecCodeSignerSDKRoot; extern const CFStringRef kSecCodeSignerSigningTime; extern const CFStringRef kSecCodeSignerTimestampAuthentication; extern const CFStringRef kSecCodeSignerRequireTimestamp; extern const CFStringRef kSecCodeSignerTimestampServer; extern const CFStringRef kSecCodeSignerTimestampOmitCertificates; // temporary add-back to bridge B&I build dependencies -- remove soon extern const CFStringRef kSecCodeSignerTSAUse; extern const CFStringRef kSecCodeSignerTSAURL; extern const CFStringRef kSecCodeSignerTSAClientAuth; extern const CFStringRef kSecCodeSignerTSANoCerts; /*! @function SecCodeSignerCreate Create a (new) SecCodeSigner object to be used for signing code. @param parameters An optional CFDictionary containing parameters that influence signing operations with the newly created SecCodeSigner. If NULL, defaults are applied to all parameters; note however that some parameters do not have useful defaults, and will need to be set before signing is attempted. @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. The kSecCSRemoveSignature flag requests that any existing signature be stripped from the target code instead of signing. @param staticCode On successful return, a SecStaticCode object reference representing the file system origin of the given SecCode. On error, unchanged. @result Upon success, noErr. Upon error, an OSStatus value documented in CSCommon.h or certain other Security framework headers. */ enum { kSecCSRemoveSignature = 1 << 0, // strip existing signature }; OSStatus SecCodeSignerCreate(CFDictionaryRef parameters, SecCSFlags flags, SecCodeSignerRef *signer); /*! @function SecCodeSignerAddSignature Create a code signature and add it to the StaticCode object being signed. @param signer A SecCodeSigner object containing all the information required to sign code. @param code A valid SecStaticCode object reference representing code files on disk. This code will be signed, and will ordinarily be modified to contain the resulting signature data. @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. @param errors An optional pointer to a CFErrorRef variable. If the call fails (and something other than noErr is returned), and this argument is non-NULL, a CFErrorRef is stored there further describing the nature and circumstances of the failure. The caller must CFRelease() this error object when done with it. @result Upon success, noErr. Upon error, an OSStatus value documented in CSCommon.h or certain other Security framework headers. */ OSStatus SecCodeSignerAddSignature(SecCodeSignerRef signer, SecStaticCodeRef code, SecCSFlags flags); OSStatus SecCodeSignerAddSignatureWithErrors(SecCodeSignerRef signer, SecStaticCodeRef code, SecCSFlags flags, CFErrorRef *errors); #ifdef __cplusplus } #endif #endif //_H_SECCODESIGNER