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