OSX/libsecurity_ssl/lib/SecureTransportPriv.h

   1 /*
   2  * Copyright (c) 1999-2001,2005-2014 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*
  25  * SecureTransportPriv.h - Apple-private exported routines
  26  */
  27
  28 #ifndef _SECURE_TRANSPORT_PRIV_H_
  29 #define _SECURE_TRANSPORT_PRIV_H_       1
  30
  31 #include <Security/SecureTransport.h>
  32 #include <Security/SecTrust.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #include <Security/sslTypes.h>
  39
  40 /* Return the list of ciphersuites associated with a SSLCiphersuiteGroup */
  41 const SSLCipherSuite *SSLCiphersuiteGroupToCiphersuiteList(SSLCiphersuiteGroup group,
  42                                                            size_t *listSize);
  43
  44 /* Determine minimum allowed TLS version for the given ciphersuite */
  45 SSLProtocol SSLCiphersuiteMinimumTLSVersion(SSLCipherSuite ciphersuite);
  46
  47 /* Determine maximum allowed TLS version for the given ciphersuite */
  48 SSLProtocol SSLCiphersuiteMaximumTLSVersion(SSLCipherSuite ciphersuite);
  49
  50 /* Create an SSL Context with an external record layer - eg: kernel accelerated layer */
  51 SSLContextRef
  52 SSLCreateContextWithRecordFuncs(CFAllocatorRef alloc,
  53                                 SSLProtocolSide protocolSide,
  54                                 SSLConnectionType connectionType,
  55                                 const struct SSLRecordFuncs *recFuncs);
  56
  57 /* Set the external record layer context */
  58 OSStatus
  59 SSLSetRecordContext         (SSLContextRef          ctx,
  60                              SSLRecordContextRef    recCtx);
  61
  62 /* The size of of client- and server-generated random numbers in hello messages. */
  63 #define SSL_CLIENT_SRVR_RAND_SIZE               32
  64
  65 /* The size of the pre-master and master secrets. */
  66 #define SSL_RSA_PREMASTER_SECRET_SIZE   48
  67 #define SSL_MASTER_SECRET_SIZE                  48
  68
  69 /*
  70  * For the following three functions, *size is the available
  71  * buffer size on entry and the actual size of the data returned
  72  * on return. The above consts are for convenience.
  73  */
  74 OSStatus SSLInternalMasterSecret(
  75    SSLContextRef context,
  76    void *secret,         // mallocd by caller, SSL_MASTER_SECRET_SIZE
  77    size_t *secretSize);  // in/out
  78
  79 OSStatus SSLInternalServerRandom(
  80    SSLContextRef context,
  81    void *randBuf,                       // mallocd by caller, SSL_CLIENT_SRVR_RAND_SIZE
  82    size_t *randSize);   // in/out
  83
  84 OSStatus SSLInternalClientRandom(
  85    SSLContextRef context,
  86    void *randBuf,               // mallocd by caller, SSL_CLIENT_SRVR_RAND_SIZE
  87    size_t *randSize);   // in/out
  88
  89 /*
  90  * Obtain the sizes of the currently negotiated HMAC digest, session
  91  * key, and session key IV.
  92  */
  93 OSStatus SSLGetCipherSizes(
  94         SSLContextRef context,
  95         size_t *digestSize,
  96         size_t *symmetricKeySize,
  97         size_t *ivSize);
  98
  99 OSStatus SSLInternal_PRF(
 100    SSLContextRef context,
 101    const void *secret,
 102    size_t secretLen,
 103    const void *label,
 104    size_t labelLen,
 105    const void *seed,
 106    size_t seedLen,
 107    void *out,                   // mallocd by caller, length >= outLen
 108    size_t outLen);
 109
 110 /*
 111  * Obtain a SecTrustRef representing peer certificates. Valid anytime,
 112  * subsequent to a handshake attempt. The returned SecTrustRef is valid
 113  * only as long as the SSLContextRef is.
 114  */
 115 OSStatus
 116 SSLGetPeerSecTrust                      (SSLContextRef          context,
 117                                                          SecTrustRef            *secTrust);     /* RETURNED */
 118
 119 /*
 120  * Obtain resumable session info. Can be called anytime subsequent to
 121  * handshake attempt.
 122  *
 123  * if sessionWasResumed is True on return, the session is indeed a
 124  * resumed session; the sessionID (an opaque blob generated by the
 125  * server) is returned in *sessionID. The length of the sessionID
 126  * is returned in *sessionIDLength. Caller must allocate the
 127  * sessionID buffer; it max size is MAX_SESSION_ID_LENGTH bytes.
 128  */
 129 #define MAX_SESSION_ID_LENGTH   32
 130
 131 OSStatus
 132 SSLGetResumableSessionInfo      (
 133         SSLContextRef   context,
 134         Boolean                 *sessionWasResumed,             // RETURNED
 135         void                    *sessionID,                             // RETURNED, mallocd by caller
 136         size_t                  *sessionIDLength);              // IN/OUT
 137
 138 /*
 139  * Getters for SSLSetCertificate() and SSLSetEncryptionCertificate()
 140  */
 141 OSStatus
 142 SSLGetCertificate (
 143         SSLContextRef   context,
 144         CFArrayRef              *certRefs);                             // RETURNED, *not* retained
 145
 146 OSStatus
 147 SSLGetEncryptionCertificate (
 148         SSLContextRef   context,
 149         CFArrayRef              *certRefs);                             // RETURNED, *not* retained
 150
 151 /*
 152  * Getter for SSLSetClientSideAuthenticate()
 153  */
 154 OSStatus
 155 SSLGetClientSideAuthenticate (
 156         SSLContextRef   context,
 157         SSLAuthenticate *auth);                                 // RETURNED
 158
 159 #if !TARGET_OS_IPHONE
 160 /*
 161  * Get/set array of trusted leaf certificates.
 162  *
 163  * If none have been set previously with SSLSetTrustedLeafCertificates(),
 164  * then SSLCopyTrustedLeafCertificates() will return NULL with errSecSuccess.
 165  */
 166 OSStatus
 167 SSLSetTrustedLeafCertificates (
 168         SSLContextRef   context,
 169         CFArrayRef              certRefs);
 170
 171 OSStatus
 172 SSLCopyTrustedLeafCertificates (
 173         SSLContextRef   context,
 174         CFArrayRef              *certRefs);                             // RETURNED, caller must release
 175 #endif
 176 /*
 177  * Get/set enable of anonymous ciphers. This is deprecated and now a no-op.
 178  */
 179 OSStatus
 180 SSLSetAllowAnonymousCiphers(
 181         SSLContextRef   context,
 182         Boolean                 enable);
 183
 184 OSStatus
 185 SSLGetAllowAnonymousCiphers(
 186         SSLContextRef   context,
 187         Boolean                 *enable);
 188
 189 /*
 190  * Override the default session cache timeout for a cache entry created for
 191  * the current session.
 192  */
 193 OSStatus
 194 SSLSetSessionCacheTimeout(
 195         SSLContextRef context,
 196         uint32_t timeoutInSeconds);
 197
 198 /*
 199  * Callback function for EAP-style PAC-based session resumption.
 200  * This function is called by SecureTransport to obtain the
 201  * master secret.
 202  */
 203 typedef void (*SSLInternalMasterSecretFunction)(
 204         SSLContextRef ctx,
 205         const void *arg,                /* opaque to SecureTransport; app-specific */
 206         void *secret,                   /* mallocd by caller, SSL_MASTER_SECRET_SIZE */
 207         size_t *secretLength);  /* in/out */
 208
 209 /*
 210  * Register a callback for obtaining the master_secret when performing
 211  * PAC-based session resumption. At the time the callback is called,
 212  * the following are guaranteed to be valid:
 213  *
 214  *  -- serverRandom (via SSLInternalServerRandom())
 215  *  -- clientRandom (via SSLInternalClientRandom())
 216  *  -- negotiated protocol version (via SSLGetNegotiatedProtocolVersion())
 217  *  -- negotiated CipherSuite (via SSLGetNegotiatedCipher())
 218  *
 219  * Currently, PAC-based session resumption is only implemented on
 220  * the client side for Deployment builds.
 221  *
 222  * On the client side, this callback occurs if/when the server sends a
 223  * ChangeCipherSpec message immediately following its ServerHello
 224  * message (i.e., it's skipped the entire Key Exchange phase of
 225  * negotiation).
 226  *
 227  * On the server side (Development builds only) this callback occurs
 228  * immediately upon receipt of the Client Hello message, before we send
 229  * the Server Hello.
 230  */
 231 OSStatus
 232 SSLInternalSetMasterSecretFunction(
 233         SSLContextRef ctx,
 234         SSLInternalMasterSecretFunction mFunc,
 235         const void *arg);               /* opaque to SecureTransport; app-specific */
 236
 237 /*
 238  * Provide an opaque SessionTicket for use in PAC-based session
 239  * resumption. Client side only. The provided ticket is sent in
 240  * the ClientHello message as a SessionTicket extension.
 241  * The maximum ticketLength is 2**16-1.
 242  */
 243 OSStatus SSLInternalSetSessionTicket(
 244    SSLContextRef ctx,
 245    const void *ticket,
 246    size_t ticketLength);
 247
 248 /*
 249  * Support for specifying and obtaining ECC curves, used with the ECDH-based
 250  * ciphersuites.
 251  */
 252
 253 /*
 254  * These are the named curves from RFC 4492
 255  * section 5.1.1, with the exception of SSL_Curve_None which means
 256  * "ECDSA not negotiated".
 257  */
 258 typedef enum
 259 {
 260         SSL_Curve_None = -1,
 261
 262     SSL_Curve_sect163k1 = 1,
 263     SSL_Curve_sect163r1 = 2,
 264     SSL_Curve_sect163r2 = 3,
 265     SSL_Curve_sect193r1 = 4,
 266     SSL_Curve_sect193r2 = 5,
 267     SSL_Curve_sect233k1 = 6,
 268     SSL_Curve_sect233r1 = 7,
 269     SSL_Curve_sect239k1 = 8,
 270     SSL_Curve_sect283k1 = 9,
 271     SSL_Curve_sect283r1 = 10,
 272     SSL_Curve_sect409k1 = 11,
 273     SSL_Curve_sect409r1 = 12,
 274     SSL_Curve_sect571k1 = 13,
 275     SSL_Curve_sect571r1 = 14,
 276     SSL_Curve_secp160k1 = 15,
 277     SSL_Curve_secp160r1 = 16,
 278     SSL_Curve_secp160r2 = 17,
 279     SSL_Curve_secp192k1 = 18,
 280     SSL_Curve_secp192r1 = 19,
 281     SSL_Curve_secp224k1 = 20,
 282     SSL_Curve_secp224r1 = 21,
 283     SSL_Curve_secp256k1 = 22,
 284
 285     /* These are the ones we actually support */
 286         SSL_Curve_secp256r1 = 23,
 287         SSL_Curve_secp384r1 = 24,
 288         SSL_Curve_secp521r1 = 25
 289 } SSL_ECDSA_NamedCurve;
 290
 291 /*
 292  * Obtain the SSL_ECDSA_NamedCurve negotiated during a handshake.
 293  * Returns errSecParam if no ECDH-related ciphersuite was negotiated.
 294  */
 295 extern OSStatus SSLGetNegotiatedCurve(
 296    SSLContextRef ctx,
 297    SSL_ECDSA_NamedCurve *namedCurve);    /* RETURNED */
 298
 299 /*
 300  * Obtain the number of currently enabled SSL_ECDSA_NamedCurves.
 301  */
 302 extern OSStatus SSLGetNumberOfECDSACurves(
 303    SSLContextRef ctx,
 304    unsigned *numCurves);                                /* RETURNED */
 305
 306 /*
 307  * Obtain the ordered list of currently enabled SSL_ECDSA_NamedCurves.
 308  * Caller allocates returned array and specifies its size (in
 309  * SSL_ECDSA_NamedCurves) in *numCurves on entry; *numCurves
 310  * is the actual size of the returned array on successful return.
 311  */
 312 extern OSStatus SSLGetECDSACurves(
 313    SSLContextRef ctx,
 314    SSL_ECDSA_NamedCurve *namedCurves,   /* RETURNED */
 315    unsigned *numCurves);                                /* IN/OUT */
 316
 317 /*
 318  * Specify ordered list of allowable named curves.
 319  */
 320 extern OSStatus SSLSetECDSACurves(
 321    SSLContextRef ctx,
 322    const SSL_ECDSA_NamedCurve *namedCurves,
 323    unsigned numCurves);
 324
 325 /*
 326  * Server-specified client authentication mechanisms.
 327  */
 328 typedef enum {
 329         /* doesn't appear on the wire */
 330         SSLClientAuthNone = -1,
 331         /* RFC 2246 7.4.6 */
 332         SSLClientAuth_RSASign = 1,
 333         SSLClientAuth_DSSSign = 2,
 334         SSLClientAuth_RSAFixedDH = 3,
 335         SSLClientAuth_DSS_FixedDH = 4,
 336         /* RFC 4492 5.5 */
 337         SSLClientAuth_ECDSASign = 64,
 338         SSLClientAuth_RSAFixedECDH = 65,
 339         SSLClientAuth_ECDSAFixedECDH = 66
 340 } SSLClientAuthenticationType;
 341
 342 /* TLS 1.2 Signature Algorithms extension values for hash field. */
 343 typedef enum {
 344     SSL_HashAlgorithmNone = 0,
 345     SSL_HashAlgorithmMD5 = 1,
 346     SSL_HashAlgorithmSHA1 = 2,
 347     SSL_HashAlgorithmSHA224 = 3,
 348     SSL_HashAlgorithmSHA256 = 4,
 349     SSL_HashAlgorithmSHA384 = 5,
 350     SSL_HashAlgorithmSHA512 = 6
 351 } SSL_HashAlgorithm;
 352
 353 /* TLS 1.2 Signature Algorithms extension values for signature field. */
 354 typedef enum {
 355     SSL_SignatureAlgorithmAnonymous = 0,
 356     SSL_SignatureAlgorithmRSA = 1,
 357     SSL_SignatureAlgorithmDSA = 2,
 358     SSL_SignatureAlgorithmECDSA = 3
 359 } SSL_SignatureAlgorithm;
 360
 361 typedef struct {
 362     SSL_HashAlgorithm hash;
 363     SSL_SignatureAlgorithm signature;
 364 } SSLSignatureAndHashAlgorithm;
 365
 366 /*
 367  * Obtain the number of client authentication mechanisms specified by
 368  * the server in its Certificate Request message.
 369  * Returns errSecParam if server hasn't sent a Certificate Request message
 370  * (i.e., client certificate state is kSSLClientCertNone).
 371  */
 372 extern OSStatus SSLGetNumberOfClientAuthTypes(
 373         SSLContextRef ctx,
 374         unsigned *numTypes);
 375
 376 /*
 377  * Obtain the client authentication mechanisms specified by
 378  * the server in its Certificate Request message.
 379  * Caller allocates returned array and specifies its size (in
 380  * SSLClientAuthenticationTypes) in *numType on entry; *numTypes
 381  * is the actual size of the returned array on successful return.
 382  */
 383 extern OSStatus SSLGetClientAuthTypes(
 384    SSLContextRef ctx,
 385    SSLClientAuthenticationType *authTypes,              /* RETURNED */
 386    unsigned *numTypes);                                                 /* IN/OUT */
 387
 388 /*
 389  * -- DEPRECATED --
 390  * This is not actually useful. Currently return errSecUnimplemented.
 391  * The client auth type is fully determined by the type of private key used by
 392  * the client.
 393  */
 394 extern OSStatus SSLGetNegotiatedClientAuthType(
 395    SSLContextRef ctx,
 396    SSLClientAuthenticationType *authType);              /* RETURNED */
 397
 398
 399 /*
 400  * Obtain the number of supported_signature_algorithms specified by
 401  * the server in its Certificate Request message.
 402  * Returns errSecParam if server hasn't sent a Certificate Request message
 403  * (i.e., client certificate state is kSSLClientCertNone).
 404  */
 405 extern OSStatus SSLGetNumberOfSignatureAlgorithms(
 406     SSLContextRef ctx,
 407     unsigned *numSigAlgs);
 408
 409 /*
 410  * Obtain the supported_signature_algorithms specified by
 411  * the server in its Certificate Request message.
 412  * Caller allocates returned array and specifies its size (in
 413  * SSLClientAuthenticationTypes) in *numType on entry; *numTypes
 414  * is the actual size of the returned array on successful return.
 415  */
 416 extern OSStatus SSLGetSignatureAlgorithms(
 417     SSLContextRef ctx,
 418     SSLSignatureAndHashAlgorithm *sigAlgs,              /* RETURNED */
 419     unsigned *numSigAlgs);                                                      /* IN/OUT */
 420
 421 /* PSK SPIs */
 422
 423 /* Set the Shared Secret for PSK CipherSuite.
 424    This need to be set before the handshake starts. */
 425 OSStatus SSLSetPSKSharedSecret(SSLContextRef ctx,
 426                                const void *secret,
 427                                size_t secretLen);
 428
 429 /* Set the Client identity for PSK CipherSuite.
 430    This need to be set before the handshake starts.
 431    Only useful for client side.*/
 432 OSStatus SSLSetPSKIdentity(SSLContextRef ctx,
 433                            const void *pskIdentity,
 434                            size_t pskIdentityLen);
 435
 436 /* For client side, get the identity previously set by SSLSetPSKIdentity.
 437    For server side, get the identity provided by the client during the handshake.
 438    Might be NULL if not set. identity is owned by the SSLContext and is invalid once
 439    the SSLContext is released.
 440  */
 441 OSStatus SSLGetPSKIdentity(SSLContextRef ctx,
 442                            const void **pskIdentity,
 443                            size_t *pskIdentityLen);
 444
 445 /* For client side, set the minimum allowed DH group size for DHE ciphersuites */
 446 OSStatus SSLSetMinimumDHGroupSize(SSLContextRef ctx, unsigned nbits);
 447
 448 OSStatus SSLGetMinimumDHGroupSize(SSLContextRef ctx, unsigned *nbits);
 449
 450 OSStatus SSLSetDHEEnabled(SSLContextRef ctx, bool enabled);
 451
 452 OSStatus SSLGetDHEEnabled(SSLContextRef ctx, bool *enabled);
 453
 454 #if TARGET_OS_IPHONE
 455
 456 /* Following are SPIs on iOS */
 457
 458 /*
 459  * Set allowed SSL protocol versions. Optional.
 460  * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in
 461  * specified 'enable' boolean to be applied to all supported protocols.
 462  * The default is "all supported protocols are enabled".
 463  * This can only be called when no session is active.
 464  *
 465  * Legal values for protocol are :
 466  *              kSSLProtocol2
 467  *              kSSLProtocol3
 468  *              kTLSProtocol1
 469  *              kSSLProtocolAll
 470  *
 471  * This is deprecated in favor of SSLSetProtocolVersionMax/SSLSetProtocolVersionMin
 472  */
 473 OSStatus
 474 _SSLSetProtocolVersionEnabled (SSLContextRef    context,
 475                               SSLProtocol               protocol,
 476                                Boolean                  enable) API_UNAVAILABLE(iosmac);
 477
 478 /*
 479  * Obtain a value specified in SSLSetProtocolVersionEnabled.
 480  *
 481  * This is deprecated in favor of SSLGetProtocolVersionMax/SSLGetProtocolVersionMin
 482  */
 483 OSStatus
 484 _SSLGetProtocolVersionEnabled(SSLContextRef             context,
 485                              SSLProtocol                protocol,
 486                               Boolean                   *enable) API_UNAVAILABLE(iosmac);               /* RETURNED */
 487
 488 /*
 489  * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown,
 490  * in which case the highest possible version (currently kTLSProtocol1)
 491  * is attempted, but a lower version is accepted if the peer requires it.
 492  *
 493  * SSLSetProtocolVersion can not be called when a session is active.
 494  *
 495  * This is deprecated in favor of SSLSetProtocolVersionEnabled.
 496  *
 497  * This is deprecated in favor of SSLSetProtocolVersionMax/SSLSetProtocolVersionMin
 498  */
 499 OSStatus
 500 _SSLSetProtocolVersion          (SSLContextRef          context,
 501                              SSLProtocol                version) API_UNAVAILABLE(iosmac);
 502
 503 /*
 504  * Obtain the protocol version specified in SSLSetProtocolVersion.
 505  * This is deprecated in favor of SSLGetProtocolVersionEnabled.
 506  * If SSLSetProtocolVersionEnabled() has been called for this session,
 507  * SSLGetProtocolVersion() may return errSecParam if the protocol enable
 508  * state can not be represented by the SSLProtocol enums (e.g.,
 509  * SSL2 and TLS1 enabled, SSL3 disabled).
 510  *
 511  * This is deprecated in favor of SSLGetProtocolVersionMax/SSLGetProtocolVersionMin
 512  */
 513 OSStatus
 514 _SSLGetProtocolVersion          (SSLContextRef          context,
 515                              SSLProtocol                *protocol) API_UNAVAILABLE(iosmac);             /* RETURNED */
 516
 517 /* API REVIEW:
 518  The following 15 calls were used to change the behaviour of the trust
 519  evaluation of the certificate chain.
 520  The proper alternative is to break out of the handshake, get the
 521  peer's SecTrustRef with SSLCopyPeerTrust and evaluate that.
 522  */
 523
 524 /*
 525  * Enable/disable peer certificate chain validation. Default is enabled.
 526  * If caller disables, it is the caller's responsibility to call
 527  * SSLCopyPeerTrust() upon successful completion of the handshake
 528  * and then to perform external validation of the peer certificate
 529  * chain before proceeding with data transfer.
 530  */
 531 OSStatus
 532 _SSLSetEnableCertVerify         (SSLContextRef                  context,
 533                              Boolean                            enableVerify) API_UNAVAILABLE(iosmac);
 534
 535 OSStatus
 536 _SSLGetEnableCertVerify         (SSLContextRef                  context,
 537                              Boolean                            *enableVerify) API_UNAVAILABLE(iosmac); /* RETURNED */
 538
 539 /*
 540  * Specify the option of ignoring certificates' "expired" times.
 541  * This is a common failure in the real SSL world. Default for
 542  * this flag is false, meaning expired certs result in a
 543  * errSSLCertExpired error.
 544  */
 545 OSStatus
 546 _SSLSetAllowsExpiredCerts       (SSLContextRef          context,
 547                              Boolean                    allowsExpired) API_UNAVAILABLE(iosmac);
 548
 549 /*
 550  * Obtain the current value of an SSLContext's "allowExpiredCerts" flag.
 551  */
 552 OSStatus
 553 _SSLGetAllowsExpiredCerts       (SSLContextRef          context,
 554                              Boolean                    *allowsExpired) API_UNAVAILABLE(iosmac); /* RETURNED */
 555
 556 /*
 557  * Similar to SSLSetAllowsExpiredCerts(), this function allows the
 558  * option of ignoring "expired" status for root certificates only.
 559  * Default is false, i.e., expired root certs result in an
 560  * errSSLCertExpired error.
 561  */
 562 OSStatus
 563 _SSLSetAllowsExpiredRoots       (SSLContextRef          context,
 564                              Boolean                    allowsExpired) API_UNAVAILABLE(iosmac);
 565
 566 OSStatus
 567 _SSLGetAllowsExpiredRoots       (SSLContextRef          context,
 568                              Boolean                    *allowsExpired) API_UNAVAILABLE(iosmac); /* RETURNED */
 569
 570 /*
 571  * Specify option of allowing for an unknown root cert, i.e., one which
 572  * this software can not verify as one of a list of known good root certs.
 573  * Default for this flag is false, in which case one of the following two
 574  * errors may occur:
 575  *    -- The peer returns a cert chain with a root cert, and the chain
 576  *       verifies to that root, but the root is not one of our trusted
 577  *       roots. This results in errSSLUnknownRootCert on handshake.
 578  *    -- The peer returns a cert chain which does not contain a root cert,
 579  *       and we can't verify the chain to one of our trusted roots. This
 580  *       results in errSSLNoRootCert on handshake.
 581  *
 582  * Both of these error conditions are ignored when the AllowAnyRoot flag is true,
 583  * allowing connection to a totally untrusted peer.
 584  */
 585 OSStatus
 586 _SSLSetAllowsAnyRoot                    (SSLContextRef          context,
 587                                  Boolean                        anyRoot) API_UNAVAILABLE(iosmac);
 588
 589 /*
 590  * Obtain the current value of an SSLContext's "allow any root" flag.
 591  */
 592 OSStatus
 593 _SSLGetAllowsAnyRoot                    (SSLContextRef          context,
 594                                  Boolean                        *anyRoot) API_UNAVAILABLE(iosmac); /* RETURNED */
 595
 596 /*
 597  * Augment or replace the system's default trusted root certificate set
 598  * for this session. If replaceExisting is true, the specified roots will
 599  * be the only roots which are trusted during this session. If replaceExisting
 600  * is false, the specified roots will be added to the current set of trusted
 601  * root certs. If this function has never been called, the current trusted
 602  * root set is the same as the system's default trusted root set.
 603  * Successive calls with replaceExisting false result in accumulation
 604  * of additional root certs.
 605  *
 606  * The trustedRoots array contains SecCertificateRefs.
 607  */
 608 OSStatus
 609 _SSLSetTrustedRoots                     (SSLContextRef          context,
 610                              CFArrayRef                 trustedRoots,
 611                              Boolean                    replaceExisting) API_UNAVAILABLE(iosmac);
 612
 613 /*
 614  * Obtain an array of SecCertificateRefs representing the current
 615  * set of trusted roots. If SSLSetTrustedRoots() has never been called
 616  * for this session, this returns the system's default root set.
 617  *
 618  * Caller must CFRelease the returned CFArray.
 619  */
 620 OSStatus
 621 _SSLCopyTrustedRoots                    (SSLContextRef          context,
 622                                  CFArrayRef             *trustedRoots) API_UNAVAILABLE(iosmac); /* RETURNED */
 623
 624 /*
 625  * Add a SecCertificateRef, or a CFArray of them, to a server's list
 626  * of acceptable Certificate Authorities (CAs) to present to the client
 627  * when client authentication is performed.
 628  *
 629  * If replaceExisting is true, the specified certificate(s) will replace
 630  * a possible existing list of acceptable CAs. If replaceExisting is
 631  * false, the specified certificate(s) will be appended to the existing
 632  * list of acceptable CAs, if any.
 633  *
 634  * Returns errSecParam is this is called on an SSLContextRef which
 635  * is configured as a client, or when a session is active.
 636  */
 637 OSStatus
 638 _SSLSetCertificateAuthorities(SSLContextRef             context,
 639                              CFTypeRef                  certificateOrArray,
 640                               Boolean                   replaceExisting) API_UNAVAILABLE(iosmac);
 641
 642 /*
 643  * Obtain the certificates specified in SSLSetCertificateAuthorities(),
 644  * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not
 645  * been called.
 646  * Caller must CFRelease the returned array.
 647  */
 648
 649 OSStatus
 650 _SSLCopyCertificateAuthorities(SSLContextRef            context,
 651                               CFArrayRef                *certificates) API_UNAVAILABLE(iosmac); /* RETURNED */
 652
 653 /*
 654  * Request peer certificates. Valid anytime, subsequent to
 655  * a handshake attempt.
 656  *
 657  * The certs argument is a CFArray containing SecCertificateRefs.
 658  * Caller must CFRelease the returned array.
 659  *
 660  * The cert at index 0 of the returned array is the subject (end
 661  * entity) cert; the root cert (or the closest cert to it) is at
 662  * the end of the returned array.
 663  */
 664 /* API REVIEW:
 665  This should be removed so that applications are not tempted to
 666  use this to evaluate trust, they should use the SecTrustRef returned
 667  by SSLCopyPeerTrust instead.
 668  But this maybe useful to know which certs where returned by the server
 669  vs which where pulled internally.
 670  This would be a debug feature, so we deprecate this in iOS. There
 671  should be an API in SecTrust to allow getting the original certificates
 672  for debug purpose.
 673  */
 674 OSStatus
 675 _SSLCopyPeerCertificates                (SSLContextRef          context,
 676                              CFArrayRef                 *certs) API_UNAVAILABLE(iosmac);        /* RETURNED */
 677
 678 /*
 679  * Specify Diffie-Hellman parameters. Optional; if we are configured to allow
 680  * for D-H ciphers and a D-H cipher is negotiated, and this function has not
 681  * been called, a set of process-wide parameters will be calculated. However
 682  * that can take a long time (30 seconds).
 683  */
 684 OSStatus _SSLSetDiffieHellmanParams     (SSLContextRef                  context,
 685                                      const void                         *dhParams,
 686                                      size_t                                     dhParamsLen) API_UNAVAILABLE(iosmac);
 687
 688 /*
 689  * Return parameter block specified in SSLSetDiffieHellmanParams.
 690  * Returned data is not copied and belongs to the SSLContextRef.
 691  */
 692 OSStatus _SSLGetDiffieHellmanParams     (SSLContextRef                  context,
 693                                      const void                         **dhParams,
 694                                      size_t                                     *dhParamsLen) API_UNAVAILABLE(iosmac);
 695
 696 /*
 697  * Enable/Disable RSA blinding. This feature thwarts a known timing
 698  * attack to which RSA keys are vulnerable; enabling it is a tradeoff
 699  * between performance and security. The default for RSA blinding is
 700  * enabled.
 701  */
 702 OSStatus _SSLSetRsaBlinding                     (SSLContextRef                  context,
 703                                      Boolean                            blinding) API_UNAVAILABLE(iosmac);
 704
 705 OSStatus _SSLGetRsaBlinding                     (SSLContextRef                  context,
 706                                      Boolean                            *blinding) API_UNAVAILABLE(iosmac);
 707
 708 /*
 709  * Create a new SSL/TLS session context.
 710  * Deprecated: please use the allocator based functions, when available.
 711  */
 712 OSStatus
 713 _SSLNewContext                          (Boolean                        isServer,
 714                              SSLContextRef              *tlsContextPtr) API_UNAVAILABLE(iosmac);     /* RETURNED */
 715
 716 /*
 717  * Dispose of an SSLContextRef.  This is effectivly a CFRelease.
 718  * Deprecated.
 719  */
 720 OSStatus
 721 _SSLDisposeContext                      (SSLContextRef          context) API_UNAVAILABLE(iosmac);
 722
 723 /* We redefine the names of all SPIs to avoid collision with unavailable APIs */
 724 #define SSLSetProtocolVersionEnabled _SSLSetProtocolVersionEnabled
 725 #define SSLGetProtocolVersionEnabled _SSLGetProtocolVersionEnabled
 726 #define SSLSetProtocolVersion _SSLSetProtocolVersion
 727 #define SSLGetProtocolVersion _SSLGetProtocolVersion
 728 #define SSLSetEnableCertVerify _SSLSetEnableCertVerify
 729 #define SSLGetEnableCertVerify _SSLGetEnableCertVerify
 730 #define SSLSetAllowsExpiredCerts _SSLSetAllowsExpiredCerts
 731 #define SSLGetAllowsExpiredCerts _SSLGetAllowsExpiredCerts
 732 #define SSLSetAllowsExpiredRoots _SSLSetAllowsExpiredRoots
 733 #define SSLGetAllowsExpiredRoots _SSLGetAllowsExpiredRoots
 734 #define SSLSetAllowsAnyRoot _SSLSetAllowsAnyRoot
 735 #define SSLGetAllowsAnyRoot _SSLGetAllowsAnyRoot
 736 #define SSLSetTrustedRoots _SSLSetTrustedRoots
 737 #define SSLCopyTrustedRoots _SSLCopyTrustedRoots
 738 #define SSLSetCertificateAuthorities _SSLSetCertificateAuthorities
 739 #define SSLCopyCertificateAuthorities _SSLCopyCertificateAuthorities
 740 #define SSLCopyPeerCertificates _SSLCopyPeerCertificates
 741 #define SSLSetDiffieHellmanParams _SSLSetDiffieHellmanParams
 742 #define SSLGetDiffieHellmanParams _SSLGetDiffieHellmanParams
 743 #define SSLSetRsaBlinding   _SSLSetRsaBlinding
 744 #define SSLGetRsaBlinding       _SSLGetRsaBlinding
 745 #define SSLNewContext _SSLNewContext
 746 #define SSLNewDatagramContext _SSLNewDatagramContext
 747 #define SSLDisposeContext _SSLDisposeContext
 748
 749 #endif /* TARGET_OS_IPHONE */
 750
 751 /*
 752  * Map the SSLProtocol enum to an enum capturing the wire format (coreTLS) version.
 753  */
 754 #define SECURITY_HAS_TLS_VERSION_TRANSLATOR 1
 755 tls_protocol_version
 756 _SSLProtocolVersionToWireFormatValue   (SSLProtocol protocol);
 757
 758
 759 /*
 760  * Create a new Datagram TLS session context.
 761  * Use in place of SSLNewContext to create a DTLS session.
 762  * Deprecated: please use the allocator based functions, when available.
 763  * Also note: the symbol is prefixed with underscore in iOS (historical)
 764  */
 765 OSStatus
 766 SSLNewDatagramContext           (Boolean                        isServer,
 767                              SSLContextRef              *dtlsContextPtr) API_UNAVAILABLE(iosmac);       /* RETURNED */
 768
 769
 770
 771 /*
 772  * NPN support.
 773  *
 774  * If used, must be by client and server before SSLHandshake()
 775  *
 776  * Client: if set the client will announce NPN extension in the
 777  * ClientHello, and the a callback will provide the server list, at
 778  * that time the client needs to call SSLSetNPNData() in the callback
 779  * to provide to the server the support mechanism.
 780  *
 781  * Server: the callback will tell the server that the client supports
 782  * NPN and at that time, the server needs to set the supported NPN
 783  * types with SSLSetNPNData().
 784  */
 785 typedef void
 786 (*SSLNPNFunc)               (SSLContextRef          ctx,
 787                              void                   *info,              /* info pointer provided by SSLSetNPNFunc */
 788                              const void                     *npnData,
 789                              size_t                 npnDataLength);
 790
 791
 792 void
 793 SSLSetNPNFunc               (SSLContextRef      context,
 794                              SSLNPNFunc         npnFunc,
 795                              void               *info)
 796     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 797
 798 /*
 799  * For servers, this is the data that is announced.
 800  * For clients, this is the picked data in the npnFunc callback.
 801  *
 802  * Return an error on out of memory and if buffer it too large
 803  */
 804 OSStatus
 805 SSLSetNPNData                           (SSLContextRef      context,
 806                              const void *data,
 807                                                          size_t length)
 808     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 809
 810 /*
 811  * For servers, return client provided npn data if sent
 812  */
 813 const void *
 814 SSLGetNPNData                           (SSLContextRef      context,
 815                                                          size_t                         *length)
 816     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 817
 818 // ALPN
 819 typedef void
 820 (*SSLALPNFunc)             (SSLContextRef          ctx,
 821                             void                    *info,              /* info pointer provided by SSLSetALPNFunc */
 822                             const void                      *alpnData,
 823                             size_t                  alpnDataLength);
 824
 825 void
 826 SSLSetALPNFunc              (SSLContextRef      context,
 827                              SSLALPNFunc         alpnFunc,
 828                              void               *info)
 829     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 830
 831
 832 OSStatus
 833 SSLSetALPNData                          (SSLContextRef      context,
 834                              const void *data,
 835                              size_t length)
 836     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 837
 838 const void *
 839 SSLGetALPNData                          (SSLContextRef      context,
 840                              size_t                             *length)
 841     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 842
 843 // end of ALPN
 844
 845 #ifdef __cplusplus
 846 }
 847 #endif
 848
 849
 850 #endif  /* _SECURE_TRANSPORT_PRIV_H_ */