Security/libsecurity_ssl/lib/SecureTransport.h

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