X-Git-Url: https://git.saurik.com/apple/libsecurity_codesigning.git/blobdiff_plain/2e2533baea112414a307d169c101a9c225fd1d77..refs/heads/master:/lib/SecCodeSigner.h diff --git a/lib/SecCodeSigner.h b/lib/SecCodeSigner.h index 32c0abb..42ad089 100644 --- a/lib/SecCodeSigner.h +++ b/lib/SecCodeSigner.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2006 Apple Computer, Inc. All Rights Reserved. + * Copyright (c) 2006-2010 Apple Inc. All Rights Reserved. * * @APPLE_LICENSE_HEADER_START@ * @@ -23,7 +23,7 @@ /*! @header SecCodeSigner - SecCodeSigner represents an object that signs code. + SecCodeSigner represents an object that can sign code. */ #ifndef _H_SECCODESIGNER #define _H_SECCODESIGNER @@ -43,23 +43,102 @@ typedef struct __SecCodeSigner *SecCodeSignerRef; /* code signing object */ /*! @function SecCodeGetTypeID - Returns the type identifier of all SecCode instances. + 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. - @constant kSecCodeSignerDetached If present, a detached code signature is generated. - If absent, code signature data is written into the target code (which must - be writable). The value is a CFURL identifying the file that is replaced with - the detached signature data. - @constant kSecCodeSignerRequirements Internal code requirements. - @constant kSecCodeSignerFlags Signature flags. + 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; @@ -69,7 +148,18 @@ 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; /*! @@ -81,11 +171,18 @@ extern const CFStringRef kSecCodeSignerSigningTime; 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);