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