]> git.saurik.com Git - apple/security.git/blob - protocol/SecProtocolConfiguration.h
Security-59754.80.3.tar.gz
[apple/security.git] / protocol / SecProtocolConfiguration.h
1 /*
2 * Copyright (c) 2018 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 #ifndef SecProtocolConfiguration_h
25 #define SecProtocolConfiguration_h
26
27 #include <Security/SecProtocolObject.h>
28 #include <Security/SecureTransport.h>
29
30 #include <dispatch/dispatch.h>
31 #include <xpc/xpc.h>
32
33 #ifndef SEC_OBJECT_IMPL
34 /*!
35 * A `sec_protocol_configuration` is an object that encapsulates App Transport Security
36 * information and vends `sec_protocol_options` to clients for creating new connections.
37 * It may also be queried to determine for what domains TLS is required.
38 */
39 SEC_OBJECT_DECL(sec_protocol_configuration);
40 #endif // !SEC_OBJECT_IMPL
41
42 __BEGIN_DECLS
43
44 SEC_ASSUME_NONNULL_BEGIN
45
46 /*!
47 * @function sec_protocol_configuration_copy_singleton
48 *
49 * @abstract
50 * Copy the per-process `sec_protocol_configuration_t` object.
51 *
52 * @return A non-nil `sec_protocol_configuration_t` instance.
53 */
54 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
55 SEC_RETURNS_RETAINED sec_protocol_configuration_t
56 sec_protocol_configuration_copy_singleton(void);
57
58 /*!
59 * @function sec_protocol_configuration_set_ats_overrides
60 *
61 * @abstract
62 * Set ATS overrides
63 *
64 * @param config
65 * A `sec_protocol_configuration_t` instance.
66 *
67 * @param override_dictionary
68 * A `CFDictionaryRef` dictionary containing the ATS overrides as
69 * documented here: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33
70 *
71 * @return True if successful, and false otherwise.
72 */
73 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
74 bool
75 sec_protocol_configuration_set_ats_overrides(sec_protocol_configuration_t config, CFDictionaryRef override_dictionary);
76
77 /*!
78 * @function sec_protocol_configuration_copy_transformed_options
79 *
80 * @abstract
81 * Transform an existing `sec_protocol_options_t` instance with a `sec_protocol_configuration_t` instance.
82 *
83 * @param config
84 * A `sec_protocol_configuration_t` instance.
85 *
86 * @param options
87 * A `sec_protocol_options_t` instance.
88 *
89 * @return The transformed `sec_protocol_options` instance.
90 */
91 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
92 SEC_RETURNS_RETAINED __nullable sec_protocol_options_t
93 sec_protocol_configuration_copy_transformed_options(sec_protocol_configuration_t config, sec_protocol_options_t options);
94
95 /*!
96 * @function sec_protocol_configuration_copy_transformed_options_for_host
97 *
98 * @abstract
99 * Transform an existing `sec_protocol_options_t` instance with a `sec_protocol_configuration_t` instance
100 * using a specific host endpoint. Note that the service (port) is omitted from this formula.
101 *
102 * @param config
103 * A `sec_protocol_configuration_t` instance.
104 *
105 * @param options
106 * A `sec_protocol_options_t` instance.
107 *
108 * @param host
109 * A NULL-terminated C string containing the host in question.
110 *
111 * @return The transformed `sec_protocol_options` instance.
112 */
113 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
114 SEC_RETURNS_RETAINED __nullable sec_protocol_options_t
115 sec_protocol_configuration_copy_transformed_options_for_host(sec_protocol_configuration_t config, sec_protocol_options_t options, const char *host);
116
117 /*!
118 * @function sec_protocol_configuration_tls_required
119 *
120 * @abstract
121 * Determine if TLS is required by policy for a generic connection. Note that the service (port) is omitted
122 * from this formula.
123 *
124 * @param config
125 * A `sec_protocol_configuration_t` instance.
126 *
127 * @return True if connections require TLS, and false otherwise.
128 */
129 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
130 bool
131 sec_protocol_configuration_tls_required(sec_protocol_configuration_t config);
132
133 /*!
134 * @function sec_protocol_configuration_tls_required_for_host
135 *
136 * @abstract
137 * Determine if TLS is required -- by policy -- for the given host endpoint. Note that the service (port) is
138 * omitted from this formula.
139 *
140 * @param config
141 * A `sec_protocol_configuration_t` instance.
142 *
143 * @param host
144 * A NULL-terminated C string containing the host endpoint to examine.
145 *
146 * @param is_direct
147 * A flag which indicates if the given hostname is local (direct).
148 *
149 * @return True if connections to the endpoint require TLS, and false otherwise.
150 */
151 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
152 bool
153 sec_protocol_configuration_tls_required_for_host(sec_protocol_configuration_t config, const char *host, bool is_direct);
154
155 /*!
156 * @function sec_protocol_configuration_tls_required_for_address
157 *
158 * @abstract
159 * Determine if TLS is required -- by policy -- for the given address endpoint.
160 *
161 * @param config
162 * A `sec_protocol_configuration_t` instance.
163 *
164 * @param address
165 * A NULL-terminated C string containing the address endpoint to examine.
166 *
167 * @return True if connections to the endpoint require TLS, and false otherwise.
168 */
169 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
170 bool
171 sec_protocol_configuration_tls_required_for_address(sec_protocol_configuration_t config, const char *address);
172
173 SEC_ASSUME_NONNULL_END
174
175 __END_DECLS
176
177 #endif // SecProtocolConfiguration_h