OSX/libsecurity_codesigning/lib/CSCommon.h

   1 /*
   2  * Copyright (c) 2006-2014 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 CSCommon
  26         CSCommon is the common header of all Code Signing API headers.
  27         It defines types, constants, and error codes.
  28 */
  29 #ifndef _H_CSCOMMON
  30 #define _H_CSCOMMON
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #include <stdint.h>
  37 #include <CoreFoundation/CoreFoundation.h>
  38
  39 CF_ASSUME_NONNULL_BEGIN
  40
  41 /*
  42         Code Signing specific OSStatus codes.
  43         [Assigned range 0xFFFE_FAxx].
  44 */
  45 CF_ENUM(OSStatus) {
  46         errSecCSUnimplemented =                         -67072, /* unimplemented code signing feature */
  47         errSecCSInvalidObjectRef =                      -67071, /* invalid API object reference */
  48         errSecCSInvalidFlags =                          -67070, /* invalid or inappropriate API flag(s) specified */
  49         errSecCSObjectRequired =                        -67069, /* a required pointer argument was NULL */
  50         errSecCSStaticCodeNotFound =            -67068, /* cannot find code object on disk */
  51         errSecCSUnsupportedGuestAttributes = -67067, /* cannot locate guests using this attribute set */
  52         errSecCSInvalidAttributeValues =        -67066, /* given attribute values are invalid */
  53         errSecCSNoSuchCode =                            -67065, /* host has no guest with the requested attributes */
  54         errSecCSMultipleGuests =                        -67064, /* ambiguous guest specification (host has multiple guests with these attribute values) */
  55         errSecCSGuestInvalid =                          -67063, /* code identity has been invalidated */
  56         errSecCSUnsigned =                                      -67062, /* code object is not signed at all */
  57         errSecCSSignatureFailed =                       -67061, /* invalid signature (code or signature have been modified) */
  58         errSecCSSignatureNotVerifiable =        -67060, /* the code cannot be read by the verifier (file system permissions etc.) */
  59         errSecCSSignatureUnsupported =          -67059, /* unsupported type or version of signature */
  60         errSecCSBadDictionaryFormat =           -67058, /* a required plist file or resource is malformed */
  61         errSecCSResourcesNotSealed =            -67057, /* resources are present but not sealed by signature */
  62         errSecCSResourcesNotFound =                     -67056, /* code has no resources but signature indicates they must be present */
  63         errSecCSResourcesInvalid =                      -67055, /* the sealed resource directory is invalid */
  64         errSecCSBadResource =                           -67054, /* a sealed resource is missing or invalid */
  65         errSecCSResourceRulesInvalid =          -67053, /* invalid resource specification rule(s) */
  66         errSecCSReqInvalid =                            -67052, /* invalid or corrupted code requirement(s) */
  67         errSecCSReqUnsupported =                        -67051, /* unsupported type or version of code requirement(s) */
  68         errSecCSReqFailed =                                     -67050, /* code failed to satisfy specified code requirement(s) */
  69         errSecCSBadObjectFormat =                       -67049, /* object file format unrecognized, invalid, or unsuitable */
  70         errSecCSInternalError =                         -67048, /* internal error in Code Signing subsystem */
  71         errSecCSHostReject =                            -67047, /* code rejected its host */
  72         errSecCSNotAHost =                                      -67046, /* attempt to specify guest of code that is not a host */
  73         errSecCSSignatureInvalid =                      -67045, /* invalid or unsupported format for signature */
  74         errSecCSHostProtocolRelativePath =      -67044, /* host protocol violation - absolute guest path required */
  75         errSecCSHostProtocolContradiction =     -67043, /* host protocol violation - contradictory hosting modes */
  76         errSecCSHostProtocolDedicationError = -67042, /* host protocol violation - operation not allowed with/for a dedicated guest */
  77         errSecCSHostProtocolNotProxy =          -67041, /* host protocol violation - proxy hosting not engaged */
  78         errSecCSHostProtocolStateError =        -67040, /* host protocol violation - invalid guest state change request */
  79         errSecCSHostProtocolUnrelated =         -67039, /* host protocol violation - the given guest is not a guest of the given host */
  80                                                                          /* -67038 obsolete (no longer issued) */
  81         errSecCSNotSupported =                          -67037, /* operation inapplicable or not supported for this type of code */
  82         errSecCSCMSTooLarge =                           -67036, /* signature too large to embed (size limitation of on-disk representation) */
  83         errSecCSHostProtocolInvalidHash =       -67035, /* host protocol violation - invalid guest hash */
  84         errSecCSStaticCodeChanged =                     -67034, /* the code on disk does not match what is running */
  85         errSecCSDBDenied =                                      -67033, /* permission to use a database denied */
  86         errSecCSDBAccess =                                      -67032, /* cannot access a database */
  87         errSecCSSigDBDenied =               -67033, /* permission to use a database denied */
  88         errSecCSSigDBAccess =               -67032, /* cannot access a database */
  89         errSecCSHostProtocolInvalidAttribute = -67031, /* host returned invalid or inconsistent guest attributes */
  90         errSecCSInfoPlistFailed =                       -67030, /* invalid Info.plist (plist or signature have been modified) */
  91         errSecCSNoMainExecutable =                      -67029, /* the code has no main executable file */
  92         errSecCSBadBundleFormat =                       -67028, /* bundle format unrecognized, invalid, or unsuitable */
  93         errSecCSNoMatches =                                     -67027, /* no matches for search or update operation */
  94         errSecCSFileHardQuarantined =           -67026, /* File created by an AppSandbox, exec/open not allowed */
  95         errSecCSOutdated =                                      -67025, /* presented data is out of date */
  96         errSecCSDbCorrupt =                                     -67024, /* a system database or file is corrupt */
  97         errSecCSResourceDirectoryFailed =       -67023, /* invalid resource directory (directory or signature have been modified) */
  98         errSecCSUnsignedNestedCode =            -67022, /* nested code is unsigned */
  99         errSecCSBadNestedCode =                         -67021, /* nested code is modified or invalid */
 100         errSecCSBadCallbackValue =                      -67020, /* monitor callback returned invalid value */
 101         errSecCSHelperFailed =                          -67019, /* the codesign_allocate helper tool cannot be found or used */
 102         errSecCSVetoed =                                        -67018,
 103         errSecCSBadLVArch =                                     -67017, /* library validation flag cannot be used with an i386 binary */
 104         errSecCSResourceNotSupported =          -67016, /* unsupported resource found (something not a directory, file or symlink) */
 105         errSecCSRegularFile =                           -67015, /* the main executable or Info.plist must be a regular file (no symlinks, etc.) */
 106         errSecCSUnsealedAppRoot =                       -67014, /* unsealed contents present in the bundle root */
 107         errSecCSWeakResourceRules =                     -67013, /* resource envelope is obsolete (custom omit rules) */
 108         errSecCSDSStoreSymlink =                        -67012, /* .DS_Store files cannot be a symlink */
 109         errSecCSAmbiguousBundleFormat =         -67011, /* bundle format is ambiguous (could be app or framework) */
 110         errSecCSBadMainExecutable =                     -67010, /* main executable failed strict validation */
 111         errSecCSBadFrameworkVersion =           -67009, /* embedded framework contains modified or invalid version */
 112         errSecCSUnsealedFrameworkRoot =         -67008, /* unsealed contents present in the root directory of an embedded framework */
 113         errSecCSWeakResourceEnvelope =          -67007, /* resource envelope is obsolete (version 1 signature) */
 114     errSecCSCancelled =                                 -67006, /* operation was terminated by explicit cancelation */
 115         errSecCSInvalidPlatform =                       -67005, /* invalid platform identifier or platform mismatch */
 116         errSecCSTooBig =                                        -67004, /* code is too big for current signing format */
 117         errSecCSInvalidSymlink =                        -67003, /* invalid destination for symbolic link in bundle */
 118         errSecCSNotAppLike =                            -67002, /* the code is valid but does not seem to be an app */
 119         errSecCSBadDiskImageFormat =            -67001, /* disk image format unrecognized, invalid, or unsuitable */
 120         errSecCSUnsupportedDigestAlgorithm = -67000, /* a requested signature digest algorithm is not supported */
 121         errSecCSInvalidAssociatedFileData =     -66999, /* resource fork, Finder information, or similar detritus not allowed */
 122         errSecCSInvalidTeamIdentifier =         -66998, /* a Team Identifier string is invalid */
 123         errSecCSBadTeamIdentifier =             -66997, /* a Team Identifier is wrong or inappropriate */
 124         errSecCSSignatureUntrusted =            -66996, /* signature is valid but signer is not trusted */
 125         errSecMultipleExecSegments =            -66995, /* the image contains multiple executable segments */
 126         errSecCSInvalidEntitlements =           -66994, /* invalid entitlement plist */
 127         errSecCSInvalidRuntimeVersion =         -66993, /* an invalid runtime version was explicitly set */
 128         errSecCSRevokedNotarization =           -66992, /* notarization indicates this code has been revoked */
 129 };
 130
 131 /*
 132  * Code Signing specific CFError "user info" keys.
 133  * In calls that can return CFErrorRef indications, if a CFErrorRef is actually
 134  * returned, its "user info" dictionary may contain some of the following keys
 135  * to more closely describe the circumstances of the failure.
 136  * Do not rely on the presence of any particular key to categorize a problem;
 137  * always use the primary OSStatus return for that. The data contained under
 138  * these keys is always supplemental and optional.
 139  */
 140 extern const CFStringRef kSecCFErrorArchitecture;       /* CFStringRef: name of architecture causing the problem */
 141 extern const CFStringRef kSecCFErrorPattern;            /* CFStringRef: invalid resource selection pattern encountered */
 142 extern const CFStringRef kSecCFErrorResourceSeal;       /* CFTypeRef: invalid component in resource seal (CodeResources) */
 143 extern const CFStringRef kSecCFErrorResourceAdded;      /* CFURLRef: unsealed resource found */
 144 extern const CFStringRef kSecCFErrorResourceAltered; /* CFURLRef: modified resource found */
 145 extern const CFStringRef kSecCFErrorResourceMissing; /* CFURLRef: sealed (non-optional) resource missing */
 146 extern const CFStringRef kSecCFErrorResourceSideband; /* CFURLRef: sealed resource has invalid sideband data (resource fork, etc.) */
 147 extern const CFStringRef kSecCFErrorInfoPlist;          /* CFTypeRef: Info.plist dictionary or component thereof found invalid */
 148 extern const CFStringRef kSecCFErrorGuestAttributes; /* CFTypeRef: Guest attribute set of element not accepted */
 149 extern const CFStringRef kSecCFErrorRequirementSyntax; /* CFStringRef: compilation error for Requirement source */
 150 extern const CFStringRef kSecCFErrorPath;                       /* CFURLRef: subcomponent containing the error */
 151
 152 /*!
 153         @typedef SecCodeRef
 154         This is the type of a reference to running code.
 155
 156         In many (but not all) calls, this can be passed to a SecStaticCodeRef
 157         argument, which performs an implicit SecCodeCopyStaticCode call and
 158         operates on the result.
 159 */
 160 typedef struct CF_BRIDGED_TYPE(id) __SecCode *SecCodeRef;       /* running code */
 161
 162 /*!
 163         @typedef SecStaticCodeRef
 164         This is the type of a reference to static code on disk.
 165 */
 166 typedef struct CF_BRIDGED_TYPE(id) __SecCode const *SecStaticCodeRef;   /* code on disk */
 167
 168 /*!
 169         @typedef SecRequirementRef
 170         This is the type of a reference to a code requirement.
 171 */
 172 typedef struct CF_BRIDGED_TYPE(id) __SecRequirement *SecRequirementRef; /* code requirement */
 173
 174
 175 /*!
 176         @typedef SecGuestRef
 177         An abstract handle to identify a particular Guest in the context of its Host.
 178
 179         Guest handles are assigned by the host at will, with kSecNoGuest (zero) being
 180         reserved as the null value. They can be reused for new children if desired.
 181 */
 182 typedef u_int32_t SecGuestRef;
 183
 184 CF_ENUM(SecGuestRef) {
 185         kSecNoGuest = 0,                /* not a valid SecGuestRef */
 186 };
 187
 188
 189 /*!
 190         @typedef SecCSFlags
 191         This is the type of flags arguments to Code Signing API calls.
 192         It provides a bit mask of request and option flags. All of the bits in these
 193         masks are reserved to Apple; if you set any bits not defined in these headers,
 194         the behavior is generally undefined.
 195
 196         This list describes the flags that are shared among several Code Signing API calls.
 197         Flags that only apply to one call are defined and documented with that call.
 198         Global flags are assigned from high order down (31 -> 0); call-specific flags
 199         are assigned from the bottom up (0 -> 31).
 200
 201         @constant kSecCSDefaultFlags
 202         When passed to a flags argument throughout, indicates that default behavior
 203         is desired. Do not mix with other flags values.
 204         @constant kSecCSConsiderExpiration
 205         When passed to a call that performs code validation, requests that code signatures
 206         made by expired certificates be rejected. By default, expiration of participating
 207         certificates is not automatic grounds for rejection.
 208 */
 209 typedef CF_OPTIONS(uint32_t, SecCSFlags) {
 210     kSecCSDefaultFlags = 0,                                     /* no particular flags (default behavior) */
 211
 212     kSecCSConsiderExpiration = 1U << 31,                /* consider expired certificates invalid */
 213     kSecCSEnforceRevocationChecks = 1 << 30,    /* force revocation checks regardless of preference settings */
 214     kSecCSNoNetworkAccess = 1 << 29,            /* do not use the network, cancels "kSecCSEnforceRevocationChecks"  */
 215         kSecCSReportProgress = 1 << 28,                 /* make progress report call-backs when configured */
 216     kSecCSCheckTrustedAnchors = 1 << 27, /* build certificate chain to system trust anchors, not to any self-signed certificate */
 217         kSecCSQuickCheck = 1 << 26,             /* (internal) */
 218     kSecCSApplyEmbeddedPolicy = 1 << 25, /* Apply Embedded (iPhone) policy regardless of the platform we're running on */
 219 };
 220
 221
 222 /*!
 223         @typedef SecCodeSignatureFlags
 224         This is the type of option flags that can be embedded in a code signature
 225         during signing, and that govern the use of the signature thereafter.
 226         Some of these flags can be set through the codesign(1) command's --options
 227         argument; some are set implicitly based on signing circumstances; and all
 228         can be set with the kSecCodeSignerFlags item of a signing information dictionary.
 229
 230         @constant kSecCodeSignatureHost
 231         Indicates that the code may act as a host that controls and supervises guest
 232         code. If this flag is not set in a code signature, the code is never considered
 233         eligible to be a host, and any attempt to act like one will be ignored or rejected.
 234         @constant kSecCodeSignatureAdhoc
 235         The code has been sealed without a signing identity. No identity may be retrieved
 236         from it, and any code requirement placing restrictions on the signing identity
 237         will fail. This flag is set by the code signing API and cannot be set explicitly.
 238         @constant kSecCodeSignatureForceHard
 239         Implicitly set the "hard" status bit for the code when it starts running.
 240         This bit indicates that the code prefers to be denied access to a resource
 241         if gaining such access would cause its invalidation. Since the hard bit is
 242         sticky, setting this option bit guarantees that the code will always have
 243         it set.
 244         @constant kSecCodeSignatureForceKill
 245         Implicitly set the "kill" status bit for the code when it starts running.
 246         This bit indicates that the code wishes to be terminated with prejudice if
 247         it is ever invalidated. Since the kill bit is sticky, setting this option bit
 248         guarantees that the code will always be dynamically valid, since it will die
 249         immediately     if it becomes invalid.
 250         @constant kSecCodeSignatureForceExpiration
 251         Forces the kSecCSConsiderExpiration flag on all validations of the code.
 252         @constant kSecCodeSignatureRuntime
 253         Instructs the kernel to apply runtime hardening policies as required by the
 254         hardened runtime version
 255         @constant kSecCodeSignatureLinkerSigned
 256         The code was automatically signed by the linker. This signature should be
 257         ignored in any new signing operation.
 258  */
 259 typedef CF_OPTIONS(uint32_t, SecCodeSignatureFlags) {
 260         kSecCodeSignatureHost = 0x0001,                 /* may host guest code */
 261         kSecCodeSignatureAdhoc = 0x0002,                /* must be used without signer */
 262         kSecCodeSignatureForceHard = 0x0100,    /* always set HARD mode on launch */
 263         kSecCodeSignatureForceKill = 0x0200,    /* always set KILL mode on launch */
 264         kSecCodeSignatureForceExpiration = 0x0400, /* force certificate expiration checks */
 265         kSecCodeSignatureRestrict = 0x0800, /* restrict dyld loading */
 266         kSecCodeSignatureEnforcement = 0x1000, /* enforce code signing */
 267         kSecCodeSignatureLibraryValidation = 0x2000, /* library validation required */
 268         kSecCodeSignatureRuntime = 0x10000, /* apply runtime hardening policies */
 269         kSecCodeSignatureLinkerSigned = 0x20000, /* identify that the signature was auto-generated by the linker*/
 270 };
 271
 272 /*!
 273         @typedef SecCodeStatus
 274         The code signing system attaches a set of status flags to each running code.
 275         These flags are maintained by the code's host, and can be read by anyone.
 276         A code may change its own flags, a host may change its guests' flags,
 277         and root may change anyone's flags.     However, these flags are sticky in that
 278         each can change in only one direction (and never back, for the lifetime of the code).
 279         Not even root can violate this restriction.
 280
 281         There are other flags in SecCodeStatus that are not publicly documented.
 282         Do not rely on them, and do not ever attempt to explicitly set them.
 283
 284         @constant kSecCodeStatusValid
 285         Indicates that the code is dynamically valid, i.e. it started correctly
 286         and has not been invalidated since then. The valid bit can only be cleared.
 287
 288         Warning: This bit is not your one-stop shortcut to determining the validity     of code.
 289         It represents the dynamic component of the full validity function; if this
 290         bit is unset, the code is definitely invalid, but the converse is not always true.
 291         In fact, code hosts may represent the outcome of some delayed static validation work in this bit,
 292         and thus it strictly represents a blend of (all of) dynamic and (some of) static validity,
 293         depending on the implementation of the particular host managing the code. You can (only)
 294         rely that (1) dynamic invalidation will clear this bit; and (2) the combination
 295         of static validation and dynamic validity (as performed by the SecCodeCheckValidity* APIs)
 296         will give a correct answer.
 297
 298         @constant kSecCodeStatusHard
 299         Indicates that the code prefers to be denied access to resources if gaining access
 300         would invalidate it. This bit can only be set.
 301         It is undefined whether code that is marked hard and is already invalid will still
 302         be denied access to a resource that would invalidate it if it were still valid. That is,
 303         the code may or may not get access to such a resource while being invalid, and that choice
 304         may appear random.
 305
 306         @constant kSecCodeStatusKill
 307         Indicates that the code wants to be killed (terminated) if it ever loses its validity.
 308         This bit can only be set. Code that has the kill flag set will never be dynamically invalid
 309         (and live). Note however that a change in static validity does not necessarily trigger instant
 310         death.
 311
 312         @constant kSecCodeStatusDebugged
 313         Indicated that code has been debugged by another process that was allowed to do so. The debugger
 314         causes this to be set when it attachs.
 315
 316         @constant kSecCodeStatusPlatform
 317         Indicates the code is platform code, shipping with the operating system and signed by Apple.
 318 */
 319 typedef CF_OPTIONS(uint32_t, SecCodeStatus) {
 320         kSecCodeStatusValid     = 0x00000001,
 321         kSecCodeStatusHard      = 0x00000100,
 322         kSecCodeStatusKill      = 0x00000200,
 323         kSecCodeStatusDebugged  = 0x10000000,
 324         kSecCodeStatusPlatform  = 0x04000000,
 325 };
 326
 327
 328 /*!
 329         @typedef SecRequirementType
 330         An enumeration indicating different types of internal requirements for code.
 331  */
 332 typedef CF_ENUM(uint32_t, SecRequirementType) {
 333         kSecHostRequirementType =                       1,      /* what hosts may run us */
 334         kSecGuestRequirementType =                      2,      /* what guests we may run */
 335         kSecDesignatedRequirementType =         3,      /* designated requirement */
 336         kSecLibraryRequirementType =            4,      /* what libraries we may link against */
 337         kSecPluginRequirementType =                     5,      /* what plug-ins we may load */
 338         kSecInvalidRequirementType,                             /* invalid type of Requirement (must be last) */
 339         kSecRequirementTypeCount = kSecInvalidRequirementType /* number of valid requirement types */
 340 };
 341
 342
 343 /*!
 344  Types of cryptographic digests (hashes) used to hold code signatures
 345  together.
 346
 347  Each combination of type, length, and other parameters is a separate
 348  hash type; we don't understand "families" here.
 349
 350  These type codes govern the digest links that connect a CodeDirectory
 351  to its subordinate data structures (code pages, resources, etc.)
 352  They do not directly control other uses of hashes (such as those used
 353  within X.509 certificates and CMS blobs).
 354  */
 355 typedef CF_ENUM(uint32_t, SecCSDigestAlgorithm) {
 356         kSecCodeSignatureNoHash                                                 =  0,   /* null value */
 357         kSecCodeSignatureHashSHA1                                               =  1,   /* SHA-1 */
 358         kSecCodeSignatureHashSHA256                                             =  2,   /* SHA-256 */
 359         kSecCodeSignatureHashSHA256Truncated                    =  3,   /* SHA-256 truncated to first 20 bytes */
 360         kSecCodeSignatureHashSHA384                                             =  4,   /* SHA-384 */
 361     kSecCodeSignatureHashSHA512                     =  5,   /* SHA-512 */
 362 };
 363
 364 CF_ASSUME_NONNULL_END
 365
 366 #ifdef __cplusplus
 367 }
 368 #endif
 369
 370 #endif //_H_CSCOMMON