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