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_ */