OSX/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  */
  42 extern const CFStringRef kSecCodeInfoCdHashesFull;          /* Internal */
  43 extern const CFStringRef kSecCodeInfoCodeDirectory;                     /* Internal */
  44 extern const CFStringRef kSecCodeInfoCodeOffset;                        /* Internal */
  45 extern const CFStringRef kSecCodeInfoDiskRepInfo;           /* Internal */
  46 extern const CFStringRef kSecCodeInfoResourceDirectory;         /* Internal */
  47 extern const CFStringRef kSecCodeInfoNotarizationDate;      /* Internal */
  48 extern const CFStringRef kSecCodeInfoCMSDigestHashType;     /* Internal */
  49 extern const CFStringRef kSecCodeInfoCMSDigest;             /* Internal */
  50 extern const CFStringRef kSecCodeInfoSignatureVersion;      /* Internal */
  51
  52 extern const CFStringRef kSecCodeInfoDiskRepVersionPlatform;     /* Number */
  53 extern const CFStringRef kSecCodeInfoDiskRepVersionMin;          /* Number */
  54 extern const CFStringRef kSecCodeInfoDiskRepVersionSDK;          /* Number */
  55 extern const CFStringRef kSecCodeInfoDiskRepNoLibraryValidation; /* String */
  56
  57 /*!
  58         @function SecCodeGetStatus
  59         Retrieves the dynamic status for a SecCodeRef.
  60
  61         The dynamic status of a code can change at any time; the value returned is a snapshot
  62         in time that is inherently stale by the time it is received by the caller. However,
  63         since the status bits can only change in certain ways, some information is indefinitely
  64         valid. For example, an indication of invalidity (kSecCodeStatusValid bit off) is permanent
  65         since the valid bit cannot be set once clear, while an indication of validity (bit set)
  66         may already be out of date.
  67         Use this call with caution; it is usually wiser to call the validation API functions
  68         and let then consider the status as part of their holistic computation. However,
  69         SecCodeGetStatus is useful at times to capture persistent (sticky) status configurations.
  70
  71         @param code A valid SecCode object reference representing code running
  72         on the system.
  73         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  74         @param status Upon successful return, contains the dynamic status of code as
  75         determined by its host.
  76
  77         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  78         CSCommon.h or certain other Security framework headers.
  79  */
  80 OSStatus SecCodeGetStatus(SecCodeRef code, SecCSFlags flags, SecCodeStatus *status);
  81
  82 typedef uint32_t SecCodeStatusOperation;
  83 enum {
  84     kSecCodeOperationNull = 0,
  85     kSecCodeOperationInvalidate = 1,
  86     kSecCodeOperationSetHard = 2,
  87     kSecCodeOperationSetKill = 3,
  88 };
  89
  90 /*!
  91         @function SecCodeSetStatus
  92         Change the dynamic status of a SecCodeRef.
  93
  94         @param code A valid SecCode object reference representing code running
  95         on the system.
  96         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  97
  98         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  99         CSCommon.h or certain other Security framework headers.
 100  */
 101 OSStatus SecCodeSetStatus(SecCodeRef code, SecCodeStatusOperation operation,
 102         CFDictionaryRef arguments, SecCSFlags flags);
 103
 104
 105 /*!
 106         @function SecCodeCopyInternalRequirement
 107         For a given Code or StaticCode object, retrieves a particular kind of internal
 108         requirement that was sealed during signing.
 109
 110         This function will always fail for unsigned code. Requesting a type of internal
 111         requirement that was not given during signing is not an error.
 112
 113         Specifying a type of kSecDesignatedRequirementType is not the same as calling
 114         SecCodeCopyDesignatedRequirement. This function will only return an explicit
 115         Designated Requirement if one was specified during signing. SecCodeCopyDesignatedRequirement
 116         will synthesize a suitable Designated Requirement if one was not given explicitly.
 117
 118         @param code The Code or StaticCode object to be interrogated. For a Code
 119                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 120         @param type A SecRequirementType specifying which internal requirement is being
 121                 requested.
 122         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 123         @param requirement On successful return, contains a copy of the internal requirement
 124                 of the given type included in the given code. If the code has no such internal
 125                 requirement, this argument is set to NULL (with no error).
 126         @result On success, errSecSuccess. On error, an OSStatus value
 127                 documented in CSCommon.h or certain other Security framework headers.
 128 */
 129 OSStatus SecCodeCopyInternalRequirement(SecStaticCodeRef code, SecRequirementType type,
 130         SecCSFlags flags, SecRequirementRef *requirement);
 131
 132
 133 #if TARGET_OS_OSX
 134 /*!
 135         @function SecCodeCreateWithAuditToken
 136         Asks the kernel to return a SecCode object for a process identified
 137         by a UNIX audit token. This is a shorthand for asking SecGetRootCode()
 138         for a guest whose "audit" attribute has the given audit token.
 139
 140         @param audit A process audit token for an existing UNIX process on the system.
 141         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 142         @param process On successful return, a SecCode object reference identifying
 143         the requesteed process.
 144         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 145         CSCommon.h or certain other Security framework headers.
 146 */
 147 OSStatus SecCodeCreateWithAuditToken(const audit_token_t *audit,
 148                                      SecCSFlags flags, SecCodeRef *process)
 149     AVAILABLE_MAC_OS_X_VERSION_10_15_AND_LATER;
 150
 151 /* Deprecated and unsafe, DO NOT USE. */
 152 OSStatus SecCodeCreateWithPID(pid_t pid, SecCSFlags flags, SecCodeRef *process)
 153         AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
 154 #endif
 155
 156
 157 /*
 158         @function SecCodeSetDetachedSignature
 159         For a given Code or StaticCode object, explicitly specify the detached signature
 160         data used to verify it.
 161         This call unconditionally overrides any signature embedded in the Code and any
 162         previously specified detached signature; only the signature data specified here
 163         will be used from now on for this Code object. If NULL data is specified, the
 164         code object is returned to its natural signing state (before a detached
 165         signature was first attached to it).
 166         Any call to this function voids all cached validations for the Code object.
 167         Validations will be performed again as needed in the future. This call does not,
 168         by itself, perform or trigger any validations.
 169         Please note that it is possible to have multiple Code objects for the same static
 170         or dynamic code entity in the system. This function only attaches signature data
 171         to the particular SecStaticCodeRef involved. It is your responsibility to understand
 172         the object graph and pick the right one(s).
 173
 174         @param code A Code or StaticCode object whose signature information is to be changed.
 175         @param signature A CFDataRef containing the signature data to be used for validating
 176                 the given Code. This must be exactly the data previously generated as a detached
 177                 signature by the SecCodeSignerAddSignature API or the codesign(1) command with
 178                 the -D/--detached option.
 179                 If signature is NULL, discards any previously set signature data and reverts
 180                 to using the embedded signature, if any. If not NULL, the data is retained and used
 181                 for future validation operations.
 182                 The data may be retained or copied. Behavior is undefined if this object
 183                 is modified after this call before it is replaced through another call to this
 184                 function).
 185         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 186  */
 187 OSStatus SecCodeSetDetachedSignature(SecStaticCodeRef code, CFDataRef signature,
 188         SecCSFlags flags);
 189
 190
 191
 192 /*
 193         @function SecCodeCopyComponent
 194         For a SecStaticCodeRef, directly retrieve the binary blob for a special slot,
 195         optionally checking that its native hash is the one given.
 196
 197         @param code A code or StaticCode object.
 198         @param slot The (positive) special slot number requested.
 199         @param hash A CFDataRef containing the native slot hash for the slot requested.
 200         @result NULL if anything went wrong (including a missing slot), or a CFDataRef
 201                 containing the slot data.
 202  */
 203 CFDataRef SecCodeCopyComponent(SecCodeRef code, int slot, CFDataRef hash);
 204
 205
 206 /*
 207     @function SecCodeValidateFileResource
 208     For a SecStaticCodeRef, check that a given CFData object faithfully represents
 209     a plain-file resource in its resource seal.
 210     This call will fail if the file is missing in the bundle, even if it is optional.
 211
 212     @param code A code or StaticCode object.
 213     @param relativePath A CFStringRef containing the relative path to a sealed resource
 214         file. This path is relative to the resource base, which is either Contents or
 215         the bundle root, depending on bundle format.
 216     @param fileData A CFDataRef containing the exact contents of that resource file.
 217     @param flags Pass kSecCSDefaultFlags.
 218     @result noErr if fileData is the exact content of the file at relativePath at the
 219         time it was signed. Various error codes if it is different, there was no such file,
 220         it was not a plain file, or anything is irregular.
 221 */
 222 OSStatus SecCodeValidateFileResource(SecStaticCodeRef code, CFStringRef relativePath, CFDataRef fileData, SecCSFlags flags);
 223
 224
 225 /*
 226  @constant kSecCSStrictValidateStructure
 227  A subset of the work kSecCSStrictValidate performs, omitting work that
 228  is unnecessary on some platforms. Since the definition of what can be
 229  omitted is in flux, and since we would like to remove that notion
 230  entirely eventually, we makes this a private flag.
 231  */
 232 CF_ENUM(uint32_t) {
 233         // NOTE: These values needs to align with the public definitions for static code validity too.
 234         kSecCSStrictValidateStructure = 1 << 13,
 235         kSecCSSkipRootVolumeExceptions = 1 << 14,
 236     kSecCSSkipXattrFiles = 1 << 15,
 237 };
 238
 239 #if TARGET_OS_OSX
 240 /* Here just to make TAPI happy. */
 241 extern int GKBIS_DS_Store_Present;
 242 extern int GKBIS_Dot_underbar_Present;
 243 extern int GKBIS_Num_localizations;
 244 extern int GKBIS_Num_files;
 245 extern int GKBIS_Num_dirs;
 246 extern int GKBIS_Num_symlinks;
 247 #endif /* TARGET_OS_OSX */
 248
 249 #ifdef __cplusplus
 250 }
 251 #endif
 252
 253 #endif //_H_SECCODE