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