[apple/libsecurity_codesigning.git] / lib / SecCodeHost.h

/*
 * Copyright (c) 2006-2007 Apple Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

/*!
	@header SecCodeHost
	This header provides the hosting API for Code Signing. These are calls
	that are (only) made by code that is hosting guests.
	In the context of Code Signing, a Host is code that creates and manages other
	codes from which it defends its own integrity. As part of that duty, it maintains
	state for each of its children, and answers questions about them.

	A Host is externally represented by a SecCodeRef (it is a SecCode object).
	So is a Guest. There is no specific API object to represent Hosts or Guests.
	Within the Hosting API, guests are identified by simple numeric handles that
	are unique and valid only in the context of their specific host.

	The functions in this API always apply to the Host making the API calls.
	They cannot be used to (directly) interrogate another host.
*/
#ifndef _H_SECCODEHOST
#define _H_SECCODEHOST

#include <Security/CSCommon.h>
#include <System/sys/codesign.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
	@header SecCodeHost
	This header describes the Code Signing Hosting API. These are calls made
	by code that wishes to become a Host in the Code Signing Host/Guest infrastructure.
	Hosting allows the caller to establish separate, independent code identities
	(SecCodeRefs) for parts of itself, usually because it is loading and managing
	code in the form of scripts, plugins, etc.
	
	The Hosting API does not directly connect to the Code Signing Client APIs.
	Certain calls in the client API will cause internal queries to hosts about their
	guests. The Host side of these queries is managed through this API. The results
	will eventually be delivered to client API callers in appropriate form.
	
	If code never calls any of the Hosting API functions, it is deemed to not have
	guests and not act as a Host. This is the default and requires no action.

	Hosting operates in one of two modes, dynamic or proxy. Whichever mode is first
	engaged prevails for the lifetime of the caller. There is no way to switch between
	the two, and calling an API belonging to the opposite mode will fail.
	
	In dynamic hosting mode, the caller provides a Mach port that receives direct
	queries about its guests. Dynamic mode is engaged by calling SecHostSetHostingPort.
	
	In proxy hosting mode, the caller provides information about its guests as
	guests are created, removed, or change status. The system caches this information
	and answers queries about guests from this pool of information. The caller is not
	directly involved in answering such queries, and has no way to intervene.
*/


/*!
	@function SecHostCreateGuest
	Create a new Guest and describe its initial properties.
	
	This call activates Hosting Proxy Mode. From here on, the system will record
	guest information provided through SecHostCreateGuest, SecHostSetGuestStatus, and
	SecHostRemoveGuest, and report hosting status to callers directly. This mode
	is incompatible with dynamic host mode as established by a call to SecHostSetHostingPort.
	
	@param host Pass kSecNoGuest to create a guest of the process itself.
	To create a guest of another guest (extending the hosting chain), pass the SecGuestRef
	of the guest to act as the new guest's host. If host has a dedicated guest,
	it will be deemed to be be the actual host, recursively.
	@param status The Code Signing status word for the new guest. These are combinations
	of the CS_* flags in <sys/codesign.h>. Note that the proxy will enforce the rules for
	the stickiness of these bits. In particular, if you don't pass the CS_VALID bit during
	creation, your new guest will be born invalid and will never have a valid identity.
	@param path The canonical path to the guest's code on disk. This is the path you would
	pass to SecStaticCodeCreateWithPath to make a static code object reference. You must
	use an absolute path.
	@param attributes An optional CFDictionaryRef containing attributes that can be used
	to locate this particular guest among all of the caller's guests. The "canonical"
	attribute is automatically added for the value of guestRef. If you pass NULL,
	no other attributes are established for the guest.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior, or
	a combination of the flags defined below for special features.
	@result Upon success, noErr. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
	@param newGuest Upon successful creation of the new guest, the new SecGuestRef
	that should be used to identify the new guest from here on.
	
	@constant kSecCSDedicatedHost Declares dedicated hosting for the given host.
	In dedicated hosting, the host has exactly one guest (the one this call is
	introducing), and the host will spend all of its time from here on running
	that guest (or on its behalf). This declaration is irreversable for the lifetime
	of the host. Note that this is a declaration about the given host, and is not
	binding upon other hosts on either side of the hosting chain, though they in turn
	may declare dedicated hosting if desired.
	It is invalid to declare dedicated hosting if other guests have already been
	introduced for this host, and it is invalid to introduce additional guests
	for this host after this call.
*/
enum {
	kSecCSDedicatedHost = 1 << 0,
};

