OSX/libsecurity_ssl/lib/SecureTransport.h

   1 /*
   2  * Copyright (c) 1999-2002,2005-2016 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 /*
  25  * SecureTransport.h - Public API for Apple SSL/TLS Implementation
  26  */
  27
  28 #ifndef _SECURITY_SECURETRANSPORT_H_
  29 #define _SECURITY_SECURETRANSPORT_H_
  30
  31 /*
  32  * This file describes the public API for an implementation of the
  33  * Secure Socket Layer, V. 3.0, Transport Layer Security, V. 1.0 to V. 1.2
  34  * and Datagram Transport Layer Security V. 1.0
  35  *
  36  * There are no transport layer dependencies in this library;
  37  * it can be used with sockets, Open Transport, etc. Applications using
  38  * this library provide callback functions which do the actual I/O
  39  * on underlying network connections. Applications are also responsible
  40  * for setting up raw network connections; the application passes in
  41  * an opaque reference to the underlying (connected) entity at the
  42  * start of an SSL session in the form of an SSLConnectionRef.
  43  *
  44  * Some terminology:
  45  *
  46  * A "client" is the initiator of an SSL Session. The canonical example
  47  * of a client is a web browser, when it's talking to an https URL.
  48  *
  49  * A "server" is an entity which accepts requests for SSL sessions made
  50  * by clients. E.g., a secure web server.
  51
  52  * An "SSL Session", or "session", is bounded by calls to SSLHandshake()
  53  * and SSLClose(). An "Active session" is in some state between these
  54  * two calls, inclusive.
  55  *
  56  * An SSL Session Context, or SSLContextRef, is an opaque reference in this
  57  * library to the state associated with one session. A SSLContextRef cannot
  58  * be reused for multiple sessions.
  59  */
  60
  61 #include <CoreFoundation/CFArray.h>
  62 #include <Security/CipherSuite.h>
  63 #include <Security/SecTrust.h>
  64 #include <sys/types.h>
  65 #include <Availability.h>
  66
  67 #ifdef __cplusplus
  68 extern "C" {
  69 #endif
  70
  71 CF_ASSUME_NONNULL_BEGIN
  72 CF_IMPLICIT_BRIDGING_ENABLED
  73
  74 /***********************
  75  *** Common typedefs ***
  76  ***********************/
  77
  78 /* Opaque reference to an SSL session context */
  79 struct                      SSLContext;
  80 typedef struct CF_BRIDGED_TYPE(id) SSLContext *SSLContextRef;
  81
  82 /* Opaque reference to an I/O connection (socket, endpoint, etc.) */
  83 typedef const void *            SSLConnectionRef;
  84
  85 /* SSL Protocol version */
  86 typedef CF_ENUM(int, SSLProtocol) {
  87     kSSLProtocolUnknown = 0, /* no protocol negotiated/specified; use default */
  88     kSSLProtocol3 = 2, /* SSL 3.0 */
  89     kTLSProtocol1 = 4, /* TLS 1.0 */
  90     kTLSProtocol11 = 7, /* TLS 1.1 */
  91     kTLSProtocol12 = 8, /* TLS 1.2 */
  92     kDTLSProtocol1 = 9, /* DTLS 1.0 */
  93     kTLSProtocol13 = 10, /* TLS 1.3 */
  94
  95     kTLSProtocolMaxSupported = 999, /* Max system-supported version */
  96
  97     kSSLProtocol2 = 1, /* SSL 2.0. DEPRECATED on iOS. */
  98     kSSLProtocol3Only = 3, /* SSL 3.0. DEPRECATED on iOS. */
  99     kTLSProtocol1Only = 5, /* TLS 1.0 Only. DEPRECATED on iOS. */
 100     kSSLProtocolAll = 6, /* All TLS supported protocols. DEPRECATED on iOS. */
 101 };
 102
 103 /* SSL session options */
 104 typedef CF_ENUM(int, SSLSessionOption) {
 105         /*
 106          * Set this option to enable returning from SSLHandshake (with a result of
 107          * errSSLServerAuthCompleted) when the server authentication portion of the
 108          * handshake is complete. This disable certificate verification and
 109          * provides an opportunity to perform application-specific server
 110          * verification before deciding to continue.
 111          */
 112         kSSLSessionOptionBreakOnServerAuth = 0,
 113         /*
 114          * Set this option to enable returning from SSLHandshake (with a result of
 115          * errSSLClientCertRequested) when the server requests a client certificate.
 116          */
 117         kSSLSessionOptionBreakOnCertRequested = 1,
 118     /*
 119      * This option is the same as kSSLSessionOptionBreakOnServerAuth but applies
 120      * to the case where SecureTransport is the server and the client has presented
 121      * its certificates allowing the server to verify whether these should be
 122      * allowed to authenticate.
 123      */
 124     kSSLSessionOptionBreakOnClientAuth = 2,
 125     /*
 126      * Enable/Disable TLS False Start
 127      * When enabled, False Start will only be performed if a adequate cipher-suite is
 128      * negotiated.
 129      */
 130     kSSLSessionOptionFalseStart = 3,
 131     /*
 132      * Enable/Disable 1/n-1 record splitting for BEAST attack mitigation.
 133      * When enabled, record splitting will only be performed for TLS 1.0 connections
 134      * using a block cipher.
 135      */
 136     kSSLSessionOptionSendOneByteRecord = 4,
 137     /*
 138      * Allow/Disallow server identity change on renegotiation. Disallow by default
 139      * to avoid Triple Handshake attack.
 140      */
 141     kSSLSessionOptionAllowServerIdentityChange = 5,
 142     /*
 143      * Enable fallback countermeasures. Use this option when retyring a SSL connection
 144      * with a lower protocol version because of failure to connect.
 145      */
 146     kSSLSessionOptionFallback = 6,
 147     /*
 148      * Set this option to break from a client hello in order to check for SNI
 149      */
 150     kSSLSessionOptionBreakOnClientHello = 7,
 151     /*
 152      * Set this option to Allow renegotations. False by default.
 153      */
 154     kSSLSessionOptionAllowRenegotiation = 8,
 155     /*
 156      * Set this option to enable session tickets. False by default.
 157      */
 158     kSSLSessionOptionEnableSessionTickets = 9,
 159 };
 160
 161 /* State of an SSLSession */
 162 typedef CF_ENUM(int, SSLSessionState) {
 163         kSSLIdle,                                       /* no I/O performed yet */
 164         kSSLHandshake,                          /* SSL handshake in progress */
 165         kSSLConnected,                          /* Handshake complete, ready for normal I/O */
 166         kSSLClosed,                                     /* connection closed normally */
 167         kSSLAborted                                     /* connection aborted */
 168 };
 169
 170 /*
 171  * Status of client certificate exchange (which is optional
 172  * for both server and client).
 173  */
 174 typedef CF_ENUM(int, SSLClientCertificateState) {
 175         /* Server hasn't asked for a cert. Client hasn't sent one. */
 176         kSSLClientCertNone,
 177         /* Server has asked for a cert, but client didn't send it. */
 178         kSSLClientCertRequested,
 179         /*
 180          * Server side: We asked for a cert, client sent one, we validated
 181          *                              it OK. App can inspect the cert via
 182          *                              SSLCopyPeerCertificates().
 183          * Client side: server asked for one, we sent it.
 184          */
 185         kSSLClientCertSent,
 186         /*
 187          * Client sent a cert but failed validation. Server side only.
 188          * Server app can inspect the cert via SSLCopyPeerCertificates().
 189          */
 190         kSSLClientCertRejected
 191 };
 192
 193 /*
 194  * Convenience ciphersuite groups that collate ciphersuites of comparable security
 195  * properties into a single alias.
 196  */
 197 typedef CF_ENUM(int, SSLCiphersuiteGroup) {
 198     kSSLCiphersuiteGroupDefault,
 199     kSSLCiphersuiteGroupCompatibility,
 200     kSSLCiphersuiteGroupLegacy,
 201     kSSLCiphersuiteGroupATS,
 202     kSSLCiphersuiteGroupATSCompatibility,
 203 };
 204
 205 /*
 206  * R/W functions. The application using this library provides
 207  * these functions via SSLSetIOFuncs().
 208  *
 209  * Data's memory is allocated by caller; on entry to these two functions
 210  * the *length argument indicates both the size of the available data and the
 211  * requested byte count. Number of bytes actually transferred is returned in
 212  * *length.
 213  *
 214  * The application may configure the underlying connection to operate
 215  * in a non-blocking manner; in such a case, a read operation may
 216  * well return errSSLWouldBlock, indicating "I transferred less data than
 217  * you requested (maybe even zero bytes), nothing is wrong, except
 218  * requested I/O hasn't completed". This will be returned back up to
 219  * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(),
 220  * etc.
 221  */
 222 typedef OSStatus
 223 (*SSLReadFunc)                          (SSLConnectionRef       connection,
 224                                                          void                           *data,                  /* owned by
 225                                                                                                                                  * caller, data
 226                                                                                                                                  * RETURNED */
 227                                                          size_t                         *dataLength);   /* IN/OUT */
 228 typedef OSStatus
 229 (*SSLWriteFunc)                         (SSLConnectionRef       connection,
 230                                                          const void             *data,
 231                                                          size_t                         *dataLength);   /* IN/OUT */
 232
 233 /*************************************************
 234  *** OSStatus values unique to SecureTransport ***
 235  *************************************************/
 236
 237 /*
 238     Note: the comments that appear after these errors are used to create SecErrorMessages.strings.
 239     The comments must not be multi-line, and should be in a form meaningful to an end user. If
 240     a different or additional comment is needed, it can be put in the header doc format, or on a
 241     line that does not start with errZZZ.
 242 */
 243
 244 CF_ENUM(OSStatus) {
 245         errSSLProtocol                          = -9800,        /* SSL protocol error */
 246         errSSLNegotiation                       = -9801,        /* Cipher Suite negotiation failure */
 247         errSSLFatalAlert                        = -9802,        /* Fatal alert */
 248         errSSLWouldBlock                        = -9803,        /* I/O would block (not fatal) */
 249     errSSLSessionNotFound               = -9804,        /* attempt to restore an unknown session */
 250     errSSLClosedGraceful                = -9805,        /* connection closed gracefully */
 251     errSSLClosedAbort                   = -9806,        /* connection closed via error */
 252     errSSLXCertChainInvalid     = -9807,        /* invalid certificate chain */
 253     errSSLBadCert                               = -9808,        /* bad certificate format */
 254         errSSLCrypto                            = -9809,        /* underlying cryptographic error */
 255         errSSLInternal                          = -9810,        /* Internal error */
 256         errSSLModuleAttach                      = -9811,        /* module attach failure */
 257     errSSLUnknownRootCert               = -9812,        /* valid cert chain, untrusted root */
 258     errSSLNoRootCert                    = -9813,        /* cert chain not verified by root */
 259         errSSLCertExpired                       = -9814,        /* chain had an expired cert */
 260         errSSLCertNotYetValid           = -9815,        /* chain had a cert not yet valid */
 261         errSSLClosedNoNotify            = -9816,        /* server closed session with no notification */
 262         errSSLBufferOverflow            = -9817,        /* insufficient buffer provided */
 263         errSSLBadCipherSuite            = -9818,        /* bad SSLCipherSuite */
 264
 265         /* fatal errors detected by peer */
 266         errSSLPeerUnexpectedMsg         = -9819,        /* unexpected message received */
 267         errSSLPeerBadRecordMac          = -9820,        /* bad MAC */
 268         errSSLPeerDecryptionFail        = -9821,        /* decryption failed */
 269         errSSLPeerRecordOverflow        = -9822,        /* record overflow */
 270         errSSLPeerDecompressFail        = -9823,        /* decompression failure */
 271         errSSLPeerHandshakeFail         = -9824,        /* handshake failure */
 272         errSSLPeerBadCert                       = -9825,        /* misc. bad certificate */
 273         errSSLPeerUnsupportedCert       = -9826,        /* bad unsupported cert format */
 274         errSSLPeerCertRevoked           = -9827,        /* certificate revoked */
 275         errSSLPeerCertExpired           = -9828,        /* certificate expired */
 276         errSSLPeerCertUnknown           = -9829,        /* unknown certificate */
 277         errSSLIllegalParam                      = -9830,        /* illegal parameter */
 278         errSSLPeerUnknownCA             = -9831,        /* unknown Cert Authority */
 279         errSSLPeerAccessDenied          = -9832,        /* access denied */
 280         errSSLPeerDecodeError           = -9833,        /* decoding error */
 281         errSSLPeerDecryptError          = -9834,        /* decryption error */
 282         errSSLPeerExportRestriction     = -9835,        /* export restriction */
 283         errSSLPeerProtocolVersion       = -9836,        /* bad protocol version */
 284         errSSLPeerInsufficientSecurity = -9837, /* insufficient security */
 285         errSSLPeerInternalError         = -9838,        /* internal error */
 286         errSSLPeerUserCancelled         = -9839,        /* user canceled */
 287         errSSLPeerNoRenegotiation       = -9840,        /* no renegotiation allowed */
 288
 289         /* non-fatal result codes */
 290         errSSLPeerAuthCompleted     = -9841,    /* peer cert is valid, or was ignored if verification disabled */
 291         errSSLClientCertRequested       = -9842,        /* server has requested a client cert */
 292
 293         /* more errors detected by us */
 294         errSSLHostNameMismatch          = -9843,        /* peer host name mismatch */
 295         errSSLConnectionRefused         = -9844,        /* peer dropped connection before responding */
 296         errSSLDecryptionFail            = -9845,        /* decryption failure */
 297         errSSLBadRecordMac                      = -9846,        /* bad MAC */
 298         errSSLRecordOverflow            = -9847,        /* record overflow */
 299         errSSLBadConfiguration          = -9848,        /* configuration error */
 300         errSSLUnexpectedRecord      = -9849,    /* unexpected (skipped) record in DTLS */
 301     errSSLWeakPeerEphemeralDHKey = -9850,       /* weak ephemeral dh key  */
 302
 303     /* non-fatal result codes */
 304     errSSLClientHelloReceived   = -9851,    /* SNI */
 305
 306     /* fatal errors resulting from transport or networking errors */
 307     errSSLTransportReset        = -9852,    /* transport (socket) shutdown, e.g., TCP RST or FIN. */
 308     errSSLNetworkTimeout        = -9853,    /* network timeout triggered */
 309
 310     /* fatal errors resulting from software misconfiguration */
 311     errSSLConfigurationFailed   = -9854,    /* TLS configuration failed */
 312
 313     /* additional errors */
 314     errSSLUnsupportedExtension  = -9855,    /* unsupported TLS extension */
 315     errSSLUnexpectedMessage     = -9856,    /* peer rejected unexpected message */
 316     errSSLDecompressFail        = -9857,    /* decompression failed */
 317     errSSLHandshakeFail         = -9858,    /* handshake failed */
 318     errSSLDecodeError           = -9859,    /* decode failed */
 319     errSSLInappropriateFallback = -9860,    /* inappropriate fallback */
 320     errSSLMissingExtension      = -9861,    /* missing extension */
 321     errSSLBadCertificateStatusResponse = -9862, /* bad OCSP response */
 322     errSSLCertificateRequired   = -9863,    /* certificate required */
 323     errSSLUnknownPSKIdentity    = -9864,    /* unknown PSK identity */
 324     errSSLUnrecognizedName      = -9865,    /* unknown or unrecognized name */
 325 };
 326
 327 /* DEPRECATED aliases for errSSLPeerAuthCompleted */
 328 #define errSSLServerAuthCompleted       errSSLPeerAuthCompleted
 329 #define errSSLClientAuthCompleted       errSSLPeerAuthCompleted
 330
 331 /* DEPRECATED alias for the end of the error range */
 332 #define errSSLLast errSSLUnexpectedRecord
 333
 334 typedef CF_ENUM(int, SSLProtocolSide)
 335 {
 336     kSSLServerSide,
 337     kSSLClientSide
 338 };
 339
 340 typedef CF_ENUM(int, SSLConnectionType)
 341 {
 342     kSSLStreamType,
 343     kSSLDatagramType
 344 };
 345
 346 /*
 347  * Predefined TLS configurations constants
 348  */
 349
 350 /* Default configuration (has 3DES, no RC4) */
 351 extern const CFStringRef kSSLSessionConfig_default
 352 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0);
 353
 354 /* ATS v1 Config: TLS v1.2, only PFS ciphersuites */
 355 extern const CFStringRef kSSLSessionConfig_ATSv1
 356 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 357
 358 /* ATS v1 Config without PFS: TLS v1.2, include non PFS ciphersuites */
 359 extern const CFStringRef kSSLSessionConfig_ATSv1_noPFS
 360 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 361
 362 /* TLS v1.2 to TLS v1.0, with default ciphersuites (no 3DES, no RC4) */
 363 extern const CFStringRef kSSLSessionConfig_standard
 364 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 365
 366 /* TLS v1.2 to TLS v1.0, with default ciphersuites + RC4 + 3DES */
 367 extern const CFStringRef kSSLSessionConfig_RC4_fallback
 368 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0);
 369
 370 /* TLS v1.0 only, with default ciphersuites + fallback SCSV */
 371 extern const CFStringRef kSSLSessionConfig_TLSv1_fallback
 372 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 373
 374 /* TLS v1.0, with default ciphersuites + RC4 + 3DES + fallback SCSV */
 375 extern const CFStringRef kSSLSessionConfig_TLSv1_RC4_fallback
 376 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0);
 377
 378 /* TLS v1.2 to TLS v1.0, defaults + RC4 + DHE ciphersuites */
 379 extern const CFStringRef kSSLSessionConfig_legacy
 380 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 381
 382 /* TLS v1.2 to TLS v1.0, default + RC4 + DHE ciphersuites */
 383 extern const CFStringRef kSSLSessionConfig_legacy_DHE
 384 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 385
 386 /* TLS v1.2, anonymous ciphersuites only */
 387 extern const CFStringRef kSSLSessionConfig_anonymous
 388 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 389
 390 /* TLS v1.2 to TLS v1.0, has 3DES, no RC4 */
 391 extern const CFStringRef kSSLSessionConfig_3DES_fallback
 392 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0);
 393
 394 /* TLS v1.0, with default ciphersuites + 3DES, no RC4 */
 395 extern const CFStringRef kSSLSessionConfig_TLSv1_3DES_fallback
 396 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0);
 397
 398
 399 /******************
 400  *** Public API ***
 401  ******************/
 402
 403 /*
 404  * Secure Transport APIs require a SSLContextRef, which is an opaque
 405  * reference to the SSL session and its parameters. On Mac OS X 10.7
 406  * and earlier versions, a new context is created using SSLNewContext,
 407  * and is disposed by calling SSLDisposeContext.
 408  *
 409  * On i0S 5.0 and later, as well as Mac OS X versions after 10.7, the
 410  * SSLContextRef is a true CFType object with retain-release semantics.
 411  * New code should create a new context using SSLCreateContext (instead
 412  * of SSLNewContext), and dispose the context by calling CFRelease
 413  * (instead of SSLDisposeContext) when finished with it.
 414  */
 415
 416 /*
 417  * Return the CFTypeID for SSLContext objects.
 418  */
 419 CFTypeID
 420 SSLContextGetTypeID(void)
 421         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 422
 423 /*
 424  * Create a new instance of an SSLContextRef using the specified allocator.
 425  */
 426 __nullable
 427 SSLContextRef
 428 SSLCreateContext(CFAllocatorRef __nullable alloc, SSLProtocolSide protocolSide, SSLConnectionType connectionType)
 429         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 430
 431
 432 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 433 /*
 434  * Create a new session context.
 435  *
 436  * ==========================
 437  * MAC OS X ONLY (DEPRECATED)
 438  * ==========================
 439  * NOTE: this function is not available on iOS, and should be considered
 440  * deprecated on Mac OS X. Your code should use SSLCreateContext instead.
 441  */
 442 OSStatus
 443 SSLNewContext                           (Boolean                        isServer,
 444                                                          SSLContextRef          * __nonnull CF_RETURNS_RETAINED contextPtr)     /* RETURNED */
 445         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 446
 447 /*
 448  * Dispose of a session context.
 449  *
 450  * ==========================
 451  * MAC OS X ONLY (DEPRECATED)
 452  * ==========================
 453  * NOTE: this function is not available on iOS, and should be considered
 454  * deprecated on Mac OS X. Your code should use CFRelease to dispose a session
 455  * created with SSLCreateContext.
 456  */
 457 OSStatus
 458 SSLDisposeContext                       (SSLContextRef          context)
 459         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 460
 461 #endif /* MAC OS X */
 462
 463 /*
 464  * Determine the state of an SSL/DTLS session.
 465  */
 466 OSStatus
 467 SSLGetSessionState                      (SSLContextRef          context,
 468                                                          SSLSessionState        *state)         /* RETURNED */
 469         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 470
 471 /*
 472  * Set options for an SSL session. Must be called prior to SSLHandshake();
 473  * subsequently cannot be called while session is active.
 474  */
 475 OSStatus
 476 SSLSetSessionOption                     (SSLContextRef          context,
 477                                                          SSLSessionOption       option,
 478                                                          Boolean                        value)
 479         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0);
 480
 481 /*
 482  * Determine current value for the specified option in a given SSL session.
 483  */
 484 OSStatus
 485 SSLGetSessionOption                     (SSLContextRef          context,
 486                                                          SSLSessionOption       option,
 487                                                          Boolean                        *value)
 488         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0);
 489
 490 /********************************************************************
 491  *** Session context configuration, common to client and servers. ***
 492  ********************************************************************/
 493
 494 /*
 495  * Specify functions which do the network I/O. Must be called prior
 496  * to SSLHandshake(); subsequently cannot be called while a session is
 497  * active.
 498  */
 499 OSStatus
 500 SSLSetIOFuncs                           (SSLContextRef          context,
 501                                                          SSLReadFunc            readFunc,
 502                                                          SSLWriteFunc           writeFunc)
 503         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 504
 505
 506 /*
 507  * Set a predefined configuration for the SSL Session
 508  *
 509  * This currently affect enabled protocol versions,
 510  * enabled ciphersuites, and the kSSLSessionOptionFallback
 511  * session option.
 512  */
 513 OSStatus
 514 SSLSetSessionConfig(SSLContextRef context,
 515                     CFStringRef config)
 516     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 517
 518 /*
 519  * Set the minimum SSL protocol version allowed. Optional.
 520  * The default is the lower supported protocol.
 521  *
 522  * This can only be called when no session is active.
 523  *
 524  * For TLS contexts, legal values for minVersion are :
 525  *              kSSLProtocol3
 526  *              kTLSProtocol1
 527  *              kTLSProtocol11
 528  *              kTLSProtocol12
 529  *
 530  * For DTLS contexts, legal values for minVersion are :
 531  *      kDTLSProtocol1
 532  */
 533 OSStatus
 534 SSLSetProtocolVersionMin  (SSLContextRef      context,
 535                            SSLProtocol        minVersion)
 536     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 537
 538 /*
 539  * Get minimum protocol version allowed
 540  */
 541 OSStatus
 542 SSLGetProtocolVersionMin  (SSLContextRef      context,
 543                            SSLProtocol        *minVersion)
 544     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 545
 546 /*
 547  * Set the maximum SSL protocol version allowed. Optional.
 548  * The default is the highest supported protocol.
 549  *
 550  * This can only be called when no session is active.
 551  *
 552  * For TLS contexts, legal values for maxVersion are :
 553  *              kSSLProtocol3
 554  *              kTLSProtocol1
 555  *              kTLSProtocol11
 556  *              kTLSProtocol12
 557  *
 558  * For DTLS contexts, legal values for maxVersion are :
 559  *      kDTLSProtocol1
 560  */
 561 OSStatus
 562 SSLSetProtocolVersionMax  (SSLContextRef      context,
 563                            SSLProtocol        maxVersion)
 564     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 565
 566 /*
 567  * Get maximum protocol version allowed
 568  */
 569 OSStatus
 570 SSLGetProtocolVersionMax  (SSLContextRef      context,
 571                            SSLProtocol        *maxVersion)
 572     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 573
 574
 575 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 576 /*
 577  * Set allowed SSL protocol versions. Optional.
 578  * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in
 579  * specified 'enable' boolean to be applied to all supported protocols.
 580  * The default is "all supported protocols are enabled".
 581  * This can only be called when no session is active.
 582  *
 583  * Legal values for protocol are :
 584  *              kSSLProtocol2
 585  *              kSSLProtocol3
 586  *              kTLSProtocol1
 587  *              kSSLProtocolAll
 588  *
 589  * ==========================
 590  * MAC OS X ONLY (DEPRECATED)
 591  * ==========================
 592  * NOTE: this function is not available on iOS, and should be considered
 593  * deprecated on Mac OS X. You can use SSLSetProtocolVersionMin and/or
 594  * SSLSetProtocolVersionMax to specify which protocols are enabled.
 595  */
 596 OSStatus
 597 SSLSetProtocolVersionEnabled (SSLContextRef     context,
 598                                                          SSLProtocol            protocol,
 599                                                          Boolean                        enable)
 600         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 601
 602 /*
 603  * Obtain a value specified in SSLSetProtocolVersionEnabled.
 604  *
 605  * ==========================
 606  * MAC OS X ONLY (DEPRECATED)
 607  * ==========================
 608  * NOTE: this function is not available on iOS, and should be considered
 609  * deprecated on Mac OS X. You can use SSLGetProtocolVersionMin and/or
 610  * SSLGetProtocolVersionMax to check whether a protocol is enabled.
 611  */
 612 OSStatus
 613 SSLGetProtocolVersionEnabled(SSLContextRef              context,
 614                                                          SSLProtocol            protocol,
 615                                                          Boolean                        *enable)        /* RETURNED */
 616         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 617
 618 /*
 619  * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown,
 620  * in which case the highest possible version is attempted, but a lower
 621  * version is accepted if the peer requires it.
 622  * SSLSetProtocolVersion cannot be called when a session is active.
 623  *
 624  * ==========================
 625  * MAC OS X ONLY (DEPRECATED)
 626  * ==========================
 627  * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8.
 628  * Use SSLSetProtocolVersionMin and/or SSLSetProtocolVersionMax to specify
 629  * which protocols are enabled.
 630  */
 631 OSStatus
 632 SSLSetProtocolVersion           (SSLContextRef          context,
 633                                                          SSLProtocol            version)
 634         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA);
 635
 636 /*
 637  * Obtain the protocol version specified in SSLSetProtocolVersion.
 638  * If SSLSetProtocolVersionEnabled() has been called for this session,
 639  * SSLGetProtocolVersion() may return errSecParam if the protocol enable
 640  * state can not be represented by the SSLProtocol enums (e.g.,
 641  * SSL2 and TLS1 enabled, SSL3 disabled).
 642  *
 643  * ==========================
 644  * MAC OS X ONLY (DEPRECATED)
 645  * ==========================
 646  * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8.
 647  * Use SSLGetProtocolVersionMin and/or SSLGetProtocolVersionMax to check
 648  * whether a protocol is enabled.
 649  */
 650 OSStatus
 651 SSLGetProtocolVersion           (SSLContextRef          context,
 652                                                          SSLProtocol            *protocol)      /* RETURNED */
 653         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA);
 654
 655 #endif /* MAC OS X */
 656
 657 /*
 658  * Specify this connection's certificate(s). This is mandatory for
 659  * server connections, optional for clients. Specifying a certificate
 660  * for a client enables SSL client-side authentication. The end-entity
 661  * cert is in certRefs[0]. Specifying a root cert is optional; if it's
 662  * not specified, the root cert which verifies the cert chain specified
 663  * here must be present in the system-wide set of trusted anchor certs.
 664  *
 665  * The certRefs argument is a CFArray containing SecCertificateRefs,
 666  * except for certRefs[0], which is a SecIdentityRef.
 667  *
 668  * Must be called prior to SSLHandshake(), or immediately after
 669  * SSLHandshake has returned errSSLClientCertRequested (i.e. before the
 670  * handshake is resumed by calling SSLHandshake again.)
 671  *
 672  * SecureTransport assumes the following:
 673  *
 674  *  -- The certRef references remain valid for the lifetime of the session.
 675  *  -- The certificate specified in certRefs[0] is capable of signing.
 676  *  -- The required capabilities of the certRef[0], and of the optional cert
 677  *     specified in SSLSetEncryptionCertificate (see below), are highly
 678  *     dependent on the application. For example, to work as a server with
 679  *     Netscape clients, the cert specified here must be capable of both
 680  *     signing and encrypting.
 681  */
 682 OSStatus
 683 SSLSetCertificate                       (SSLContextRef          context,
 684                                                          CFArrayRef                     _Nullable certRefs)
 685         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 686
 687 /*
 688  * Specify I/O connection - a socket, endpoint, etc., which is
 689  * managed by caller. On the client side, it's assumed that communication
 690  * has been established with the desired server on this connection.
 691  * On the server side, it's assumed that an incoming client request
 692  * has been established.
 693  *
 694  * Must be called prior to SSLHandshake(); subsequently can only be
 695  * called when no session is active.
 696  */
 697 OSStatus
 698 SSLSetConnection                        (SSLContextRef                  context,
 699                                                          SSLConnectionRef __nullable    connection)
 700         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 701
 702 OSStatus
 703 SSLGetConnection                        (SSLContextRef          context,
 704                                                          SSLConnectionRef       * __nonnull CF_RETURNS_NOT_RETAINED connection)
 705         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 706
 707 /*
 708  * Specify the fully qualified doman name of the peer, e.g., "store.apple.com."
 709  * Optional; used to verify the common name field in peer's certificate.
 710  * Name is in the form of a C string; NULL termination optional, i.e.,
 711  * peerName[peerNameLen+1] may or may not have a NULL. In any case peerNameLen
 712  * is the number of bytes of the peer domain name.
 713  */
 714 OSStatus
 715 SSLSetPeerDomainName            (SSLContextRef          context,
 716                                                          const char                     * __nullable peerName,
 717                                                          size_t                         peerNameLen)
 718         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 719
 720 /*
 721  * Determine the buffer size needed for SSLGetPeerDomainName().
 722  */
 723 OSStatus
 724 SSLGetPeerDomainNameLength      (SSLContextRef          context,
 725                                                          size_t                         *peerNameLen)   // RETURNED
 726         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 727
 728 /*
 729  * Obtain the value specified in SSLSetPeerDomainName().
 730  */
 731 OSStatus
 732 SSLGetPeerDomainName            (SSLContextRef          context,
 733                                                          char                           *peerName,              // returned here
 734                                                          size_t                         *peerNameLen)   // IN/OUT
 735         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 736
 737
 738 /*
 739  * Determine the buffer size needed for SSLCopyRequestedPeerNameLength().
 740  */
 741 OSStatus
 742 SSLCopyRequestedPeerName    (SSLContextRef      context,
 743                              char               *peerName,
 744                              size_t             *peerNameLen)
 745     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 746
 747 /*
 748  * Server Only: obtain the hostname specified by the client in the ServerName extension (SNI)
 749  */
 750 OSStatus
 751 SSLCopyRequestedPeerNameLength  (SSLContextRef  ctx,
 752                                  size_t         *peerNameLen)
 753     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 754
 755
 756 /*
 757  * Specify the Datagram TLS Hello Cookie.
 758  * This is to be called for server side only and is optional.
 759  * The default is a zero len cookie. The maximum cookieLen is 32 bytes.
 760  */
 761 OSStatus
 762 SSLSetDatagramHelloCookie       (SSLContextRef          dtlsContext,
 763                              const void         * __nullable cookie,
 764                              size_t             cookieLen)
 765         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 766
 767 /*
 768  * Specify the maximum record size, including all DTLS record headers.
 769  * This should be set appropriately to avoid fragmentation
 770  * of Datagrams during handshake, as fragmented datagrams may
 771  * be dropped by some network.
 772  * This is for Datagram TLS only
 773  */
 774 OSStatus
 775 SSLSetMaxDatagramRecordSize (SSLContextRef              dtlsContext,
 776                              size_t             maxSize)
 777         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 778
 779 /*
 780  * Get the maximum record size, including all Datagram TLS record headers.
 781  * This is for Datagram TLS only
 782  */
 783 OSStatus
 784 SSLGetMaxDatagramRecordSize (SSLContextRef              dtlsContext,
 785                              size_t             *maxSize)
 786         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
 787
 788 /*
 789  * Obtain the actual negotiated protocol version of the active
 790  * session, which may be different that the value specified in
 791  * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no
 792  * SSL session is in progress.
 793  */
 794 OSStatus
 795 SSLGetNegotiatedProtocolVersion         (SSLContextRef          context,
 796                                                                          SSLProtocol            *protocol)      /* RETURNED */
 797         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 798
 799 /*
 800  * Determine number and values of all of the SSLCipherSuites we support.
 801  * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in
 802  * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
 803  * will be returned.
 804  */
 805 OSStatus
 806 SSLGetNumberSupportedCiphers (SSLContextRef                     context,
 807                                                           size_t                                *numCiphers)
 808         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 809
 810 OSStatus
 811 SSLGetSupportedCiphers           (SSLContextRef                 context,
 812                                                           SSLCipherSuite                *ciphers,               /* RETURNED */
 813                                                           size_t                                *numCiphers)    /* IN/OUT */
 814         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 815
 816 /*
 817  * Specify a (typically) restricted set of SSLCipherSuites to be enabled by
 818  * the current SSLContext. Can only be called when no session is active. Default
 819  * set of enabled SSLCipherSuites is the same as the complete set of supported
 820  * SSLCipherSuites as obtained by SSLGetSupportedCiphers().
 821  */
 822 OSStatus
 823 SSLSetEnabledCiphers            (SSLContextRef                  context,
 824                                                          const SSLCipherSuite   *ciphers,
 825                                                          size_t                                 numCiphers)
 826         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 827
 828 /*
 829  * Determine number and values of all of the SSLCipherSuites currently enabled.
 830  * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in
 831  * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
 832  * will be returned.
 833  */
 834 OSStatus
 835 SSLGetNumberEnabledCiphers      (SSLContextRef                  context,
 836                                                          size_t                                 *numCiphers)
 837         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 838
 839 OSStatus
 840 SSLGetEnabledCiphers            (SSLContextRef                  context,
 841                                                          SSLCipherSuite                 *ciphers,               /* RETURNED */
 842                                                          size_t                                 *numCiphers)    /* IN/OUT */
 843         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 844
 845 /*
 846  * Forcibly enable or disable session ticket resumption. By default, session tickets
 847  * are disabled.
 848  */
 849 OSStatus
 850 SSLSetSessionTicketsEnabled     (SSLContextRef          context,
 851                                  Boolean                enabled)
 852     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 853
 854
 855 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 856 /*
 857  * Enable/disable peer certificate chain validation. Default is enabled.
 858  * If caller disables, it is the caller's responsibility to call
 859  * SSLCopyPeerCertificates() upon successful completion of the handshake
 860  * and then to perform external validation of the peer certificate
 861  * chain before proceeding with data transfer.
 862  *
 863  * ==========================
 864  * MAC OS X ONLY (DEPRECATED)
 865  * ==========================
 866  * NOTE: this function is not available on iOS, and should be considered
 867  * deprecated on Mac OS X. To disable peer certificate chain validation, you
 868  * can instead use SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth
 869  * to true. This will disable verification and cause SSLHandshake to return with
 870  * an errSSLServerAuthCompleted result when the peer certificates have been
 871  * received; at that time, you can choose to evaluate peer trust yourself, or
 872  * simply call SSLHandshake again to proceed with the handshake.
 873  */
 874 OSStatus
 875 SSLSetEnableCertVerify          (SSLContextRef                  context,
 876                                                          Boolean                                enableVerify)
 877         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 878
 879 /*
 880  * Check whether peer certificate chain validation is enabled.
 881  *
 882  * ==========================
 883  * MAC OS X ONLY (DEPRECATED)
 884  * ==========================
 885  * NOTE: this function is not available on iOS, and should be considered
 886  * deprecated on Mac OS X. To check whether peer certificate chain validation
 887  * is enabled in a context, call SSLGetSessionOption to obtain the value of
 888  * the kSSLSessionOptionBreakOnServerAuth session option flag. If the value
 889  * of this option flag is true, then verification is disabled.
 890  */
 891 OSStatus
 892 SSLGetEnableCertVerify          (SSLContextRef                  context,
 893                                                          Boolean                                *enableVerify)  /* RETURNED */
 894         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 895
 896 /*
 897  * Specify the option of ignoring certificates' "expired" times.
 898  * This is a common failure in the real SSL world. Default setting for this
 899  * flag is false, meaning expired certs result in an errSSLCertExpired error.
 900  *
 901  * ==========================
 902  * MAC OS X ONLY (DEPRECATED)
 903  * ==========================
 904  * NOTE: this function is not available on iOS, and should be considered
 905  * deprecated on Mac OS X. To ignore expired certificate errors, first disable
 906  * Secure Transport's automatic verification of peer certificates by calling
 907  * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
 908  * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
 909  * your code should obtain the SecTrustRef for the peer's certificates and
 910  * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
 911  * The SecTrustSetOptions function allows you to specify that the expiration
 912  * status of certificates should be ignored for this evaluation.
 913  *
 914  * Example:
 915  *
 916  *      status = SSLSetSessionOption(ctx, kSSLSessionOptionBreakOnServerAuth, true);
 917  *      do {
 918  *              status = SSLHandshake(ctx);
 919  *
 920  *              if (status == errSSLServerAuthCompleted) {
 921  *                      SecTrustRef peerTrust = NULL;
 922  *                      status = SSLCopyPeerTrust(ctx, &peerTrust);
 923  *                      if (status == errSecSuccess) {
 924  *                              SecTrustResultType trustResult;
 925  *                              // set flag to allow expired certificates
 926  *                              SecTrustSetOptions(peerTrust, kSecTrustOptionAllowExpired);
 927  *                              status = SecTrustEvaluate(peerTrust, &trustResult);
 928  *                              if (status == errSecSuccess) {
 929  *                                      // A "proceed" result means the cert is explicitly trusted,
 930  *                                      // e.g. "Always Trust" was clicked;
 931  *                                      // "Unspecified" means the cert has no explicit trust settings,
 932  *                                      // but is implicitly OK since it chains back to a trusted root.
 933  *                                      // Any other result means the cert is not trusted.
 934  *                                      //
 935  *                                      if (trustResult == kSecTrustResultProceed ||
 936  *                                              trustResult == kSecTrustResultUnspecified) {
 937  *                                              // certificate is trusted
 938  *                                              status = errSSLWouldBlock; // so we call SSLHandshake again
 939  *                                      } else if (trustResult == kSecTrustResultRecoverableTrustFailure) {
 940  *                                              // not trusted, for some reason other than being expired;
 941  *                                              // could ask the user whether to allow the connection here
 942  *                                              //
 943  *                                              status = errSSLXCertChainInvalid;
 944  *                                      } else {
 945  *                                              // cannot use this certificate (fatal)
 946  *                                              status = errSSLBadCert;
 947  *                                      }
 948  *                              }
 949  *                              if (peerTrust) {
 950  *                                      CFRelease(peerTrust);
 951  *                              }
 952  *                      }
 953  *              } // errSSLServerAuthCompleted
 954  *
 955  *      } while (status == errSSLWouldBlock);
 956  *
 957  */
 958 OSStatus
 959 SSLSetAllowsExpiredCerts        (SSLContextRef          context,
 960                                                          Boolean                        allowsExpired)
 961         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 962
 963 /*
 964  * Obtain the current value of an SSLContext's "allowExpiredCerts" flag.
 965  *
 966  * ==========================
 967  * MAC OS X ONLY (DEPRECATED)
 968  * ==========================
 969  * NOTE: this function is not available on iOS, and should be considered
 970  * deprecated on Mac OS X.
 971  */
 972 OSStatus
 973 SSLGetAllowsExpiredCerts        (SSLContextRef          context,
 974                                                          Boolean                        *allowsExpired) /* RETURNED */
 975         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
 976
 977 /*
 978  * Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the
 979  * option of ignoring "expired" status for root certificates only.
 980  * Default setting is false, i.e., expired root certs result in an
 981  * errSSLCertExpired error.
 982  *
 983  * ==========================
 984  * MAC OS X ONLY (DEPRECATED)
 985  * ==========================
 986  * NOTE: this function is not available on iOS, and should be considered
 987  * deprecated on Mac OS X. To ignore expired certificate errors, first disable
 988  * Secure Transport's automatic verification of peer certificates by calling
 989  * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
 990  * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
 991  * your code should obtain the SecTrustRef for the peer's certificates and
 992  * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
 993  * The SecTrustSetOptions function allows you to specify that the expiration
 994  * status of certificates should be ignored for this evaluation.
 995  *
 996  * See the description of the SSLSetAllowsExpiredCerts function (above)
 997  * for a code example. The kSecTrustOptionAllowExpiredRoot option can be used
 998  * instead of kSecTrustOptionAllowExpired to allow expired roots only.
 999  */
