lib/CSCommon.h

   1 /*
   2  * Copyright (c) 2006-2010 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
  40 /*
  41         Code Signing specific OSStatus codes.
  42         [Assigned range 0xFFFE_FAxx].
  43 */
  44 enum {
  45         errSecCSUnimplemented =                         -67072, /* unimplemented code signing feature */
  46         errSecCSInvalidObjectRef =                      -67071, /* invalid API object reference */
  47         errSecCSInvalidFlags =                          -67070, /* invalid or inappropriate API flag(s) specified */
  48         errSecCSObjectRequired =                        -67069, /* a required pointer argument was NULL */
  49         errSecCSStaticCodeNotFound =            -67068, /* cannot find code object on disk */
  50         errSecCSUnsupportedGuestAttributes = -67067, /* cannot locate guests using this attribute set */
  51         errSecCSInvalidAttributeValues =        -67066, /* given attribute values are invalid */
  52         errSecCSNoSuchCode =                            -67065, /* host has no guest with the requested attributes */
  53         errSecCSMultipleGuests =                        -67064, /* ambiguous guest specification (host has multiple guests with these attribute values) */
  54         errSecCSGuestInvalid =                          -67063, /* code identity has been invalidated */
  55         errSecCSUnsigned =                                      -67062, /* code object is not signed at all */
  56         errSecCSSignatureFailed =                       -67061, /* invalid signature (code or signature have been modified) */
  57         errSecCSSignatureNotVerifiable =        -67060, /* the code cannot be read by the verifier (file system permissions etc.) */
  58         errSecCSSignatureUnsupported =          -67059, /* unsupported type or version of signature */
  59         errSecCSBadDictionaryFormat =           -67058, /* a required plist file or resource is malformed */
  60         errSecCSResourcesNotSealed =            -67057, /* resources are present but not sealed by signature */
  61         errSecCSResourcesNotFound =                     -67056, /* code has no resources but signature indicates they must be present */
  62         errSecCSResourcesInvalid =                      -67055, /* the sealed resource directory is invalid */
  63         errSecCSBadResource =                           -67054, /* a sealed resource is missing or invalid */
  64         errSecCSResourceRulesInvalid =          -67053, /* invalid resource specification rule(s) */
  65         errSecCSReqInvalid =                            -67052, /* invalid or corrupted code requirement(s) */
  66         errSecCSReqUnsupported =                        -67051, /* unsupported type or version of code requirement(s) */
  67         errSecCSReqFailed =                                     -67050, /* code failed to satisfy specified code requirement(s) */
  68         errSecCSBadObjectFormat =                       -67049, /* object file format unrecognized, invalid, or unsuitable */
  69         errSecCSInternalError =                         -67048, /* internal error in Code Signing subsystem */
  70         errSecCSHostReject =                            -67047, /* code rejected its host */
  71         errSecCSNotAHost =                                      -67046, /* attempt to specify guest of code that is not a host */
  72         errSecCSSignatureInvalid =                      -67045, /* invalid or unsupported format for signature */
  73         errSecCSHostProtocolRelativePath =      -67044, /* host protocol violation - absolute guest path required */
  74         errSecCSHostProtocolContradiction =     -67043, /* host protocol violation - contradictory hosting modes */
  75         errSecCSHostProtocolDedicationError = -67042, /* host protocol violation - operation not allowed with/for a dedicated guest */
  76         errSecCSHostProtocolNotProxy =          -67041, /* host protocol violation - proxy hosting not engaged */
  77         errSecCSHostProtocolStateError =        -67040, /* host protocol violation - invalid guest state change request */
  78         errSecCSHostProtocolUnrelated =         -67039, /* host protocol violation - the given guest is not a guest of the given host */
  79                                                                          /* -67038 obsolete (no longer issued) */
  80         errSecCSNotSupported =                          -67037, /* operation inapplicable or not supported for this type of code */
  81         errSecCSCMSTooLarge =                           -67036, /* signature too large to embed (size limitation of on-disk representation) */
  82         errSecCSHostProtocolInvalidHash =       -67035, /* host protocol violation - invalid guest hash */
  83         errSecCSStaticCodeChanged =                     -67034, /* the code on disk does not match what is running */
  84         errSecCSDBDenied =                                      -67033, /* permission to use a database denied */
  85         errSecCSDBAccess =                                      -67032, /* cannot access a database */
  86         errSecCSSigDBDenied = errSecCSDBDenied,
  87         errSecCSSigDBAccess = errSecCSDBAccess,
  88         errSecCSHostProtocolInvalidAttribute = -67031, /* host returned invalid or inconsistent guest attributes */
  89         errSecCSInfoPlistFailed =                       -67030, /* invalid Info.plist (plist or signature have been modified) */
  90         errSecCSNoMainExecutable =                      -67029, /* the code has no main executable file */
  91         errSecCSBadBundleFormat =                       -67028, /* bundle format unrecognized, invalid, or unsuitable */
  92         errSecCSNoMatches =                             -67027, /* no matches for search or update operation */
  93 };
  94
  95
  96 /*
  97  * Code Signing specific CFError "user info" keys.
  98  * In calls that can return CFErrorRef indications, if a CFErrorRef is actually
  99  * returned, its "user info" dictionary may contain some of the following keys
 100  * to more closely describe the circumstances of the failure.
 101  * Do not rely on the presence of any particular key to categorize a problem;
 102  * always use the primary OSStatus return for that. The data contained under
 103  * these keys is always supplemental and optional.
 104  */
 105 extern const CFStringRef kSecCFErrorArchitecture;       /* CFStringRef: name of architecture causing the problem */
 106 extern const CFStringRef kSecCFErrorPattern;            /* CFStringRef: invalid resource selection pattern encountered */
 107 extern const CFStringRef kSecCFErrorResourceSeal;       /* CFTypeRef: invalid component in resource seal (CodeResources) */
 108 extern const CFStringRef kSecCFErrorResourceAdded;      /* CFURLRef: unsealed resource found */
 109 extern const CFStringRef kSecCFErrorResourceAltered; /* CFURLRef: modified resource found */
 110 extern const CFStringRef kSecCFErrorResourceMissing; /* CFURLRef: sealed (non-optional) resource missing */
 111 extern const CFStringRef kSecCFErrorInfoPlist;          /* CFTypeRef: Info.plist dictionary or component thereof found invalid */
 112 extern const CFStringRef kSecCFErrorGuestAttributes; /* CFTypeRef: Guest attribute set of element not accepted */
 113 extern const CFStringRef kSecCFErrorRequirementSyntax; /* CFStringRef: compilation error for Requirement source */
 114 extern const CFStringRef kSecCFErrorPath;                       /* CFURLRef: subcomponent containing the error */
 115
 116
 117 /*!
 118         @typedef SecCodeRef
 119         This is the type of a reference to running code.
 120
 121         In many (but not all) calls, this can be passed to a SecStaticCodeRef
 122         argument, which performs an implicit SecCodeCopyStaticCode call and
 123         operates on the result.
 124 */
 125 typedef struct __SecCode *SecCodeRef;                           /* running code */
 126
 127 /*!
 128         @typedef SecStaticCodeRef
 129         This is the type of a reference to static code on disk.
 130 */
 131 typedef struct __SecCode const *SecStaticCodeRef;       /* code on disk */
 132
 133 /*!
 134         @typedef SecRequirementRef
 135         This is the type of a reference to a code requirement.
 136 */
 137 typedef struct __SecRequirement *SecRequirementRef;     /* code requirement */
 138
 139
 140 /*!
 141         @typedef SecGuestRef
 142         An abstract handle to identify a particular Guest in the context of its Host.
 143
 144         Guest handles are assigned by the host at will, with kSecNoGuest (zero) being
 145         reserved as the null value. They can be reused for new children if desired.
 146 */
 147 typedef u_int32_t SecGuestRef;
 148
 149 enum {
 150         kSecNoGuest = 0,                /* not a valid SecGuestRef */
 151 };
 152
 153
 154 /*!
 155         @typedef SecCSFlags
 156         This is the type of flags arguments to Code Signing API calls.
 157         It provides a bit mask of request and option flags. All of the bits in these
 158         masks are reserved to Apple; if you set any bits not defined in these headers,
 159         the behavior is generally undefined.
 160
 161         This list describes the flags that are shared among several Code Signing API calls.
 162         Flags that only apply to one call are defined and documented with that call.
 163         Global flags are assigned from high order down (31 -> 0); call-specific flags
 164         are assigned from the bottom up (0 -> 31).
 165
 166         @constant kSecCSDefaultFlags
 167         When passed to a flags argument throughout, indicates that default behavior
 168         is desired. Do not mix with other flags values.
 169         @constant kSecCSConsiderExpiration
 170         When passed to a call that performs code validation, requests that code signatures
 171         made by expired certificates be rejected. By default, expiration of participating
 172         certificates is not automatic grounds for rejection.
 173 */
 174 typedef uint32_t SecCSFlags;
 175
 176 enum {
 177         kSecCSDefaultFlags = 0,                                 /* no particular flags (default behavior) */
 178
 179         kSecCSConsiderExpiration = 1 << 31,             /* consider expired certificates invalid */
 180         kSecCSEnforceRevocationChecks = 1 << 30,        /* force revocation checks regardless of preference settings */
 181 };
 182
 183
 184 /*!
 185         @typedef SecCodeSignatureFlags
 186         This is the type of option flags that can be embedded in a code signature
 187         during signing, and that govern the use of the signature thereafter.
 188         Some of these flags can be set through the codesign(1) command's --options
 189         argument; some are set implicitly based on signing circumstances; and all
 190         can be set with the kSecCodeSignerFlags item of a signing information dictionary.
 191
 192         @constant kSecCodeSignatureHost
 193         Indicates that the code may act as a host that controls and supervises guest
 194         code. If this flag is not set in a code signature, the code is never considered
 195         eligible to be a host, and any attempt to act like one will be ignored or rejected.
 196         @constant kSecCodeSignatureAdhoc
 197         The code has been sealed without a signing identity. No identity may be retrieved
 198         from it, and any code requirement placing restrictions on the signing identity
 199         will fail. This flag is set by the code signing API and cannot be set explicitly.
 200         @constant kSecCodeSignatureForceHard
 201         Implicitly set the "hard" status bit for the code when it starts running.
 202         This bit indicates that the code prefers to be denied access to a resource
 203         if gaining such access would cause its invalidation. Since the hard bit is
 204         sticky, setting this option bit guarantees that the code will always have
 205         it set.
 206         @constant kSecCodeSignatureForceKill
 207         Implicitly set the "kill" status bit for the code when it starts running.
 208         This bit indicates that the code wishes to be terminated with prejudice if
 209         it is ever invalidated. Since the kill bit is sticky, setting this option bit
 210         guarantees that the code will always be dynamically valid, since it will die
 211         immediately     if it becomes invalid.
 212         @constant kSecCodeSignatureForceExpiration
 213         Forces the kSecCSConsiderExpiration flag on all validations of the code.
 214  */
 215 typedef uint32_t SecCodeSignatureFlags;
 216
 217 enum {
 218         kSecCodeSignatureHost = 0x0001,                 /* may host guest code */
 219         kSecCodeSignatureAdhoc = 0x0002,                /* must be used without signer */
 220         kSecCodeSignatureForceHard = 0x0100,    /* always set HARD mode on launch */
 221         kSecCodeSignatureForceKill = 0x0200,    /* always set KILL mode on launch */
 222         kSecCodeSignatureForceExpiration = 0x0400, /* force certificate expiration checks */
 223 };
 224
 225
 226 /*!
 227         @typedef SecCodeStatus
 228         The code signing system attaches a set of status flags to each running code.
 229         These flags are maintained by the code's host, and can be read by anyone.
 230         A code may change its own flags, a host may change its guests' flags,
 231         and root may change anyone's flags.     However, these flags are sticky in that
 232         each can change in only one direction (and never back, for the lifetime of the code).
 233         Not even root can violate this restriction.
 234
 235         There are other flags in SecCodeStatus that are not publicly documented.
 236         Do not rely on them, and do not ever attempt to explicitly set them.
 237
 238         @constant kSecCodeStatusValid
 239         Indicates that the code is dynamically valid, i.e. it started correctly
 240         and has not been invalidated since then. The valid bit can only be cleared.
 241
 242         Warning: This bit is not your one-stop shortcut to determining the validity     of code.
 243         It represents the dynamic component of the full validity function; if this
 244         bit is unset, the code is definitely invalid, but the converse is not always true.
 245         In fact, code hosts may represent the outcome of some delayed static validation work in this bit,
 246         and thus it strictly represents a blend of (all of) dynamic and (some of) static validity,
 247         depending on the implementation of the particular host managing the code. You can (only)
 248         rely that (1) dynamic invalidation will clear this bit; and (2) the combination
 249         of static validation and dynamic validity (as performed by the SecCodeCheckValidity* APIs)
 250         will give a correct answer.
 251
 252         @constant kSecCodeStatusHard
 253         Indicates that the code prefers to be denied access to resources if gaining access
 254         would invalidate it. This bit can only be set.
 255         It is undefined whether code that is marked hard and is already invalid will still
 256         be denied access to a resource that would invalidate it if it were still valid. That is,
 257         the code may or may not get access to such a resource while being invalid, and that choice
 258         may appear random.
 259
 260         @constant kSecCodeStatusKill
 261         Indicates that the code wants to be killed (terminated) if it ever loses its validity.
 262         This bit can only be set. Code that has the kill flag set will never be dynamically invalid
 263         (and live). Note however that a change in static validity does not necessarily trigger instant
 264         death.
 265 */
 266 typedef uint32_t SecCodeStatus;
 267 enum {
 268         kSecCodeStatusValid =   0x0001,
 269         kSecCodeStatusHard =    0x0100,
 270         kSecCodeStatusKill =    0x0200,
 271 };
 272
 273
 274 /*!
 275         @typedef SecRequirementType
 276         An enumeration indicating different types of internal requirements for code.
 277  */
 278 typedef uint32_t SecRequirementType;
 279
 280 enum {
 281         kSecHostRequirementType =                       1,      /* what hosts may run us */
 282         kSecGuestRequirementType =                      2,      /* what guests we may run */
 283         kSecDesignatedRequirementType =         3,      /* designated requirement */
 284         kSecLibraryRequirementType =            4,      /* what libraries we may link against */
 285         kSecPluginRequirementType =                     5,      /* what plug-ins we may load */
 286         kSecInvalidRequirementType,                             /* invalid type of Requirement (must be last) */
 287         kSecRequirementTypeCount = kSecInvalidRequirementType /* number of valid requirement types */
 288 };
 289
 290
 291 #ifdef __cplusplus
 292 }
 293 #endif
 294
 295 #endif //_H_CSCOMMON