lib/CSCommon.h

   1 /*
   2  * Copyright (c) 2006-2007 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,                       /* invalid API object reference */
  47         errSecCSInvalidFlags,                           /* invalid or inapprpopriate API flag(s) specified */
  48         errSecCSObjectRequired,                         /* a required pointer argument was NULL */
  49         errSecCSStaticCodeNotFound,                     /* cannot find code object on disk */
  50         errSecCSUnsupportedGuestAttributes,     /* cannot locate guests using this attribute set */
  51         errSecCSInvalidAttributeValues,         /* given attribute values are invalid */
  52         errSecCSNoSuchCode,                                     /* host has no guest with the requested attributes */
  53         errSecCSMultipleGuests,                         /* host has multiple guests with this attribute value */
  54         errSecCSGuestInvalid,                           /* code identity has been invalidated */
  55         errSecCSUnsigned,                                       /* code object is not signed */
  56         errSecCSSignatureFailed,                        /* code or signature modified */
  57         errSecCSSignatureNotVerifiable,         /* signature cannot be read, e.g., due to a filesystem that maps root to an unprivileged user */
  58         errSecCSSignatureUnsupported,           /* unsupported type or version of signature */
  59         errSecCSBadDictionaryFormat,            /* a required plist file or resource is malformed */
  60         errSecCSResourcesNotSealed,                     /* resources are not sealed by signature */
  61         errSecCSResourcesNotFound,                      /* cannot find sealed resources in code */
  62         errSecCSResourcesInvalid,                       /* the sealed resource directory is invalid */
  63         errSecCSBadResource,                            /* a sealed resource is missing or invalid */
  64         errSecCSResourceRulesInvalid,           /* invalid resource selection rule(s) */
  65         errSecCSReqInvalid,                                     /* invalid or corrupted code requirement(s) */
  66         errSecCSReqUnsupported,                         /* unsupported type or version of code requirement(s) */
  67         errSecCSReqFailed,                                      /* failed to satisfy code requirement(s) */
  68         errSecCSBadObjectFormat,                        /* object file format invalid or unsuitable */
  69         errSecCSInternalError,                          /* internal error in Code Signing subsystem */
  70         errSecCSHostReject,                                     /* code rejected its host */
  71         errSecCSNotAHost,                                       /* this code is not a host */
  72         errSecCSSignatureInvalid,                       /* invalid format for signature */
  73         errSecCSHostProtocolRelativePath,       /* host protocol violation - absolute guest path required */
  74         errSecCSHostProtocolContradiction,      /* host protocol violation - contradictory hosting modes */
  75         errSecCSHostProtocolDedicationError, /* host protocol violation - operation not allowed with/for a dedicated guest */
  76         errSecCSHostProtocolNotProxy,           /* host protocol violation - proxy hosting not engaged */
  77         errSecCSHostProtocolStateError,         /* host protocol violation - invalid guest state change request */
  78         errSecCSHostProtocolUnrelated,          /* host protocol violation - the given guest is not a guest of the given host */
  79         errSecCSInvalidOperation,                       /* requested operation is not valid */
  80         errSecCSNotSupported,                           /* operation not supported for this type of code */
  81         errSecCSCMSTooLarge,                            /* signature too large to embed */
  82         errSecCSHostProtocolInvalidHash,        /* host protocol violation - invalid guest hash */
  83         errSecCSStaticCodeChanged,                      /* the program on disk does not match what is running */
  84         errSecCSSigDBDenied,                            /* access to signature database denied */
  85         errSecCSSigDBAccess,                            /* cannot access signature database */
  86         errSecCSHostProtocolInvalidAttribute, /* host returned invalid or inconsistent guest attributes */
  87 };
  88
  89
  90 /*
  91  * Code Signing specific CFError "user info" keys.
  92  * In calls that can return CFErrorRef indications, if a CFErrorRef is actually
  93  * returned, its "user info" dictionary will contain some (but not all) of the
  94  * following keys to more closely describe the circumstances of the failure.
  95  */
  96 extern const CFStringRef kSecCFErrorPattern;            /* CFStringRef: invalid resource selection pattern encountered */
  97 extern const CFStringRef kSecCFErrorResourceSeal;       /* CFTypeRef: invalid component in resource seal (CodeResources) */
  98 extern const CFStringRef kSecCFErrorResourceAdded;      /* CFURLRef: unsealed resource found */
  99 extern const CFStringRef kSecCFErrorResourceAltered; /* CFURLRef: modified resource found */
 100 extern const CFStringRef kSecCFErrorResourceMissing; /* CFURLRef: sealed (non-optional) resource missing */
 101 extern const CFStringRef kSecCFErrorInfoPlist;          /* CFTypeRef: Info.plist dictionary or component found invalid */
 102 extern const CFStringRef kSecCFErrorGuestAttributes; /* CFTypeRef: Guest attribute set of element not accepted */
 103 extern const CFStringRef kSecCFErrorRequirementSyntax; /* CFStringRef: compilation error for Requirement source */
 104
 105
 106 /*!
 107         @typedef SecCodeRef
 108         This is the type of a reference to running code.
 109
 110         In many (but not all) calls, this can be passed to a SecStaticCodeRef
 111         argument, which performs an implicit SecCodeCopyStaticCode call and
 112         operates on the result.
 113 */
 114 typedef struct __SecCode *SecCodeRef;                           /* running code */
 115
 116 /*!
 117         @typedef SecStaticCodeRef
 118         This is the type of a reference to static code on disk.
 119 */
 120 typedef struct __SecCode const *SecStaticCodeRef;       /* code on disk */
 121
 122 /*!
 123         @typedef SecRequirementRef
 124         This is the type of a reference to a code requirement.
 125 */
 126 typedef struct __SecRequirement *SecRequirementRef;     /* code requirement */
 127
 128
 129 /*!
 130         @typedef SecGuestRef
 131         An abstract handle to identify a particular Guest in the context of its Host.
 132
 133         Guest handles are assigned by the host at will, with kSecNoGuest (zero) being
 134         reserved as the null value. They can be reused for new children if desired.
 135 */
 136 typedef u_int32_t SecGuestRef;
 137
 138 enum {
 139         kSecNoGuest = 0,                /* not a valid SecGuestRef */
 140 };
 141
 142
 143 /*!
 144         @typedef SecCSFlags
 145         This is the type of flags arguments to Code Signing API calls.
 146         It provides a bit mask of request and option flags. All of the bits in these
 147         masks are reserved to Apple; if you set any bits not defined in these headers,
 148         the behavior is generally undefined.
 149
 150         This list describes the flags that are shared among several Code Signing API calls.
 151         Flags that only apply to one call are defined and documented with that call.
 152         Global flags are assigned from high order down (31 -> 0); call-specific flags
 153         are assigned from the bottom up (0 -> 31).
 154
 155         @constant kSecCSDefaultFlags
 156         When passed to a flags argument throughout, indicates that default behavior
 157         is desired. Do not mix with other flags values.
 158         @constant kSecCSConsiderExpiration
 159         When passed to a call that performs code validation, requests that code signatures
 160         made by expired certificates be rejected. By default, expiration of participating
 161         certificates is not automatic grounds for rejection.
 162 */
 163 typedef uint32_t SecCSFlags;
 164
 165 enum {
 166         kSecCSDefaultFlags = 0,                                 /* no particular flags (default behavior) */
 167
 168         kSecCSConsiderExpiration = 1 << 31,             /* consider expired certificates invalid */
 169 };
 170
 171
 172 /*!
 173         @typedef SecCodeSignatureFlags
 174         This is the type of option flags that can be embedded in a code signature
 175         during signing, and that govern the use of the signature thereafter.
 176         Some of these flags can be set through the codesign(1) command's --options
 177         argument; some are set implicitly based on signing circumstances; and all
 178         can be set with the kSecCodeSignerFlags item of a signing information dictionary.
 179
 180         @constant kSecCodeSignatureHost
 181         Indicates that the code may act as a host that controls and supervises guest
 182         code. If this flag is not set in a code signature, the code is never considered
 183         eligible to be a host, and any attempt to act like one will be ignored.
 184         @constant kSecCodeSignatureAdhoc
 185         The code has been sealed without a signing identity. No identity may be retrieved
 186         from it, and any code requirement placing restrictions on the signing identity
 187         will fail. This flag is set by the code signing API and cannot be set explicitly.
 188         @constant kSecCodeSignatureForceHard
 189         Implicitly set the "hard" status bit for the code when it starts running.
 190         This bit indicates that the code prefers to be denied access to a resource
 191         if gaining such access would cause its invalidation. Since the hard bit is
 192         sticky, setting this option bit guarantees that the code will always have
 193         it set.
 194         @constant kSecCodeSignatureForceKill
 195         Implicitly set the "kill" status bit for the code when it starts running.
 196         This bit indicates that the code wishes to be terminated with prejudice if
 197         it is ever invalidated. Since the kill bit is sticky, setting this option bit
 198         guarantees that the code will always be valid, since it will die immediately
 199         if it becomes invalid.
 200         @constant kSecCodeSignatureForceExpiration
 201         Forces the kSecCSConsiderExpiration flag on all validations of the code.
 202  */
 203 typedef uint32_t SecCodeSignatureFlags;
 204
 205 enum {
 206         kSecCodeSignatureHost = 0x0001,                 /* may host guest code */
 207         kSecCodeSignatureAdhoc = 0x0002,                /* must be used without signer */
 208         kSecCodeSignatureForceHard = 0x0100,    /* always set HARD mode on launch */
 209         kSecCodeSignatureForceKill = 0x0200,    /* always set KILL mode on launch */
 210         kSecCodeSignatureForceExpiration = 0x0400, /* force certificat expiration checks */
 211 };
 212
 213
 214 /*!
 215         @typedef SecCodeStatus
 216         The code signing system attaches a set of operational flags to each running code.
 217         These flags are maintained by the code's host, and can be read by anyone.
 218         A code may change its own flags, and root may change anyone's flags.
 219         However, these flags are sticky in that each can change in only one direction
 220         (and never back, for the lifetime of the code). Not even root can violate this restriction.
 221
 222         There are other flags in SecCodeStatus that are not publicly documented.
 223         Do not rely on them.
 224
 225         @constant kSecCodeStatusValid
 226         Indicates that the code is dynamically valid, i.e. it started properly signed
 227         and has not been invalidated since it started. The valid bit can only be cleared.
 228         Note that this bit does not make any representations on the static validity of the code.
 229         @constant kSecCodeStatusHard
 230         Indicates that the code prefers to be denied access to resources if gaining access
 231         would invalidate it. This bit can only be set.
 232         It is undefined whether a code that is marked hard and is already invalid will still
 233         be denied access to a resource that would invalidate it if it were still valid. That is,
 234         the code may or may not get access to such a resource while being invalid, and that choice
 235         may seem random.
 236         @constant kSecCodeStatusKill
 237         Indicates that the code wants to be killed (terminated) if it ever loses its validity.
 238         This bit can only be set. Code that has the kill flag set will never be invalid (and live).
 239 */
 240 typedef uint32_t SecCodeStatus;
 241 enum {
 242         kSecCodeStatusValid =   0x0001,
 243         kSecCodeStatusHard =    0x0100,
 244         kSecCodeStatusKill =    0x0200,
 245 };
 246
 247
 248 /*!
 249         @typedef SecRequirementType
 250         An enumeration indicating different types of internal requirements for code.
 251  */
 252 typedef uint32_t SecRequirementType;
 253
 254 enum {
 255         kSecHostRequirementType = 1,                    /* what hosts may run us */
 256         kSecGuestRequirementType = 2,                   /* what guests we may run */
 257         kSecDesignatedRequirementType = 3,              /* designated requirement */
 258         kSecLibraryRequirementType = 4,                 /* what libraries we may link against */
 259         kSecInvalidRequirementType,                             /* invalid type of Requirement (must be last) */
 260         kSecRequirementTypeCount = kSecInvalidRequirementType /* number of valid requirement types */
 261 };
 262
 263
 264 #ifdef __cplusplus
 265 }
 266 #endif
 267
 268 #endif //_H_CSCOMMON