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 35extern "C" { 36#endif 37 38#include <Security/sslTypes.h> 39 40/* Create an SSL Context with an external record layer - eg: kernel accelerated layer */ 41SSLContextRef 42SSLCreateContextWithRecordFuncs(CFAllocatorRef alloc, 43 SSLProtocolSide protocolSide, 44 SSLConnectionType connectionType, 45 const struct SSLRecordFuncs *recFuncs); 46 47/* Set the external record layer context */ 48OSStatus 49SSLSetRecordContext (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 */ 64OSStatus SSLInternalMasterSecret( 65 SSLContextRef context, 66 void *secret, // mallocd by caller, SSL_MASTER_SECRET_SIZE 67 size_t *secretSize); // in/out 68 69OSStatus SSLInternalServerRandom( 70 SSLContextRef context, 71 void *randBuf, // mallocd by caller, SSL_CLIENT_SRVR_RAND_SIZE 72 size_t *randSize); // in/out 73 74OSStatus 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 */ 83OSStatus SSLGetCipherSizes( 84 SSLContextRef context, 85 size_t *digestSize, 86 size_t *symmetricKeySize, 87 size_t *ivSize); 88 89OSStatus 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 */ 105OSStatus 106SSLGetPeerSecTrust (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 121OSStatus 122SSLGetResumableSessionInfo ( 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 */ 131OSStatus 132SSLGetCertificate ( 133 SSLContextRef context, 134 CFArrayRef *certRefs); // RETURNED, *not* retained 135 136OSStatus 137SSLGetEncryptionCertificate ( 138 SSLContextRef context, 139 CFArrayRef *certRefs); // RETURNED, *not* retained 140 141/* 142 * Getter for SSLSetClientSideAuthenticate() 143 */ 144OSStatus 145SSLGetClientSideAuthenticate ( 146 SSLContextRef context, 147 SSLAuthenticate *auth); // RETURNED 148 149/* 150 * Get/set array of trusted leaf certificates. 151 * 152 * If none have been set previously with SSLSetTrustedLeafCertificates(), 153 * then SSLCopyTrustedLeafCertificates() will return NULL with errSecSuccess. 154 */ 155OSStatus 156SSLSetTrustedLeafCertificates ( 157 SSLContextRef context, 158 CFArrayRef certRefs); 159 160OSStatus 161SSLCopyTrustedLeafCertificates ( 162 SSLContextRef context, 163 CFArrayRef *certRefs); // RETURNED, caller must release 164 165/* 166 * Get/set enable of anonymous ciphers. Default is enabled. 167 * 168 * SSLSetAllowAnonymousCiphers() returns errSecBadReq if SSLSetEnabledCiphers() 169 * has already been called. 170 * 171 * The enable state set by SSLSetAllowAnonymousCiphers() is ignored if 172 * SSLSetEnabledCiphers() is called after SSLSetAllowAnonymousCiphers() is 173 * called, i.e., SSLSetEnabledCiphers() overrides SSLSetAllowAnonymousCiphers(). 174 * 175 * NOTE: "Anonymous" ciphers include those ciphers that perform no encryption, 176 * as well as ciphers that perform no authentication, since neither are secure. 177 */ 178OSStatus 179SSLSetAllowAnonymousCiphers( 180 SSLContextRef context, 181 Boolean enable); 182 183OSStatus 184SSLGetAllowAnonymousCiphers( 185 SSLContextRef context, 186 Boolean *enable); 187 188/* 189 * Override the default session cache timeout for a cache entry created for 190 * the current session. 191 */ 192OSStatus 193SSLSetSessionCacheTimeout( 194 SSLContextRef context, 195 uint32_t timeoutInSeconds); 196 197/* 198 * Callback function for EAP-style PAC-based session resumption. 199 * This function is called by SecureTransport to obtain the 200 * master secret. 201 */ 202typedef void (*SSLInternalMasterSecretFunction)( 203 SSLContextRef ctx, 204 const void *arg, /* opaque to SecureTransport; app-specific */ 205 void *secret, /* mallocd by caller, SSL_MASTER_SECRET_SIZE */ 206 size_t *secretLength); /* in/out */ 207 208/* 209 * Register a callback for obtaining the master_secret when performing 210 * PAC-based session resumption. At the time the callback is called, 211 * the following are guaranteed to be valid: 212 * 213 * -- serverRandom (via SSLInternalServerRandom()) 214 * -- clientRandom (via SSLInternalClientRandom()) 215 * -- negotiated protocol version (via SSLGetNegotiatedProtocolVersion()) 216 * -- negotiated CipherSuite (via SSLGetNegotiatedCipher()) 217 * 218 * Currently, PAC-based session resumption is only implemented on 219 * the client side for Deployment builds. 220 * 221 * On the client side, this callback occurs if/when the server sends a 222 * ChangeCipherSpec message immediately following its ServerHello 223 * message (i.e., it's skipped the entire Key Exchange phase of 224 * negotiation). 225 * 226 * On the server side (Development builds only) this callback occurs 227 * immediately upon receipt of the Client Hello message, before we send 228 * the Server Hello. 229 */ 230OSStatus 231SSLInternalSetMasterSecretFunction( 232 SSLContextRef ctx, 233 SSLInternalMasterSecretFunction mFunc, 234 const void *arg); /* opaque to SecureTransport; app-specific */ 235 236/* 237 * Provide an opaque SessionTicket for use in PAC-based session 238 * resumption. Client side only. The provided ticket is sent in 239 * the ClientHello message as a SessionTicket extension. 240 * The maximum ticketLength is 2**16-1. 241 */ 242OSStatus SSLInternalSetSessionTicket( 243 SSLContextRef ctx, 244 const void *ticket, 245 size_t ticketLength); 246 247/* 248 * Support for specifying and obtaining ECC curves, used with the ECDH-based 249 * ciphersuites. 250 */ 251 252/* 253 * These are the named curves from RFC 4492 254 * section 5.1.1, with the exception of SSL_Curve_None which means 255 * "ECDSA not negotiated". 256 */ 257typedef enum 258{ 259 SSL_Curve_None = -1, 260 261 SSL_Curve_sect163k1 = 1, 262 SSL_Curve_sect163r1 = 2, 263 SSL_Curve_sect163r2 = 3, 264 SSL_Curve_sect193r1 = 4, 265 SSL_Curve_sect193r2 = 5, 266 SSL_Curve_sect233k1 = 6, 267 SSL_Curve_sect233r1 = 7, 268 SSL_Curve_sect239k1 = 8, 269 SSL_Curve_sect283k1 = 9, 270 SSL_Curve_sect283r1 = 10, 271 SSL_Curve_sect409k1 = 11, 272 SSL_Curve_sect409r1 = 12, 273 SSL_Curve_sect571k1 = 13, 274 SSL_Curve_sect571r1 = 14, 275 SSL_Curve_secp160k1 = 15, 276 SSL_Curve_secp160r1 = 16, 277 SSL_Curve_secp160r2 = 17, 278 SSL_Curve_secp192k1 = 18, 279 SSL_Curve_secp192r1 = 19, 280 SSL_Curve_secp224k1 = 20, 281 SSL_Curve_secp224r1 = 21, 282 SSL_Curve_secp256k1 = 22, 283 284 /* These are the ones we actually support */ 285 SSL_Curve_secp256r1 = 23, 286 SSL_Curve_secp384r1 = 24, 287 SSL_Curve_secp521r1 = 25 288} SSL_ECDSA_NamedCurve; 289 290/* 291 * Obtain the SSL_ECDSA_NamedCurve negotiated during a handshake. 292 * Returns errSecParam if no ECDH-related ciphersuite was negotiated. 293 */ 294extern OSStatus SSLGetNegotiatedCurve( 295 SSLContextRef ctx, 296 SSL_ECDSA_NamedCurve *namedCurve); /* RETURNED */ 297 298/* 299 * Obtain the number of currently enabled SSL_ECDSA_NamedCurves. 300 */ 301extern OSStatus SSLGetNumberOfECDSACurves( 302 SSLContextRef ctx, 303 unsigned *numCurves); /* RETURNED */ 304 305/* 306 * Obtain the ordered list of currently enabled SSL_ECDSA_NamedCurves. 307 * Caller allocates returned array and specifies its size (in 308 * SSL_ECDSA_NamedCurves) in *numCurves on entry; *numCurves 309 * is the actual size of the returned array on successful return. 310 */ 311extern OSStatus SSLGetECDSACurves( 312 SSLContextRef ctx, 313 SSL_ECDSA_NamedCurve *namedCurves, /* RETURNED */ 314 unsigned *numCurves); /* IN/OUT */ 315 316/* 317 * Specify ordered list of allowable named curves. 318 */ 319extern OSStatus SSLSetECDSACurves( 320 SSLContextRef ctx, 321 const SSL_ECDSA_NamedCurve *namedCurves, 322 unsigned numCurves); 323 324/* 325 * Server-specified client authentication mechanisms. 326 */ 327typedef enum { 328 /* doesn't appear on the wire */ 329 SSLClientAuthNone = -1, 330 /* RFC 2246 7.4.6 */ 331 SSLClientAuth_RSASign = 1, 332 SSLClientAuth_DSSSign = 2, 333 SSLClientAuth_RSAFixedDH = 3, 334 SSLClientAuth_DSS_FixedDH = 4, 335 /* RFC 4492 5.5 */ 336 SSLClientAuth_ECDSASign = 64, 337 SSLClientAuth_RSAFixedECDH = 65, 338 SSLClientAuth_ECDSAFixedECDH = 66 339} SSLClientAuthenticationType; 340 341/* TLS 1.2 Signature Algorithms extension values for hash field. */ 342typedef enum { 343 SSL_HashAlgorithmNone = 0, 344 SSL_HashAlgorithmMD5 = 1, 345 SSL_HashAlgorithmSHA1 = 2, 346 SSL_HashAlgorithmSHA224 = 3, 347 SSL_HashAlgorithmSHA256 = 4, 348 SSL_HashAlgorithmSHA384 = 5, 349 SSL_HashAlgorithmSHA512 = 6 350} SSL_HashAlgorithm; 351 352/* TLS 1.2 Signature Algorithms extension values for signature field. */ 353typedef enum { 354 SSL_SignatureAlgorithmAnonymous = 0, 355 SSL_SignatureAlgorithmRSA = 1, 356 SSL_SignatureAlgorithmDSA = 2, 357 SSL_SignatureAlgorithmECDSA = 3 358} SSL_SignatureAlgorithm; 359 360typedef struct { 361 SSL_HashAlgorithm hash; 362 SSL_SignatureAlgorithm signature; 363} SSLSignatureAndHashAlgorithm; 364 365/* 366 * Obtain the number of client authentication mechanisms specified by 367 * the server in its Certificate Request message. 368 * Returns errSecParam if server hasn't sent a Certificate Request message 369 * (i.e., client certificate state is kSSLClientCertNone). 370 */ 371extern OSStatus SSLGetNumberOfClientAuthTypes( 372 SSLContextRef ctx, 373 unsigned *numTypes); 374 375/* 376 * Obtain the client authentication mechanisms specified by 377 * the server in its Certificate Request message. 378 * Caller allocates returned array and specifies its size (in 379 * SSLClientAuthenticationTypes) in *numType on entry; *numTypes 380 * is the actual size of the returned array on successful return. 381 */ 382extern OSStatus SSLGetClientAuthTypes( 383 SSLContextRef ctx, 384 SSLClientAuthenticationType *authTypes, /* RETURNED */ 385 unsigned *numTypes); /* IN/OUT */ 386 387/* 388 * Obtain the SSLClientAuthenticationType actually performed. 389 * Only valid if client certificate state is kSSLClientCertSent 390 * or kSSLClientCertRejected; SSLClientAuthNone is returned as 391 * the negotiated auth type otherwise. 392 */ 393extern OSStatus SSLGetNegotiatedClientAuthType( 394 SSLContextRef ctx, 395 SSLClientAuthenticationType *authType); /* RETURNED */ 396 397 398/* 399 * Obtain the number of supported_signature_algorithms specified by 400 * the server in its Certificate Request message. 401 * Returns errSecParam if server hasn't sent a Certificate Request message 402 * (i.e., client certificate state is kSSLClientCertNone). 403 */ 404extern OSStatus SSLGetNumberOfSignatureAlgorithms( 405 SSLContextRef ctx, 406 unsigned *numSigAlgs); 407 408/* 409 * Obtain the supported_signature_algorithms specified by 410 * the server in its Certificate Request message. 411 * Caller allocates returned array and specifies its size (in 412 * SSLClientAuthenticationTypes) in *numType on entry; *numTypes 413 * is the actual size of the returned array on successful return. 414 */ 415extern OSStatus SSLGetSignatureAlgorithms( 416 SSLContextRef ctx, 417 SSLSignatureAndHashAlgorithm *sigAlgs, /* RETURNED */ 418 unsigned *numSigAlgs); /* IN/OUT */ 419 420/* PSK SPIs */ 421 422/* Set the Shared Secret for PSK CipherSuite. 423 This need to be set before the handshake starts. */ 424OSStatus SSLSetPSKSharedSecret(SSLContextRef ctx, 425 const void *secret, 426 size_t secretLen); 427 428/* Set the Client identity for PSK CipherSuite. 429 This need to be set before the handshake starts. 430 Only useful for client side.*/ 431OSStatus SSLSetPSKIdentity(SSLContextRef ctx, 432 const void *pskIdentity, 433 size_t pskIdentityLen); 434 435/* For client side, get the identity previously set by SSLSetPSKIdentity. 436 For server side, get the identity provided by the client during the handshake. 437 Might be NULL if not set. identity is owned by the SSLContext and is invalid once 438 the SSLContext is released. 439 */ 440OSStatus SSLGetPSKIdentity(SSLContextRef ctx, 441 const void **pskIdentity, 442 size_t *pskIdentityLen); 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 */ 463OSStatus 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 */ 473OSStatus 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 */ 489OSStatus 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 */ 503OSStatus 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 */ 521OSStatus 522_SSLSetEnableCertVerify (SSLContextRef context, 523 Boolean enableVerify); 524 525OSStatus 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 */ 535OSStatus 536_SSLSetAllowsExpiredCerts (SSLContextRef context, 537 Boolean allowsExpired); 538 539/* 540 * Obtain the current value of an SSLContext's "allowExpiredCerts" flag. 541 */ 542OSStatus 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 */ 552OSStatus 553_SSLSetAllowsExpiredRoots (SSLContextRef context, 554 Boolean allowsExpired); 555 556OSStatus 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 */ 575OSStatus 576_SSLSetAllowsAnyRoot (SSLContextRef context, 577 Boolean anyRoot); 578 579/* 580 * Obtain the current value of an SSLContext's "allow any root" flag. 581 */ 582OSStatus 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 */ 598OSStatus 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 */ 610OSStatus 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 */ 627OSStatus 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 639OSStatus 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 */ 664OSStatus 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 */ 674OSStatus _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 */ 682OSStatus _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 */ 692OSStatus _SSLSetRsaBlinding (SSLContextRef context, 693 Boolean blinding); 694 695OSStatus _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 */ 702OSStatus 703_SSLNewContext (Boolean isServer, 704 SSLContextRef *tlsContextPtr); /* RETURNED */ 705 706/* 707 * Dispose of an SSLContextRef. This is effectivly a CFRelease. 708 * Deprecated. 709 */ 710OSStatus 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 */ 748OSStatus 749SSLNewDatagramContext (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 */ 768typedef void 769(*SSLNPNFunc) (SSLContextRef ctx, 770 void *info, /* info pointer provided by SSLSetNPNFunc */ 771 const void *npnData, 772 size_t npnDataLength); 773 774 775void 776SSLSetNPNFunc (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 */ 787OSStatus 788SSLSetNPNData (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 */ 796const void * 797SSLGetNPNData (SSLContextRef context, 798 size_t *length) 799 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0); 800 801 802#ifdef __cplusplus 803} 804#endif 805 806 807#endif /* _SECURE_TRANSPORT_PRIV_H_ */ 808