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 #include <Security/CSCommon.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  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 SecCodeCopySelf
  49         Obtains a SecCode object for the code making the call.
  50         The calling code is determined in a way that is subject to modification over
  51         time, but obeys the following rules. If it is a UNIX process, its process id (pid)
  52         is always used. If it is an active code host that has a dedicated guest, such a guest
  53         is always preferred. If it is a host that has called SecHostSelectGuest, such selection
  54         is considered until revoked.
  55
  56         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  57         @param self Upon successful return, contains a SecCodeRef representing the caller.
  58
  59         @result Upon success, noErr. Upon error, an OSStatus value documented in
  60         CSCommon.h or certain other Security framework headers.
  61  */
  62 OSStatus SecCodeCopySelf(SecCSFlags flags, SecCodeRef *self);
  63
  64
  65 /*!
  66         @function SecCodeCopyStaticCode
  67         Given a SecCode object, locate its origin in the file system and return
  68         a SecStaticCode object representing it.
  69
  70         The link established by this call is generally reliable but is NOT guaranteed
  71         to be secure.
  72
  73         Many API functions taking SecStaticCodeRef arguments will also directly
  74         accept a SecCodeRef and apply this translation implicitly, operating on
  75         its result or returning its error code if any. Each of these functions
  76         calls out that behavior in its documentation.
  77
  78         @param code A valid SecCode object reference representing code running
  79         on the system.
  80         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  81         @param staticCode On successful return, a SecStaticCode object reference representing
  82         the file system origin of the given SecCode. On error, unchanged.
  83         @result Upon success, noErr. Upon error, an OSStatus value documented in
  84         CSCommon.h or certain other Security framework headers.
  85 */
  86 OSStatus SecCodeCopyStaticCode(SecCodeRef code, SecCSFlags flags, SecStaticCodeRef *staticCode);
  87
  88
  89 /*!
  90         @function SecCodeCopyHost
  91         Given a SecCode object, identify the (different) SecCode object that acts
  92         as its host. A SecCode's host acts as a supervisor and controller,
  93         and is the ultimate authority on the its dynamic validity and status.
  94         The host relationship is securely established (absent reported errors).
  95
  96         @param code A valid SecCode object reference representing code running
  97         on the system.
  98         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  99         @param host On successful return, a SecCode object reference identifying
 100         the code's host.
 101         @result Upon success, noErr. Upon error, an OSStatus value documented in
 102         CSCommon.h or certain other Security framework headers.
 103 */
 104 OSStatus SecCodeCopyHost(SecCodeRef guest, SecCSFlags flags, SecCodeRef *host);
 105
 106
 107 /*!
 108         @function SecCodeCopyGuestWithAttributes
 109         Asks a SecCode object acting as a Code Signing host to identify one of
 110         its guests by the type and value of specific attribute(s). Different hosts
 111         support different types and combinations of attributes.
 112
 113         The methods a host uses to identify, separate, and control its guests
 114         are specific to each type of host. This call provides a generic abstraction layer
 115         that allows uniform interrogation of all hosts. A SecCode that does not
 116         act as a host will always return errSecCSNoSuchCode. A SecCode that does
 117         support hosting may return itself to signify that the attribute refers to
 118         itself rather than one of its hosts.
 119
 120         @param host A valid SecCode object reference representing code running
 121         on the system that acts as a Code Signing host. As a special case, passing
 122         NULL indicates that the Code Signing root of trust should be used as a starting
 123         point. Currently, that is the system kernel.
 124         @param attributes A CFDictionary containing zero or more attribute selector
 125         values. Each selector has a CFString key and associated CFTypeRef value.
 126         The key name identifies the attribute being specified; the associated value,
 127         whose type depends on the the key name, selects a particular value or other
 128         constraint on that attribute. Each host only supports particular combinations
 129         of keys and values,     and errors will be returned if any unsupported set is requested.
 130         As a special case, NULL is taken to mean an empty attribute set.
 131         Note that some hosts that support hosting chains (guests being hosts)
 132         may return sub-guests in this call. In other words, do not assume that
 133         a SecCodeRef returned by this call is a direct guest of the queried host
 134         (though it will be a proximate guest, i.e. a guest's guest some way down).
 135         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 136         @param guest On successful return, a SecCode object reference identifying
 137         the particular guest of the host that owns the attribute value(s) specified.
 138         This argument will not be changed if the call fails (does not return noErr).
 139         @result Upon success, noErr. Upon error, an OSStatus value documented in
 140         CSCommon.h or certain other Security framework headers. In particular:
 141         @error errSecCSUnsupportedGuestAttributes The host does not support the attribute
 142         type given by attributeType.
 143         @error errSecCSInvalidAttributeValues The type of value given for a guest
 144         attribute is not supported by the host.
 145         @error errSecCSNoSuchCode The host has no guest with the attribute value given
 146         by attributeValue, even though the value is of a supported type. This may also
 147         be returned if the host code does not currently act as a Code Signing host.
 148         @error errSecCSNotAHost The specified host cannot, in fact, act as a code
 149         host. (It is missing the kSecCodeSignatureHost option flag in its code
 150         signature.)
 151         @error errSecCSMultipleGuests The attributes specified do not uniquely identify
 152         a guest (the specification is ambiguous).
 153 */
 154 extern const CFStringRef kSecGuestAttributeCanonical;
 155 extern const CFStringRef kSecGuestAttributeHash;
 156 extern const CFStringRef kSecGuestAttributeMachPort;
 157 extern const CFStringRef kSecGuestAttributePid;
 158 extern const CFStringRef kSecGuestAttributeArchitecture;
 159 extern const CFStringRef kSecGuestAttributeSubarchitecture;
 160
 161 OSStatus SecCodeCopyGuestWithAttributes(SecCodeRef host,
 162         CFDictionaryRef attributes,     SecCSFlags flags, SecCodeRef *guest);
 163
 164
 165 /*!
 166         @function SecCodeCheckValidity
 167         Performs dynamic validation of the given SecCode object. The call obtains and
 168         verifies the signature on the code object. It checks the validity of only those
 169         sealed components required to establish identity. It checks the SecCode's
 170         dynamic validity status as reported by its host. It ensures that the SecCode's
 171         host is in turn valid. Finally, it validates the code against a SecRequirement
 172         if one is given. The call succeeds if all these conditions are satisfactory.
 173         It fails otherwise.
 174
 175         This call is secure against attempts to modify the file system source of the
 176         SecCode.
 177
 178         @param code The code object to be validated.
 179         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 180         @param requirement An optional code requirement specifying additional conditions
 181         the code object must satisfy to be considered valid. If NULL, no additional
 182         requirements are imposed.
 183         @param errors An optional pointer to a CFErrorRef variable. If the call fails
 184         (and something other than noErr is returned), and this argument is non-NULL,
 185         a CFErrorRef is stored there further describing the nature and circumstances
 186         of the failure. The caller must CFRelease() this error object when done with it.
 187         @result If validation passes, noErr. If validation fails, an OSStatus value
 188         documented in CSCommon.h or certain other Security framework headers.
 189 */
 190 OSStatus SecCodeCheckValidity(SecCodeRef code, SecCSFlags flags,
 191         SecRequirementRef requirement);
 192
 193 OSStatus SecCodeCheckValidityWithErrors(SecCodeRef code, SecCSFlags flags,
 194         SecRequirementRef requirement, CFErrorRef *errors);
 195
 196
 197 /*!
 198         @function SecCodeCopyPath
 199         For a given Code or StaticCode object, returns a URL to a location on disk where the
 200         code object can be found. For single files, the URL points to that file.
 201         For bundles, it points to the directory containing the entire bundle.
 202
 203         This returns the same URL as the kSecCodeInfoMainExecutable key returned
 204         by SecCodeCopySigningInformation.
 205
 206         @param code The Code or StaticCode object to be located. For a Code
 207                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 208         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 209         @param path On successful return, contains a CFURL identifying the location
 210         on disk of the staticCode object.
 211         @result On success, noErr. On error, an OSStatus value
 212         documented in CSCommon.h or certain other Security framework headers.
 213 */
 214 OSStatus SecCodeCopyPath(SecStaticCodeRef staticCode, SecCSFlags flags,
 215         CFURLRef *path);
 216
 217
 218 /*!
 219         @function SecCodeCopyDesignatedRequirement
 220         For a given Code or StaticCode object, determines its Designated Code Requirement.
 221         The Designated Requirement is the SecRequirement that the code believes
 222         should be used to properly identify it in the future.
 223
 224         If the SecCode contains an explicit Designated Requirement, a copy of that
 225         is returned. If it does not, a SecRequirement is implicitly constructed from
 226         its signing authority and its embedded unique identifier. No Designated
 227         Requirement can be obtained from code that is unsigned. Code that is modified
 228         after signature, improperly signed, or has become invalid, may or may not yield
 229         a Designated Requirement. This call does not validate the SecStaticCode argument.
 230
 231         @param code The Code or StaticCode object to be interrogated. For a Code
 232                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 233         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 234         @param requirement On successful return, contains a copy of a SecRequirement
 235         object representing the code's Designated Requirement. On error, unchanged.
 236         @result On success, noErr. On error, an OSStatus value
 237                 documented in CSCommon.h or certain other Security framework headers.
 238 */
 239 OSStatus SecCodeCopyDesignatedRequirement(SecStaticCodeRef code, SecCSFlags flags,
 240         SecRequirementRef *requirement);
 241
 242
 243 /*
 244         @function SecCodeCopySigningInformation
 245         For a given Code or StaticCode object, extract various pieces of information
 246         from its code signature and return them in the form of a CFDictionary. The amount
 247         and detail level of the data is controlled by the flags passed to the call.
 248
 249         If the code exists but is not signed at all, this call will succeed and return
 250         a dictionary that does NOT contain the kSecCodeInfoIdentifier key. This is the
 251         recommended way to check quickly whether a code is signed.
 252
 253         If the signing data for the code is corrupt or invalid, this call may fail or it
 254         may return partial data. To ensure that only valid data is returned (and errors
 255         are raised for invalid data), you must successfully call one of the CheckValidity
 256         functions on the code before calling CopySigningInformation.
 257
 258         @param code The Code or StaticCode object to be interrogated. For a Code
 259                 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
 260                 Note that dynamic information (kSecCSDynamicInformation) cannot be obtained
 261                 for a StaticCode argument.
 262         @param flags Optional flags. Use any or all of the kSecCS*Information flags
 263                 to select what information to return. A generic set of entries is returned
 264                 regardless; you may specify kSecCSDefaultFlags for just those.
 265         @param information A CFDictionary containing information about the code is stored
 266                 here on successful completion. The contents of the dictionary depend on
 267                 the flags passed. Regardless of flags, the kSecCodeInfoIdentifier key is
 268                 always present if the code is signed, and always absent if the code is
 269                 unsigned.
 270                 Note that some of the objects returned are (retained) "live" API objects
 271                 used by the code signing infrastructure. Making changes to these objects
 272                 is unsupported and may cause subsequent code signing operations on the
 273                 affected code to behave in undefined ways.
 274         @result On success, noErr. On error, an OSStatus value
 275                 documented in CSCommon.h or certain other Security framework headers.
 276
 277         Flags:
 278
 279         @constant kSecCSSigningInformation Return cryptographic signing information,
 280                 including the certificate chain and CMS data (if any). For ad-hoc signed
 281                 code, there are no certificates and the CMS data is empty.
 282         @constant kSecCSRequirementInformation Return information about internal code
 283                 requirements embedded in the code. This includes the Designated Requirement.
 284         @constant kSecCSInternalInformation Return internal code signing information.
 285                 This information is for use by Apple, and is subject to change without notice.
 286                 It will not be further documented here.
 287         @constant kSecCSDynamicInformation Return dynamic validity information about
 288                 the Code. The subject code must be a SecCodeRef (not a SecStaticCodeRef).
 289         @constant kSecCSContentInformation Return more information about the file system
 290                 contents making up the signed code on disk. It is not generally advisable to
 291                 make use of this information, but some utilities (such as software-update
 292                 tools) may find it useful.
 293
 294         Dictionary keys:
 295
 296         @constant kSecCodeInfoCertificates A CFArray of SecCertificates identifying the
 297                 certificate chain of the signing certificate as seen by the system. Absent
 298                 for ad-hoc signed code. May be partial or absent in error cases.
 299         @constant kSecCodeInfoChangedFiles A CFArray of CFURLs identifying all files in
 300                 the code that may have been modified by the process of signing it. (In other
 301                 words, files not in this list will not have been touched by the signing operation.)
 302         @constant kSecCodeInfoCMS A CFData containing the CMS cryptographic object that
 303                 secures the code signature. Empty for ad-hoc signed code.
 304         @constant kSecCodeInfoDesignatedRequirement A SecRequirement describing the
 305                 actual Designated Requirement of the code.
 306         @constant kSecCodeInfoEntitlements A CFData containing the embedded entitlement
 307                 blob of the code, if any.
 308         @constant kSecCodeInfoFormat A CFString characterizing the type and format of
 309                 the code. Suitable for display to a (knowledeable) user.
 310         @constant kSecCodeInfoIdentifier A CFString with the actual signing identifier
 311                 sealed into the signature. Absent for unsigned code.
 312         @constant kSecCodeInfoImplicitDesignatedRequirement A SecRequirement describing
 313                 the designated requirement that the system did generate, or would have generated,
 314                 for the code. If the Designated Requirement was implicitly generated, this is
 315                 the same object as kSecCodeInfoDesignatedRequirement; this can be used to test
 316                 for an explicit Designated Requirement.
 317         @constant kSecCodeInfoMainExecutable A CFURL identifying the main executable file
 318                 of the code. For single files, that is the file itself. For bundles, it is the
 319                 main executable as identified by its Info.plist.
 320         @constant kSecCodeInfoPList A retained CFDictionary referring to the secured Info.plist
 321                 as seen by code signing. Absent if no Info.plist is known to the code signing
 322                 subsystem. Note that this is not the same dictionary as the one CFBundle would
 323                 give you (CFBundle is free to add entries to the on-disk plist).
 324         @constant kSecCodeInfoRequirements A CFString describing the internal requirements
 325                 of the code in canonical syntax.
 326         @constant kSecCodeInfoRequirementsData A CFData containing the internal requirements
 327                 of the code as a binary blob.
 328         @constant kSecCodeInfoSource A CFString describing the source of the code signature
 329                 used for the code object. The values are meant to be shown in informational
 330                 displays; do not rely on the precise value returned.
 331         @constant kSecCodeInfoStatus A CFNumber containing the dynamic status word of the
 332                 (running) code. This is a snapshot at the time the API is executed and may be
 333                 out of date by the time you examine it. Do note however that most of the bits
 334                 are sticky and thus some values are permanently reliable. Be careful.
 335         @constant kSecCodeInfoTime A CFDate describing the signing date (securely) embedded
 336                 in the code signature. Note that a signer is able to omit this date or pre-date
 337                 it. Nobody certifies that this was really the date the code was signed; however,
 338                 you do know that this is the date the signer wanted you to see.
 339                 Ad-hoc signatures have no CMS and thus never have secured signing dates.
 340         @constant kSecCodeInfoTrust The (retained) SecTrust object the system uses to
 341                 evaluate the validity of the code's signature. You may use the SecTrust API
 342                 to extract detailed information, particularly for reasons why certificate
 343                 validation may have failed. This object may continue to be used for further
 344                 evaluations of this code; if you make any changes to it, behavior is undefined.
 345         @constant kSecCodeInfoUnique A CFData binary identifier that uniquely identifies
 346                 the static code in question. It can be used to recognize this particular code
 347                 (and none other) now or in the future. Compare to kSecCodeInfoIdentifier, which
 348                 remains stable across (developer-approved) updates.
 349                 This is currently the SHA-1 hash of the code's CodeDirectory. However, future
 350                 versions of the system may use a different algorithm for newly signed code.
 351                 Already-signed code not change the reported value in this case.
 352  */
 353 enum {
 354         kSecCSInternalInformation = 1 << 0,
 355         kSecCSSigningInformation = 1 << 1,
 356         kSecCSRequirementInformation = 1 << 2,
 357         kSecCSDynamicInformation = 1 << 3,
 358         kSecCSContentInformation = 1 << 4
 359 };
 360
 361                                                                                                         /* flag required to get this value */
 362 extern const CFStringRef kSecCodeInfoCertificates;      /* Signing */
 363 extern const CFStringRef kSecCodeInfoChangedFiles;      /* Content */
 364 extern const CFStringRef kSecCodeInfoCMS;                       /* Signing */
 365 extern const CFStringRef kSecCodeInfoDesignatedRequirement; /* Requirement */
 366 extern const CFStringRef kSecCodeInfoEntitlements;      /* Requirement */
 367 extern const CFStringRef kSecCodeInfoFormat;            /* generic */
 368 extern const CFStringRef kSecCodeInfoIdentifier;        /* generic */
 369 extern const CFStringRef kSecCodeInfoImplicitDesignatedRequirement; /* Requirement */
 370 extern const CFStringRef kSecCodeInfoMainExecutable; /* generic */
 371 extern const CFStringRef kSecCodeInfoPList;                     /* generic */
 372 extern const CFStringRef kSecCodeInfoRequirements;      /* Requirement */
 373 extern const CFStringRef kSecCodeInfoRequirementData; /* Requirement */
 374 extern const CFStringRef kSecCodeInfoSource;            /* generic */
 375 extern const CFStringRef kSecCodeInfoStatus;            /* Dynamic */
 376 extern const CFStringRef kSecCodeInfoTime;                      /* Signing */
 377 extern const CFStringRef kSecCodeInfoTrust;                     /* Signing */
 378 extern const CFStringRef kSecCodeInfoUnique;            /* generic */
 379
 380 OSStatus SecCodeCopySigningInformation(SecStaticCodeRef code, SecCSFlags flags,
 381         CFDictionaryRef *information);
 382
 383
 384 /*
 385         @function SecCodeMapMemory
 386         For a given Code or StaticCode object, ask the kernel to accept the signing information
 387         currently attached to it in the caller and use it to validate memory page-ins against it,
 388         updating dynamic validity state accordingly. This change affects all processes that have
 389         the main executable of this code mapped.
 390
 391         @param code A Code or StaticCode object representing the signed code whose main executable
 392                 should be subject to page-in validation.
 393         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 394  */
 395 OSStatus SecCodeMapMemory(SecStaticCodeRef code, SecCSFlags flags);
 396
 397
 398 #ifdef __cplusplus
 399 }
 400 #endif
 401
 402 #endif //_H_SECCODE