Security/libsecurity_codesigning/lib/SecCodePriv.h

   1 /*
   2  * Copyright (c) 2006-2007,2011,2013 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25         @header SecCodePriv
  26         SecCodePriv is the private counter-part to SecCode. Its contents are not
  27         official API, and are subject to change without notice.
  28 */
  29 #ifndef _H_SECCODEPRIV
  30 #define _H_SECCODEPRIV
  31
  32 #include <Security/SecCode.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38
  39 /*
  40  *      Private constants for SecCodeCopySigningInformation.
  41  *      These are returned with the
  42  */
  43 extern const CFStringRef kSecCodeInfoCodeDirectory;                     /* Internal */
  44 extern const CFStringRef kSecCodeInfoCodeOffset;                        /* Internal */
  45 extern const CFStringRef kSecCodeInfoResourceDirectory;         /* Internal */
  46
  47
  48 /*!
  49         @function SecCodeGetStatus
  50         Retrieves the dynamic status for a SecCodeRef.
  51
  52         The dynamic status of a code can change at any time; the value returned is a snapshot
  53         in time that is inherently stale by the time it is received by the caller. However,
  54         since the status bits can only change in certain ways, some information is indefinitely
  55         valid. For example, an indication of invalidity (kSecCodeStatusValid bit off) is permanent
  56         since the valid bit cannot be set once clear, while an indication of validity (bit set)
  57         may already be out of date.
  58         Use this call with caution; it is usually wiser to call the validation API functions
  59         and let then consider the status as part of their holistic computation. However,
  60         SecCodeGetStatus is useful at times to capture persistent (sticky) status configurations.
  61
  62         @param code A valid SecCode object reference representing code running
  63         on the system.
  64         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  65         @param status Upon successful return, contains the dynamic status of code as
  66         determined by its host.
  67
  68         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  69         CSCommon.h or certain other Security framework headers.
  70  */
  71 OSStatus SecCodeGetStatus(SecCodeRef code, SecCSFlags flags, SecCodeStatus *status);
  72
  73
  74 /*!
  75         @function SecCodeSetStatus
  76         Change the dynamic status of a SecCodeRef.
  77
  78         @param code A valid SecCode object reference representing code running
  79         on the system.
  80         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  81         @param status Upon successful return, contains the dynamic status of code as
  82         determined by its host.
  83
  84         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  85         CSCommon.h or certain other Security framework headers.
  86  */
  87 typedef uint32_t SecCodeStatusOperation;
  88 enum {
  89         kSecCodeOperationNull = 0,
  90         kSecCodeOperationInvalidate = 1,
  91         kSecCodeOperationSetHard = 2,
  92         kSecCodeOperationSetKill = 3,
  93 };
  94
  95 OSStatus SecCodeSetStatus(SecCodeRef code, SecCodeStatusOperation operation,
  96         CFDictionaryRef arguments, SecCSFlags flags);
  97
  98
  99 /*!
 100         @function SecCodeCopyInternalRequirement
 101         For a given Code or StaticCode object, retrieves a particular kind of internal
 102         requirement that was sealed during signing.
 103
 104         This function will always fail for unsigned code. Requesting a type of internal
 105         requirement that was not given during signing is not an error.
 106
 107         Specifying a type of kSecDesignatedRequirementType is not the same as calling
 108         SecCodeCopyDesignatedRequirement. This function will only return an explicit
 109         Designated Requirement if one was specified during signing. SecCodeCopyDesignatedRequirement
 110         will synthesize a suitable Designated Requirement if one was not given explicitly.
 111
 112         @param code The Code or StaticCode object to be interrogated. For a Code
 113                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 114         @param type A SecRequirementType specifying which internal requirement is being
 115                 requested.
 116         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 117         @param requirement On successful return, contains a copy of the internal requirement
 118                 of the given type included in the given code. If the code has no such internal
 119                 requirement, this argument is set to NULL (with no error).
 120         @result On success, errSecSuccess. On error, an OSStatus value
 121                 documented in CSCommon.h or certain other Security framework headers.
 122 */
 123 OSStatus SecCodeCopyInternalRequirement(SecStaticCodeRef code, SecRequirementType type,
 124         SecCSFlags flags, SecRequirementRef *requirement);
 125
 126
 127 /*!
 128         @function SecCodeCreateWithPID
 129         Asks the kernel to return a SecCode object for a process identified
 130         by a UNIX process id (pid). This is a shorthand for asking SecGetRootCode()
 131         for a guest whose "pid" attribute has the given pid value.
 132
 133         This is a deprecated convenience function.
 134         Call SecCodeCopyGuestWithAttributes instead.
 135
 136         @param pid A process id for an existing UNIX process on the system.
 137         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 138         @param process On successful return, a SecCode object reference identifying
 139         the requesteed process.
 140         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 141         CSCommon.h or certain other Security framework headers.
 142 */
 143 OSStatus SecCodeCreateWithPID(pid_t pid, SecCSFlags flags, SecCodeRef *process)
 144         AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
 145
 146
 147 /*
 148         @function SecCodeSetDetachedSignature
 149         For a given Code or StaticCode object, explicitly specify the detached signature
 150         data used to verify it.
 151         This call unconditionally overrides any signature embedded in the Code and any
 152         previously specified detached signature; only the signature data specified here
 153         will be used from now on for this Code object. If NULL data is specified, the
 154         code object is returned to its natural signing state (before a detached
 155         signature was first attached to it).
 156         Any call to this function voids all cached validations for the Code object.
 157         Validations will be performed again as needed in the future. This call does not,
 158         by itself, perform or trigger any validations.
 159         Please note that it is possible to have multiple Code objects for the same static
 160         or dynamic code entity in the system. This function only attaches signature data
 161         to the particular SecStaticCodeRef involved. It is your responsibility to understand
 162         the object graph and pick the right one(s).
 163
 164         @param code A Code or StaticCode object whose signature information is to be changed.
 165         @param signature A CFDataRef containing the signature data to be used for validating
 166                 the given Code. This must be exactly the data previously generated as a detached
 167                 signature by the SecCodeSignerAddSignature API or the codesign(1) command with
 168                 the -D/--detached option.
 169                 If signature is NULL, discards any previously set signature data and reverts
 170                 to using the embedded signature, if any. If not NULL, the data is retained and used
 171                 for future validation operations.
 172                 The data may be retained or copied. Behavior is undefined if this object
 173                 is modified after this call before it is replaced through another call to this
 174                 function).
 175         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 176  */
 177 OSStatus SecCodeSetDetachedSignature(SecStaticCodeRef code, CFDataRef signature,
 178         SecCSFlags flags);
 179
 180
 181 #ifdef __cplusplus
 182 }
 183 #endif
 184
 185 #endif //_H_SECCODE