X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/80e2389990082500d76eb566d4946be3e786c3ef..d8f41ccd20de16f8ebe2ccc84d47bf1cb2b26bbb:/libsecurity_codesigning/lib/SecCode.h diff --git a/libsecurity_codesigning/lib/SecCode.h b/libsecurity_codesigning/lib/SecCode.h deleted file mode 100644 index ee773ae1..00000000 --- a/libsecurity_codesigning/lib/SecCode.h +++ /dev/null @@ -1,444 +0,0 @@ -/* - * 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 SecCode - SecCode represents separately indentified running code in the system. - In addition to UNIX processes, this can also include (with suitable support) - scripts, applets, widgets, etc. -*/ -#ifndef _H_SECCODE -#define _H_SECCODE - -#include - -#ifdef __cplusplus -extern "C" { -#endif - - -/*! - @function SecCodeGetTypeID - Returns the type identifier of all SecCode instances. -*/ -CFTypeID SecCodeGetTypeID(void); - - -/*! - @function SecCodeCopySelf - Obtains a SecCode object for the code making the call. - The calling code is determined in a way that is subject to modification over - time, but obeys the following rules. If it is a UNIX process, its process id (pid) - is always used. If it is an active code host that has a dedicated guest, such a guest - is always preferred. If it is a host that has called SecHostSelectGuest, such selection - is considered until revoked. - - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @param self Upon successful return, contains a SecCodeRef representing the caller. - - @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in - CSCommon.h or certain other Security framework headers. - */ -OSStatus SecCodeCopySelf(SecCSFlags flags, SecCodeRef *self); - - -/*! - @function SecCodeCopyStaticCode - Given a SecCode object, locate its origin in the file system and return - a SecStaticCode object representing it. - - The link established by this call is generally reliable but is NOT guaranteed - to be secure. - - Many API functions taking SecStaticCodeRef arguments will also directly - accept a SecCodeRef and apply this translation implicitly, operating on - its result or returning its error code if any. Each of these functions - calls out that behavior in its documentation. - - If the code was obtained from a universal (aka "fat") program file, - the resulting SecStaticCodeRef will refer only to the architecture actually - being used. This means that multiple running codes started from the same file - may conceivably result in different static code references if they ended up - using different execution architectures. (This is unusual but possible.) - - @param code A valid SecCode object reference representing code running - on the system. - - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @constant kSecCSUseAllArchitectures - If code refers to a single architecture of a universal binary, return a SecStaticCodeRef - that refers to the entire universal code with all its architectures. By default, the - returned static reference identifies only the actual architecture of the running program. - - @param staticCode On successful return, a SecStaticCode object reference representing - the file system origin of the given SecCode. On error, unchanged. - @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in - CSCommon.h or certain other Security framework headers. -*/ -enum { - kSecCSUseAllArchitectures = 1 << 0, -}; - -OSStatus SecCodeCopyStaticCode(SecCodeRef code, SecCSFlags flags, SecStaticCodeRef *staticCode); - - -/*! - @function SecCodeCopyHost - Given a SecCode object, identify the (different) SecCode object that acts - as its host. A SecCode's host acts as a supervisor and controller, - and is the ultimate authority on the its dynamic validity and status. - The host relationship is securely established (absent reported errors). - - @param code A valid SecCode object reference representing code running - on the system. - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @param host On successful return, a SecCode object reference identifying - the code's host. - @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in - CSCommon.h or certain other Security framework headers. -*/ -OSStatus SecCodeCopyHost(SecCodeRef guest, SecCSFlags flags, SecCodeRef *host); - - -/*! - @function SecCodeCopyGuestWithAttributes - This is the omnibus API function for obtaining dynamic code references. - In general, it asks a particular code acting as a code host to locate - and return a guest with given attributes. Different hosts support - different combinations of attributes and values for guest selection. - - Asking the NULL host invokes system default procedures for obtaining - any running code in the system with the attributes given. The returned - code may be anywhere in the system. - - The methods a host uses to identify, separate, and control its guests - are specific to each type of host. This call provides a generic abstraction layer - that allows uniform interrogation of all hosts. A SecCode that does not - act as a host will always return errSecCSNoSuchCode. A SecCode that does - support hosting may return itself to signify that the attribute refers to - itself rather than one of its hosts. - - @param host A valid SecCode object reference representing code running - on the system that acts as a Code Signing host. As a special case, passing - NULL indicates that the Code Signing root of trust should be used as a starting - point. Currently, that is the system kernel. - @param attributes A CFDictionary containing zero or more attribute selector - values. Each selector has a CFString key and associated CFTypeRef value. - The key name identifies the attribute being specified; the associated value, - whose type depends on the the key name, selects a particular value or other - constraint on that attribute. Each host only supports particular combinations - of keys and values, and errors will be returned if any unsupported set is requested. - As a special case, NULL is taken to mean an empty attribute set. - Note that some hosts that support hosting chains (guests being hosts) - may return sub-guests in this call. In other words, do not assume that - a SecCodeRef returned by this call is a direct guest of the queried host - (though it will be a proximate guest, i.e. a guest's guest some way down). - Asking the NULL host for NULL attributes returns a code reference for the system root - of trust (at present, the running Darwin kernel). - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @param guest On successful return, a SecCode object reference identifying - the particular guest of the host that owns the attribute value(s) specified. - This argument will not be changed if the call fails (does not return errSecSuccess). - @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in - CSCommon.h or certain other Security framework headers. In particular: - @error errSecCSUnsupportedGuestAttributes The host does not support the attribute - type given by attributeType. - @error errSecCSInvalidAttributeValues The type of value given for a guest - attribute is not supported by the host. - @error errSecCSNoSuchCode The host has no guest with the attribute value given - by attributeValue, even though the value is of a supported type. This may also - be returned if the host code does not currently act as a Code Signing host. - @error errSecCSNotAHost The specified host cannot, in fact, act as a code - host. (It is missing the kSecCodeSignatureHost option flag in its code - signature.) - @error errSecCSMultipleGuests The attributes specified do not uniquely identify - a guest (the specification is ambiguous). -*/ -extern const CFStringRef kSecGuestAttributeCanonical; -extern const CFStringRef kSecGuestAttributeHash; -extern const CFStringRef kSecGuestAttributeMachPort; -extern const CFStringRef kSecGuestAttributePid; -extern const CFStringRef kSecGuestAttributeDynamicCode; -extern const CFStringRef kSecGuestAttributeDynamicCodeInfoPlist; -extern const CFStringRef kSecGuestAttributeArchitecture; -extern const CFStringRef kSecGuestAttributeSubarchitecture; - -OSStatus SecCodeCopyGuestWithAttributes(SecCodeRef host, - CFDictionaryRef attributes, SecCSFlags flags, SecCodeRef *guest); - - -/*! - @function SecCodeCheckValidity - Performs dynamic validation of the given SecCode object. The call obtains and - verifies the signature on the code object. It checks the validity of only those - sealed components required to establish identity. It checks the SecCode's - dynamic validity status as reported by its host. It ensures that the SecCode's - host is in turn valid. Finally, it validates the code against a SecRequirement - if one is given. The call succeeds if all these conditions are satisfactory. - It fails otherwise. - - This call is secure against attempts to modify the file system source of the - SecCode. - - @param code The code object to be validated. - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @param requirement An optional code requirement specifying additional conditions - the code object must satisfy to be considered valid. If NULL, no additional - requirements are imposed. - @param errors An optional pointer to a CFErrorRef variable. If the call fails - (and something other than errSecSuccess 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 If validation passes, errSecSuccess. If validation fails, an OSStatus value - documented in CSCommon.h or certain other Security framework headers. -*/ -OSStatus SecCodeCheckValidity(SecCodeRef code, SecCSFlags flags, - SecRequirementRef requirement); - -OSStatus SecCodeCheckValidityWithErrors(SecCodeRef code, SecCSFlags flags, - SecRequirementRef requirement, CFErrorRef *errors); - - -/*! - @function SecCodeCopyPath - For a given Code or StaticCode object, returns a URL to a location on disk where the - code object can be found. For single files, the URL points to that file. - For bundles, it points to the directory containing the entire bundle. - - This returns the same URL as the kSecCodeInfoMainExecutable key returned - by SecCodeCopySigningInformation. - - @param code The Code or StaticCode object to be located. For a Code - argument, its StaticCode is processed as per SecCodeCopyStaticCode. - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @param path On successful return, contains a CFURL identifying the location - on disk of the staticCode object. - @result On success, errSecSuccess. On error, an OSStatus value - documented in CSCommon.h or certain other Security framework headers. -*/ -OSStatus SecCodeCopyPath(SecStaticCodeRef staticCode, SecCSFlags flags, - CFURLRef *path); - - -/*! - @function SecCodeCopyDesignatedRequirement - For a given Code or StaticCode object, determines its Designated Code Requirement. - The Designated Requirement is the SecRequirement that the code believes - should be used to properly identify it in the future. - - If the SecCode contains an explicit Designated Requirement, a copy of that - is returned. If it does not, a SecRequirement is implicitly constructed from - its signing authority and its embedded unique identifier. No Designated - Requirement can be obtained from code that is unsigned. Code that is modified - after signature, improperly signed, or has become invalid, may or may not yield - a Designated Requirement. This call does not validate the SecStaticCode argument. - - @param code The Code or StaticCode object to be interrogated. For a Code - argument, its StaticCode is processed as per SecCodeCopyStaticCode. - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - @param requirement On successful return, contains a copy of a SecRequirement - object representing the code's Designated Requirement. On error, unchanged. - @result On success, errSecSuccess. On error, an OSStatus value - documented in CSCommon.h or certain other Security framework headers. -*/ -OSStatus SecCodeCopyDesignatedRequirement(SecStaticCodeRef code, SecCSFlags flags, - SecRequirementRef *requirement); - - -/* - @function SecCodeCopySigningInformation - For a given Code or StaticCode object, extract various pieces of information - from its code signature and return them in the form of a CFDictionary. The amount - and detail level of the data is controlled by the flags passed to the call. - - If the code exists but is not signed at all, this call will succeed and return - a dictionary that does NOT contain the kSecCodeInfoIdentifier key. This is the - recommended way to check quickly whether a code is signed. - - If the signing data for the code is corrupt or invalid, this call may fail or it - may return partial data. To ensure that only valid data is returned (and errors - are raised for invalid data), you must successfully call one of the CheckValidity - functions on the code before calling CopySigningInformation. - - @param code The Code or StaticCode object to be interrogated. For a Code - argument, its StaticCode is processed as per SecCodeCopyStaticCode. - Note that dynamic information (kSecCSDynamicInformation) cannot be obtained - for a StaticCode argument. - @param flags Optional flags. Use any or all of the kSecCS*Information flags - to select what information to return. A generic set of entries is returned - regardless; you may specify kSecCSDefaultFlags for just those. - @param information A CFDictionary containing information about the code is stored - here on successful completion. The contents of the dictionary depend on - the flags passed. Regardless of flags, the kSecCodeInfoIdentifier key is - always present if the code is signed, and always absent if the code is - unsigned. - Note that some of the objects returned are (retained) "live" API objects - used by the code signing infrastructure. Making changes to these objects - is unsupported and may cause subsequent code signing operations on the - affected code to behave in undefined ways. - @result On success, errSecSuccess. On error, an OSStatus value - documented in CSCommon.h or certain other Security framework headers. - - Flags: - - @constant kSecCSSigningInformation Return cryptographic signing information, - including the certificate chain and CMS data (if any). For ad-hoc signed - code, there are no certificates and the CMS data is empty. - @constant kSecCSRequirementInformation Return information about internal code - requirements embedded in the code. This includes the Designated Requirement. - @constant kSecCSInternalInformation Return internal code signing information. - This information is for use by Apple, and is subject to change without notice. - It will not be further documented here. - @constant kSecCSDynamicInformation Return dynamic validity information about - the Code. The subject code must be a SecCodeRef (not a SecStaticCodeRef). - @constant kSecCSContentInformation Return more information about the file system - contents making up the signed code on disk. It is not generally advisable to - make use of this information, but some utilities (such as software-update - tools) may find it useful. - - Dictionary keys: - - @constant kSecCodeInfoCertificates A CFArray of SecCertificates identifying the - certificate chain of the signing certificate as seen by the system. Absent - for ad-hoc signed code. May be partial or absent in error cases. - @constant kSecCodeInfoChangedFiles A CFArray of CFURLs identifying all files in - the code that may have been modified by the process of signing it. (In other - words, files not in this list will not have been touched by the signing operation.) - @constant kSecCodeInfoCMS A CFData containing the CMS cryptographic object that - secures the code signature. Empty for ad-hoc signed code. - @constant kSecCodeInfoDesignatedRequirement A SecRequirement describing the - actual Designated Requirement of the code. - @constant kSecCodeInfoEntitlements A CFData containing the embedded entitlement - blob of the code, if any. - @constant kSecCodeInfoEntitlementsDict A CFDictionary containing the embedded entitlements - of the code if it has entitlements and they are in standard dictionary form. - Absent if the code has no entitlements, or they are in a different format (in which - case, see kSecCodeInfoEntitlements). - @constant kSecCodeInfoFlags A CFNumber with the static (on-disk) state of the object. - Contants are defined by the type SecCodeSignatureFlags. - @constant kSecCodeInfoFormat A CFString characterizing the type and format of - the code. Suitable for display to a (knowledeable) user. - @constant kSecCodeInfoDigestAlgorithm A CFNumber indicating the kind of cryptographic - hash function used within the signature to seal its pieces together. - @constant kSecCodeInfoIdentifier A CFString with the actual signing identifier - sealed into the signature. Absent for unsigned code. - @constant kSecCodeInfoImplicitDesignatedRequirement A SecRequirement describing - the designated requirement that the system did generate, or would have generated, - for the code. If the Designated Requirement was implicitly generated, this is - the same object as kSecCodeInfoDesignatedRequirement; this can be used to test - for an explicit Designated Requirement. - @constant kSecCodeInfoMainExecutable A CFURL identifying the main executable file - of the code. For single files, that is the file itself. For bundles, it is the - main executable as identified by its Info.plist. - @constant kSecCodeInfoPList A retained CFDictionary referring to the secured Info.plist - as seen by code signing. Absent if no Info.plist is known to the code signing - subsystem. Note that this is not the same dictionary as the one CFBundle would - give you (CFBundle is free to add entries to the on-disk plist). - @constant kSecCodeInfoRequirements A CFString describing the internal requirements - of the code in canonical syntax. - @constant kSecCodeInfoRequirementsData A CFData containing the internal requirements - of the code as a binary blob. - @constant kSecCodeInfoSource A CFString describing the source of the code signature - used for the code object. The values are meant to be shown in informational - displays; do not rely on the precise value returned. - @constant kSecCodeInfoStatus A CFNumber containing the dynamic status word of the - (running) code. This is a snapshot at the time the API is executed and may be - out of date by the time you examine it. Do note however that most of the bits - are sticky and thus some values are permanently reliable. Be careful. - @constant kSecCodeInfoTime A CFDate describing the signing date (securely) embedded - in the code signature. Note that a signer is able to omit this date or pre-date - it. Nobody certifies that this was really the date the code was signed; however, - you do know that this is the date the signer wanted you to see. - Ad-hoc signatures have no CMS and thus never have secured signing dates. - @constant kSecCodeInfoTimestamp A CFDate describing the signing date as (securely) - certified by a timestamp authority service. This time cannot be falsified by the - signer; you trust the timestamp authority's word on this. - Ad-hoc signatures have no CMS and thus never have secured signing dates. - @constant kSecCodeInfoTrust The (retained) SecTrust object the system uses to - evaluate the validity of the code's signature. You may use the SecTrust API - to extract detailed information, particularly for reasons why certificate - validation may have failed. This object may continue to be used for further - evaluations of this code; if you make any changes to it, behavior is undefined. - @constant kSecCodeInfoUnique A CFData binary identifier that uniquely identifies - the static code in question. It can be used to recognize this particular code - (and none other) now or in the future. Compare to kSecCodeInfoIdentifier, which - remains stable across (developer-approved) updates. - This is currently the SHA-1 hash of the code's CodeDirectory. However, future - versions of the system may use a different algorithm for newly signed code. - Already-signed code not change the reported value in this case. - */ -enum { - kSecCSInternalInformation = 1 << 0, - kSecCSSigningInformation = 1 << 1, - kSecCSRequirementInformation = 1 << 2, - kSecCSDynamicInformation = 1 << 3, - kSecCSContentInformation = 1 << 4 -}; - - /* flag required to get this value */ -extern const CFStringRef kSecCodeInfoCertificates; /* Signing */ -extern const CFStringRef kSecCodeInfoChangedFiles; /* Content */ -extern const CFStringRef kSecCodeInfoCMS; /* Signing */ -extern const CFStringRef kSecCodeInfoDesignatedRequirement; /* Requirement */ -extern const CFStringRef kSecCodeInfoEntitlements; /* Requirement */ -extern const CFStringRef kSecCodeInfoEntitlementsDict; /* Requirement */ -extern const CFStringRef kSecCodeInfoFlags; /* generic */ -extern const CFStringRef kSecCodeInfoFormat; /* generic */ -extern const CFStringRef kSecCodeInfoDigestAlgorithm; /* generic */ -extern const CFStringRef kSecCodeInfoIdentifier; /* generic */ -extern const CFStringRef kSecCodeInfoImplicitDesignatedRequirement; /* Requirement */ -extern const CFStringRef kSecCodeInfoMainExecutable; /* generic */ -extern const CFStringRef kSecCodeInfoPList; /* generic */ -extern const CFStringRef kSecCodeInfoRequirements; /* Requirement */ -extern const CFStringRef kSecCodeInfoRequirementData; /* Requirement */ -extern const CFStringRef kSecCodeInfoSource; /* generic */ -extern const CFStringRef kSecCodeInfoStatus; /* Dynamic */ -extern const CFStringRef kSecCodeInfoTeamIdentifier; /* Signing */ -extern const CFStringRef kSecCodeInfoTime; /* Signing */ -extern const CFStringRef kSecCodeInfoTimestamp; /* Signing */ -extern const CFStringRef kSecCodeInfoTrust; /* Signing */ -extern const CFStringRef kSecCodeInfoUnique; /* generic */ - -OSStatus SecCodeCopySigningInformation(SecStaticCodeRef code, SecCSFlags flags, - CFDictionaryRef *information); - - -/* - @function SecCodeMapMemory - For a given Code or StaticCode object, ask the kernel to accept the signing information - currently attached to it in the caller and use it to validate memory page-ins against it, - updating dynamic validity state accordingly. This change affects all processes that have - the main executable of this code mapped. - - @param code A Code or StaticCode object representing the signed code whose main executable - should be subject to page-in validation. - @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. - */ -OSStatus SecCodeMapMemory(SecStaticCodeRef code, SecCSFlags flags); - - -#ifdef __cplusplus -} -#endif - -#endif //_H_SECCODE