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 /* Current capabilities */
  32 #define ST_SERVER_MODE_ENABLE           1
  33 #define ST_CLIENT_AUTHENTICATION        0
  34
  35 /*
  36  * This file describes the public API for an implementation of the
  37  * Secure Socket Layer, V. 3.0, and Transport Layer Security, V. 1.0.
  38  * This implementation is based on Netscape's SSLRef 3.0, modified
  39  * for Apple use. (Appropriate copyrights and acknowledgements are
  40  * found elsewhere, and in all files containing Netscape code.)
  41  *
  42  * As in SSLRef 3.0, there no transport layer dependencies in this library;
  43  * it can be used with sockets, Open Transport, etc. Applications using
  44  * this library provide callback functions which do the actual I/O
  45  * on underlying network connections. Applications are also responsible
  46  * for setting up raw network connections; the application passes in
  47  * an opaque reference to the underlying (connected) entity at the
  48  * start of an SSL session in the form of an SSLConnectionRef.
  49  *
  50  * Some terminology:
  51  *
  52  * A "client" is the initiator of an SSL Session. The canonical example
  53  * of a client is a web browser, when it's talking to an https URL.
  54  *
  55  * A "server" is an entity which accepts requests for SSL sessions made
  56  * by clients. E.g., a secure web server.
  57
  58  * An "SSL Session", or "session", is bounded by calls to SSLHandshake()
  59  * and SSLClose(). An "Active session" is in some state between these
  60  * two calls, inclusive.
  61  *
  62  * An SSL Session Context, or SSLContextRef, is an opaque reference in this
  63  * library to the state associated with one session. A SSLContextRef cannot
  64  * be reused for multiple sessions.
  65  */
  66
  67 #include <CoreServices/../Frameworks/CarbonCore.framework/Headers/MacTypes.h>
  68 #include <CoreFoundation/CFArray.h>
  69 #include <Security/CipherSuite.h>
  70 #include <sys/types.h>
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 /***********************
  77  *** Common typedefs ***
  78  ***********************/
  79
  80 /* Opaque reference to an SSL session context */
  81 struct                      SSLContext;
  82 typedef struct SSLContext   *SSLContextRef;
  83
  84 /* Opaque reference to an I/O conection (socket, Endpoint, etc.) */
  85 typedef const void *            SSLConnectionRef;
  86
  87 /* SSL Protocol version */
  88 typedef enum {
  89         kSSLProtocolUnknown,            /* no protocol negotiated/specified; use default */
  90         kSSLProtocol2,                          /* SSL 2.0 only */
  91         kSSLProtocol3,                          /* SSL 3.0 preferred, 2.0 OK if peer requires */
  92         kSSLProtocol3Only,                      /* use SSL 3.0 only, fail if peer tries to
  93                                                                  * negotiate 2.0 */
  94         kTLSProtocol1,                          /* TLS 1.0 preferred, lower versions OK */
  95         kTLSProtocol1Only                       /* TLS 1.0 only */
  96 } SSLProtocol;
  97
  98 /* State of an SSLSession */
  99 typedef enum {
 100         kSSLIdle,                                       /* no I/O performed yet */
 101         kSSLHandshake,                          /* SSL handshake in progress */
 102         kSSLConnected,                          /* Handshake complete, ready for normal I/O */
 103         kSSLClosed,                                     /* connection closed normally */
 104         kSSLAborted                                     /* connection aborted */
 105 } SSLSessionState;
 106
 107 /*
 108  * R/W functions. The application using this library provides
 109  * these functions via SSLSetIOFuncs().
 110  *
 111  * Data's memory is allocated by caller; on entry to these two functions
 112  * the *length argument indicates both the size of the available data and the
 113  * requested byte count. Number of bytes actually transferred is returned in
 114  * *length.
 115  *
 116  * The application may configure the underlying connection to operate
 117  * in a non-blocking manner; in such a case, a read operation may
 118  * well return SSLWouldBlockErr, indicating "I transferred less data than
 119  * you requested (maybe even zero bytes), nothing is wrong, except
 120  * requested I/O hasn't completed". This will be returned back up to
 121  * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(),
 122  * etc.
 123  */
 124 typedef OSStatus
 125 (*SSLReadFunc)                          (SSLConnectionRef       connection,
 126                                                          void                           *data,                  /* owned by
 127                                                                                                                                  * caller, data
 128                                                                                                                                  * RETURNED */
 129                                                          size_t                         *dataLength);   /* IN/OUT */
 130 typedef OSStatus
 131 (*SSLWriteFunc)                         (SSLConnectionRef       connection,
 132                                                          const void             *data,
 133                                                          size_t                         *dataLength);   /* IN/OUT */
 134
 135
 136 /*************************************************
 137  *** OSStatus values unique to SecureTransport ***
 138  *************************************************/
 139
 140 enum {
 141         errSSLProtocol                          = -9800,        /* SSL protocol error */
 142         errSSLNegotiation                       = -9801,        /* Cipher Suite negotiation failure */
 143         errSSLFatalAlert                        = -9802,        /* Fatal alert */
 144         errSSLWouldBlock                        = -9803,        /* I/O would block (not fatal) */
 145     errSSLSessionNotFound               = -9804,        /* attempt to restore an unknown
 146                                                                                  *    session */
 147     errSSLClosedGraceful                = -9805,        /* connection closed gracefully */
 148     errSSLClosedAbort                   = -9806,        /* connection closed via error */
 149     errSSLXCertChainInvalid     = -9807,        /* Invalid certificate chain */
 150     errSSLBadCert                               = -9808,        /* bad certificate format */
 151         errSSLCrypto                            = -9809,        /* underlying cryptographic error */
 152         errSSLInternal                          = -9810,        /* Internal error */
 153         errSSLModuleAttach                      = -9811,        /* module attach failure */
 154     errSSLUnknownRootCert               = -9812,        /* valid cert chain, untrusted root */
 155     errSSLNoRootCert                    = -9813,        /* cert chain not verified by root */
 156         errSSLCertExpired                       = -9814,        /* chain had an expired cert */
 157         errSSLCertNotYetValid           = -9815,        /* chain had a cert not yet valid */
 158         errSSLClosedNoNotify            = -9816,        /* server closed session with no
 159                                                                                          *     notification */
 160         errSSLBufferOverflow            = -9817,        /* insufficient buffer provided */
 161         errSSLBadCipherSuite            = -9818,        /* bad SSLCipherSuite */
 162         errSSLLast                                      = -9849         /* end of range, to be deleted */
 163 };
 164
 165
 166 /******************
 167  *** Public API ***
 168  ******************/
 169
 170 /*
 171  * Create a new session context.
 172  */
 173 OSStatus
 174 SSLNewContext                           (Boolean                        isServer,
 175                                                          SSLContextRef          *contextPtr);   /* RETURNED */
 176
 177 /*
 178  * Dispose of an SSLContextRef.
 179  */
 180 OSStatus
 181 SSLDisposeContext                       (SSLContextRef          context);
 182
 183 /*
 184  * Determine the state of an SSL session.
 185  */
 186 OSStatus
 187 SSLGetSessionState                      (SSLContextRef          context,
 188                                                          SSLSessionState        *state);        /* RETURNED */
 189
 190
 191 /********************************************************************
 192  *** Session context configuration, common to client and servers. ***
 193  ********************************************************************/
 194
 195 /*
 196  * Specify functions which do the network I/O. Must be called prior
 197  * to SSLHandshake(); subsequently can not be called while a session is
 198  * active.
 199  */
 200 OSStatus
 201 SSLSetIOFuncs                           (SSLContextRef          context,
 202                                                          SSLReadFunc            read,
 203                                                          SSLWriteFunc           write);
 204
 205 /*
 206  * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown,
 207  * in which case the highest possible version (currently kTLSProtocol1)
 208  * is attempted, but a lower version is accepted if the peer requires it.
 209  *
 210  * SSLSetProtocolVersion can not be called when a session is active.
 211  */
 212 OSStatus
 213 SSLSetProtocolVersion           (SSLContextRef          context,
 214                                                          SSLProtocol            version);
 215
 216 OSStatus
 217 SSLGetProtocolVersion           (SSLContextRef          context,
 218                                                          SSLProtocol            *protocol);             /* RETURNED */
 219
 220 #if             (ST_SERVER_MODE_ENABLE || ST_CLIENT_AUTHENTICATION)
 221
 222 /*
 223  * Specify this connection's certificate(s). This is mandatory for
 224  * server connections, optional for clients. Specifying a certificate
 225  * for a client enables SSL client-side authentication. The end-entity
 226  * cert is in certRefs[0]. Specifying a root cert is optional; if it's
 227  * not specified, the root cert which verifies the cert chain specified
 228  * here must be present in the system-wide set of trusted anchor certs.
 229  *
 230  * The certRefs argument is a CFArray containing SecCertificateRefs,
 231  * except for certRefs[0], which is a SecIdentityRef.
 232  *
 233  * Can only be called when no session is active.
 234  *
 235  * SecureTransport assumes the following:
 236  *
 237  *      -- The certRef references remains valid for the lifetime of the
 238  *     session.
 239  *  -- The specified certRefs[0] is capable of signing.
 240  *  -- The required capabilities of the certRef[0], and of the optional cert
 241  *     specified in SSLSetEncryptionCertificate (see below), are highly
 242  *     dependent on the application. For example, to work as a server with
 243  *     Netscape clients, the cert specified here must be capable of both
 244  *     signing and encrypting.
 245  */
 246 OSStatus
 247 SSLSetCertificate                       (SSLContextRef          context,
 248                                                          CFArrayRef                     certRefs);
 249
 250 #endif  /* (ST_SERVER_MODE_ENABLE || ST_CLIENT_AUTHENTICATION) */
 251
 252 /*
 253  * Specify I/O connection - a socket, endpoint, etc., which is
 254  * managed by caller. On the client side, it's assumed that communication
 255  * has been established with the desired server on this connection.
 256  * On the server side, it's assumed that an incoming client request
 257  * has been established.
 258  *
 259  * Must be called prior to SSLHandshake(); subsequently can only be
 260  * called when no session is active.
 261  */
 262 OSStatus
 263 SSLSetConnection                        (SSLContextRef          context,
 264                                                          SSLConnectionRef       connection);
 265
 266 /*
 267  * Specify the fully qualified doman name of the peer, e.g., "store.apple.com."
 268  * Optional; used to verify the common name field in peer's certificate.
 269  * Name is in the form of a C string; NULL termination optional, i.e.,
 270  * peerName[peerNameLen[1] may or may not have a NULL. In any case peerNameLen
 271  * is the number of bytes of the peer domain name.
 272  */
 273 OSStatus
 274 SSLSetPeerDomainName            (SSLContextRef          context,
 275                                                          const char                     *peerName,
 276                                                          size_t                         peerNameLen);
 277
 278 /*
 279  * Determine the buffer size needed for SSLGetPeerDomainName().
 280  */
 281 OSStatus
 282 SSLGetPeerDomainNameLength      (SSLContextRef          context,
 283                                                          size_t                         *peerNameLen);  // RETURNED
 284
 285 /*
 286  * Obtain the value specified in SSLSetPeerDomainName().
 287  */
 288 OSStatus
 289 SSLGetPeerDomainName            (SSLContextRef          context,
 290                                                          char                           *peerName,              // returned here
 291                                                          size_t                         *peerNameLen);  // IN/OUT
 292
 293 /*
 294  * Obtain the actual negotiated protocol version of the active
 295  * session, which may be different that the value specified in
 296  * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no
 297  * SSL session is in progress.
 298  */
 299 OSStatus
 300 SSLGetNegotiatedProtocolVersion         (SSLContextRef          context,
 301                                                                          SSLProtocol            *protocol); /* RETURNED */
 302
 303 /*
 304  * Determine number and values of all of the SSLCipherSuites we support.
 305  * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in
 306  * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
 307  * will be returned.
 308  */
 309 OSStatus
 310 SSLGetNumberSupportedCiphers (SSLContextRef                     context,
 311                                                           size_t                                *numCiphers);
 312
 313 OSStatus
 314 SSLGetSupportedCiphers           (SSLContextRef                 context,
 315                                                           SSLCipherSuite                *ciphers,               /* RETURNED */
 316                                                           size_t                                *numCiphers);   /* IN/OUT */
 317
 318 /*
 319  * Specify a (typically) restricted set of SSLCipherSuites to be enabled by
 320  * the current SSLContext. Can only be called when no session is active. Default
 321  * set of enabled SSLCipherSuites is the same as the complete set of supported
 322  * SSLCipherSuites as obtained by SSLGetSupportedCiphers().
 323  */
 324 OSStatus
 325 SSLSetEnabledCiphers            (SSLContextRef                  context,
 326                                                          const SSLCipherSuite   *ciphers,
 327                                                          size_t                                 numCiphers);
 328
 329 /*
 330  * Determine number and values of all of the SSLCipherSuites currently enabled.
 331  * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in
 332  * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
 333  * will be returned.
 334  */
 335 OSStatus
 336 SSLGetNumberEnabledCiphers      (SSLContextRef                  context,
 337                                                          size_t                                 *numCiphers);
 338
 339 OSStatus
 340 SSLGetEnabledCiphers            (SSLContextRef                  context,
 341                                                          SSLCipherSuite                 *ciphers,               /* RETURNED */
 342                                                          size_t                                 *numCiphers);   /* IN/OUT */
 343
 344
 345 /*
 346  * Specify the option of ignoring certificates' "expired" times.
 347  * This is a common failure in the real SSL world. Default for
 348  * this flag is false, meaning expired certs result in a
 349  * errSSLCertExpired error.
 350  */
 351 OSStatus
 352 SSLSetAllowsExpiredCerts        (SSLContextRef          context,
 353                                                          Boolean                        allowsExpired);
 354
 355 /*
 356  * Obtain the current value of an SSLContext's "allowExpiredCerts" flag.
 357  */
 358 OSStatus
 359 SSLGetAllowsExpiredCerts        (SSLContextRef          context,
 360                                                          Boolean                        *allowsExpired); /* RETURNED */
 361
 362 /*
 363  * Specify option of allowing for an unknown root cert, i.e., one which
 364  * this software can not verify as one of a list of known good root certs.
 365  * Default for this flag is false, in which case one of the following two
 366  * errors may occur:
 367  *    -- The peer returns a cert chain with a root cert, and the chain
 368  *       verifies to that root, but the root is not one of our trusted
 369  *       roots. This results in errSSLUnknownRootCert on handshake.
 370  *    -- The peer returns a cert chain which does not contain a root cert,
 371  *       and we can't verify the chain to one of our trusted roots. This
 372  *       results in errSSLNoRootCert on handshake.
 373  *
 374  * Both of these error conditions are ignored when the AllowAnyRoot flag is true,
 375  * allowing connection to a totally untrusted peer.
 376  */
 377 OSStatus
 378 SSLSetAllowsAnyRoot                     (SSLContextRef          context,
 379                                                          Boolean                        anyRoot);
 380
 381 /*
 382  * Obtain the current value of an SSLContext's "allow any root" flag.
 383  */
 384 OSStatus
 385 SSLGetAllowsAnyRoot                     (SSLContextRef          context,
 386                                                          Boolean                        *anyRoot); /* RETURNED */
 387
 388 /*
 389  * Request peer certificates. Valid anytime, subsequent to
 390  * a handshake attempt.
 391  *
 392  * The certs argument is a CFArray containing CFDataRefs, each
 393  * of which is one DER-encoded cert. The entire array is created
 394  * by the SecureTransport library and must be released by the caller.
 395  * The cert at the end of the returned array is the subject (end
 396  * entity) cert; the root cert (or the closest cert to it) is in
 397  * index 0 of the returned array.
 398  */
 399 OSStatus
 400 SSLGetPeerCertificates          (SSLContextRef          context,
 401                                                          CFArrayRef                     *certs);        /* RETURNED */
 402
 403 /*
 404  * Specify some data, opaque to this library, which is sufficient
 405  * to uniquely identify the peer of the current session. An example
 406  * would be IP address and port, stored in some caller-private manner.
 407  * To be optionally called prior to SSLHandshake for the current
 408  * session. This is mandatory if this session is to be resumable.
 409  *
 410  * SecureTransport allocates its own copy of the incoming peerID. The
 411  * data provided in *peerID, while opaque to SecureTransport, is used
 412  * in a byte-for-byte compare to other previous peerID values set by the
 413  * current application. Matching peerID blobs result in SecureTransport
 414  * attempting to resume an SSL session with the same parameters as used
 415  * in the previous session which specified the same peerID bytes.
 416  */
 417 OSStatus
 418 SSLSetPeerID                            (SSLContextRef          context,
 419                                                          const void             *peerID,
 420                                                          size_t                         peerIDLen);
 421
 422 /*
 423  * Obtain current PeerID. Returns NULL pointer, zero length if
 424  * SSLSetPeerID has not been called for this context.
 425  */
 426 OSStatus
 427 SSLGetPeerID                            (SSLContextRef          context,
 428                                                          const void             **peerID,
 429                                                          size_t                         *peerIDLen);
 430
 431 /*
 432  * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated
 433  * for this session. Only valid when a session is active.
 434  */
 435 OSStatus
 436 SSLGetNegotiatedCipher          (SSLContextRef          context,
 437                                                          SSLCipherSuite         *cipherSuite);
 438
 439
 440 /********************************************************
 441  *** Session context configuration, server side only. ***
 442  ********************************************************/
 443
 444 #if             ST_SERVER_MODE_ENABLE
 445 /*
 446  * Specify this connection's encryption certificate(s). This is
 447  * used in one of the following cases:
 448  *
 449  *      -- The end-entity certificate specified in SSLSetCertificate() is
 450  *         not capable of encryption.
 451  *
 452  *  -- The end-entity certificate specified in SSLSetCertificate()
 453  *         contains a key which is too large (i.e., too strong) for legal
 454  *         encryption in this session. In this case a weaker cert is
 455  *     specified here and is used for server-initiated key exchange.
 456  *
 457  * The certRefs argument is a CFArray containing SecCertificateRefs,
 458  * except for certRefs[0], which is a SecIdentityRef.
 459  *
 460  * The following assumptions are made:
 461  *
 462  *      -- The certRefs references remains valid for the lifetime of the
 463  *     connection.
 464  *  -- The specified certRefs[0] is capable of encryption.
 465  *
 466  * Can only be called when no session is active.
 467  *
 468  * Notes:
 469  * ------
 470  *
 471  * -- SSL servers which enforce the SSL3 spec to the letter will
 472  *    not accept encryption certs with key sizes larger than 512
 473  *    bits for exportable ciphers. Apps which wish to use encryption
 474  *    certs with key sizes larger than 512 bits should disable the
 475  *    use of exportable ciphers via the SSLSetEnabledCiphers() call.
 476  */
 477 OSStatus
 478 SSLSetEncryptionCertificate     (SSLContextRef          context,
 479                                                          CFArrayRef                     certRefs);
 480
 481 /*
 482  * Specify requirements for client-side authentication.
 483  * Optional; Default is kNeverAuthenticate.
 484  *
 485  * Can only be called when no session is active.
 486  */
 487 typedef enum {
 488         kNeverAuthenticate,                     /* skip client authentication */
 489         kAlwaysAuthenticate,            /* require it */
 490         kTryAuthenticate                        /* try to authenticate, but not an error
 491                                                                  * if client doesn't have a cert */
 492 } SSLAuthenticate;
 493
 494 OSStatus
 495 SSLSetClientSideAuthenticate    (SSLContextRef          context,
 496                                                                  SSLAuthenticate        auth);
 497
 498 #endif  /* ST_SERVER_MODE_ENABLE */
 499
 500 /*******************************
 501  ******** I/O Functions ********
 502  *******************************/
 503
 504 /*
 505  * Note: depending on the configuration of the underlying I/O
 506  * connection, all SSL I/O functions can return SSLWouldBlockErr,
 507  * indicating "not complete, nothing is wrong, except required
 508  * I/O hasn't completed". Caller may need to repeat I/Os as necessary
 509  * if the underlying connection has been configured to behave in
 510  * a non-blocking manner.
 511  */
 512
 513 /*
 514  * Perform the SSL handshake. On successful return, session is
 515  * ready for normal secure application I/O via SSLWrite and SSLRead.
 516  *
 517  * Interesting error returns:
 518  *
 519  *      errSSLUnknownRootCert: Peer had a valid cert chain, but the root of
 520  *              the chain is unknown.
 521  *
 522  *      errSSLNoRootCert: Peer had a cert chain which was not verifiable
 523  *              to a root cert. Handshake was aborted; peer's cert chain
 524  *              available via SSLGetPeerCertificates().
 525  *
 526  *      errSSLCertExpired: Peer's cert chain had one or more expired certs.
 527  *
 528  *  errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e.,
 529  *              signature verification within the chain failed, or no certs
 530  *              were found).
 531  *
 532  *  In all of the above errors, the handshake was aborted; peer's
 533  *  cert chain available via SSLGetPeerCertificates().
 534  *
 535  * A return value of errSSLWouldBlock indicates that SSLHandshake has to be called
 536  * again (and again and again until something else is returned).
 537  */
 538 OSStatus
 539 SSLHandshake                            (SSLContextRef          context);
 540
 541 /*
 542  * Normal application-level read/write. On both of these, a errSSLWouldBlock
 543  * return and a partially completed transfer - or even zero bytes transferred -
 544  * are NOT mutually exclusive.
 545  */
 546 OSStatus
 547 SSLWrite                                        (SSLContextRef          context,
 548                                                          const void *           data,
 549                                                          size_t                         dataLength,
 550                                                          size_t                         *processed);    /* RETURNED */
 551
 552 /*
 553  * data is mallocd by caller; available size specified in
 554  * dataLength; actual number of bytes read returned in
 555  * *processed.
 556  */
 557 OSStatus
 558 SSLRead                                         (SSLContextRef          context,
 559                                                          void *                         data,                   /* RETURNED */
 560                                                          size_t                         dataLength,
 561                                                          size_t                         *processed);    /* RETURNED */
 562
 563 /*
 564  * Determine how much data the client can be guaranteed to
 565  * obtain via SSLRead() without blocking or causing any low-level
 566  * read operations to occur.
 567  */
 568 OSStatus
 569 SSLGetBufferedReadSize          (SSLContextRef context,
 570                                                          size_t *bufSize);                              /* RETURNED */
 571
 572 /*
 573  * Terminate current SSL session.
 574  */
 575 OSStatus
 576 SSLClose                                        (SSLContextRef          context);
 577
 578 #ifdef __cplusplus
 579 }
 580 #endif
 581
 582 #endif /* !_SECURITY_SECURETRANSPORT_H_ */