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