OSStatus SecHostCreateGuest(SecGuestRef host,
	uint32_t status, CFURLRef path, CFDictionaryRef attributes,
	SecCSFlags flags, SecGuestRef *newGuest);


/*!
	@function SecHostRemoveGuest
	Announce that the guest with the given guestRef has permanently disappeared.
	It removes all memory of the guest from the hosting system. You cannot remove
	a dedicated guest.

	@param host The SecGuestRef that was used to create guest. You cannot specify
	a proximate host (host of a host) here. However, the substitution for dedicated
	guests described for SecHostCreateGuest also takes place here.
	@param guest The handle for a Guest previously created with SecHostCreateGuest
	that has not previously been destroyed. This guest is to be destroyed now.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@result Upon success, noErr. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecHostRemoveGuest(SecGuestRef host, SecGuestRef guest, SecCSFlags flags);


/*!
	@function SecHostSelectGuest
	Tell the Code Signing host subsystem that the calling thread will now act
	on behalf of the given Guest. This must be a valid Guest previously created
	with SecHostCreateGuest.
	
	@param guestRef The handle for a Guest previously created with SecHostCreateGuest
	on whose behalf this thread will act from now on. This setting will be remembered
	until it is changed (or the thread terminates).
	To indicate that the thread will act on behalf of the Host itself (rather than
	any Guest), pass kSecNoGuest.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@result Upon success, noErr. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecHostSelectGuest(SecGuestRef guestRef, SecCSFlags flags);


/*!
	@function SecHostSelectedGuest
	Retrieve the handle for the Guest currently selected for the calling thread.
	
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param guestRef Will be assigned the SecGuestRef currently in effect for
	the calling thread. If no Guest is active on this thread (i.e. the thread
	is acting for the Host), the return value is kSecNoGuest.
	@result Upon success, noErr. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecHostSelectedGuest(SecCSFlags flags, SecGuestRef *guestRef);


/*!
	@function SecHostSetGuestStatus
	Updates the status of a particular guest.
	
	@param guestRef The handle for a Guest previously created with SecHostCreateGuest
	on whose behalf this thread will act from now on. This setting will be remembered
	until it is changed (or the thread terminates).
	@param status The new Code Signing status word for the guest. The proxy enforces
	the restrictions on changes to guest status; in particular, the CS_VALID bit can only
	be cleared, and the CS_HARD and CS_KILL flags can only be set. Pass the previous
	guest status to indicate that no change is desired.
	@param attributes An optional dictionary containing attributes to be used to distinguish
	this guest from all guests of the caller. If given, it completely replaces the attributes
	specified earlier. If NULL, previously established attributes are retained.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@result Upon success, noErr. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
 */
OSStatus SecHostSetGuestStatus(SecGuestRef guestRef,
	uint32_t status, CFDictionaryRef attributes,
	SecCSFlags flags);


/*!
	@function SecHostSetHostingPort
	Tells the Code Signing Hosting subsystem that the calling code will directly respond
	to hosting inquiries over the given port.
	
	This API should be the first hosting API call made. With it, the calling code takes
	direct responsibility for answering questions about its guests using the hosting IPC
	services. The SecHostCreateGuest, SecHostDestroyGuest and SecHostSetGuestStatus calls
	are not valid after this. The SecHostSelectGuest and SecHostSelectedGuest calls will
	still work, and will use whatever SecGuestRefs the caller has assigned in its internal
	data structures.
	
	This call cannot be undone; once it is made, record-and-forward facilities are
	disabled for the lifetime of the calling code.
	
	@param hostingPort A Mach message port with send rights. This port will be recorded
	and handed to parties interested in querying the host about its children.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@result Upon success, noErr. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
 */
OSStatus SecHostSetHostingPort(mach_port_t hostingPort, SecCSFlags flags);


#ifdef __cplusplus
}
#endif

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