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_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))
 57API_UNAVAILABLE(tvos, watchos)
 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))
 90API_UNAVAILABLE(tvos, watchos)
 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))
125API_UNAVAILABLE(tvos, watchos)
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))
157API_UNAVAILABLE(tvos, watchos)
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))
205API_UNAVAILABLE(tvos, watchos)
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))
232API_UNAVAILABLE(tvos, watchos)
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