Security-59754.80.3.tar.gz

[apple/security.git] / OSX / libsecurity_codesigning / lib / SecCode.h

diff --git a/OSX/libsecurity_codesigning/lib/SecCode.h b/OSX/libsecurity_codesigning/lib/SecCode.h
index a5c7dd0e9ee5d0139e54305667b26c602306248f..14009a51874963de7cc7ea1fd815fa9d8baa4280 100644 (file)
--- a/OSX/libsecurity_codesigning/lib/SecCode.h
+++ b/OSX/libsecurity_codesigning/lib/SecCode.h
@@ -32,6 +32,7 @@
 
 #include <Security/CSCommon.h>
 #include <CoreFoundation/CFBase.h>
 
 #include <Security/CSCommon.h>
 #include <CoreFoundation/CFBase.h>

+#include <xpc/xpc.h>

 
 #ifdef __cplusplus
 extern "C" {
 
 #ifdef __cplusplus
 extern "C" {


@@ -51,9 +52,7 @@ CFTypeID SecCodeGetTypeID(void);
        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)
        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.
+       is always used.

 
        @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
        @param self Upon successful return, contains a SecCodeRef representing the caller.
 
        @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
        @param self Upon successful return, contains a SecCodeRef representing the caller.


@@ -111,7 +110,7 @@ OSStatus SecCodeCopyStaticCode(SecCodeRef code, SecCSFlags flags, SecStaticCodeR
        and is the ultimate authority on the its dynamic validity and status.
        The host relationship is securely established (absent reported errors).
        
        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
+       @param guest 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
        on the system.
        @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
        @param host On successful return, a SecCode object reference identifying


@@ -121,6 +120,17 @@ OSStatus SecCodeCopyStaticCode(SecCodeRef code, SecCSFlags flags, SecStaticCodeR
 */
 OSStatus SecCodeCopyHost(SecCodeRef guest, SecCSFlags flags, SecCodeRef * __nonnull CF_RETURNS_RETAINED host);
 
 */
 OSStatus SecCodeCopyHost(SecCodeRef guest, SecCSFlags flags, SecCodeRef * __nonnull CF_RETURNS_RETAINED host);
 

+extern const CFStringRef kSecGuestAttributeCanonical;
+extern const CFStringRef kSecGuestAttributeHash;
+extern const CFStringRef kSecGuestAttributeMachPort;
+extern const CFStringRef kSecGuestAttributePid;
+extern const CFStringRef kSecGuestAttributeAudit;
+extern const CFStringRef kSecGuestAttributeDynamicCode;
+extern const CFStringRef kSecGuestAttributeDynamicCodeInfoPlist;
+extern const CFStringRef kSecGuestAttributeArchitecture;
+extern const CFStringRef kSecGuestAttributeSubarchitecture;
+
+#if TARGET_OS_OSX

 /*!
        @function SecCodeCopyGuestWithAttributes
        This is the omnibus API function for obtaining dynamic code references.
 /*!
        @function SecCodeCopyGuestWithAttributes
        This is the omnibus API function for obtaining dynamic code references.


@@ -175,18 +185,33 @@ OSStatus SecCodeCopyHost(SecCodeRef guest, SecCSFlags flags, SecCodeRef * __nonn
        @error errSecCSMultipleGuests The attributes specified do not uniquely identify
        a guest (the specification is ambiguous).
 */
        @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 __nullable host,
        CFDictionaryRef __nullable attributes,  SecCSFlags flags, SecCodeRef * __nonnull CF_RETURNS_RETAINED guest);
 
 
 OSStatus SecCodeCopyGuestWithAttributes(SecCodeRef __nullable host,
        CFDictionaryRef __nullable attributes,  SecCSFlags flags, SecCodeRef * __nonnull CF_RETURNS_RETAINED guest);
 

+/*!
+       @function SecCodeCreateWithXPCMessage
+       Creates a SecCode reference to the process that sent the provided XPC message, using the
+    associated audit token.
+
+       @param message The xpc_object_t of a message recieved via xpc to look up the audit token
+       of the process that sent the message.
+       @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
+       @param processRef On successful return, a SecCode object reference identifying
+       the particular guest of the process from the audit token. 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 errSecCSInvalidObjectRef The xpc_object_t was not of type XPC_TYPE_DICTIONARY.
+       @error errSecCSInvalidObjectRef The xpc_object_t was not an xpc message with an associated
+       connection.
+    For a complete list of errors, please see {@link SecCodeCopyGuestWithAttributes}.
+*/
+OSStatus SecCodeCreateWithXPCMessage(xpc_object_t message, SecCSFlags flags,
+       SecCodeRef * __nonnull CF_RETURNS_RETAINED target);
+
+#endif // TARGET_OS_OSX
+

 
 /*!
        @function SecCodeCheckValidity
 
 /*!
        @function SecCodeCheckValidity


@@ -201,6 +226,30 @@ OSStatus SecCodeCopyGuestWithAttributes(SecCodeRef __nullable host,
        This call is secure against attempts to modify the file system source of the
        SecCode.
 
        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.
+       @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 __nullable requirement);
+
+/*!
+       @function SecCodeCheckValidityWithErrors
+       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
        @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


@@ -213,9 +262,6 @@ OSStatus SecCodeCopyGuestWithAttributes(SecCodeRef __nullable host,
        @result If validation passes, errSecSuccess. If validation fails, an OSStatus value
        documented in CSCommon.h or certain other Security framework headers.
 */
        @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 __nullable requirement);
-

 OSStatus SecCodeCheckValidityWithErrors(SecCodeRef code, SecCSFlags flags,
        SecRequirementRef __nullable requirement, CFErrorRef *errors);
 
 OSStatus SecCodeCheckValidityWithErrors(SecCodeRef code, SecCSFlags flags,
        SecRequirementRef __nullable requirement, CFErrorRef *errors);
 


@@ -226,10 +272,7 @@ OSStatus SecCodeCheckValidityWithErrors(SecCodeRef code, SecCSFlags flags,
        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.
        
        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
+       @param staticCode 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
                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


@@ -270,7 +313,10 @@ OSStatus SecCodeCopyDesignatedRequirement(SecStaticCodeRef code, SecCSFlags flag
        @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
        @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.
+       and detail level of the data is controlled by the flags passed to the call. For
+       Code objects, some of the signing information returned will be from disk. You can
+       call one of the CheckValidity functions to check that the content on disk matches
+       the signing information attached to the running Code.

        
        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
        
        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


@@ -340,10 +386,12 @@ OSStatus SecCodeCopyDesignatedRequirement(SecStaticCodeRef code, SecCSFlags flag
        @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
        @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 actually used to establish integrity of the signature.
+               hash function chosen to establish integrity of the signature on this system, which
+        is the best supported algorithm from kSecCodeInfoDigestAlgorithms.

        @constant kSecCodeInfoDigestAlgorithms A CFArray of CFNumbers indicating the kinds of
                cryptographic hash functions available within the signature. The ordering of those items
        @constant kSecCodeInfoDigestAlgorithms A CFArray of CFNumbers indicating the kinds of
                cryptographic hash functions available within the signature. The ordering of those items

-               has no significance.
+               has no significance in terms of priority, but determines the order in which
+        the hashes appear in kSecCodeInfoCdHashes.

        @constant kSecCodeInfoPlatformIdentifier If this code was signed as part of an operating
                system release, this value identifies that release.
        @constant kSecCodeInfoIdentifier A CFString with the actual signing identifier
        @constant kSecCodeInfoPlatformIdentifier If this code was signed as part of an operating
                system release, this value identifies that release.
        @constant kSecCodeInfoIdentifier A CFString with the actual signing identifier


@@ -391,21 +439,28 @@ OSStatus SecCodeCopyDesignatedRequirement(SecStaticCodeRef code, SecCSFlags flag
                remains stable across (developer-approved) updates.
                The algorithm used may change from time to time. However, for any existing signature,
                the value is stable.
                remains stable across (developer-approved) updates.
                The algorithm used may change from time to time. However, for any existing signature,
                the value is stable.

+       @constant kSecCodeInfoCdHashes An array containing the values of the kSecCodeInfoUnique
+        binary identifier for every digest algorithm supported in the signature, in the same
+        order as in the kSecCodeInfoDigestAlgorithms array. The kSecCodeInfoUnique value
+        will be contained in this array, and be the one corresponding to the
+        kSecCodeInfoDigestAlgorithm value.

  */
 CF_ENUM(uint32_t) {
        kSecCSInternalInformation = 1 << 0,
        kSecCSSigningInformation = 1 << 1,
        kSecCSRequirementInformation = 1 << 2,
        kSecCSDynamicInformation = 1 << 3,
  */
 CF_ENUM(uint32_t) {
        kSecCSInternalInformation = 1 << 0,
        kSecCSSigningInformation = 1 << 1,
        kSecCSRequirementInformation = 1 << 2,
        kSecCSDynamicInformation = 1 << 3,

-       kSecCSContentInformation = 1 << 4
+       kSecCSContentInformation = 1 << 4,
+    kSecCSSkipResourceDirectory = 1 << 5,
+    kSecCSCalculateCMSDigest = 1 << 6,

 };
                                                                                                        /* 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 */
 };
                                                                                                        /* 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 kSecCodeInfoEntitlements;     /* generic */
+extern const CFStringRef kSecCodeInfoEntitlementsDict; /* generic */

 extern const CFStringRef kSecCodeInfoFlags;            /* generic */
 extern const CFStringRef kSecCodeInfoFormat;           /* generic */
 extern const CFStringRef kSecCodeInfoDigestAlgorithm; /* generic */
 extern const CFStringRef kSecCodeInfoFlags;            /* generic */
 extern const CFStringRef kSecCodeInfoFormat;           /* generic */
 extern const CFStringRef kSecCodeInfoDigestAlgorithm; /* generic */


@@ -425,6 +480,7 @@ extern const CFStringRef kSecCodeInfoTimestamp;             /* Signing */
 extern const CFStringRef kSecCodeInfoTrust;                    /* Signing */
 extern const CFStringRef kSecCodeInfoUnique;           /* generic */
 extern const CFStringRef kSecCodeInfoCdHashes;         /* generic */
 extern const CFStringRef kSecCodeInfoTrust;                    /* Signing */
 extern const CFStringRef kSecCodeInfoUnique;           /* generic */
 extern const CFStringRef kSecCodeInfoCdHashes;         /* generic */

+extern const CFStringRef kSecCodeInfoRuntimeVersion; /*generic */

 
 OSStatus SecCodeCopySigningInformation(SecStaticCodeRef code, SecCSFlags flags,
        CFDictionaryRef * __nonnull CF_RETURNS_RETAINED information);
 
 OSStatus SecCodeCopySigningInformation(SecStaticCodeRef code, SecCSFlags flags,
        CFDictionaryRef * __nonnull CF_RETURNS_RETAINED information);