1#ifndef __XPC_PEER_REQ_H__
2#define __XPC_PEER_REQ_H__
3
4#ifndef __XPC_INDIRECT__
5#error "Please #include <xpc/xpc.h> instead of this file directly."
6// For HeaderDoc.
7#include <xpc/base.h>
8#endif // __XPC_INDIRECT__
9
10XPC_ASSUME_NONNULL_BEGIN
11__BEGIN_DECLS
12
13XPC_SWIFT_NOEXPORT
14/*!
15 * @typedef xpc_peer_requirement_t
16 *
17 * @abstract
18 * XPC peer requirement is an abstract type that represents a validated
19 * requirement on peers.
20 *
21 * @discussion
22 * Users can specify a requirement via `xpc_peer_requirement_create_*` API.
23 * These constructors will return a non-null xpc_peer_requirement_t if the
24 * requirement is valid. Users can set a xpc_peer_requirement_t on connections,
25 * sessions or listeners using one of `xpc_*_set_peer_requirement` API.
26 *
27 * xpc_peer_requirement_t is reference counted and concurrency-safe. One
28 * xpc_peer_requirement_t can be shared among multiple connections, sessions
29 * or listeners.
30 */
31OS_OBJECT_DECL_SENDABLE_CLASS(xpc_peer_requirement);
32
33#pragma mark Constructors
34
35/*!
36 * @function xpc_peer_requirement_create_entitlement_exists
37 * Create a requirement that the peer has the specified entitlement
38 *
39 * @param entitlement
40 * The entitlement the peer must have. It is safe to deallocate the entitlement
41 * string after calling this function.
42 *
43 * @param error_out
44 * An out-parameter that, if set and in the event of an error, will point to an
45 * {@link xpc_rich_error_t} describing the details of any errors that occurred.
46 *
47 * @result
48 * On success this returns a new peer requirement object. On failure this will
49 * return NULL and if set, error_out will be set to an error describing the
50 * failure.
51 *
52 * @discussion
53 * This function will return NULL promptly if the entitlement requirement is
54 * invalid.
55 */
56API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
57
58XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED
59xpc_peer_requirement_t _Nullable
60xpc_peer_requirement_create_entitlement_exists(const char *entitlement,
61 xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out);
62
63/*!
64 * @function xpc_peer_requirement_create_entitlement_matches_value
65 * Create a requirement that the peer has the entitlement with matching value
66 *
67 * @param entitlement
68 * The entitlement the peer must have. It is safe to deallocate the entitlement
69 * string after calling this function.
70 *
71 * @param value
72 * The value that the entitlement must match. It is safe to deallocate the value
73 * object after calling this function. Valid xpc types for this object are
74 * `XPC_TYPE_BOOL`, `XPC_TYPE_STRING` and `XPC_TYPE_INT64`.
75 *
76 * @param error_out
77 * An out-parameter that, if set and in the event of an error, will point to an
78 * {@link xpc_rich_error_t} describing the details of any errors that occurred.
79 *
80 * @result
81 * On success this returns a new peer requirement object. On failure this will
82 * return NULL and if set, error_out will be set to an error describing the
83 * failure.
84 *
85 * @discussion
86 * This function will return NULL promptly if the entitlement requirement is
87 * invalid.
88 */
89API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
90
91XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED
92xpc_peer_requirement_t _Nullable
93xpc_peer_requirement_create_entitlement_matches_value(const char *entitlement,
94 xpc_object_t value,
95 xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out);
96
97/*!
98 * @function xpc_peer_requirement_create_team_identity
99 * Create a requirement that the peer has the specified identity and is signed
100 * with the same team identifier as the current process
101 *
102 * @param signing_identifier
103 * The optional signing identifier the peer must have. It is safe to deallocate
104 * the signing identifier string after calling this function.
105 *
106 * @param error_out
107 * An out-parameter that, if set and in the event of an error, will point to an
108 * {@link xpc_rich_error_t} describing the details of any errors that occurred.
109 *
110 * @result
111 * On success this returns a new peer requirement object. On failure this will
112 * return NULL and if set, error_out will be set to an error describing the
113 * failure.
114 *
115 * @discussion
116 * This function will return NULL promptly if the identity requirement is
117 * invalid.
118 *
119 * The peer process must be signed as either a Testflight app or an App store
120 * app, or be signed by an apple issued development certificate, an enterprise
121 * distributed certificate (embedded only), or a Developer ID certificate (macOS
122 * only)
123 */
124API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
125
126XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED
127xpc_peer_requirement_t _Nullable
128xpc_peer_requirement_create_team_identity(
129 const char * _Nullable signing_identifier,
130 xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out);
131
132/*!
133 * @function xpc_peer_requirement_create_platform_identity
134 * Create a requirement that the peer has the specified identity and is from
135 * platform binary.
136 *
137 * @param signing_identifier
138 * The optional signing identifier the peer must have. If not specified, this
139 * function ensures that the peer process' executable is a platform binary. It
140 * is safe to deallocate the signing identifier string after calling this
141 * function.
142 *
143 * @param error_out
144 * An out-parameter that, if set and in the event of an error, will point to an
145 * {@link xpc_rich_error_t} describing the details of any errors that occurred.
146 *
147 * @result
148 * On success this returns a new peer requirement object. On failure this will
149 * return NULL and if set, error_out will be set to an error describing the
150 * failure.
151 *
152 * @discussion
153 * This function will return NULL promptly if the identity requirement is
154 * invalid.
155 */
156API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
157
158XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED
159xpc_peer_requirement_t _Nullable
160xpc_peer_requirement_create_platform_identity(
161 const char * _Nullable signing_identifier,
162 xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out);
163
164/*!
165 * @function xpc_peer_requirement_create_lwcr
166 * Create a requirement that the peer has the specified lightweight code requirement
167 *
168 * @param lwcr
169 * The lightweight code requirement the peer must have. It is safe to deallocate
170 * the lightweight code requirement object after calling this function.
171 *
172 * @param error_out
173 * An out-parameter that, if set and in the event of an error, will point to an
174 * {@link xpc_rich_error_t} describing the details of any errors that occurred.
175 *
176 * @result
177 * On success this returns a new peer requirement object. On failure this will
178 * return NULL and if set, error_out will be set to an error describing the
179 * failure.
180 *
181 * @discussion
182 * This function will return NULL promptly if the lightweight code requirement
183 * is invalid.
184 *
185 * The lightweight code requirement must be an `xpc_dictionary_t` equivalent of
186 * an LWCR constraint (see
187 * https://developer.apple.com/documentation/security/defining_launch_environment_and_library_constraints
188 * for details on the contents of the dictionary)
189 *
190 * The lightweight code requirement in the example below uses the $or operator
191 * to require that an executable’s either signed with the Team ID 8XCUU22SN2, or
192 * is an operating system executable:
193 * ```c
194 * xpc_object_t or_val = xpc_dictionary_create_empty();
195 * xpc_dictionary_set_string(or_val, "team-identifier", "8XCUU22SN2");
196 * xpc_dictionary_set_int64(or_val, "validation-category", 1);
197 *
198 * xpc_object_t lwcr = xpc_dictionary_create_empty();
199 * xpc_dictionary_set_value(lwcr, "$or", or_val);
200 *
201 * xpc_peer_requirement_t req = xpc_peer_requirement_create_lwcr(lwcr, NULL);
202 * ```
203 */
204API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
205
206XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED
207xpc_peer_requirement_t _Nullable
208xpc_peer_requirement_create_lwcr(xpc_object_t lwcr,
209 xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out);
210
211#pragma mark Matching Peer Requirement on Received Messages
212
213/*!
214 * @function xpc_peer_requirement_match_received_message
215 * Check the specified requirement against a received message from the peer.
216 *
217 * @param peer_requirement
218 * The requirement the peer must have
219 *
220 * @param message
221 * The received dictionary to be checked
222 *
223 * @param error_out
224 * An out-parameter that, if set and in the event of an error, will point to an
225 * {@link xpc_rich_error_t} describing the details of any errors that occurred.
226 *
227 * @result
228 * On match this returns true. On mismatch or failure this will return false and
229 * if set, error_out will be set to an error describing the failure.
230 */
231API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
232
233XPC_EXPORT XPC_SWIFT_NOEXPORT
234bool
235xpc_peer_requirement_match_received_message(xpc_peer_requirement_t peer_requirement,
236 xpc_object_t message,
237 xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out);
238
239__END_DECLS
240XPC_ASSUME_NONNULL_END
241
242#endif