libsecurity_ssl/lib/SecureTransport.h

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