SecureTransport/SecureTransport/SecureTransport.h

   1 /*
   2  * Copyright (c) 2000-2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 /*
  20         File:           SecureTransport.h
  21
  22         Contains:       Public API for Apple SSL/TLS Implementation
  23
  24         Copyright: (c) 1999-2002 by Apple Computer, Inc., all rights reserved.
  25
  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, and Transport Layer Security, V. 1.0.
  34  *
  35  * There no transport layer dependencies in this library;
  36  * it can be used with sockets, Open Transport, etc. Applications using
  37  * this library provide callback functions which do the actual I/O
  38  * on underlying network connections. Applications are also responsible
  39  * for setting up raw network connections; the application passes in
  40  * an opaque reference to the underlying (connected) entity at the
  41  * start of an SSL session in the form of an SSLConnectionRef.
  42  *
  43  * Some terminology:
  44  *
  45  * A "client" is the initiator of an SSL Session. The canonical example
  46  * of a client is a web browser, when it's talking to an https URL.
  47  *
  48  * A "server" is an entity which accepts requests for SSL sessions made
  49  * by clients. E.g., a secure web server.
  50
  51  * An "SSL Session", or "session", is bounded by calls to SSLHandshake()
  52  * and SSLClose(). An "Active session" is in some state between these
  53  * two calls, inclusive.
  54  *
  55  * An SSL Session Context, or SSLContextRef, is an opaque reference in this
  56  * library to the state associated with one session. A SSLContextRef cannot
  57  * be reused for multiple sessions.
  58  */
  59
  60 #include <CoreServices/../Frameworks/CarbonCore.framework/Headers/MacTypes.h>
  61 #include <CoreFoundation/CFArray.h>
  62 #include <Security/CipherSuite.h>
  63 #include <sys/types.h>
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /***********************
  70  *** Common typedefs ***
  71  ***********************/
  72
  73 /* Opaque reference to an SSL session context */
  74 struct                      SSLContext;
  75 typedef struct SSLContext   *SSLContextRef;
  76
  77 /* Opaque reference to an I/O conection (socket, Endpoint, etc.) */
  78 typedef const void *            SSLConnectionRef;
  79
  80 /* SSL Protocol version */
  81 typedef enum {
  82         kSSLProtocolUnknown,            /* no protocol negotiated/specified; use default */
  83         kSSLProtocol2,                          /* SSL 2.0 only */
  84         kSSLProtocol3,                          /* SSL 3.0 preferred, 2.0 OK if peer requires */
  85         kSSLProtocol3Only,                      /* use SSL 3.0 only, fail if peer tries to
  86                                                                  * negotiate 2.0 */
  87         kTLSProtocol1,                          /* TLS 1.0 preferred, lower versions OK */
  88         kTLSProtocol1Only,                      /* TLS 1.0 only */
  89         kSSLProtocolAll                         /* all supported versions */
  90 } SSLProtocol;
  91
  92 /* State of an SSLSession */
  93 typedef enum {
  94         kSSLIdle,                                       /* no I/O performed yet */
  95         kSSLHandshake,                          /* SSL handshake in progress */
  96         kSSLConnected,                          /* Handshake complete, ready for normal I/O */
  97         kSSLClosed,                                     /* connection closed normally */
  98         kSSLAborted                                     /* connection aborted */
  99 } SSLSessionState;
 100
 101 /*
 102  * Status of client certificate exchange (which is optional
 103  * for both server and client).
 104  */
 105 typedef enum {
 106         /* Server hasn't asked for a cert. Client hasn't sent one. */
 107         kSSLClientCertNone,
 108         /* Server has asked for a cert, but client didn't send it. */
 109         kSSLClientCertRequested,
 110         /*
 111          * Server side: We asked for a cert, client sent one, we validated
 112          *                              it OK. App can inspect the cert via
 113          *                              SSLGetPeerCertificates().
 114          * Client side: server asked for one, we sent it.
 115          */
 116         kSSLClientCertSent,
 117         /*
 118          * Client sent a cert but failed validation. Server side only.
 119          * Server app can inspect the cert via SSLGetPeerCertificates().
 120          */
 121         kSSLClientCertRejected
 122 } SSLClientCertificateState;
 123
 124 /*
 125  * R/W functions. The application using this library provides
 126  * these functions via SSLSetIOFuncs().
 127  *
 128  * Data's memory is allocated by caller; on entry to these two functions
 129  * the *length argument indicates both the size of the available data and the
 130  * requested byte count. Number of bytes actually transferred is returned in
 131  * *length.
 132  *
 133  * The application may configure the underlying connection to operate
 134  * in a non-blocking manner; in such a case, a read operation may
 135  * well return errSSLWouldBlock, indicating "I transferred less data than
 136  * you requested (maybe even zero bytes), nothing is wrong, except
 137  * requested I/O hasn't completed". This will be returned back up to
 138  * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(),
 139  * etc.
 140  */
 141 typedef OSStatus
 142 (*SSLReadFunc)                          (SSLConnectionRef       connection,
 143                                                          void                           *data,                  /* owned by
 144                                                                                                                                  * caller, data
 145                                                                                                                                  * RETURNED */
 146                                                          size_t                         *dataLength);   /* IN/OUT */
 147 typedef OSStatus
 148 (*SSLWriteFunc)                         (SSLConnectionRef       connection,
 149                                                          const void             *data,
 150                                                          size_t                         *dataLength);   /* IN/OUT */
 151
 152
 153 /*************************************************
 154  *** OSStatus values unique to SecureTransport ***
 155  *************************************************/
 156
 157 /*
 158     Note: the comments that appear after these errors are used to create SecErrorMessages.strings.
 159     The comments must not be multi-line, and should be in a form meaningful to an end user. If
 160     a different or additional comment is needed, it can be put in the header doc format, or on a
 161     line that does not start with errZZZ.
 162 */
 163
 164 enum {
 165         errSSLProtocol                          = -9800,        /* SSL protocol error */
 166         errSSLNegotiation                       = -9801,        /* Cipher Suite negotiation failure */
 167         errSSLFatalAlert                        = -9802,        /* Fatal alert */
 168         errSSLWouldBlock                        = -9803,        /* I/O would block (not fatal) */
 169     errSSLSessionNotFound               = -9804,        /* attempt to restore an unknown session */
 170     errSSLClosedGraceful                = -9805,        /* connection closed gracefully */
 171     errSSLClosedAbort                   = -9806,        /* connection closed via error */
 172     errSSLXCertChainInvalid     = -9807,        /* Invalid certificate chain */
 173     errSSLBadCert                               = -9808,        /* bad certificate format */
 174         errSSLCrypto                            = -9809,        /* underlying cryptographic error */
 175         errSSLInternal                          = -9810,        /* Internal error */
 176         errSSLModuleAttach                      = -9811,        /* module attach failure */
 177     errSSLUnknownRootCert               = -9812,        /* valid cert chain, untrusted root */
 178     errSSLNoRootCert                    = -9813,        /* cert chain not verified by root */
 179         errSSLCertExpired                       = -9814,        /* chain had an expired cert */
 180         errSSLCertNotYetValid           = -9815,        /* chain had a cert not yet valid */
 181         errSSLClosedNoNotify            = -9816,        /* server closed session with no notification */
 182         errSSLBufferOverflow            = -9817,        /* insufficient buffer provided */
 183         errSSLBadCipherSuite            = -9818,        /* bad SSLCipherSuite */
 184
 185         /* fatal errors detected by peer */
 186         errSSLPeerUnexpectedMsg         = -9819,        /* unexpected message received */
 187         errSSLPeerBadRecordMac          = -9820,        /* bad MAC */
 188         errSSLPeerDecryptionFail        = -9821,        /* decryption failed */
 189         errSSLPeerRecordOverflow        = -9822,        /* record overflow */
 190         errSSLPeerDecompressFail        = -9823,        /* decompression failure */
 191         errSSLPeerHandshakeFail         = -9824,        /* handshake failure */
 192         errSSLPeerBadCert                       = -9825,        /* misc. bad certificate */
 193         errSSLPeerUnsupportedCert       = -9826,        /* bad unsupported cert format */
 194         errSSLPeerCertRevoked           = -9827,        /* certificate revoked */
 195         errSSLPeerCertExpired           = -9828,        /* certificate expired */
 196         errSSLPeerCertUnknown           = -9829,        /* unknown certificate */
 197         errSSLIllegalParam                      = -9830,        /* illegal parameter */
 198         errSSLPeerUnknownCA             = -9831,        /* unknown Cert Authority */
 199         errSSLPeerAccessDenied          = -9832,        /* access denied */
 200         errSSLPeerDecodeError           = -9833,        /* decoding error */
 201         errSSLPeerDecryptError          = -9834,        /* decryption error */
 202         errSSLPeerExportRestriction     = -9835,        /* export restriction */
 203         errSSLPeerProtocolVersion       = -9836,        /* bad protocol version */
 204         errSSLPeerInsufficientSecurity = -9837, /* insufficient security */
 205         errSSLPeerInternalError         = -9838,        /* internal error */
 206         errSSLPeerUserCancelled         = -9839,        /* user canceled */
 207         errSSLPeerNoRenegotiation       = -9840,        /* no renegotiation allowed */
 208
 209         /* more errors detected by us */
 210         errSSLDecryptionFail            = -9845,        /* decryption failure */
 211         errSSLBadRecordMac                      = -9846,        /* bad MAC */
 212         errSSLRecordOverflow            = -9847,        /* Record Overflow */
 213         errSSLBadConfiguration          = -9848,        /* configuration error */
 214         errSSLLast                                      = -9849         /* end of range, to be deleted */
 215 };
 216
 217
 218 /******************
 219  *** Public API ***
 220  ******************/
 221
 222 /*
 223  * Create a new session context.
 224  */
 225 OSStatus
 226 SSLNewContext                           (Boolean                        isServer,
 227                                                          SSLContextRef          *contextPtr);   /* RETURNED */
 228
 229 /*
 230  * Dispose of an SSLContextRef.
 231  */
 232 OSStatus
 233 SSLDisposeContext                       (SSLContextRef          context);
 234
 235 /*
 236  * Determine the state of an SSL session.
 237  */
 238 OSStatus
 239 SSLGetSessionState                      (SSLContextRef          context,
 240                                                          SSLSessionState        *state);        /* RETURNED */
 241
 242
 243 /********************************************************************
 244  *** Session context configuration, common to client and servers. ***
 245  ********************************************************************/
 246
 247 /*
 248  * Specify functions which do the network I/O. Must be called prior
 249  * to SSLHandshake(); subsequently can not be called while a session is
 250  * active.
 251  */
 252 OSStatus
 253 SSLSetIOFuncs                           (SSLContextRef          context,
 254                                                          SSLReadFunc            read,
 255                                                          SSLWriteFunc           write);
 256
 257 /*
 258  * Set allowed SSL protocol versions. Optional.
 259  * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in
 260  * specified 'enable' boolean to be applied to all supported protocols.
 261  * The default is "all supported protocols are enabled".
 262  * This can only be called when no session is active.
 263  *
 264  * Legal values for protocol are :
 265  *              kSSLProtocol2
 266  *              kSSLProtocol3
 267  *              kTLSProtocol1
 268  *              kSSLProtocolAll
 269  */
 270 OSStatus
 271 SSLSetProtocolVersionEnabled (SSLContextRef     context,
 272                                                          SSLProtocol            protocol,
 273                                                          Boolean                        enable);
 274
 275 /*
 276  * Obtain a value specified in SSLSetProtocolVersionEnabled.
 277  */
 278 OSStatus
 279 SSLGetProtocolVersionEnabled(SSLContextRef              context,
 280                                                          SSLProtocol            protocol,
 281                                                          Boolean                        *enable);               /* RETURNED */
 282
 283 /*
 284  * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown,
 285  * in which case the highest possible version (currently kTLSProtocol1)
 286  * is attempted, but a lower version is accepted if the peer requires it.
 287  *
 288  * SSLSetProtocolVersion can not be called when a session is active.
 289  *
 290  * This is deprecated in favor of SSLSetProtocolVersionEnabled.
 291  */
 292 OSStatus
 293 SSLSetProtocolVersion           (SSLContextRef          context,
 294                                                          SSLProtocol            version);
 295
 296 /*
 297  * Obtain the protocol version specified in SSLSetProtocolVersion.
 298  * This is deprecated in favor of SSLGetProtocolVersionEnabled.
 299  * If SSLSetProtocolVersionEnabled() has been called for this session,
 300  * SSLGetProtocolVersion() may return paramErr if the protocol enable
 301  * state can not be represented by the SSLProtocol enums (e.g.,
 302  * SSL2 and TLS1 enabled, SSL3 disabled).
 303  */
 304 OSStatus
 305 SSLGetProtocolVersion           (SSLContextRef          context,
 306                                                          SSLProtocol            *protocol);             /* RETURNED */
 307
 308 /*
 309  * Specify this connection's certificate(s). This is mandatory for
 310  * server connections, optional for clients. Specifying a certificate
 311  * for a client enables SSL client-side authentication. The end-entity
 312  * cert is in certRefs[0]. Specifying a root cert is optional; if it's
 313  * not specified, the root cert which verifies the cert chain specified
 314  * here must be present in the system-wide set of trusted anchor certs.
 315  *
 316  * The certRefs argument is a CFArray containing SecCertificateRefs,
 317  * except for certRefs[0], which is a SecIdentityRef.
 318  *
 319  * Can only be called when no session is active.
 320  *
 321  * SecureTransport assumes the following:
 322  *
 323  *      -- The certRef references remains valid for the lifetime of the
 324  *     session.
 325  *  -- The specified certRefs[0] is capable of signing.
 326  *  -- The required capabilities of the certRef[0], and of the optional cert
 327  *     specified in SSLSetEncryptionCertificate (see below), are highly
 328  *     dependent on the application. For example, to work as a server with
 329  *     Netscape clients, the cert specified here must be capable of both
 330  *     signing and encrypting.
 331  */
 332 OSStatus
 333 SSLSetCertificate                       (SSLContextRef          context,
 334                                                          CFArrayRef                     certRefs);
 335
 336 /*
 337  * Specify I/O connection - a socket, endpoint, etc., which is
 338  * managed by caller. On the client side, it's assumed that communication
 339  * has been established with the desired server on this connection.
 340  * On the server side, it's assumed that an incoming client request
 341  * has been established.
 342  *
 343  * Must be called prior to SSLHandshake(); subsequently can only be
 344  * called when no session is active.
 345  */
 346 OSStatus
 347 SSLSetConnection                        (SSLContextRef          context,
 348                                                          SSLConnectionRef       connection);
 349
 350 OSStatus
 351 SSLGetConnection                        (SSLContextRef          context,
 352                                                          SSLConnectionRef       *connection);
 353
 354 /*
 355  * Specify the fully qualified doman name of the peer, e.g., "store.apple.com."
 356  * Optional; used to verify the common name field in peer's certificate.
 357  * Name is in the form of a C string; NULL termination optional, i.e.,
 358  * peerName[peerNameLen[1] may or may not have a NULL. In any case peerNameLen
 359  * is the number of bytes of the peer domain name.
 360  */
 361 OSStatus
 362 SSLSetPeerDomainName            (SSLContextRef          context,
 363                                                          const char                     *peerName,
 364                                                          size_t                         peerNameLen);
 365
 366 /*
 367  * Determine the buffer size needed for SSLGetPeerDomainName().
 368  */
 369 OSStatus
 370 SSLGetPeerDomainNameLength      (SSLContextRef          context,
 371                                                          size_t                         *peerNameLen);  // RETURNED
 372
 373 /*
 374  * Obtain the value specified in SSLSetPeerDomainName().
 375  */
 376 OSStatus
 377 SSLGetPeerDomainName            (SSLContextRef          context,
 378                                                          char                           *peerName,              // returned here
 379                                                          size_t                         *peerNameLen);  // IN/OUT
 380
 381 /*
 382  * Obtain the actual negotiated protocol version of the active
 383  * session, which may be different that the value specified in
 384  * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no
 385  * SSL session is in progress.
 386  */
 387 OSStatus
 388 SSLGetNegotiatedProtocolVersion         (SSLContextRef          context,
 389                                                                          SSLProtocol            *protocol); /* RETURNED */
 390
 391 /*
 392  * Determine number and values of all of the SSLCipherSuites we support.
 393  * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in
 394  * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
 395  * will be returned.
 396  */
 397 OSStatus
 398 SSLGetNumberSupportedCiphers (SSLContextRef                     context,
 399                                                           size_t                                *numCiphers);
 400
 401 OSStatus
 402 SSLGetSupportedCiphers           (SSLContextRef                 context,
 403                                                           SSLCipherSuite                *ciphers,               /* RETURNED */
 404                                                           size_t                                *numCiphers);   /* IN/OUT */
 405
 406 /*
 407  * Specify a (typically) restricted set of SSLCipherSuites to be enabled by
 408  * the current SSLContext. Can only be called when no session is active. Default
 409  * set of enabled SSLCipherSuites is the same as the complete set of supported
 410  * SSLCipherSuites as obtained by SSLGetSupportedCiphers().
 411  */
 412 OSStatus
 413 SSLSetEnabledCiphers            (SSLContextRef                  context,
 414                                                          const SSLCipherSuite   *ciphers,
 415                                                          size_t                                 numCiphers);
 416
 417 /*
 418  * Determine number and values of all of the SSLCipherSuites currently enabled.
 419  * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in
 420  * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
 421  * will be returned.
 422  */
 423 OSStatus
 424 SSLGetNumberEnabledCiphers      (SSLContextRef                  context,
 425                                                          size_t                                 *numCiphers);
 426
 427 OSStatus
 428 SSLGetEnabledCiphers            (SSLContextRef                  context,
 429                                                          SSLCipherSuite                 *ciphers,               /* RETURNED */
 430                                                          size_t                                 *numCiphers);   /* IN/OUT */
 431
 432 /*
 433  * Enable/disable peer certificate chain validation. Default is enabled.
 434  * If caller disables, it is the caller's responsibility to call
 435  * SSLGetPeerCertificates() upon successful completion of the handshake
 436  * and then to perform external validation of the peer certificate
 437  * chain before proceeding with data transfer.
 438  */
 439 OSStatus
 440 SSLSetEnableCertVerify          (SSLContextRef                  context,
 441                                                          Boolean                                enableVerify);
 442
 443 OSStatus
 444 SSLGetEnableCertVerify          (SSLContextRef                  context,
 445                                                          Boolean                                *enableVerify); /* RETURNED */
 446
 447
 448 /*
 449  * Specify the option of ignoring certificates' "expired" times.
 450  * This is a common failure in the real SSL world. Default for
 451  * this flag is false, meaning expired certs result in a
 452  * errSSLCertExpired error.
 453  */
 454 OSStatus
 455 SSLSetAllowsExpiredCerts        (SSLContextRef          context,
 456                                                          Boolean                        allowsExpired);
 457
 458 /*
 459  * Obtain the current value of an SSLContext's "allowExpiredCerts" flag.
 460  */
 461 OSStatus
 462 SSLGetAllowsExpiredCerts        (SSLContextRef          context,
 463                                                          Boolean                        *allowsExpired); /* RETURNED */
 464
 465 /*
 466  * Similar to SSLSetAllowsExpiredCerts(), this function allows the
 467  * option of ignoring "expired" status for root certificates only.
 468  * Default is false, i.e., expired root certs result in an
 469  * errSSLCertExpired error.
 470  */
 471 OSStatus
 472 SSLSetAllowsExpiredRoots        (SSLContextRef          context,
 473                                                          Boolean                        allowsExpired);
 474
 475 OSStatus
 476 SSLGetAllowsExpiredRoots        (SSLContextRef          context,
 477                                                          Boolean                        *allowsExpired); /* RETURNED */
 478
 479 /*
 480  * Specify option of allowing for an unknown root cert, i.e., one which
 481  * this software can not verify as one of a list of known good root certs.
 482  * Default for this flag is false, in which case one of the following two
 483  * errors may occur:
 484  *    -- The peer returns a cert chain with a root cert, and the chain
 485  *       verifies to that root, but the root is not one of our trusted
 486  *       roots. This results in errSSLUnknownRootCert on handshake.
 487  *    -- The peer returns a cert chain which does not contain a root cert,
 488  *       and we can't verify the chain to one of our trusted roots. This
 489  *       results in errSSLNoRootCert on handshake.
 490  *
 491  * Both of these error conditions are ignored when the AllowAnyRoot flag is true,
 492  * allowing connection to a totally untrusted peer.
 493  */
 494 OSStatus
 495 SSLSetAllowsAnyRoot                     (SSLContextRef          context,
 496                                                          Boolean                        anyRoot);
 497
 498 /*
 499  * Obtain the current value of an SSLContext's "allow any root" flag.
 500  */
 501 OSStatus
 502 SSLGetAllowsAnyRoot                     (SSLContextRef          context,
 503                                                          Boolean                        *anyRoot); /* RETURNED */
 504
 505 /*
 506  * Augment or replace the system's default trusted root certificate set
 507  * for this session. If replaceExisting is true, the specified roots will
 508  * be the only roots which are trusted during this session. If replaceExisting
 509  * is false, the specified roots will be added to the current set of trusted
 510  * root certs. If this function has never been called, the current trusted
 511  * root set is the same as the system's default trusted root set.
 512  * Successive calls with replaceExisting false result in accumulation
 513  * of additional root certs.
 514  *
 515  * The trustedRoots array contains SecCertificateRefs.
 516  */
 517 OSStatus
 518 SSLSetTrustedRoots                      (SSLContextRef          context,
 519                                                          CFArrayRef             trustedRoots,
 520                                                          Boolean                        replaceExisting);
 521
 522 /*
 523  * Obtain an array of SecCertificateRefs representing the current
 524  * set of trusted roots. If SSLSetTrustedRoots() has never been called
 525  * for this session, this returns the system's default root set.
 526  */
 527 OSStatus
 528 SSLGetTrustedRoots                      (SSLContextRef          context,
 529                                                          CFArrayRef             *trustedRoots); /* RETURNED */
 530
 531 /*
 532  * Request peer certificates. Valid anytime, subsequent to
 533  * a handshake attempt.
 534  *
 535  * The certs argument is a CFArray containing SecCertificateRefs.
 536  * The entire array is created by the SecureTransport library
 537  * and must be released by the caller. The cert at index 0 of
 538  * the returned array is the subject (end entity) cert; the
 539  * root cert (or the closest cert to it) is at the end of the
 540  * returned array.
 541  */
 542 OSStatus
 543 SSLGetPeerCertificates          (SSLContextRef          context,
 544                                                          CFArrayRef                     *certs);        /* RETURNED */
 545
 546 /*
 547  * Specify some data, opaque to this library, which is sufficient
 548  * to uniquely identify the peer of the current session. An example
 549  * would be IP address and port, stored in some caller-private manner.
 550  * To be optionally called prior to SSLHandshake for the current
 551  * session. This is mandatory if this session is to be resumable.
 552  *
 553  * SecureTransport allocates its own copy of the incoming peerID. The
 554  * data provided in *peerID, while opaque to SecureTransport, is used
 555  * in a byte-for-byte compare to other previous peerID values set by the
 556  * current application. Matching peerID blobs result in SecureTransport
 557  * attempting to resume an SSL session with the same parameters as used
 558  * in the previous session which specified the same peerID bytes.
 559  */
 560 OSStatus
 561 SSLSetPeerID                            (SSLContextRef          context,
 562                                                          const void             *peerID,
 563                                                          size_t                         peerIDLen);
 564
 565 /*
 566  * Obtain current PeerID. Returns NULL pointer, zero length if
 567  * SSLSetPeerID has not been called for this context.
 568  */
 569 OSStatus
 570 SSLGetPeerID                            (SSLContextRef          context,
 571                                                          const void             **peerID,
 572                                                          size_t                         *peerIDLen);
 573
 574 /*
 575  * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated
 576  * for this session. Only valid when a session is active.
 577  */
 578 OSStatus
 579 SSLGetNegotiatedCipher          (SSLContextRef          context,
 580                                                          SSLCipherSuite         *cipherSuite);
 581
 582
 583 /********************************************************
 584  *** Session context configuration, server side only. ***
 585  ********************************************************/
 586
 587 /*
 588  * Specify this connection's encryption certificate(s). This is
 589  * used in one of the following cases:
 590  *
 591  *      -- The end-entity certificate specified in SSLSetCertificate() is
 592  *         not capable of encryption.
 593  *
 594  *  -- The end-entity certificate specified in SSLSetCertificate()
 595  *         contains a key which is too large (i.e., too strong) for legal
 596  *         encryption in this session. In this case a weaker cert is
 597  *     specified here and is used for server-initiated key exchange.
 598  *
 599  * The certRefs argument is a CFArray containing SecCertificateRefs,
 600  * except for certRefs[0], which is a SecIdentityRef.
 601  *
 602  * The following assumptions are made:
 603  *
 604  *      -- The certRefs references remains valid for the lifetime of the
 605  *     connection.
 606  *  -- The specified certRefs[0] is capable of encryption.
 607  *
 608  * Can only be called when no session is active.
 609  *
 610  * Notes:
 611  * ------
 612  *
 613  * -- SSL servers which enforce the SSL3 spec to the letter will
 614  *    not accept encryption certs with key sizes larger than 512
 615  *    bits for exportable ciphers. Apps which wish to use encryption
 616  *    certs with key sizes larger than 512 bits should disable the
 617  *    use of exportable ciphers via the SSLSetEnabledCiphers() call.
 618  */
 619 OSStatus
 620 SSLSetEncryptionCertificate     (SSLContextRef          context,
 621                                                          CFArrayRef                     certRefs);
 622
 623 /*
 624  * Specify requirements for client-side authentication.
 625  * Optional; Default is kNeverAuthenticate.
 626  *
 627  * Can only be called when no session is active.
 628  */
 629 typedef enum {
 630         kNeverAuthenticate,                     /* skip client authentication */
 631         kAlwaysAuthenticate,            /* require it */
 632         kTryAuthenticate                        /* try to authenticate, but not an error
 633                                                                  * if client doesn't have a cert */
 634 } SSLAuthenticate;
 635
 636 OSStatus
 637 SSLSetClientSideAuthenticate    (SSLContextRef          context,
 638                                                                  SSLAuthenticate        auth);
 639
 640 /*
 641  * Add a DER-encoded dinstiguished name to list of acceptable names
 642  * to be specified in requests for client certificates.
 643  */
 644 OSStatus
 645 SSLAddDistinguishedName         (SSLContextRef          context,
 646                                                          const void             *derDN,
 647                                                          size_t                         derDNLen);
 648
 649 /*
 650  * Obtain client certificate exhange status. Can be called
 651  * any time. Reflects the *last* client certificate state change;
 652  * subsequent to a renegotiation attempt by either peer, the state
 653  * is reset to kSSLClientCertNone.
 654  */
 655 OSStatus
 656 SSLGetClientCertificateState    (SSLContextRef                          context,
 657                                                                  SSLClientCertificateState      *clientState);
 658
 659 /*
 660  * Specify Diffie-Hellman parameters. Optional; if we are configured to allow
 661  * for D-H ciphers and a D-H cipher is negotiated, and this function has not
 662  * been called, a set of process-wide parameters will be calculated. However
 663  * that can take a long time (30 seconds).
 664  */
 665 OSStatus SSLSetDiffieHellmanParams      (SSLContextRef                  context,
 666                                                                          const void                     *dhParams,
 667                                                                          size_t                                 dhParamsLen);
 668
 669 /*
 670  * Return parameter block specified in SSLSetDiffieHellmanParams.
 671  * Returned data is not copied and belongs to the SSLContextRef.
 672  */
 673 OSStatus SSLGetDiffieHellmanParams      (SSLContextRef                  context,
 674                                                                          const void                     **dhParams,
 675                                                                          size_t                                 *dhParamsLen);
 676 /*
 677  * Enable/Disable RSA blinding. This feature thwarts a known timing
 678  * attack to which RSA keys are vulnerable; enabling it is a tradeoff
 679  * between performance and security. The default for RSA blinding is
 680  * enabled.
 681  */
 682 OSStatus SSLSetRsaBlinding                      (SSLContextRef                  context,
 683                                                                          Boolean                                blinding);
 684
 685 OSStatus SSLGetRsaBlinding                      (SSLContextRef                  context,
 686                                                                          Boolean                                *blinding);
 687
 688 /*******************************
 689  ******** I/O Functions ********
 690  *******************************/
 691
 692 /*
 693  * Note: depending on the configuration of the underlying I/O
 694  * connection, all SSL I/O functions can return errSSLWouldBlock,
 695  * indicating "not complete, nothing is wrong, except required
 696  * I/O hasn't completed". Caller may need to repeat I/Os as necessary
 697  * if the underlying connection has been configured to behave in
 698  * a non-blocking manner.
 699  */
 700
 701 /*
 702  * Perform the SSL handshake. On successful return, session is
 703  * ready for normal secure application I/O via SSLWrite and SSLRead.
 704  *
 705  * Interesting error returns:
 706  *
 707  *      errSSLUnknownRootCert: Peer had a valid cert chain, but the root of
 708  *              the chain is unknown.
 709  *
 710  *      errSSLNoRootCert: Peer had a cert chain which was not verifiable
 711  *              to a root cert. Handshake was aborted; peer's cert chain
 712  *              available via SSLGetPeerCertificates().
 713  *
 714  *      errSSLCertExpired: Peer's cert chain had one or more expired certs.
 715  *
 716  *  errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e.,
 717  *              signature verification within the chain failed, or no certs
 718  *              were found).
 719  *
 720  *  In all of the above errors, the handshake was aborted; peer's
 721  *  cert chain available via SSLGetPeerCertificates().
 722  *
 723  * A return value of errSSLWouldBlock indicates that SSLHandshake has to be called
 724  * again (and again and again until something else is returned).
 725  */
 726 OSStatus
 727 SSLHandshake                            (SSLContextRef          context);
 728
 729 /*
 730  * Normal application-level read/write. On both of these, a errSSLWouldBlock
 731  * return and a partially completed transfer - or even zero bytes transferred -
 732  * are NOT mutually exclusive.
 733  */
 734 OSStatus
 735 SSLWrite                                        (SSLContextRef          context,
 736                                                          const void *           data,
 737                                                          size_t                         dataLength,
 738                                                          size_t                         *processed);    /* RETURNED */
 739
 740 /*
 741  * data is mallocd by caller; available size specified in
 742  * dataLength; actual number of bytes read returned in
 743  * *processed.
 744  */
 745 OSStatus
 746 SSLRead                                         (SSLContextRef          context,
 747                                                          void *                         data,                   /* RETURNED */
 748                                                          size_t                         dataLength,
 749                                                          size_t                         *processed);    /* RETURNED */
 750
 751 /*
 752  * Determine how much data the client can be guaranteed to
 753  * obtain via SSLRead() without blocking or causing any low-level
 754  * read operations to occur.
 755  */
 756 OSStatus
 757 SSLGetBufferedReadSize          (SSLContextRef context,
 758                                                          size_t *bufSize);                              /* RETURNED */
 759
 760 /*
 761  * Terminate current SSL session.
 762  */
 763 OSStatus
 764 SSLClose                                        (SSLContextRef          context);
 765
 766 #ifdef __cplusplus
 767 }
 768 #endif
 769
 770 #endif /* !_SECURITY_SECURETRANSPORT_H_ */