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