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