OSX/libsecurity_codesigning/lib/SecCodeHost.h

   1 /*
   2  * Copyright (c) 2006-2007,2011,2013 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 SecCodeHost
  26         This header provides the hosting API for Code Signing. These are calls
  27         that are (only) made by code that is hosting guests.
  28         In the context of Code Signing, a Host is code that creates and manages other
  29         codes from which it defends its own integrity. As part of that duty, it maintains
  30         state for each of its children, and answers questions about them.
  31
  32         A Host is externally represented by a SecCodeRef (it is a SecCode object).
  33         So is a Guest. There is no specific API object to represent Hosts or Guests.
  34         Within the Hosting API, guests are identified by simple numeric handles that
  35         are unique and valid only in the context of their specific host.
  36
  37         The functions in this API always apply to the Host making the API calls.
  38         They cannot be used to (directly) interrogate another host.
  39 */
  40 #ifndef _H_SECCODEHOST
  41 #define _H_SECCODEHOST
  42
  43 #include <Security/CSCommon.h>
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 CF_ASSUME_NONNULL_BEGIN
  50
  51 /*!
  52         @header SecCodeHost
  53         This header describes the Code Signing Hosting API. These are calls made
  54         by code that wishes to become a Host in the Code Signing Host/Guest infrastructure.
  55         Hosting allows the caller to establish separate, independent code identities
  56         (SecCodeRefs) for parts of itself, usually because it is loading and managing
  57         code in the form of scripts, plugins, etc.
  58
  59         The Hosting API does not directly connect to the Code Signing Client APIs.
  60         Certain calls in the client API will cause internal queries to hosts about their
  61         guests. The Host side of these queries is managed through this API. The results
  62         will eventually be delivered to client API callers in appropriate form.
  63
  64         If code never calls any of the Hosting API functions, it is deemed to not have
  65         guests and not act as a Host. This is the default and requires no action.
  66
  67         Hosting operates in one of two modes, dynamic or proxy. Whichever mode is first
  68         engaged prevails for the lifetime of the caller. There is no way to switch between
  69         the two, and calling an API belonging to the opposite mode will fail.
  70
  71         In dynamic hosting mode, the caller provides a Mach port that receives direct
  72         queries about its guests. Dynamic mode is engaged by calling SecHostSetHostingPort.
  73
  74         In proxy hosting mode, the caller provides information about its guests as
  75         guests are created, removed, or change status. The system caches this information
  76         and answers queries about guests from this pool of information. The caller is not
  77         directly involved in answering such queries, and has no way to intervene.
  78 */
  79
  80
  81 /*!
  82         @function SecHostCreateGuest
  83         Create a new Guest and describe its initial properties.
  84
  85         This call activates Hosting Proxy Mode. From here on, the system will record
  86         guest information provided through SecHostCreateGuest, SecHostSetGuestStatus, and
  87         SecHostRemoveGuest, and report hosting status to callers directly. This mode
  88         is incompatible with dynamic host mode as established by a call to SecHostSetHostingPort.
  89
  90         @param host Pass kSecNoGuest to create a guest of the process itself.
  91         To create a guest of another guest (extending the hosting chain), pass the SecGuestRef
  92         of the guest to act as the new guest's host. If host has a dedicated guest,
  93         it will be deemed to be be the actual host, recursively.
  94         @param status The Code Signing status word for the new guest. These are combinations
  95         of the kSecCodeStatus* flags in <Security/CSCommon.h>. Note that the proxy will enforce
  96         the rules for the stickiness of these bits. In particular, if you don't pass the
  97         kSecCodeStatusValid bit during creation, your new guest will be born invalid and will
  98         never have a valid identity.
  99         @param path The canonical path to the guest's code on disk. This is the path you would
 100         pass to SecStaticCodeCreateWithPath to make a static code object reference. You must
 101         use an absolute path.
 102         @param attributes An optional CFDictionaryRef containing attributes that can be used
 103         to locate this particular guest among all of the caller's guests. The "canonical"
 104         attribute is automatically added for the value of guestRef. If you pass NULL,
 105         no other attributes are established for the guest.
 106         While any key can be used in the attributes dictionary, the kSecGuestAttribute* constants
 107         (in SecCode.h) are conventionally used here.
 108         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior, or
 109         a combination of the flags defined below for special features.
 110         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 111         CSCommon.h or certain other Security framework headers.
 112         @param newGuest Upon successful creation of the new guest, the new SecGuestRef
 113         that should be used to identify the new guest from here on.
 114
 115         @constant kSecCSDedicatedHost Declares dedicated hosting for the given host.
 116         In dedicated hosting, the host has exactly one guest (the one this call is
 117         introducing), and the host will spend all of its time from here on running
 118         that guest (or on its behalf). This declaration is irreversable for the lifetime
 119         of the host. Note that this is a declaration about the given host, and is not
 120         binding upon other hosts on either side of the hosting chain, though they in turn
 121         may declare dedicated hosting if desired.
 122         It is invalid to declare dedicated hosting if other guests have already been
 123         introduced for this host, and it is invalid to introduce additional guests
 124         for this host after this call.
 125         @constant kSecCSGenerateGuestHash Ask the proxy to generate the binary identifier
 126         (hash of CodeDirectory) from the copy on disk at the path given. This is not optimal
 127         since an attacker with write access may be able to substitute a different copy just
 128         in time, but it is convenient. For optimal security, the host should calculate the
 129         hash from the loaded in-memory signature of its guest and pass the result as an
 130         attribute with key kSecGuestAttributeHash.
 131 */
 132 CF_ENUM(uint32_t) {
 133         kSecCSDedicatedHost = 1 << 0,
 134         kSecCSGenerateGuestHash = 1 << 1,
 135 };
 136
 137 OSStatus SecHostCreateGuest(SecGuestRef host,
 138         uint32_t status, CFURLRef path, CFDictionaryRef __nullable attributes,
 139         SecCSFlags flags, SecGuestRef * __nonnull newGuest);
 140
 141
 142 /*!
 143         @function SecHostRemoveGuest
 144         Announce that the guest with the given guestRef has permanently disappeared.
 145         It removes all memory of the guest from the hosting system. You cannot remove
 146         a dedicated guest.
 147
 148         @param host The SecGuestRef that was used to create guest. You cannot specify
 149         a proximate host (host of a host) here. However, the substitution for dedicated
 150         guests described for SecHostCreateGuest also takes place here.
 151         @param guest The handle for a Guest previously created with SecHostCreateGuest
 152         that has not previously been destroyed. This guest is to be destroyed now.
 153         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 154         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 155         CSCommon.h or certain other Security framework headers.
 156 */
 157 OSStatus SecHostRemoveGuest(SecGuestRef host, SecGuestRef guest, SecCSFlags flags);
 158
 159
 160 /*!
 161         @function SecHostSelectGuest
 162         Tell the Code Signing host subsystem that the calling thread will now act
 163         on behalf of the given Guest. This must be a valid Guest previously created
 164         with SecHostCreateGuest.
 165
 166         @param guestRef The handle for a Guest previously created with SecHostCreateGuest
 167         on whose behalf this thread will act from now on. This setting will be remembered
 168         until it is changed (or the thread terminates).
 169         To indicate that the thread will act on behalf of the Host itself (rather than
 170         any Guest), pass kSecNoGuest.
 171         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 172         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 173         CSCommon.h or certain other Security framework headers.
 174 */
 175 OSStatus SecHostSelectGuest(SecGuestRef guestRef, SecCSFlags flags);
 176
 177
 178 /*!
 179         @function SecHostSelectedGuest
 180         Retrieve the handle for the Guest currently selected for the calling thread.
 181
 182         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 183         @param guestRef Will be assigned the SecGuestRef currently in effect for
 184         the calling thread. If no Guest is active on this thread (i.e. the thread
 185         is acting for the Host), the return value is kSecNoGuest.
 186         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 187         CSCommon.h or certain other Security framework headers.
 188 */
 189 OSStatus SecHostSelectedGuest(SecCSFlags flags, SecGuestRef * __nonnull guestRef);
 190
 191
 192 /*!
 193         @function SecHostSetGuestStatus
 194         Updates the status of a particular guest.
 195
 196         @param guestRef The handle for a Guest previously created with SecHostCreateGuest
 197         on whose behalf this thread will act from now on. This setting will be remembered
 198         until it is changed (or the thread terminates).
 199         @param status The new Code Signing status word for the guest. The proxy enforces
 200         the restrictions on changes to guest status; in particular, the kSecCodeStatusValid bit can only
 201         be cleared, and the kSecCodeStatusHard and kSecCodeStatusKill flags can only be set. Pass the previous
 202         guest status to indicate that no change is desired.
 203         @param attributes An optional dictionary containing attributes to be used to distinguish
 204         this guest from all guests of the caller. If given, it completely replaces the attributes
 205         specified earlier. If NULL, previously established attributes are retained.
 206         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 207         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 208         CSCommon.h or certain other Security framework headers.
 209  */
 210 OSStatus SecHostSetGuestStatus(SecGuestRef guestRef,
 211         uint32_t status, CFDictionaryRef __nullable attributes,
 212         SecCSFlags flags);
 213
 214
 215 /*!
 216         @function SecHostSetHostingPort
 217         Tells the Code Signing Hosting subsystem that the calling code will directly respond
 218         to hosting inquiries over the given port.
 219
 220         This API should be the first hosting API call made. With it, the calling code takes
 221         direct responsibility for answering questions about its guests using the hosting IPC
 222         services. The SecHostCreateGuest, SecHostDestroyGuest and SecHostSetGuestStatus calls
 223         are not valid after this. The SecHostSelectGuest and SecHostSelectedGuest calls will
 224         still work, and will use whatever SecGuestRefs the caller has assigned in its internal
 225         data structures.
 226
 227         This call cannot be undone; once it is made, record-and-forward facilities are
 228         disabled for the lifetime of the calling code.
 229
 230         @param hostingPort A Mach message port with send rights. This port will be recorded
 231         and handed to parties interested in querying the host about its children.
 232         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 233         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 234         CSCommon.h or certain other Security framework headers.
 235  */
 236 OSStatus SecHostSetHostingPort(mach_port_t hostingPort, SecCSFlags flags);
 237
 238 CF_ASSUME_NONNULL_END
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243
 244 #endif //_H_SECCODEHOST