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