2 * Copyright (c) 2018 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
24 #ifndef SecProtocolTypes_h
25 #define SecProtocolTypes_h
27 #include <Security/SecProtocolObject.h>
28 #include <Security/SecTrust.h>
29 #include <Security/SecCertificate.h>
30 #include <Security/SecIdentity.h>
31 #include <Security/CipherSuite.h>
32 #include <Security/SecBase.h>
34 #ifndef SEC_OBJECT_IMPL
36 * These are os_object compatible and ARC-able wrappers around existing CoreFoundation
37 * Security types, including: SecTrustRef, SecIdentityRef, and SecCertificateRef. They allow
38 * clients to use these types in os_object-type APIs and data structures. The underlying
39 * CoreFoundation types may be extracted and used by clients as needed.
41 SEC_OBJECT_DECL(sec_trust
);
42 SEC_OBJECT_DECL(sec_identity
);
43 SEC_OBJECT_DECL(sec_certificate
);
44 #endif // !SEC_OBJECT_IMPL
47 * @enum tls_protocol_version_t enumeration
48 * @abstract Enumerations for the set of supported TLS and DTLS protocol versions.
50 * @constant tls_protocol_version_TLSv10 TLS 1.0 [https://tools.ietf.org/html/rfc4346]
51 * @constant tls_protocol_version_TLSv11 TLS 1.1 [https://tools.ietf.org/html/rfc2246]
52 * @constant tls_protocol_version_TLSv12 TLS 1.2 [https://tools.ietf.org/html/rfc5246]
53 * @constant tls_protocol_version_TLSv13 TLS 1.3 [https://tools.ietf.org/html/rfc8446]
54 * @constant tls_protocol_version_DTLSv10 DTLS 1.0 [https://tools.ietf.org/html/rfc4347]
55 * @constant tls_protocol_version_DTLSv12 DTLS 1.2 [https://tools.ietf.org/html/rfc6347]
57 typedef CF_ENUM(uint16_t, tls_protocol_version_t
) {
58 tls_protocol_version_TLSv10
CF_SWIFT_NAME(TLSv10
) = 0x0301,
59 tls_protocol_version_TLSv11
CF_SWIFT_NAME(TLSv11
) = 0x0302,
60 tls_protocol_version_TLSv12
CF_SWIFT_NAME(TLSv12
) = 0x0303,
61 tls_protocol_version_TLSv13
CF_SWIFT_NAME(TLSv13
) = 0x0304,
62 tls_protocol_version_DTLSv10
CF_SWIFT_NAME(DTLSv10
) = 0xfeff,
63 tls_protocol_version_DTLSv12
CF_SWIFT_NAME(DTLSv12
) = 0xfefd,
67 * @enum tls_ciphersuite_t enumeration
68 * @abstract Enumerations for the set of supported TLS and DTLS ciphersuites.
70 * See https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4
71 * for ciphersuite codepoint allocations and reference RFCs.
73 * @constant tls_ciphersuite_RSA_WITH_3DES_EDE_CBC_SHA
74 * @constant tls_ciphersuite_RSA_WITH_AES_128_CBC_SHA
75 * @constant tls_ciphersuite_RSA_WITH_AES_256_CBC_SHA
76 * @constant tls_ciphersuite_RSA_WITH_AES_128_GCM_SHA256
77 * @constant tls_ciphersuite_RSA_WITH_AES_256_GCM_SHA384
78 * @constant tls_ciphersuite_RSA_WITH_AES_128_CBC_SHA256
79 * @constant tls_ciphersuite_RSA_WITH_AES_256_CBC_SHA256
80 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
81 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
82 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
83 * @constant tls_ciphersuite_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
84 * @constant tls_ciphersuite_ECDHE_RSA_WITH_AES_128_CBC_SHA
85 * @constant tls_ciphersuite_ECDHE_RSA_WITH_AES_256_CBC_SHA
86 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
87 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
88 * @constant tls_ciphersuite_ECDHE_RSA_WITH_AES_128_CBC_SHA256
89 * @constant tls_ciphersuite_ECDHE_RSA_WITH_AES_256_CBC_SHA384
90 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
91 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
92 * @constant tls_ciphersuite_ECDHE_RSA_WITH_AES_128_GCM_SHA256
93 * @constant tls_ciphersuite_ECDHE_RSA_WITH_AES_256_GCM_SHA384
94 * @constant tls_ciphersuite_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
95 * @constant tls_ciphersuite_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
96 * @constant tls_ciphersuite_AES_128_GCM_SHA256
97 * @constant tls_ciphersuite_AES_256_GCM_SHA384
98 * @constant tls_ciphersuite_CHACHA20_POLY1305_SHA256
100 typedef CF_ENUM(uint16_t, tls_ciphersuite_t
) {
101 tls_ciphersuite_RSA_WITH_3DES_EDE_CBC_SHA
CF_SWIFT_NAME(RSA_WITH_3DES_EDE_CBC_SHA
) = 0x000A,
102 tls_ciphersuite_RSA_WITH_AES_128_CBC_SHA
CF_SWIFT_NAME(RSA_WITH_AES_128_CBC_SHA
) = 0x002F,
103 tls_ciphersuite_RSA_WITH_AES_256_CBC_SHA
CF_SWIFT_NAME(RSA_WITH_AES_256_CBC_SHA
) = 0x0035,
104 tls_ciphersuite_RSA_WITH_AES_128_GCM_SHA256
CF_SWIFT_NAME(RSA_WITH_AES_128_GCM_SHA256
) = 0x009C,
105 tls_ciphersuite_RSA_WITH_AES_256_GCM_SHA384
CF_SWIFT_NAME(RSA_WITH_AES_256_GCM_SHA384
) = 0x009D,
106 tls_ciphersuite_RSA_WITH_AES_128_CBC_SHA256
CF_SWIFT_NAME(RSA_WITH_AES_128_CBC_SHA256
) = 0x003C,
107 tls_ciphersuite_RSA_WITH_AES_256_CBC_SHA256
CF_SWIFT_NAME(RSA_WITH_AES_256_CBC_SHA256
) = 0x003D,
108 tls_ciphersuite_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
) = 0xC008,
109 tls_ciphersuite_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_AES_128_CBC_SHA
) = 0xC009,
110 tls_ciphersuite_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_AES_256_CBC_SHA
) = 0xC00A,
111 tls_ciphersuite_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
CF_SWIFT_NAME(ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
) = 0xC012,
112 tls_ciphersuite_ECDHE_RSA_WITH_AES_128_CBC_SHA
CF_SWIFT_NAME(ECDHE_RSA_WITH_AES_128_CBC_SHA
) = 0xC013,
113 tls_ciphersuite_ECDHE_RSA_WITH_AES_256_CBC_SHA
CF_SWIFT_NAME(ECDHE_RSA_WITH_AES_256_CBC_SHA
) = 0xC014,
114 tls_ciphersuite_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
) = 0xC023,
115 tls_ciphersuite_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
) = 0xC024,
116 tls_ciphersuite_ECDHE_RSA_WITH_AES_128_CBC_SHA256
CF_SWIFT_NAME(ECDHE_RSA_WITH_AES_128_CBC_SHA256
) = 0xC027,
117 tls_ciphersuite_ECDHE_RSA_WITH_AES_256_CBC_SHA384
CF_SWIFT_NAME(ECDHE_RSA_WITH_AES_256_CBC_SHA384
) = 0xC028,
118 tls_ciphersuite_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
) = 0xC02B,
119 tls_ciphersuite_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
) = 0xC02C,
120 tls_ciphersuite_ECDHE_RSA_WITH_AES_128_GCM_SHA256
CF_SWIFT_NAME(ECDHE_RSA_WITH_AES_128_GCM_SHA256
) = 0xC02F,
121 tls_ciphersuite_ECDHE_RSA_WITH_AES_256_GCM_SHA384
CF_SWIFT_NAME(ECDHE_RSA_WITH_AES_256_GCM_SHA384
) = 0xC030,
122 tls_ciphersuite_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
CF_SWIFT_NAME(ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
) = 0xCCA8,
123 tls_ciphersuite_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
CF_SWIFT_NAME(ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
) = 0xCCA9,
124 tls_ciphersuite_AES_128_GCM_SHA256
CF_SWIFT_NAME(AES_128_GCM_SHA256
) = 0x1301,
125 tls_ciphersuite_AES_256_GCM_SHA384
CF_SWIFT_NAME(AES_256_GCM_SHA384
) = 0x1302,
126 tls_ciphersuite_CHACHA20_POLY1305_SHA256
CF_SWIFT_NAME(CHACHA20_POLY1305_SHA256
) = 0x1303,
130 * @enum tls_ciphersuite_group_t enumeration
131 * @abstract Convenience ciphersuite groups that collate ciphersuites of comparable security
132 * properties into a single alias.
134 * @constant tls_ciphersuite_group_default
135 * @constant tls_ciphersuite_group_compatibility
136 * @constant tls_ciphersuite_group_legacy
137 * @constant tls_ciphersuite_group_ats
138 * @constant tls_ciphersuite_group_ats_compatibility
140 typedef CF_ENUM(uint16_t, tls_ciphersuite_group_t
) {
141 tls_ciphersuite_group_default
,
142 tls_ciphersuite_group_compatibility
,
143 tls_ciphersuite_group_legacy
,
144 tls_ciphersuite_group_ats
,
145 tls_ciphersuite_group_ats_compatibility
,
149 * @enum SSLProtocol enumeration
150 * @abstract Enumerations for the set of supported TLS and DTLS protocol versions.
152 * @note This enumeration is deprecated. Use `tls_protocol_version_t` instead.
154 typedef CF_ENUM(int, SSLProtocol
) {
155 kSSLProtocolUnknown
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 0,
156 kTLSProtocol1
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 4,
157 kTLSProtocol11
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 7,
158 kTLSProtocol12
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 8,
159 kDTLSProtocol1
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 9,
160 kTLSProtocol13
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 10,
161 kDTLSProtocol12
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 11,
162 kTLSProtocolMaxSupported
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 999,
163 kSSLProtocol2
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 1,
164 kSSLProtocol3
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 2,
165 kSSLProtocol3Only
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 3,
166 kTLSProtocol1Only
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 5,
167 kSSLProtocolAll
CF_ENUM_DEPRECATED(10_2
, 10_15
, 5_0
, 13_0
) = 6,
172 SEC_ASSUME_NONNULL_BEGIN
175 * @function sec_trust_create
178 * Create an ARC-able `sec_trust_t` instance from a `SecTrustRef`.
181 * A `SecTrustRef` instance.
183 * @return a `sec_trust_t` instance.
185 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
186 SEC_RETURNS_RETAINED _Nullable sec_trust_t
187 sec_trust_create(SecTrustRef trust
);
190 * @function sec_trust_copy_ref
193 * Copy a retained reference to the underlying `SecTrustRef` instance.
196 * A `sec_trust_t` instance.
198 * @return The underlying `SecTrustRef` instance.
200 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
202 sec_trust_copy_ref(sec_trust_t trust
);
205 * @function sec_identity_create
208 * Create an ARC-able `sec_identity_t` instance from a `SecIdentityRef`.
211 * A `SecIdentityRef` instance.
213 * @return a `sec_identity_t` instance.
215 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
216 SEC_RETURNS_RETAINED _Nullable sec_identity_t
217 sec_identity_create(SecIdentityRef identity
);
220 * @function sec_identity_create_with_certificates
223 * Create an ARC-able `sec_identity_t` instance from a `SecIdentityRef` and
224 * array of SecCertificateRef instances.
227 * A `SecIdentityRef` instance.
229 * @param certificates
230 * An array of `SecCertificateRef` instances.
232 * @return a `sec_identity_t` instance.
234 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
235 SEC_RETURNS_RETAINED _Nullable sec_identity_t
236 sec_identity_create_with_certificates(SecIdentityRef identity
, CFArrayRef certificates
);
240 * @function sec_identity_access_certificates
243 * Access the certificates associated with the `sec_identity_t` instance.
246 * A `sec_identity_t` instance.
249 * A block to invoke one or more times with `sec_certificate_t` instances.
251 * @return Returns true if the peer certificates were accessible, false otherwise.
253 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
255 sec_identity_access_certificates(sec_identity_t identity
,
256 void (^handler
)(sec_certificate_t certificate
));
260 * @function sec_identity_copy_ref
263 * Copy a retained reference to the underlying `SecIdentityRef` instance.
266 * A `sec_identity_t` instance.
268 * @return The underlying `SecIdentityRef` instance.
270 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
271 _Nullable SecIdentityRef
272 sec_identity_copy_ref(sec_identity_t identity
);
275 * @function sec_identity_copy_certificates_ref
278 * Copy a retained reference to the underlying `CFArrayRef` container of `SecCertificateRef` types.
281 * A `sec_identity_t` instance.
283 * @return The underlying `CFArrayRef` container with `SecCertificateRef` instances.
285 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
287 sec_identity_copy_certificates_ref(sec_identity_t identity
);
290 * @function sec_certificate_create
293 * Create an ARC-able `sec_certificate_t` instance from a `SecCertificateRef`.
296 * A `SecCertificateRef` instance.
298 * @return a `sec_certificate_t` instance.
300 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
301 SEC_RETURNS_RETAINED _Nullable sec_certificate_t
302 sec_certificate_create(SecCertificateRef certificate
);
305 * @function sec_certificate_copy_ref
308 * Copy a retained reference to the underlying `SecCertificateRef` instance.
311 * A `sec_certificate_t` instance.
313 * @return The underlying `SecCertificateRef` instance.
315 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
317 sec_certificate_copy_ref(sec_certificate_t certificate
);
319 SEC_ASSUME_NONNULL_END
323 #endif // SecProtocolTypes_h