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