1000 OSStatus
1001 SSLSetAllowsExpiredRoots        (SSLContextRef          context,
1002                                                          Boolean                        allowsExpired)
1003         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1004
1005 /*
1006  * Obtain the current value of an SSLContext's "allow expired roots" flag.
1007  *
1008  * ==========================
1009  * MAC OS X ONLY (DEPRECATED)
1010  * ==========================
1011  * NOTE: this function is not available on iOS, and should be considered
1012  * deprecated on Mac OS X.
1013  */
1014 OSStatus
1015 SSLGetAllowsExpiredRoots        (SSLContextRef          context,
1016                                                          Boolean                        *allowsExpired) /* RETURNED */
1017         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1018
1019 /*
1020  * Specify option of allowing for an unknown root cert, i.e., one which
1021  * this software can not verify as one of a list of known good root certs.
1022  * Default for this flag is false, in which case one of the following two
1023  * errors may occur:
1024  *    -- The peer returns a cert chain with a root cert, and the chain
1025  *       verifies to that root, but the root is not one of our trusted
1026  *       roots. This results in errSSLUnknownRootCert on handshake.
1027  *    -- The peer returns a cert chain which does not contain a root cert,
1028  *       and we can't verify the chain to one of our trusted roots. This
1029  *       results in errSSLNoRootCert on handshake.
1030  *
1031  * Both of these error conditions are ignored when the AllowAnyRoot flag is
1032  * true, allowing connection to a totally untrusted peer.
1033  *
1034  * ==========================
1035  * MAC OS X ONLY (DEPRECATED)
1036  * ==========================
1037  * NOTE: this function is not available on iOS, and should be considered
1038  * deprecated on Mac OS X. To ignore unknown root cert errors, first disable
1039  * Secure Transport's automatic verification of peer certificates by calling
1040  * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
1041  * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
1042  * your code should obtain the SecTrustRef for the peer's certificates and
1043  * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
1044  *
1045  * See the description of the SSLSetAllowsExpiredCerts function (above)
1046  * for a code example. Note that an unknown root certificate will cause
1047  * SecTrustEvaluate to report kSecTrustResultRecoverableTrustFailure as the
1048  * trust result.
1049  */
1050 OSStatus
1051 SSLSetAllowsAnyRoot                     (SSLContextRef          context,
1052                                                          Boolean                        anyRoot)
1053         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1054
1055 /*
1056  * Obtain the current value of an SSLContext's "allow any root" flag.
1057  *
1058  * ==========================
1059  * MAC OS X ONLY (DEPRECATED)
1060  * ==========================
1061  * NOTE: this function is not available on iOS, and should be considered
1062  * deprecated on Mac OS X.
1063  */
1064 OSStatus
1065 SSLGetAllowsAnyRoot                     (SSLContextRef          context,
1066                                                          Boolean                        *anyRoot) /* RETURNED */
1067         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1068
1069 /*
1070  * Augment or replace the system's default trusted root certificate set
1071  * for this session. If replaceExisting is true, the specified roots will
1072  * be the only roots which are trusted during this session. If replaceExisting
1073  * is false, the specified roots will be added to the current set of trusted
1074  * root certs. If this function has never been called, the current trusted
1075  * root set is the same as the system's default trusted root set.
1076  * Successive calls with replaceExisting false result in accumulation
1077  * of additional root certs.
1078  *
1079  * The trustedRoots array contains SecCertificateRefs.
1080  *
1081  * ==========================
1082  * MAC OS X ONLY (DEPRECATED)
1083  * ==========================
1084  * NOTE: this function is not available on iOS, and should be considered
1085  * deprecated on Mac OS X. To trust specific roots in a session, first disable
1086  * Secure Transport's automatic verification of peer certificates by calling
1087  * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
1088  * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
1089  * your code should obtain the SecTrustRef for the peer's certificates and
1090  * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
1091  *
1092  * See the description of the SSLSetAllowsExpiredCerts function (above)
1093  * for a code example. You can call SecTrustSetAnchorCertificates to
1094  * augment the system's trusted root set, or SecTrustSetAnchorCertificatesOnly
1095  * to make these the only trusted roots, prior to calling SecTrustEvaluate.
1096  */
1097 OSStatus
1098 SSLSetTrustedRoots                      (SSLContextRef          context,
1099                                                          CFArrayRef             trustedRoots,
1100                                                          Boolean                        replaceExisting)
1101         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1102
1103 /*
1104  * Obtain an array of SecCertificateRefs representing the current
1105  * set of trusted roots. If SSLSetTrustedRoots() has never been called
1106  * for this session, this returns the system's default root set.
1107  *
1108  * Caller must CFRelease the returned CFArray.
1109  *
1110  * ==========================
1111  * MAC OS X ONLY (DEPRECATED)
1112  * ==========================
1113  * NOTE: this function is not available on iOS, and should be considered
1114  * deprecated on Mac OS X. To get the current set of trusted roots, call the
1115  * SSLCopyPeerTrust function to obtain the SecTrustRef for the peer certificate
1116  * chain, then SecTrustCopyCustomAnchorCertificates (see SecTrust.h).
1117  */
1118 OSStatus
1119 SSLCopyTrustedRoots                     (SSLContextRef          context,
1120                                                          CFArrayRef             * __nonnull CF_RETURNS_RETAINED trustedRoots)   /* RETURNED */
1121         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1122
1123 /*
1124  * Request peer certificates. Valid anytime, subsequent to a handshake attempt.
1125  *
1126  * The certs argument is a CFArray containing SecCertificateRefs.
1127  * Caller must CFRelease the returned array.
1128  *
1129  * The cert at index 0 of the returned array is the subject (end
1130  * entity) cert; the root cert (or the closest cert to it) is at
1131  * the end of the returned array.
1132  *
1133  * ==========================
1134  * MAC OS X ONLY (DEPRECATED)
1135  * ==========================
1136  * NOTE: this function is not available on iOS, and should be considered
1137  * deprecated on Mac OS X. To get peer certificates, call SSLCopyPeerTrust
1138  * to obtain the SecTrustRef for the peer certificate chain, then use the
1139  * SecTrustGetCertificateCount and SecTrustGetCertificateAtIndex functions
1140  * to retrieve individual certificates in the chain (see SecTrust.h).
1141  */
1142 OSStatus
1143 SSLCopyPeerCertificates         (SSLContextRef          context,
1144                                                          CFArrayRef                     * __nonnull CF_RETURNS_RETAINED certs)          /* RETURNED */
1145         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1146
1147 #endif /* MAC OS X */
1148
1149 /*
1150  * Obtain a SecTrustRef representing peer certificates. Valid anytime,
1151  * subsequent to a handshake attempt. Caller must CFRelease the returned
1152  * trust reference.
1153  *
1154  * The returned trust reference will have already been evaluated for you,
1155  * unless one of the following is true:
1156  * - Your code has disabled automatic certificate verification, by calling
1157  *   SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true.
1158  * - Your code has called SSLSetPeerID, and this session has been resumed
1159  *   from an earlier cached session.
1160  *
1161  * In these cases, your code should call SecTrustEvaluate prior to
1162  * examining the peer certificate chain or trust results (see SecTrust.h).
1163  *
1164  * NOTE: if you have not called SSLHandshake at least once prior to
1165  * calling this function, the returned trust reference will be NULL.
1166  */
1167 OSStatus
1168 SSLCopyPeerTrust                        (SSLContextRef          context,
1169                                                          SecTrustRef            * __nonnull CF_RETURNS_RETAINED trust)          /* RETURNED */
1170         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0);
1171
1172 /*
1173  * Specify some data, opaque to this library, which is sufficient
1174  * to uniquely identify the peer of the current session. An example
1175  * would be IP address and port, stored in some caller-private manner.
1176  * To be optionally called prior to SSLHandshake for the current
1177  * session. This is mandatory if this session is to be resumable.
1178  *
1179  * SecureTransport allocates its own copy of the incoming peerID. The
1180  * data provided in *peerID, while opaque to SecureTransport, is used
1181  * in a byte-for-byte compare to other previous peerID values set by the
1182  * current application. Matching peerID blobs result in SecureTransport
1183  * attempting to resume an SSL session with the same parameters as used
1184  * in the previous session which specified the same peerID bytes.
1185  */
1186 OSStatus
1187 SSLSetPeerID                            (SSLContextRef          context,
1188                                                          const void             * __nullable peerID,
1189                                                          size_t                         peerIDLen)
1190         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1191
1192 /*
1193  * Obtain current PeerID. Returns NULL pointer, zero length if
1194  * SSLSetPeerID has not been called for this context.
1195  */
1196 OSStatus
1197 SSLGetPeerID                            (SSLContextRef          context,
1198                                                          const void             * __nullable * __nonnull peerID,
1199                                                          size_t                         *peerIDLen)
1200         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1201
1202 /*
1203  * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated
1204  * for this session. Only valid when a session is active.
1205  */
1206 OSStatus
1207 SSLGetNegotiatedCipher          (SSLContextRef          context,
1208                                                          SSLCipherSuite         *cipherSuite)
1209         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1210
1211 /*
1212  * Set the ALPN protocols to be passed in the ALPN negotiation.
1213  * This is the list of supported application-layer protocols supported.
1214  *
1215  * The protocols parameter must be an array of CFStringRef values
1216  * with ASCII-encoded reprensetations of the supported protocols, e.g., "http/1.1".
1217  *
1218  * See RFC 7301 for more information.
1219  */
1220 OSStatus
1221 SSLSetALPNProtocols         (SSLContextRef      context,
1222                              CFArrayRef         protocols)
1223     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
1224
1225 /*
1226  * Get the ALPN protocols associated with this SSL context.
1227  * This is the list of supported application-layer protocols supported.
1228  *
1229  * The resultant protocols array will contain CFStringRef values containing
1230  * ASCII-encoded representations of the supported protocols, e.g., "http/1.1".
1231  *
1232  * See RFC 7301 for more information.
1233  *
1234  * Note: The `protocols` pointer must be NULL, otherwise the copy will fail.
1235  * This function will allocate memory for the CFArrayRef container
1236  * if there is data to provide. Otherwise, the pointer will remain NULL.
1237  */
1238 OSStatus
1239 SSLCopyALPNProtocols        (SSLContextRef      context,
1240                              CFArrayRef         __nullable * __nonnull protocols)           /* RETURNED */
1241     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
1242
1243 /*
1244  * Set the OCSP response for the given SSL session.
1245  *
1246  * The response parameter must be a non-NULL CFDataRef containing the
1247  * bytes of the OCSP response.
1248  */
1249 OSStatus
1250 SSLSetOCSPResponse          (SSLContextRef      context,
1251                              CFDataRef          __nonnull response)
1252 __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
1253
1254 /********************************************************
1255  *** Session context configuration, server side only. ***
1256  ********************************************************/
1257
1258 /*
1259  * This function is deprecated in OSX 10.11 and iOS 9.0 and
1260  * has no effect on the TLS handshake since OSX 10.10 and
1261  * iOS 8.0. Using separate RSA certificates for encryption
1262  * and signing is no longer supported.
1263  */
1264 OSStatus
1265 SSLSetEncryptionCertificate     (SSLContextRef          context,
1266                                                          CFArrayRef                     certRefs)
1267         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_11, __IPHONE_5_0, __IPHONE_9_0);
1268
1269 /*
1270  * Specify requirements for client-side authentication.
1271  * Optional; Default is kNeverAuthenticate.
1272  *
1273  * Can only be called when no session is active.
1274  */
1275 typedef CF_ENUM(int, SSLAuthenticate) {
1276         kNeverAuthenticate,                     /* skip client authentication */
1277         kAlwaysAuthenticate,            /* require it */
1278         kTryAuthenticate                        /* try to authenticate, but not an error
1279                                                                  * if client doesn't have a cert */
1280 };
1281
1282 OSStatus
1283 SSLSetClientSideAuthenticate    (SSLContextRef          context,
1284                                                                  SSLAuthenticate        auth)
1285         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1286
1287 /*
1288  * Add a DER-encoded distinguished name to list of acceptable names
1289  * to be specified in requests for client certificates.
1290  */
1291 OSStatus
1292 SSLAddDistinguishedName         (SSLContextRef          context,
1293                                                          const void             * __nullable derDN,
1294                                                          size_t                         derDNLen)
1295         __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_5_0);
1296
1297
1298 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
1299 /*
1300  * Add a SecCertificateRef, or a CFArray of them, to a server's list
1301  * of acceptable Certificate Authorities (CAs) to present to the client
1302  * when client authentication is performed.
1303  *
1304  * If replaceExisting is true, the specified certificate(s) will replace
1305  * a possible existing list of acceptable CAs. If replaceExisting is
1306  * false, the specified certificate(s) will be appended to the existing
1307  * list of acceptable CAs, if any.
1308  *
1309  * Returns errSecParam if this is called on a SSLContextRef which
1310  * is configured as a client, or when a session is active.
1311  *
1312  * NOTE: this function is currently not available on iOS.
1313  */
1314 OSStatus
1315 SSLSetCertificateAuthorities(SSLContextRef              context,
1316                                                          CFTypeRef                      certificateOrArray,
1317                                                          Boolean                        replaceExisting)
1318         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
1319
1320 /*
1321  * Obtain the certificates specified in SSLSetCertificateAuthorities(),
1322  * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not
1323  * been called.
1324  * Caller must CFRelease the returned array.
1325  *
1326  * NOTE: this function is currently not available on iOS.
1327  */
1328 OSStatus
1329 SSLCopyCertificateAuthorities(SSLContextRef             context,
1330                                                           CFArrayRef            * __nonnull CF_RETURNS_RETAINED certificates)   /* RETURNED */
1331         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
1332
1333 #endif /* MAC OS X */
1334
1335 /*
1336  * Obtain the list of acceptable distinguished names as provided by
1337  * a server (if the SSLContextRef is configured as a client), or as
1338  * specified by SSLSetCertificateAuthorities (if the SSLContextRef
1339  * is configured as a server).
1340  * The returned array contains CFDataRefs, each of which represents
1341  * one DER-encoded RDN.
1342  *
1343  * Caller must CFRelease the returned array.
1344  */
1345 OSStatus
1346 SSLCopyDistinguishedNames       (SSLContextRef          context,
1347                                                          CFArrayRef                     * __nonnull CF_RETURNS_RETAINED names)
1348         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_5_0);
1349
1350 /*
1351  * Obtain client certificate exchange status. Can be called
1352  * any time. Reflects the *last* client certificate state change;
1353  * subsequent to a renegotiation attempt by either peer, the state
1354  * is reset to kSSLClientCertNone.
1355  */
1356 OSStatus
1357 SSLGetClientCertificateState    (SSLContextRef                          context,
1358                                                                  SSLClientCertificateState      *clientState)
1359         __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_5_0);
1360
1361
1362 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
1363 /*
1364  * Specify Diffie-Hellman parameters. Optional; if we are configured to allow
1365  * for D-H ciphers and a D-H cipher is negotiated, and this function has not
1366  * been called, a set of process-wide parameters will be calculated. However
1367  * that can take a long time (30 seconds).
1368  *
1369  * NOTE: this function is currently not available on iOS.
1370  */
1371 OSStatus SSLSetDiffieHellmanParams      (SSLContextRef                  context,
1372                                                                          const void                     * __nullable dhParams,
1373                                                                          size_t                                 dhParamsLen)
1374         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA);
1375
1376 /*
1377  * Return parameter block specified in SSLSetDiffieHellmanParams.
1378  * Returned data is not copied and belongs to the SSLContextRef.
1379  *
1380  * NOTE: this function is currently not available on iOS.
1381  */
1382 OSStatus SSLGetDiffieHellmanParams      (SSLContextRef                  context,
1383                                                                          const void                     * __nullable * __nonnull dhParams,
1384                                                                          size_t                                 *dhParamsLen)
1385         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA);
1386
1387 /*
1388  * Enable/Disable RSA blinding. This feature thwarts a known timing
1389  * attack to which RSA keys are vulnerable; enabling it is a tradeoff
1390  * between performance and security. The default for RSA blinding is
1391  * enabled.
1392  *
1393  * ==========================
1394  * MAC OS X ONLY (DEPRECATED)
1395  * ==========================
1396  * NOTE: this function is not available on iOS, and should be considered
1397  * deprecated on Mac OS X. RSA blinding is enabled unconditionally, as
1398  * it prevents a known way for an attacker to recover the private key,
1399  * and the performance gain of disabling it is negligible.
1400  */
1401 OSStatus SSLSetRsaBlinding                      (SSLContextRef                  context,
1402                                                                          Boolean                                blinding)
1403         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1404
1405 OSStatus SSLGetRsaBlinding                      (SSLContextRef                  context,
1406                                                                          Boolean                                *blinding)
1407         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA);
1408
1409 #endif /* MAC OS X */
1410
1411 /*******************************
1412  ******** I/O Functions ********
1413  *******************************/
1414
1415 /*
1416  * Note: depending on the configuration of the underlying I/O
1417  * connection, all SSL I/O functions can return errSSLWouldBlock,
1418  * indicating "not complete, nothing is wrong, except required
1419  * I/O hasn't completed". Caller may need to repeat I/Os as necessary
1420  * if the underlying connection has been configured to behave in
1421  * a non-blocking manner.
1422  */
1423
1424 /*
1425  * Perform the SSL handshake. On successful return, session is
1426  * ready for normal secure application I/O via SSLWrite and SSLRead.
1427  *
1428  * Interesting error returns:
1429  *
1430  *  errSSLUnknownRootCert: Peer had a valid cert chain, but the root of
1431  *      the chain is unknown.
1432  *
1433  *  errSSLNoRootCert: Peer had a cert chain which did not end in a root.
1434  *
1435  *  errSSLCertExpired: Peer's cert chain had one or more expired certs.
1436  *
1437  *  errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e.,
1438  *      signature verification within the chain failed, or no certs
1439  *      were found).
1440  *
1441  *  In all of the above errors, the handshake was aborted; the peer's
1442  *  cert chain is available via SSLCopyPeerTrust or SSLCopyPeerCertificates.
1443  *
1444  *  Other interesting result codes:
1445  *
1446  *  errSSLPeerAuthCompleted: Peer's cert chain is valid, or was ignored if
1447  *      cert verification was disabled via SSLSetEnableCertVerify. The application
1448  *      may decide to continue with the handshake (by calling SSLHandshake
1449  *      again), or close the connection at this point.
1450  *
1451  *  errSSLClientCertRequested: The server has requested a client certificate.
1452  *      The client may choose to examine the server's certificate and
1453  *      distinguished name list, then optionally call SSLSetCertificate prior
1454  *      to resuming the handshake by calling SSLHandshake again.
1455  *
1456  * A return value of errSSLWouldBlock indicates that SSLHandshake has to be
1457  * called again (and again and again until something else is returned).
1458  */
1459 OSStatus
1460 SSLHandshake                            (SSLContextRef          context)
1461         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1462
1463 /*
1464  * Server Only: Request renegotation.
1465  * This will return an error if the server is already renegotiating, or if the session is closed.
1466  * After this return without error, the application should call SSLHandshake() and/or SSLRead() as
1467  * for the original handshake.
1468  */
1469 OSStatus
1470 SSLReHandshake                          (SSLContextRef          context)
1471     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
1472
1473
1474 /*
1475  * Normal application-level read/write. On both of these, a errSSLWouldBlock
1476  * return and a partially completed transfer - or even zero bytes transferred -
1477  * are NOT mutually exclusive.
1478  */
1479 OSStatus
1480 SSLWrite                                        (SSLContextRef          context,
1481                                                          const void *           __nullable data,
1482                                                          size_t                         dataLength,
1483                                                          size_t                         *processed)             /* RETURNED */
1484         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1485
1486 /*
1487  * data is mallocd by caller; available size specified in
1488  * dataLength; actual number of bytes read returned in
1489  * *processed.
1490  */
1491 OSStatus
1492 SSLRead                                         (SSLContextRef          context,
1493                                                          void *                         data,                   /* RETURNED */
1494                                                          size_t                         dataLength,
1495                                                          size_t                         *processed)             /* RETURNED */
1496         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1497
1498 /*
1499  * Determine how much data the client can be guaranteed to
1500  * obtain via SSLRead() without blocking or causing any low-level
1501  * read operations to occur.
1502  */
1503 OSStatus
1504 SSLGetBufferedReadSize          (SSLContextRef context,
1505                                                          size_t *bufSize)                                       /* RETURNED */
1506         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1507
1508 /*
1509  * Determine how much data the application can be guaranteed to write
1510  * with SSLWrite() without causing fragmentation. The value is based on
1511  * the maximum Datagram Record size defined by the application with
1512  * SSLSetMaxDatagramRecordSize(), minus the DTLS Record header size.
1513  */
1514 OSStatus
1515 SSLGetDatagramWriteSize         (SSLContextRef dtlsContext,
1516                                                          size_t *bufSize)
1517         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0);
1518
1519 /*
1520  * Terminate current SSL session.
1521  */
1522 OSStatus
1523 SSLClose                                        (SSLContextRef          context)
1524         __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
1525
1526 /*
1527  * Set the status of a SSLContextRef. This is to be done after handling
1528  * steps of the SSL handshake such as server certificate validation.
1529  */
1530 OSStatus
1531 SSLSetError                 (SSLContextRef      context,
1532                              OSStatus           status)
1533     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
1534
1535 CF_IMPLICIT_BRIDGING_DISABLED
1536 CF_ASSUME_NONNULL_END
1537
1538 #ifdef __cplusplus
1539 }
1540 #endif
1541
1542 #endif /* !_SECURITY_SECURETRANSPORT_H_ */