protocol/SecProtocolTypes.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 SecProtocolTypes_h
  25 #define SecProtocolTypes_h
  26
  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>
  33
  34 #ifndef SEC_OBJECT_IMPL
  35 /*!
  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.
  40  */
  41 SEC_OBJECT_DECL(sec_trust);
  42 SEC_OBJECT_DECL(sec_identity);
  43 SEC_OBJECT_DECL(sec_certificate);
  44 #endif // !SEC_OBJECT_IMPL
  45
  46 /*!
  47  * @enum tls_protocol_version_t enumeration
  48  * @abstract Enumerations for the set of supported TLS and DTLS protocol versions.
  49  *
  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]
  56  */
  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,
  64 };
  65
  66 /*!
  67  * @enum tls_ciphersuite_t enumeration
  68  * @abstract Enumerations for the set of supported TLS and DTLS ciphersuites.
  69  *
  70  * See https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4
  71  * for ciphersuite codepoint allocations and reference RFCs.
  72  *
  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
  99  */
 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,
 127 };
 128
 129 /*!
 130  * @enum tls_ciphersuite_group_t enumeration
 131  * @abstract Convenience ciphersuite groups that collate ciphersuites of comparable security
 132  *  properties into a single alias.
 133  *
 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
 139  */
 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,
 146 };
 147
 148 /*!
 149  * @enum SSLProtocol enumeration
 150  * @abstract Enumerations for the set of supported TLS and DTLS protocol versions.
 151  *
 152  * @note This enumeration is deprecated. Use `tls_protocol_version_t` instead.
 153  */
 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,
 168 };
 169
 170 __BEGIN_DECLS
 171
 172 SEC_ASSUME_NONNULL_BEGIN
 173
 174 /*!
 175  * @function sec_trust_create
 176  *
 177  * @abstract
 178  *      Create an ARC-able `sec_trust_t` instance from a `SecTrustRef`.
 179  *
 180  * @param trust
 181  *      A `SecTrustRef` instance.
 182  *
 183  * @return a `sec_trust_t` instance.
 184  */
 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);
 188
 189 /*!
 190  * @function sec_trust_copy_ref
 191  *
 192  * @abstract
 193  *      Copy a retained reference to the underlying `SecTrustRef` instance.
 194  *
 195  * @param trust
 196  *      A `sec_trust_t` instance.
 197  *
 198  * @return The underlying `SecTrustRef` instance.
 199  */
 200 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 201 SecTrustRef
 202 sec_trust_copy_ref(sec_trust_t trust);
 203
 204 /*!
 205  * @function sec_identity_create
 206  *
 207  * @abstract
 208  *      Create an ARC-able `sec_identity_t` instance from a `SecIdentityRef`.
 209  *
 210  * @param identity
 211  *      A `SecIdentityRef` instance.
 212  *
 213  * @return a `sec_identity_t` instance.
 214  */
 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);
 218
 219 /*!
 220  * @function sec_identity_create_with_certificates
 221  *
 222  * @abstract
 223  *      Create an ARC-able `sec_identity_t` instance from a `SecIdentityRef` and
 224  *      array of SecCertificateRef instances.
 225  *
 226  * @param identity
 227  *      A `SecIdentityRef` instance.
 228  *
 229  * @param certificates
 230  *      An array of `SecCertificateRef` instances.
 231  *
 232  * @return a `sec_identity_t` instance.
 233  */
 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);
 237
 238 #ifdef __BLOCKS__
 239 /*!
 240  * @function sec_identity_access_certificates
 241  *
 242  * @abstract
 243  *      Access the certificates associated with the `sec_identity_t` instance.
 244  *
 245  * @param identity
 246  *      A `sec_identity_t` instance.
 247  *
 248  * @param handler
 249  *      A block to invoke one or more times with `sec_certificate_t` instances.
 250  *
 251  * @return Returns true if the peer certificates were accessible, false otherwise.
 252  */
 253 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 254 bool
 255 sec_identity_access_certificates(sec_identity_t identity,
 256                                  void (^handler)(sec_certificate_t certificate));
 257 #endif // __BLOCKS__
 258
 259 /*!
 260  * @function sec_identity_copy_ref
 261  *
 262  * @abstract
 263  *      Copy a retained reference to the underlying `SecIdentityRef` instance.
 264  *
 265  * @param identity
 266  *      A `sec_identity_t` instance.
 267  *
 268  * @return The underlying `SecIdentityRef` instance.
 269  */
 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);
 273
 274 /*!
 275  * @function sec_identity_copy_certificates_ref
 276  *
 277  * @abstract
 278  *      Copy a retained reference to the underlying `CFArrayRef` container of `SecCertificateRef` types.
 279  *
 280  * @param identity
 281  *      A `sec_identity_t` instance.
 282  *
 283  * @return The underlying `CFArrayRef` container with `SecCertificateRef` instances.
 284  */
 285 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 286 _Nullable CFArrayRef
 287 sec_identity_copy_certificates_ref(sec_identity_t identity);
 288
 289 /*!
 290  * @function sec_certificate_create
 291  *
 292  * @abstract
 293  *      Create an ARC-able `sec_certificate_t` instance from a `SecCertificateRef`.
 294  *
 295  * @param certificate
 296  *      A `SecCertificateRef` instance.
 297  *
 298  * @return a `sec_certificate_t` instance.
 299  */
 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);
 303
 304 /*!
 305  * @function sec_certificate_copy_ref
 306  *
 307  * @abstract
 308  *      Copy a retained reference to the underlying `SecCertificateRef` instance.
 309  *
 310  * @param certificate
 311  *      A `sec_certificate_t` instance.
 312  *
 313  * @return The underlying `SecCertificateRef` instance.
 314  */
 315 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 316 SecCertificateRef
 317 sec_certificate_copy_ref(sec_certificate_t certificate);
 318
 319 SEC_ASSUME_NONNULL_END
 320
 321 __END_DECLS
 322
 323 #endif // SecProtocolTypes_h