OSX/libsecurity_ssl/lib/SecureTransport.h

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