lib/SecCode.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 SecCode
  26         SecCode represents separately indentified running code in the system.
  27         In addition to UNIX processes, this can also include (with suitable support)
  28         scripts, applets, widgets, etc.
  29 */
  30 #ifndef _H_SECCODE
  31 #define _H_SECCODE
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 #include <Security/CSCommon.h>
  38
  39
  40 /*!
  41         @function SecCodeGetTypeID
  42         Returns the type identifier of all SecCode instances.
  43 */
  44 CFTypeID SecCodeGetTypeID(void);
  45
  46
  47 /*!
  48         @function SecGetRootCode
  49         Obtains a SecCode object for the running code that hosts the entire system.
  50         This object usually represents the system kernel. It is always considered
  51         valid and is implicitly trusted by everyone.
  52
  53         This object has no host.
  54
  55         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  56
  57         @result An object reference to the root Code. This call should never fail.
  58         If this call returns NULL, Code Signing is unusable.
  59 */
  60 SecCodeRef SecGetRootCode(SecCSFlags flags);
  61
  62
  63 /*!
  64         @function SecCodeCopySelf
  65         Obtains a SecCode object for the code making the call.
  66         The calling code is determined in a way that is subject to modification over
  67         time, but obeys the following rules. If it is a UNIX process, its process id (pid)
  68         is always used. If it is an active code host that has a dedicated guest, such a guest
  69         is always preferred. If it is a host that has called SecHostSelectGuest, such selection
  70         is considered until revoked.
  71
  72         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  73
  74         @result Upon success, noErr. Upon error, an OSStatus value documented in
  75         CSCommon.h or certain other Security framework headers.
  76  */
  77 OSStatus SecCodeCopySelf(SecCSFlags flags, SecCodeRef *self);
  78
  79
  80
  81 /*!
  82         @function SecCodeCopyStaticCode
  83         Given a SecCode object, locate its origin in the file system and return
  84         a SecStaticCode object representing it.
  85
  86         The link established by this call is generally reliable but is NOT guaranteed
  87         to be secure.
  88
  89         Many API functions taking SecStaticCodeRef arguments will also directly
  90         accept a SecCodeRef and apply this translation implicitly, operating on
  91         its result or returning its error code if any. Each of these functions
  92         calls out that behavior in its documentation.
  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         @param staticCode On successful return, a SecStaticCode object reference representing
  98         the file system origin of the given SecCode. On error, unchanged.
  99         @result Upon success, noErr. Upon error, an OSStatus value documented in
 100         CSCommon.h or certain other Security framework headers.
 101 */
 102 OSStatus SecCodeCopyStaticCode(SecCodeRef code, SecCSFlags flags, SecStaticCodeRef *staticCode);
 103
 104
 105 /*!
 106         @function SecCodeCopyHost
 107         Given a SecCode object, identify the (different) SecCode object that acts
 108         as its host. A SecCode's host acts as a supervisor and controller,
 109         and is the ultimate authority on the its dynamic validity and status.
 110         The host relationship is securely established (absent reported errors).
 111
 112         @param code A valid SecCode object reference representing code running
 113         on the system.
 114         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 115         @param host On successful return, a SecCode object reference identifying
 116         the code's host.
 117         @result Upon success, noErr. Upon error, an OSStatus value documented in
 118         CSCommon.h or certain other Security framework headers.
 119 */
 120 OSStatus SecCodeCopyHost(SecCodeRef guest, SecCSFlags flags, SecCodeRef *host);
 121
 122
 123 /*!
 124         @function SecCodeCopyGuestWithAttributes
 125         Asks a SecCode object acting as a Code Signing host to identify one of
 126         its guests by the type and value of specific attribute(s). Different hosts
 127         support different types and combinations of attributes.
 128
 129         The methods a host uses to identify, separate, and control its guests
 130         are specific to each type of host. This call provides a generic abstraction layer
 131         that allows uniform interrogation of all hosts. A SecCode that does not
 132         act as a host will always return errSecCSNoSuchCode. A SecCode that does
 133         support hosting may return itself to signify that the attribute refers to
 134         itself rather than one of its hosts.
 135
 136         @param host A valid SecCode object reference representing code running
 137         on the system that acts as a Code Signing host. As a special case, passing
 138         NULL indicates that the Code Signing root of trust should be used as a starting
 139         point. Currently, that is the system kernel.
 140         @param attributes A CFDictionary containing one or more attribute selector
 141         values. Each selector has a CFString key and associated CFTypeRef value.
 142         The key name identifies the attribute being selected; the associated value,
 143         whose type depends on the the key name, selects a particular value or other
 144         constraint on that attribute. Each host only supports particular combinations
 145         of keys and values,     and errors will be returned if any unsupported set is requested.
 146         As a special case, NULL is taken to mean an empty attribute set.
 147         Also note that some hosts that support hosting chains (guests being hosts)
 148         may return sub-guests in this call. In other words, do not assume that
 149         a SecCodeRef returned by this call is an immediate guest of the queried host
 150         (though it will be a proximate guest, i.e. a guest's guest some way down).
 151         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 152         @param guest On successful return, a SecCode object reference identifying
 153         the particular guest of the host that owns the attribute value specified.
 154         This argument will not be changed if the call fails (does not return noErr).
 155         @result Upon success, noErr. Upon error, an OSStatus value documented in
 156         CSCommon.h or certain other Security framework headers. In particular:
 157         @error errSecCSUnsupportedGuestAttributes The host does not support the attribute
 158         type given by attributeType.
 159         @error errSecCSInvalidAttributeValues The type of value given for a guest
 160         attribute is not supported by the host.
 161         @error errSecCSNoSuchCode The host has no guest with the attribute value given
 162         by attributeValue, even though the value is of a supported type. This may also
 163         be returned if the host code does not currently act as a Code Signing host.
 164         @error errSecCSNotAHost The putative host cannot, in fact, act as a code
 165         host. (It is missing the kSecCodeSignatureHost option flag in its code
 166         signature.)
 167         @error errSecCSMultipleGuests The attributes specified do not uniquely identify
 168         a guest (the specification is ambiguous).
 169 */
 170 extern const CFStringRef kSecGuestAttributePid;
 171 extern const CFStringRef kSecGuestAttributeCanonical;
 172 extern const CFStringRef kSecGuestAttributeMachPort;
 173
 174 OSStatus SecCodeCopyGuestWithAttributes(SecCodeRef host,
 175         CFDictionaryRef attributes,     SecCSFlags flags, SecCodeRef *guest);
 176
 177
 178 /*!
 179         @function SecCodeCreateWithPID
 180         Asks the kernel to return a SecCode object for a process identified
 181         by a UNIX process id (pid). This is a shorthand for asking SecGetRootCode()
 182         for a guest whose "pid" attribute has the given pid value.
 183
 184         @param pid A process id for an existing UNIX process on the system.
 185         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 186         @param process On successful return, a SecCode object reference identifying
 187         the requesteed process.
 188         @result Upon success, noErr. Upon error, an OSStatus value documented in
 189         CSCommon.h or certain other Security framework headers.
 190 */
 191 OSStatus SecCodeCreateWithPID(pid_t pid, SecCSFlags flags, SecCodeRef *process);
 192
 193
 194 /*!
 195         @function SecCodeCheckValidity
 196         Performs dynamic validation of the given SecCode object. The call obtains and
 197         verifies the signature on the code object. It checks the validity of only those
 198         sealed components required to establish identity. It checks the SecCode's
 199         dynamic validity status as reported by its host. It ensures that the SecCode's
 200         host is in turn valid. Finally, it validates the code against a SecRequirement
 201         if one is given. The call succeeds if all these conditions are satisfactory.
 202         It fails otherwise.
 203
 204         This call is secure against attempts to modify the file system source of the
 205         SecCode.
 206
 207         @param code The code object to be validated.
 208         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 209         @param requirement An optional code requirement specifying additional conditions
 210         the code object must satisfy to be considered valid. If NULL, no additional
 211         requirements are imposed.
 212         @param errors An optional pointer to a CFErrorRef variable. If the call fails
 213         (and something other than noErr is returned), and this argument is non-NULL,
 214         a CFErrorRef is stored there further describing the nature and circumstances
 215         of the failure. The caller must CFRelease() this error object when done with it.
 216         @result If validation passes, noErr. If validation fails, an OSStatus value
 217         documented in CSCommon.h or certain other Security framework headers.
 218 */
 219 OSStatus SecCodeCheckValidity(SecCodeRef code, SecCSFlags flags,
 220         SecRequirementRef requirement);
 221
 222 OSStatus SecCodeCheckValidityWithErrors(SecCodeRef code, SecCSFlags flags,
 223         SecRequirementRef requirement, CFErrorRef *errors);
 224
 225
 226 /*!
 227         @function SecCodeCopyPath
 228         For a given Code or StaticCode object, returns a URL to a location on disk where the
 229         code object can be found. For single files, the URL points to that file.
 230         For bundles, it points to the directory containing the entire bundle.
 231
 232         This returns the same URL as the kSecCodeInfoMainExecutable key returned
 233         by SecCodeCopySigningInformation.
 234
 235         @param code The Code or StaticCode object to be located. For a Code
 236                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 237         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 238         @param path On successful return, contains a CFURL identifying the location
 239         on disk of the staticCode object.
 240         @result On success, noErr. On error, an OSStatus value
 241         documented in CSCommon.h or certain other Security framework headers.
 242 */
 243 OSStatus SecCodeCopyPath(SecStaticCodeRef staticCode, SecCSFlags flags,
 244         CFURLRef *path);
 245
 246
 247 /*!
 248         @function SecCodeCopyDesignatedRequirement
 249         For a given Code or StaticCode object, determines its Designated Code Requirement.
 250         The Designated Requirement is the SecRequirement that the code believes
 251         should be used to properly identify it in the future.
 252
 253         If the SecCode contains an explicit Designated Requirement, a copy of that
 254         is returned. If it does not, a SecRequirement is implicitly constructed from
 255         its signing authority and its embedded unique identifier. No Designated
 256         Requirement can be obtained from code that is unsigned. Code that is modified
 257         after signature, improperly signed, or has become invalid, may or may not yield
 258         a Designated Requirement. This call does not validate the SecStaticCode argument.
 259
 260         @param code The Code or StaticCode object to be interrogated. For a Code
 261                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 262         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 263         @param requirement On successful return, contains a copy of a SecRequirement
 264         object representing the code's Designated Requirement. On error, unchanged.
 265         @result On success, noErr. On error, an OSStatus value
 266         documented in CSCommon.h or certain other Security framework headers.
 267 */
 268 OSStatus SecCodeCopyDesignatedRequirement(SecStaticCodeRef code, SecCSFlags flags,
 269         SecRequirementRef *requirement);
 270
 271
 272 /*
 273         @function SecCodeCopySigningInformation
 274         For a given Code or StaticCode object, extract various pieces of information
 275         from its code signature and return them in the form of a CFDictionary. The amount
 276         and detail level of the data is controlled by the flags passed to the call.
 277
 278         If the code exists but is not signed at all, this call will succeed and return
 279         a dictionary that does NOT contain the kSecCodeInfoIdentifier key. This is the
 280         recommended way to check quickly whether a code is signed.
 281
 282         If the signing data for the code is corrupt or invalid, this call may fail or it
 283         may return partial data. To ensure that only valid data is returned (and errors
 284         are raised for invalid data), you must successfully call one of the CheckValidity
 285         functions on the code before calling CopySigningInformation.
 286
 287         @param code The Code or StaticCode object to be interrogated. For a Code
 288                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 289         @param flags Optional flags. Use any or all of the kSecCS*Information flags
 290                 to select what information to return. A generic set of entries is returned
 291                 regardless; you may specify kSecCSDefaultFlags for just those.
 292         @param information A CFDictionary containing information about the code is stored
 293                 here on successful completion. The contents of the dictionary depend on
 294                 the flags passed. Regardless of flags, the kSecCodeInfoIdentifier key is always present
 295                 if the code is signed, and absent if the code is entirely unsigned.
 296         @result On success, noErr. On error, an OSStatus value
 297         documented in CSCommon.h or certain other Security framework headers.
 298
 299         @constant kSecCSSigningInformation Return cryptographic signing information,
 300                 including the certificate chain and CMS data.
 301         @constant kSecCSRequirementInformation Return information about internal code
 302                 requirements embedded in the code.
 303         @constant kSecCSInternalInformation Return internal code signing information.
 304                 This information is for use by Apple, and is subject to change.
 305                 It will not be further documented here.
 306         @constant kSecCSDynamicInformation Return dynamic validity information about
 307                 the Code. The subject code must be a SecCodeRef (not a SecStaticCodeRef).
 308         @constant kSecCSContentInformation Return more information about the file system
 309                 contents making up the signed code on disk. It is not generally advisable to
 310                 make use of this information, but some utilities (such as software-update
 311                 tools) may find it useful.
 312  */
 313 enum {
 314         kSecCSInternalInformation = 1 << 0,
 315         kSecCSSigningInformation = 1 << 1,
 316         kSecCSRequirementInformation = 1 << 2,
 317         kSecCSDynamicInformation = 1 << 3,
 318         kSecCSContentInformation = 1 << 4
 319 };
 320
 321                                                                                                         /* flag required to get this value */
 322 extern const CFStringRef kSecCodeInfoCertificates;      /* Signing */
 323 extern const CFStringRef kSecCodeInfoChangedFiles;      /* Content */
 324 extern const CFStringRef kSecCodeInfoCMS;                       /* Signing */
 325 extern const CFStringRef kSecCodeInfoTime;                      /* Signing */
 326 extern const CFStringRef kSecCodeInfoDesignatedRequirement; /* Requirement */
 327 extern const CFStringRef kSecCodeInfoFormat;            /* generic */
 328 extern const CFStringRef kSecCodeInfoIdentifier;        /* generic */
 329 extern const CFStringRef kSecCodeInfoImplicitDesignatedRequirement; /* Requirement */
 330 extern const CFStringRef kSecCodeInfoMainExecutable; /* generic */
 331 extern const CFStringRef kSecCodeInfoPList;                     /* generic */
 332 extern const CFStringRef kSecCodeInfoRequirements;      /* Requirement */
 333 extern const CFStringRef kSecCodeInfoStatus;            /* Dynamic */
 334 extern const CFStringRef kSecCodeInfoTrust;                     /* Signing */
 335
 336 OSStatus SecCodeCopySigningInformation(SecStaticCodeRef code, SecCSFlags flags,
 337         CFDictionaryRef *information);
 338
 339
 340 /*
 341         @function SecCodeSetDetachedSignature
 342         For a given Code or StaticCode object, explicitly specify the detached signature
 343         data used to verify it.
 344         This call unconditionally overrides any signature embedded in the Code and any
 345         previously specified detached signature; only the signature data specified here
 346         will be used from now on for this Code object. If NULL data is specified, this
 347         call reverts to using any embedded signature.
 348         Any call to this function voids all cached validations for the Code object.
 349         Validations will be performed again as needed in the future. This call does not,
 350         by itself, perform or trigger any validations.
 351         Please note that it is possible to have multiple Code objects for the same static
 352         or dynamic code entity in the system. This function only attaches signature data
 353         to the particular SecStaticCodeRef involved. It is your responsibility to understand
 354         the object graph and pick the right one(s).
 355
 356         @param code A Code or StaticCode object whose signature information is to be changed.
 357         @param signature A CFDataRef containing the signature data to be used for validating
 358                 the given Code. This must be exactly the data previously generated as a detached
 359                 signature by the SecCodeSignerAddSignature API or the codesign(1) command with
 360                 the -D/--detached option.
 361                 If signature is NULL, discards any previously set signature data and reverts
 362                 to using the embedded signature, if any. If not NULL, the data is retained and used
 363                 for future validation operations.
 364         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 365  */
 366 OSStatus SecCodeSetDetachedSignature(SecStaticCodeRef code, CFDataRef signature,
 367         SecCSFlags flags);
 368
 369
 370 /*
 371         @function SecCodeMapMemory
 372         For a given Code or StaticCode object, ask the kernel to accept the signing information
 373         currently attached to it in the caller and use it to validate memory page-ins against it,
 374         updating dynamic validity state accordingly. This change affects all processes that have
 375         the main executable of this code mapped.
 376
 377         @param code A Code or StaticCode object representing the signed code whose main executable
 378                 should be subject to page-in validation.
 379         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 380  */
 381 OSStatus SecCodeMapMemory(SecStaticCodeRef code, SecCSFlags flags);
 382
 383
 384 #ifdef __cplusplus
 385 }
 386 #endif
 387
 388 #endif //_H_SECCODE