X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/72a12576750f52947eb043106ba5c12c0d07decf..b1ab9ed8d0e0f1c3b66d7daa8fd5564444c56195:/libsecurity_codesigning/lib/SecCodeSigner.h diff --git a/libsecurity_codesigning/lib/SecCodeSigner.h b/libsecurity_codesigning/lib/SecCodeSigner.h new file mode 100644 index 00000000..42ad0899 --- /dev/null +++ b/libsecurity_codesigning/lib/SecCodeSigner.h @@ -0,0 +1,218 @@ +/* + * 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 + +/*! + @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