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