2 * Copyright (c) 1999-2002,2005-2016 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
25 * SecureTransport.h - Public API for Apple SSL/TLS Implementation
28 #ifndef _SECURITY_SECURETRANSPORT_H_
29 #define _SECURITY_SECURETRANSPORT_H_
32 * This file describes the public API for an implementation of the
33 * Secure Socket Layer, V. 3.0, Transport Layer Security, V. 1.0 to V. 1.2
34 * and Datagram Transport Layer Security V. 1.0
36 * There are no transport layer dependencies in this library;
37 * it can be used with sockets, Open Transport, etc. Applications using
38 * this library provide callback functions which do the actual I/O
39 * on underlying network connections. Applications are also responsible
40 * for setting up raw network connections; the application passes in
41 * an opaque reference to the underlying (connected) entity at the
42 * start of an SSL session in the form of an SSLConnectionRef.
46 * A "client" is the initiator of an SSL Session. The canonical example
47 * of a client is a web browser, when it's talking to an https URL.
49 * A "server" is an entity which accepts requests for SSL sessions made
50 * by clients. E.g., a secure web server.
52 * An "SSL Session", or "session", is bounded by calls to SSLHandshake()
53 * and SSLClose(). An "Active session" is in some state between these
54 * two calls, inclusive.
56 * An SSL Session Context, or SSLContextRef, is an opaque reference in this
57 * library to the state associated with one session. A SSLContextRef cannot
58 * be reused for multiple sessions.
61 #include <CoreFoundation/CFArray.h>
62 #include <Security/CipherSuite.h>
63 #include <Security/SecTrust.h>
64 #include <sys/types.h>
65 #include <Availability.h>
71 CF_ASSUME_NONNULL_BEGIN
72 CF_IMPLICIT_BRIDGING_ENABLED
74 /***********************
75 *** Common typedefs ***
76 ***********************/
78 /* Opaque reference to an SSL session context */
80 typedef struct CF_BRIDGED_TYPE(id
) SSLContext
*SSLContextRef
;
82 /* Opaque reference to an I/O connection (socket, endpoint, etc.) */
83 typedef const void * SSLConnectionRef
;
85 /* SSL Protocol version */
86 typedef CF_ENUM(int, SSLProtocol
) {
87 kSSLProtocolUnknown
= 0, /* no protocol negotiated/specified; use default */
88 kSSLProtocol3
= 2, /* SSL 3.0 */
89 kTLSProtocol1
= 4, /* TLS 1.0 */
90 kTLSProtocol11
= 7, /* TLS 1.1 */
91 kTLSProtocol12
= 8, /* TLS 1.2 */
92 kDTLSProtocol1
= 9, /* DTLS 1.0 */
93 kTLSProtocol13
= 10, /* TLS 1.3 */
95 kTLSProtocolMaxSupported
= 999, /* Max system-supported version */
97 kSSLProtocol2
= 1, /* SSL 2.0. DEPRECATED on iOS. */
98 kSSLProtocol3Only
= 3, /* SSL 3.0. DEPRECATED on iOS. */
99 kTLSProtocol1Only
= 5, /* TLS 1.0 Only. DEPRECATED on iOS. */
100 kSSLProtocolAll
= 6, /* All TLS supported protocols. DEPRECATED on iOS. */
103 /* SSL session options */
104 typedef CF_ENUM(int, SSLSessionOption
) {
106 * Set this option to enable returning from SSLHandshake (with a result of
107 * errSSLServerAuthCompleted) when the server authentication portion of the
108 * handshake is complete. This disable certificate verification and
109 * provides an opportunity to perform application-specific server
110 * verification before deciding to continue.
112 kSSLSessionOptionBreakOnServerAuth
= 0,
114 * Set this option to enable returning from SSLHandshake (with a result of
115 * errSSLClientCertRequested) when the server requests a client certificate.
117 kSSLSessionOptionBreakOnCertRequested
= 1,
119 * This option is the same as kSSLSessionOptionBreakOnServerAuth but applies
120 * to the case where SecureTransport is the server and the client has presented
121 * its certificates allowing the server to verify whether these should be
122 * allowed to authenticate.
124 kSSLSessionOptionBreakOnClientAuth
= 2,
126 * Enable/Disable TLS False Start
127 * When enabled, False Start will only be performed if a adequate cipher-suite is
130 kSSLSessionOptionFalseStart
= 3,
132 * Enable/Disable 1/n-1 record splitting for BEAST attack mitigation.
133 * When enabled, record splitting will only be performed for TLS 1.0 connections
134 * using a block cipher.
136 kSSLSessionOptionSendOneByteRecord
= 4,
138 * Allow/Disallow server identity change on renegotiation. Disallow by default
139 * to avoid Triple Handshake attack.
141 kSSLSessionOptionAllowServerIdentityChange
= 5,
143 * Enable fallback countermeasures. Use this option when retyring a SSL connection
144 * with a lower protocol version because of failure to connect.
146 kSSLSessionOptionFallback
= 6,
148 * Set this option to break from a client hello in order to check for SNI
150 kSSLSessionOptionBreakOnClientHello
= 7,
152 * Set this option to Allow renegotations. False by default.
154 kSSLSessionOptionAllowRenegotiation
= 8,
156 * Set this option to enable session tickets. False by default.
158 kSSLSessionOptionEnableSessionTickets
= 9,
161 /* State of an SSLSession */
162 typedef CF_ENUM(int, SSLSessionState
) {
163 kSSLIdle
, /* no I/O performed yet */
164 kSSLHandshake
, /* SSL handshake in progress */
165 kSSLConnected
, /* Handshake complete, ready for normal I/O */
166 kSSLClosed
, /* connection closed normally */
167 kSSLAborted
/* connection aborted */
171 * Status of client certificate exchange (which is optional
172 * for both server and client).
174 typedef CF_ENUM(int, SSLClientCertificateState
) {
175 /* Server hasn't asked for a cert. Client hasn't sent one. */
177 /* Server has asked for a cert, but client didn't send it. */
178 kSSLClientCertRequested
,
180 * Server side: We asked for a cert, client sent one, we validated
181 * it OK. App can inspect the cert via
182 * SSLCopyPeerCertificates().
183 * Client side: server asked for one, we sent it.
187 * Client sent a cert but failed validation. Server side only.
188 * Server app can inspect the cert via SSLCopyPeerCertificates().
190 kSSLClientCertRejected
194 * R/W functions. The application using this library provides
195 * these functions via SSLSetIOFuncs().
197 * Data's memory is allocated by caller; on entry to these two functions
198 * the *length argument indicates both the size of the available data and the
199 * requested byte count. Number of bytes actually transferred is returned in
202 * The application may configure the underlying connection to operate
203 * in a non-blocking manner; in such a case, a read operation may
204 * well return errSSLWouldBlock, indicating "I transferred less data than
205 * you requested (maybe even zero bytes), nothing is wrong, except
206 * requested I/O hasn't completed". This will be returned back up to
207 * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(),
211 (*SSLReadFunc
) (SSLConnectionRef connection
,
212 void *data
, /* owned by
215 size_t *dataLength
); /* IN/OUT */
217 (*SSLWriteFunc
) (SSLConnectionRef connection
,
219 size_t *dataLength
); /* IN/OUT */
221 /*************************************************
222 *** OSStatus values unique to SecureTransport ***
223 *************************************************/
226 Note: the comments that appear after these errors are used to create SecErrorMessages.strings.
227 The comments must not be multi-line, and should be in a form meaningful to an end user. If
228 a different or additional comment is needed, it can be put in the header doc format, or on a
229 line that does not start with errZZZ.
233 errSSLProtocol
= -9800, /* SSL protocol error */
234 errSSLNegotiation
= -9801, /* Cipher Suite negotiation failure */
235 errSSLFatalAlert
= -9802, /* Fatal alert */
236 errSSLWouldBlock
= -9803, /* I/O would block (not fatal) */
237 errSSLSessionNotFound
= -9804, /* attempt to restore an unknown session */
238 errSSLClosedGraceful
= -9805, /* connection closed gracefully */
239 errSSLClosedAbort
= -9806, /* connection closed via error */
240 errSSLXCertChainInvalid
= -9807, /* invalid certificate chain */
241 errSSLBadCert
= -9808, /* bad certificate format */
242 errSSLCrypto
= -9809, /* underlying cryptographic error */
243 errSSLInternal
= -9810, /* Internal error */
244 errSSLModuleAttach
= -9811, /* module attach failure */
245 errSSLUnknownRootCert
= -9812, /* valid cert chain, untrusted root */
246 errSSLNoRootCert
= -9813, /* cert chain not verified by root */
247 errSSLCertExpired
= -9814, /* chain had an expired cert */
248 errSSLCertNotYetValid
= -9815, /* chain had a cert not yet valid */
249 errSSLClosedNoNotify
= -9816, /* server closed session with no notification */
250 errSSLBufferOverflow
= -9817, /* insufficient buffer provided */
251 errSSLBadCipherSuite
= -9818, /* bad SSLCipherSuite */
253 /* fatal errors detected by peer */
254 errSSLPeerUnexpectedMsg
= -9819, /* unexpected message received */
255 errSSLPeerBadRecordMac
= -9820, /* bad MAC */
256 errSSLPeerDecryptionFail
= -9821, /* decryption failed */
257 errSSLPeerRecordOverflow
= -9822, /* record overflow */
258 errSSLPeerDecompressFail
= -9823, /* decompression failure */
259 errSSLPeerHandshakeFail
= -9824, /* handshake failure */
260 errSSLPeerBadCert
= -9825, /* misc. bad certificate */
261 errSSLPeerUnsupportedCert
= -9826, /* bad unsupported cert format */
262 errSSLPeerCertRevoked
= -9827, /* certificate revoked */
263 errSSLPeerCertExpired
= -9828, /* certificate expired */
264 errSSLPeerCertUnknown
= -9829, /* unknown certificate */
265 errSSLIllegalParam
= -9830, /* illegal parameter */
266 errSSLPeerUnknownCA
= -9831, /* unknown Cert Authority */
267 errSSLPeerAccessDenied
= -9832, /* access denied */
268 errSSLPeerDecodeError
= -9833, /* decoding error */
269 errSSLPeerDecryptError
= -9834, /* decryption error */
270 errSSLPeerExportRestriction
= -9835, /* export restriction */
271 errSSLPeerProtocolVersion
= -9836, /* bad protocol version */
272 errSSLPeerInsufficientSecurity
= -9837, /* insufficient security */
273 errSSLPeerInternalError
= -9838, /* internal error */
274 errSSLPeerUserCancelled
= -9839, /* user canceled */
275 errSSLPeerNoRenegotiation
= -9840, /* no renegotiation allowed */
277 /* non-fatal result codes */
278 errSSLPeerAuthCompleted
= -9841, /* peer cert is valid, or was ignored if verification disabled */
279 errSSLClientCertRequested
= -9842, /* server has requested a client cert */
281 /* more errors detected by us */
282 errSSLHostNameMismatch
= -9843, /* peer host name mismatch */
283 errSSLConnectionRefused
= -9844, /* peer dropped connection before responding */
284 errSSLDecryptionFail
= -9845, /* decryption failure */
285 errSSLBadRecordMac
= -9846, /* bad MAC */
286 errSSLRecordOverflow
= -9847, /* record overflow */
287 errSSLBadConfiguration
= -9848, /* configuration error */
288 errSSLUnexpectedRecord
= -9849, /* unexpected (skipped) record in DTLS */
289 errSSLWeakPeerEphemeralDHKey
= -9850, /* weak ephemeral dh key */
291 /* non-fatal result codes */
292 errSSLClientHelloReceived
= -9851, /* SNI */
295 /* DEPRECATED aliases for errSSLPeerAuthCompleted */
296 #define errSSLServerAuthCompleted errSSLPeerAuthCompleted
297 #define errSSLClientAuthCompleted errSSLPeerAuthCompleted
299 /* DEPRECATED alias for the end of the error range */
300 #define errSSLLast errSSLUnexpectedRecord
302 typedef CF_ENUM(int, SSLProtocolSide
)
308 typedef CF_ENUM(int, SSLConnectionType
)
315 * Predefined TLS configurations constants
318 /* Default configuration (has 3DES, no RC4) */
319 extern const CFStringRef kSSLSessionConfig_default
320 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_13
,__IPHONE_5_0
,__IPHONE_11_0
);
322 /* ATS v1 Config: TLS v1.2, only PFS ciphersuites */
323 extern const CFStringRef kSSLSessionConfig_ATSv1
324 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
326 /* ATS v1 Config without PFS: TLS v1.2, include non PFS ciphersuites */
327 extern const CFStringRef kSSLSessionConfig_ATSv1_noPFS
328 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
330 /* TLS v1.2 to TLS v1.0, with default ciphersuites (no 3DES, no RC4) */
331 extern const CFStringRef kSSLSessionConfig_standard
332 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
334 /* TLS v1.2 to TLS v1.0, with default ciphersuites + RC4 + 3DES */
335 extern const CFStringRef kSSLSessionConfig_RC4_fallback
336 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_13
,__IPHONE_5_0
,__IPHONE_11_0
);
338 /* TLS v1.0 only, with default ciphersuites + fallback SCSV */
339 extern const CFStringRef kSSLSessionConfig_TLSv1_fallback
340 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
342 /* TLS v1.0, with default ciphersuites + RC4 + 3DES + fallback SCSV */
343 extern const CFStringRef kSSLSessionConfig_TLSv1_RC4_fallback
344 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_13
,__IPHONE_5_0
,__IPHONE_11_0
);
346 /* TLS v1.2 to TLS v1.0, defaults + RC4 + DHE ciphersuites */
347 extern const CFStringRef kSSLSessionConfig_legacy
348 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
350 /* TLS v1.2 to TLS v1.0, default + RC4 + DHE ciphersuites */
351 extern const CFStringRef kSSLSessionConfig_legacy_DHE
352 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
354 /* TLS v1.2, anonymous ciphersuites only */
355 extern const CFStringRef kSSLSessionConfig_anonymous
356 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
358 /* TLS v1.2 to TLS v1.0, has 3DES, no RC4 */
359 extern const CFStringRef kSSLSessionConfig_3DES_fallback
360 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_13
,__IPHONE_5_0
,__IPHONE_11_0
);
362 /* TLS v1.0, with default ciphersuites + 3DES, no RC4 */
363 extern const CFStringRef kSSLSessionConfig_TLSv1_3DES_fallback
364 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_13
,__IPHONE_5_0
,__IPHONE_11_0
);
372 * Secure Transport APIs require a SSLContextRef, which is an opaque
373 * reference to the SSL session and its parameters. On Mac OS X 10.7
374 * and earlier versions, a new context is created using SSLNewContext,
375 * and is disposed by calling SSLDisposeContext.
377 * On i0S 5.0 and later, as well as Mac OS X versions after 10.7, the
378 * SSLContextRef is a true CFType object with retain-release semantics.
379 * New code should create a new context using SSLCreateContext (instead
380 * of SSLNewContext), and dispose the context by calling CFRelease
381 * (instead of SSLDisposeContext) when finished with it.
385 * Return the CFTypeID for SSLContext objects.
388 SSLContextGetTypeID(void)
389 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
392 * Create a new instance of an SSLContextRef using the specified allocator.
396 SSLCreateContext(CFAllocatorRef __nullable alloc
, SSLProtocolSide protocolSide
, SSLConnectionType connectionType
)
397 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
400 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
402 * Create a new session context.
404 * ==========================
405 * MAC OS X ONLY (DEPRECATED)
406 * ==========================
407 * NOTE: this function is not available on iOS, and should be considered
408 * deprecated on Mac OS X. Your code should use SSLCreateContext instead.
411 SSLNewContext (Boolean isServer
,
412 SSLContextRef
* __nonnull CF_RETURNS_RETAINED contextPtr
) /* RETURNED */
413 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
416 * Dispose of a session context.
418 * ==========================
419 * MAC OS X ONLY (DEPRECATED)
420 * ==========================
421 * NOTE: this function is not available on iOS, and should be considered
422 * deprecated on Mac OS X. Your code should use CFRelease to dispose a session
423 * created with SSLCreateContext.
426 SSLDisposeContext (SSLContextRef context
)
427 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
429 #endif /* MAC OS X */
432 * Determine the state of an SSL/DTLS session.
435 SSLGetSessionState (SSLContextRef context
,
436 SSLSessionState
*state
) /* RETURNED */
437 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
440 * Set options for an SSL session. Must be called prior to SSLHandshake();
441 * subsequently cannot be called while session is active.
444 SSLSetSessionOption (SSLContextRef context
,
445 SSLSessionOption option
,
447 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_5_0
);
450 * Determine current value for the specified option in a given SSL session.
453 SSLGetSessionOption (SSLContextRef context
,
454 SSLSessionOption option
,
456 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_5_0
);
458 /********************************************************************
459 *** Session context configuration, common to client and servers. ***
460 ********************************************************************/
463 * Specify functions which do the network I/O. Must be called prior
464 * to SSLHandshake(); subsequently cannot be called while a session is
468 SSLSetIOFuncs (SSLContextRef context
,
469 SSLReadFunc readFunc
,
470 SSLWriteFunc writeFunc
)
471 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
475 * Set a predefined configuration for the SSL Session
477 * This currently affect enabled protocol versions,
478 * enabled ciphersuites, and the kSSLSessionOptionFallback
482 SSLSetSessionConfig(SSLContextRef context
,
484 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_10_0
);
487 * Set the minimum SSL protocol version allowed. Optional.
488 * The default is the lower supported protocol.
490 * This can only be called when no session is active.
492 * For TLS contexts, legal values for minVersion are :
498 * For DTLS contexts, legal values for minVersion are :
502 SSLSetProtocolVersionMin (SSLContextRef context
,
503 SSLProtocol minVersion
)
504 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
507 * Get minimum protocol version allowed
510 SSLGetProtocolVersionMin (SSLContextRef context
,
511 SSLProtocol
*minVersion
)
512 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
515 * Set the maximum SSL protocol version allowed. Optional.
516 * The default is the highest supported protocol.
518 * This can only be called when no session is active.
520 * For TLS contexts, legal values for maxVersion are :
526 * For DTLS contexts, legal values for maxVersion are :
530 SSLSetProtocolVersionMax (SSLContextRef context
,
531 SSLProtocol maxVersion
)
532 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
535 * Get maximum protocol version allowed
538 SSLGetProtocolVersionMax (SSLContextRef context
,
539 SSLProtocol
*maxVersion
)
540 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
543 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
545 * Set allowed SSL protocol versions. Optional.
546 * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in
547 * specified 'enable' boolean to be applied to all supported protocols.
548 * The default is "all supported protocols are enabled".
549 * This can only be called when no session is active.
551 * Legal values for protocol are :
557 * ==========================
558 * MAC OS X ONLY (DEPRECATED)
559 * ==========================
560 * NOTE: this function is not available on iOS, and should be considered
561 * deprecated on Mac OS X. You can use SSLSetProtocolVersionMin and/or
562 * SSLSetProtocolVersionMax to specify which protocols are enabled.
565 SSLSetProtocolVersionEnabled (SSLContextRef context
,
566 SSLProtocol protocol
,
568 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
571 * Obtain a value specified in SSLSetProtocolVersionEnabled.
573 * ==========================
574 * MAC OS X ONLY (DEPRECATED)
575 * ==========================
576 * NOTE: this function is not available on iOS, and should be considered
577 * deprecated on Mac OS X. You can use SSLGetProtocolVersionMin and/or
578 * SSLGetProtocolVersionMax to check whether a protocol is enabled.
581 SSLGetProtocolVersionEnabled(SSLContextRef context
,
582 SSLProtocol protocol
,
583 Boolean
*enable
) /* RETURNED */
584 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
587 * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown,
588 * in which case the highest possible version is attempted, but a lower
589 * version is accepted if the peer requires it.
590 * SSLSetProtocolVersion cannot be called when a session is active.
592 * ==========================
593 * MAC OS X ONLY (DEPRECATED)
594 * ==========================
595 * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8.
596 * Use SSLSetProtocolVersionMin and/or SSLSetProtocolVersionMax to specify
597 * which protocols are enabled.
600 SSLSetProtocolVersion (SSLContextRef context
,
602 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_8
,__IPHONE_NA
,__IPHONE_NA
);
605 * Obtain the protocol version specified in SSLSetProtocolVersion.
606 * If SSLSetProtocolVersionEnabled() has been called for this session,
607 * SSLGetProtocolVersion() may return errSecParam if the protocol enable
608 * state can not be represented by the SSLProtocol enums (e.g.,
609 * SSL2 and TLS1 enabled, SSL3 disabled).
611 * ==========================
612 * MAC OS X ONLY (DEPRECATED)
613 * ==========================
614 * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8.
615 * Use SSLGetProtocolVersionMin and/or SSLGetProtocolVersionMax to check
616 * whether a protocol is enabled.
619 SSLGetProtocolVersion (SSLContextRef context
,
620 SSLProtocol
*protocol
) /* RETURNED */
621 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_8
,__IPHONE_NA
,__IPHONE_NA
);
623 #endif /* MAC OS X */
626 * Specify this connection's certificate(s). This is mandatory for
627 * server connections, optional for clients. Specifying a certificate
628 * for a client enables SSL client-side authentication. The end-entity
629 * cert is in certRefs[0]. Specifying a root cert is optional; if it's
630 * not specified, the root cert which verifies the cert chain specified
631 * here must be present in the system-wide set of trusted anchor certs.
633 * The certRefs argument is a CFArray containing SecCertificateRefs,
634 * except for certRefs[0], which is a SecIdentityRef.
636 * Must be called prior to SSLHandshake(), or immediately after
637 * SSLHandshake has returned errSSLClientCertRequested (i.e. before the
638 * handshake is resumed by calling SSLHandshake again.)
640 * SecureTransport assumes the following:
642 * -- The certRef references remain valid for the lifetime of the session.
643 * -- The certificate specified in certRefs[0] is capable of signing.
644 * -- The required capabilities of the certRef[0], and of the optional cert
645 * specified in SSLSetEncryptionCertificate (see below), are highly
646 * dependent on the application. For example, to work as a server with
647 * Netscape clients, the cert specified here must be capable of both
648 * signing and encrypting.
651 SSLSetCertificate (SSLContextRef context
,
652 CFArrayRef _Nullable certRefs
)
653 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
656 * Specify I/O connection - a socket, endpoint, etc., which is
657 * managed by caller. On the client side, it's assumed that communication
658 * has been established with the desired server on this connection.
659 * On the server side, it's assumed that an incoming client request
660 * has been established.
662 * Must be called prior to SSLHandshake(); subsequently can only be
663 * called when no session is active.
666 SSLSetConnection (SSLContextRef context
,
667 SSLConnectionRef __nullable connection
)
668 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
671 SSLGetConnection (SSLContextRef context
,
672 SSLConnectionRef
* __nonnull CF_RETURNS_NOT_RETAINED connection
)
673 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
676 * Specify the fully qualified doman name of the peer, e.g., "store.apple.com."
677 * Optional; used to verify the common name field in peer's certificate.
678 * Name is in the form of a C string; NULL termination optional, i.e.,
679 * peerName[peerNameLen+1] may or may not have a NULL. In any case peerNameLen
680 * is the number of bytes of the peer domain name.
683 SSLSetPeerDomainName (SSLContextRef context
,
684 const char * __nullable peerName
,
686 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
689 * Determine the buffer size needed for SSLGetPeerDomainName().
692 SSLGetPeerDomainNameLength (SSLContextRef context
,
693 size_t *peerNameLen
) // RETURNED
694 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
697 * Obtain the value specified in SSLSetPeerDomainName().
700 SSLGetPeerDomainName (SSLContextRef context
,
701 char *peerName
, // returned here
702 size_t *peerNameLen
) // IN/OUT
703 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
707 * Determine the buffer size needed for SSLCopyRequestedPeerNameLength().
710 SSLCopyRequestedPeerName (SSLContextRef context
,
713 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
716 * Server Only: obtain the hostname specified by the client in the ServerName extension (SNI)
719 SSLCopyRequestedPeerNameLength (SSLContextRef ctx
,
721 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
725 * Specify the Datagram TLS Hello Cookie.
726 * This is to be called for server side only and is optional.
727 * The default is a zero len cookie. The maximum cookieLen is 32 bytes.
730 SSLSetDatagramHelloCookie (SSLContextRef dtlsContext
,
731 const void * __nullable cookie
,
733 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
736 * Specify the maximum record size, including all DTLS record headers.
737 * This should be set appropriately to avoid fragmentation
738 * of Datagrams during handshake, as fragmented datagrams may
739 * be dropped by some network.
740 * This is for Datagram TLS only
743 SSLSetMaxDatagramRecordSize (SSLContextRef dtlsContext
,
745 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
748 * Get the maximum record size, including all Datagram TLS record headers.
749 * This is for Datagram TLS only
752 SSLGetMaxDatagramRecordSize (SSLContextRef dtlsContext
,
754 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
757 * Obtain the actual negotiated protocol version of the active
758 * session, which may be different that the value specified in
759 * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no
760 * SSL session is in progress.
763 SSLGetNegotiatedProtocolVersion (SSLContextRef context
,
764 SSLProtocol
*protocol
) /* RETURNED */
765 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
768 * Determine number and values of all of the SSLCipherSuites we support.
769 * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in
770 * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
774 SSLGetNumberSupportedCiphers (SSLContextRef context
,
776 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
779 SSLGetSupportedCiphers (SSLContextRef context
,
780 SSLCipherSuite
*ciphers
, /* RETURNED */
781 size_t *numCiphers
) /* IN/OUT */
782 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
785 * Specify a (typically) restricted set of SSLCipherSuites to be enabled by
786 * the current SSLContext. Can only be called when no session is active. Default
787 * set of enabled SSLCipherSuites is the same as the complete set of supported
788 * SSLCipherSuites as obtained by SSLGetSupportedCiphers().
791 SSLSetEnabledCiphers (SSLContextRef context
,
792 const SSLCipherSuite
*ciphers
,
794 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
797 * Determine number and values of all of the SSLCipherSuites currently enabled.
798 * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in
799 * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
803 SSLGetNumberEnabledCiphers (SSLContextRef context
,
805 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
808 SSLGetEnabledCiphers (SSLContextRef context
,
809 SSLCipherSuite
*ciphers
, /* RETURNED */
810 size_t *numCiphers
) /* IN/OUT */
811 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
814 * Forcibly enable or disable session ticket resumption. By default, session tickets
818 SSLSetSessionTicketsEnabled (SSLContextRef context
,
820 __OSX_AVAILABLE_STARTING(__MAC_10_13
, __IPHONE_11_0
);
823 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
825 * Enable/disable peer certificate chain validation. Default is enabled.
826 * If caller disables, it is the caller's responsibility to call
827 * SSLCopyPeerCertificates() upon successful completion of the handshake
828 * and then to perform external validation of the peer certificate
829 * chain before proceeding with data transfer.
831 * ==========================
832 * MAC OS X ONLY (DEPRECATED)
833 * ==========================
834 * NOTE: this function is not available on iOS, and should be considered
835 * deprecated on Mac OS X. To disable peer certificate chain validation, you
836 * can instead use SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth
837 * to true. This will disable verification and cause SSLHandshake to return with
838 * an errSSLServerAuthCompleted result when the peer certificates have been
839 * received; at that time, you can choose to evaluate peer trust yourself, or
840 * simply call SSLHandshake again to proceed with the handshake.
843 SSLSetEnableCertVerify (SSLContextRef context
,
844 Boolean enableVerify
)
845 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
848 * Check whether peer certificate chain validation is enabled.
850 * ==========================
851 * MAC OS X ONLY (DEPRECATED)
852 * ==========================
853 * NOTE: this function is not available on iOS, and should be considered
854 * deprecated on Mac OS X. To check whether peer certificate chain validation
855 * is enabled in a context, call SSLGetSessionOption to obtain the value of
856 * the kSSLSessionOptionBreakOnServerAuth session option flag. If the value
857 * of this option flag is true, then verification is disabled.
860 SSLGetEnableCertVerify (SSLContextRef context
,
861 Boolean
*enableVerify
) /* RETURNED */
862 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
865 * Specify the option of ignoring certificates' "expired" times.
866 * This is a common failure in the real SSL world. Default setting for this
867 * flag is false, meaning expired certs result in an errSSLCertExpired error.
869 * ==========================
870 * MAC OS X ONLY (DEPRECATED)
871 * ==========================
872 * NOTE: this function is not available on iOS, and should be considered
873 * deprecated on Mac OS X. To ignore expired certificate errors, first disable
874 * Secure Transport's automatic verification of peer certificates by calling
875 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
876 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
877 * your code should obtain the SecTrustRef for the peer's certificates and
878 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
879 * The SecTrustSetOptions function allows you to specify that the expiration
880 * status of certificates should be ignored for this evaluation.
884 * status = SSLSetSessionOption(ctx, kSSLSessionOptionBreakOnServerAuth, true);
886 * status = SSLHandshake(ctx);
888 * if (status == errSSLServerAuthCompleted) {
889 * SecTrustRef peerTrust = NULL;
890 * status = SSLCopyPeerTrust(ctx, &peerTrust);
891 * if (status == errSecSuccess) {
892 * SecTrustResultType trustResult;
893 * // set flag to allow expired certificates
894 * SecTrustSetOptions(peerTrust, kSecTrustOptionAllowExpired);
895 * status = SecTrustEvaluate(peerTrust, &trustResult);
896 * if (status == errSecSuccess) {
897 * // A "proceed" result means the cert is explicitly trusted,
898 * // e.g. "Always Trust" was clicked;
899 * // "Unspecified" means the cert has no explicit trust settings,
900 * // but is implicitly OK since it chains back to a trusted root.
901 * // Any other result means the cert is not trusted.
903 * if (trustResult == kSecTrustResultProceed ||
904 * trustResult == kSecTrustResultUnspecified) {
905 * // certificate is trusted
906 * status = errSSLWouldBlock; // so we call SSLHandshake again
907 * } else if (trustResult == kSecTrustResultRecoverableTrustFailure) {
908 * // not trusted, for some reason other than being expired;
909 * // could ask the user whether to allow the connection here
911 * status = errSSLXCertChainInvalid;
913 * // cannot use this certificate (fatal)
914 * status = errSSLBadCert;
918 * CFRelease(peerTrust);
921 * } // errSSLServerAuthCompleted
923 * } while (status == errSSLWouldBlock);
927 SSLSetAllowsExpiredCerts (SSLContextRef context
,
928 Boolean allowsExpired
)
929 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
932 * Obtain the current value of an SSLContext's "allowExpiredCerts" flag.
934 * ==========================
935 * MAC OS X ONLY (DEPRECATED)
936 * ==========================
937 * NOTE: this function is not available on iOS, and should be considered
938 * deprecated on Mac OS X.
941 SSLGetAllowsExpiredCerts (SSLContextRef context
,
942 Boolean
*allowsExpired
) /* RETURNED */
943 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
946 * Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the
947 * option of ignoring "expired" status for root certificates only.
948 * Default setting is false, i.e., expired root certs result in an
949 * errSSLCertExpired error.
951 * ==========================
952 * MAC OS X ONLY (DEPRECATED)
953 * ==========================
954 * NOTE: this function is not available on iOS, and should be considered
955 * deprecated on Mac OS X. To ignore expired certificate errors, first disable
956 * Secure Transport's automatic verification of peer certificates by calling
957 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
958 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
959 * your code should obtain the SecTrustRef for the peer's certificates and
960 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
961 * The SecTrustSetOptions function allows you to specify that the expiration
962 * status of certificates should be ignored for this evaluation.
964 * See the description of the SSLSetAllowsExpiredCerts function (above)
965 * for a code example. The kSecTrustOptionAllowExpiredRoot option can be used
966 * instead of kSecTrustOptionAllowExpired to allow expired roots only.
969 SSLSetAllowsExpiredRoots (SSLContextRef context
,
970 Boolean allowsExpired
)
971 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
974 * Obtain the current value of an SSLContext's "allow expired roots" flag.
976 * ==========================
977 * MAC OS X ONLY (DEPRECATED)
978 * ==========================
979 * NOTE: this function is not available on iOS, and should be considered
980 * deprecated on Mac OS X.
983 SSLGetAllowsExpiredRoots (SSLContextRef context
,
984 Boolean
*allowsExpired
) /* RETURNED */
985 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
988 * Specify option of allowing for an unknown root cert, i.e., one which
989 * this software can not verify as one of a list of known good root certs.
990 * Default for this flag is false, in which case one of the following two
992 * -- The peer returns a cert chain with a root cert, and the chain
993 * verifies to that root, but the root is not one of our trusted
994 * roots. This results in errSSLUnknownRootCert on handshake.
995 * -- The peer returns a cert chain which does not contain a root cert,
996 * and we can't verify the chain to one of our trusted roots. This
997 * results in errSSLNoRootCert on handshake.
999 * Both of these error conditions are ignored when the AllowAnyRoot flag is
1000 * true, allowing connection to a totally untrusted peer.
1002 * ==========================
1003 * MAC OS X ONLY (DEPRECATED)
1004 * ==========================
1005 * NOTE: this function is not available on iOS, and should be considered
1006 * deprecated on Mac OS X. To ignore unknown root cert errors, first disable
1007 * Secure Transport's automatic verification of peer certificates by calling
1008 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
1009 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
1010 * your code should obtain the SecTrustRef for the peer's certificates and
1011 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
1013 * See the description of the SSLSetAllowsExpiredCerts function (above)
1014 * for a code example. Note that an unknown root certificate will cause
1015 * SecTrustEvaluate to report kSecTrustResultRecoverableTrustFailure as the
1019 SSLSetAllowsAnyRoot (SSLContextRef context
,
1021 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1024 * Obtain the current value of an SSLContext's "allow any root" flag.
1026 * ==========================
1027 * MAC OS X ONLY (DEPRECATED)
1028 * ==========================
1029 * NOTE: this function is not available on iOS, and should be considered
1030 * deprecated on Mac OS X.
1033 SSLGetAllowsAnyRoot (SSLContextRef context
,
1034 Boolean
*anyRoot
) /* RETURNED */
1035 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1038 * Augment or replace the system's default trusted root certificate set
1039 * for this session. If replaceExisting is true, the specified roots will
1040 * be the only roots which are trusted during this session. If replaceExisting
1041 * is false, the specified roots will be added to the current set of trusted
1042 * root certs. If this function has never been called, the current trusted
1043 * root set is the same as the system's default trusted root set.
1044 * Successive calls with replaceExisting false result in accumulation
1045 * of additional root certs.
1047 * The trustedRoots array contains SecCertificateRefs.
1049 * ==========================
1050 * MAC OS X ONLY (DEPRECATED)
1051 * ==========================
1052 * NOTE: this function is not available on iOS, and should be considered
1053 * deprecated on Mac OS X. To trust specific roots in a session, first disable
1054 * Secure Transport's automatic verification of peer certificates by calling
1055 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
1056 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
1057 * your code should obtain the SecTrustRef for the peer's certificates and
1058 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
1060 * See the description of the SSLSetAllowsExpiredCerts function (above)
1061 * for a code example. You can call SecTrustSetAnchorCertificates to
1062 * augment the system's trusted root set, or SecTrustSetAnchorCertificatesOnly
1063 * to make these the only trusted roots, prior to calling SecTrustEvaluate.
1066 SSLSetTrustedRoots (SSLContextRef context
,
1067 CFArrayRef trustedRoots
,
1068 Boolean replaceExisting
)
1069 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1072 * Obtain an array of SecCertificateRefs representing the current
1073 * set of trusted roots. If SSLSetTrustedRoots() has never been called
1074 * for this session, this returns the system's default root set.
1076 * Caller must CFRelease the returned CFArray.
1078 * ==========================
1079 * MAC OS X ONLY (DEPRECATED)
1080 * ==========================
1081 * NOTE: this function is not available on iOS, and should be considered
1082 * deprecated on Mac OS X. To get the current set of trusted roots, call the
1083 * SSLCopyPeerTrust function to obtain the SecTrustRef for the peer certificate
1084 * chain, then SecTrustCopyCustomAnchorCertificates (see SecTrust.h).
1087 SSLCopyTrustedRoots (SSLContextRef context
,
1088 CFArrayRef
* __nonnull CF_RETURNS_RETAINED trustedRoots
) /* RETURNED */
1089 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1092 * Request peer certificates. Valid anytime, subsequent to a handshake attempt.
1094 * The certs argument is a CFArray containing SecCertificateRefs.
1095 * Caller must CFRelease the returned array.
1097 * The cert at index 0 of the returned array is the subject (end
1098 * entity) cert; the root cert (or the closest cert to it) is at
1099 * the end of the returned array.
1101 * ==========================
1102 * MAC OS X ONLY (DEPRECATED)
1103 * ==========================
1104 * NOTE: this function is not available on iOS, and should be considered
1105 * deprecated on Mac OS X. To get peer certificates, call SSLCopyPeerTrust
1106 * to obtain the SecTrustRef for the peer certificate chain, then use the
1107 * SecTrustGetCertificateCount and SecTrustGetCertificateAtIndex functions
1108 * to retrieve individual certificates in the chain (see SecTrust.h).
1111 SSLCopyPeerCertificates (SSLContextRef context
,
1112 CFArrayRef
* __nonnull CF_RETURNS_RETAINED certs
) /* RETURNED */
1113 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1115 #endif /* MAC OS X */
1118 * Obtain a SecTrustRef representing peer certificates. Valid anytime,
1119 * subsequent to a handshake attempt. Caller must CFRelease the returned
1122 * The returned trust reference will have already been evaluated for you,
1123 * unless one of the following is true:
1124 * - Your code has disabled automatic certificate verification, by calling
1125 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true.
1126 * - Your code has called SSLSetPeerID, and this session has been resumed
1127 * from an earlier cached session.
1129 * In these cases, your code should call SecTrustEvaluate prior to
1130 * examining the peer certificate chain or trust results (see SecTrust.h).
1132 * NOTE: if you have not called SSLHandshake at least once prior to
1133 * calling this function, the returned trust reference will be NULL.
1136 SSLCopyPeerTrust (SSLContextRef context
,
1137 SecTrustRef
* __nonnull CF_RETURNS_RETAINED trust
) /* RETURNED */
1138 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_5_0
);
1141 * Specify some data, opaque to this library, which is sufficient
1142 * to uniquely identify the peer of the current session. An example
1143 * would be IP address and port, stored in some caller-private manner.
1144 * To be optionally called prior to SSLHandshake for the current
1145 * session. This is mandatory if this session is to be resumable.
1147 * SecureTransport allocates its own copy of the incoming peerID. The
1148 * data provided in *peerID, while opaque to SecureTransport, is used
1149 * in a byte-for-byte compare to other previous peerID values set by the
1150 * current application. Matching peerID blobs result in SecureTransport
1151 * attempting to resume an SSL session with the same parameters as used
1152 * in the previous session which specified the same peerID bytes.
1155 SSLSetPeerID (SSLContextRef context
,
1156 const void * __nullable peerID
,
1158 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1161 * Obtain current PeerID. Returns NULL pointer, zero length if
1162 * SSLSetPeerID has not been called for this context.
1165 SSLGetPeerID (SSLContextRef context
,
1166 const void * __nullable
* __nonnull peerID
,
1168 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1171 * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated
1172 * for this session. Only valid when a session is active.
1175 SSLGetNegotiatedCipher (SSLContextRef context
,
1176 SSLCipherSuite
*cipherSuite
)
1177 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1180 * Set the ALPN protocols to be passed in the ALPN negotiation.
1181 * This is the list of supported application-layer protocols supported.
1183 * The protocols parameter must be an array of CFStringRef values
1184 * with ASCII-encoded reprensetations of the supported protocols, e.g., "http/1.1".
1186 * See RFC 7301 for more information.
1189 SSLSetALPNProtocols (SSLContextRef context
,
1190 CFArrayRef protocols
)
1191 __OSX_AVAILABLE_STARTING(__MAC_10_13
, __IPHONE_11_0
);
1194 * Get the ALPN protocols associated with this SSL context.
1195 * This is the list of supported application-layer protocols supported.
1197 * The resultant protocols array will contain CFStringRef values containing
1198 * ASCII-encoded representations of the supported protocols, e.g., "http/1.1".
1200 * See RFC 7301 for more information.
1202 * Note: The `protocols` pointer must be NULL, otherwise the copy will fail.
1203 * This function will allocate memory for the CFArrayRef container
1204 * if there is data to provide. Otherwise, the pointer will remain NULL.
1207 SSLCopyALPNProtocols (SSLContextRef context
,
1208 CFArrayRef __nullable
* __nonnull protocols
) /* RETURNED */
1209 __OSX_AVAILABLE_STARTING(__MAC_10_13
, __IPHONE_11_0
);
1212 * Set the OCSP response for the given SSL session.
1214 * The response parameter must be a non-NULL CFDataRef containing the
1215 * bytes of the OCSP response.
1218 SSLSetOCSPResponse (SSLContextRef context
,
1219 CFDataRef __nonnull response
)
1220 __OSX_AVAILABLE_STARTING(__MAC_10_13
, __IPHONE_11_0
);
1222 /********************************************************
1223 *** Session context configuration, server side only. ***
1224 ********************************************************/
1227 * This function is deprecated in OSX 10.11 and iOS 9.0 and
1228 * has no effect on the TLS handshake since OSX 10.10 and
1229 * iOS 8.0. Using separate RSA certificates for encryption
1230 * and signing is no longer supported.
1233 SSLSetEncryptionCertificate (SSLContextRef context
,
1234 CFArrayRef certRefs
)
1235 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
, __MAC_10_11
, __IPHONE_5_0
, __IPHONE_9_0
);
1238 * Specify requirements for client-side authentication.
1239 * Optional; Default is kNeverAuthenticate.
1241 * Can only be called when no session is active.
1243 typedef CF_ENUM(int, SSLAuthenticate
) {
1244 kNeverAuthenticate
, /* skip client authentication */
1245 kAlwaysAuthenticate
, /* require it */
1246 kTryAuthenticate
/* try to authenticate, but not an error
1247 * if client doesn't have a cert */
1251 SSLSetClientSideAuthenticate (SSLContextRef context
,
1252 SSLAuthenticate auth
)
1253 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1256 * Add a DER-encoded distinguished name to list of acceptable names
1257 * to be specified in requests for client certificates.
1260 SSLAddDistinguishedName (SSLContextRef context
,
1261 const void * __nullable derDN
,
1263 __OSX_AVAILABLE_STARTING(__MAC_10_4
, __IPHONE_5_0
);
1266 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
1268 * Add a SecCertificateRef, or a CFArray of them, to a server's list
1269 * of acceptable Certificate Authorities (CAs) to present to the client
1270 * when client authentication is performed.
1272 * If replaceExisting is true, the specified certificate(s) will replace
1273 * a possible existing list of acceptable CAs. If replaceExisting is
1274 * false, the specified certificate(s) will be appended to the existing
1275 * list of acceptable CAs, if any.
1277 * Returns errSecParam if this is called on a SSLContextRef which
1278 * is configured as a client, or when a session is active.
1280 * NOTE: this function is currently not available on iOS.
1283 SSLSetCertificateAuthorities(SSLContextRef context
,
1284 CFTypeRef certificateOrArray
,
1285 Boolean replaceExisting
)
1286 __OSX_AVAILABLE_STARTING(__MAC_10_5
, __IPHONE_NA
);
1289 * Obtain the certificates specified in SSLSetCertificateAuthorities(),
1290 * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not
1292 * Caller must CFRelease the returned array.
1294 * NOTE: this function is currently not available on iOS.
1297 SSLCopyCertificateAuthorities(SSLContextRef context
,
1298 CFArrayRef
* __nonnull CF_RETURNS_RETAINED certificates
) /* RETURNED */
1299 __OSX_AVAILABLE_STARTING(__MAC_10_5
, __IPHONE_NA
);
1301 #endif /* MAC OS X */
1304 * Obtain the list of acceptable distinguished names as provided by
1305 * a server (if the SSLContextRef is configured as a client), or as
1306 * specified by SSLSetCertificateAuthorities (if the SSLContextRef
1307 * is configured as a server).
1308 * The returned array contains CFDataRefs, each of which represents
1309 * one DER-encoded RDN.
1311 * Caller must CFRelease the returned array.
1314 SSLCopyDistinguishedNames (SSLContextRef context
,
1315 CFArrayRef
* __nonnull CF_RETURNS_RETAINED names
)
1316 __OSX_AVAILABLE_STARTING(__MAC_10_5
, __IPHONE_5_0
);
1319 * Obtain client certificate exchange status. Can be called
1320 * any time. Reflects the *last* client certificate state change;
1321 * subsequent to a renegotiation attempt by either peer, the state
1322 * is reset to kSSLClientCertNone.
1325 SSLGetClientCertificateState (SSLContextRef context
,
1326 SSLClientCertificateState
*clientState
)
1327 __OSX_AVAILABLE_STARTING(__MAC_10_3
, __IPHONE_5_0
);
1330 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
1332 * Specify Diffie-Hellman parameters. Optional; if we are configured to allow
1333 * for D-H ciphers and a D-H cipher is negotiated, and this function has not
1334 * been called, a set of process-wide parameters will be calculated. However
1335 * that can take a long time (30 seconds).
1337 * NOTE: this function is currently not available on iOS.
1339 OSStatus
SSLSetDiffieHellmanParams (SSLContextRef context
,
1340 const void * __nullable dhParams
,
1342 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_NA
);
1345 * Return parameter block specified in SSLSetDiffieHellmanParams.
1346 * Returned data is not copied and belongs to the SSLContextRef.
1348 * NOTE: this function is currently not available on iOS.
1350 OSStatus
SSLGetDiffieHellmanParams (SSLContextRef context
,
1351 const void * __nullable
* __nonnull dhParams
,
1352 size_t *dhParamsLen
)
1353 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_NA
);
1356 * Enable/Disable RSA blinding. This feature thwarts a known timing
1357 * attack to which RSA keys are vulnerable; enabling it is a tradeoff
1358 * between performance and security. The default for RSA blinding is
1361 * ==========================
1362 * MAC OS X ONLY (DEPRECATED)
1363 * ==========================
1364 * NOTE: this function is not available on iOS, and should be considered
1365 * deprecated on Mac OS X. RSA blinding is enabled unconditionally, as
1366 * it prevents a known way for an attacker to recover the private key,
1367 * and the performance gain of disabling it is negligible.
1369 OSStatus
SSLSetRsaBlinding (SSLContextRef context
,
1371 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1373 OSStatus
SSLGetRsaBlinding (SSLContextRef context
,
1375 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1377 #endif /* MAC OS X */
1379 /*******************************
1380 ******** I/O Functions ********
1381 *******************************/
1384 * Note: depending on the configuration of the underlying I/O
1385 * connection, all SSL I/O functions can return errSSLWouldBlock,
1386 * indicating "not complete, nothing is wrong, except required
1387 * I/O hasn't completed". Caller may need to repeat I/Os as necessary
1388 * if the underlying connection has been configured to behave in
1389 * a non-blocking manner.
1393 * Perform the SSL handshake. On successful return, session is
1394 * ready for normal secure application I/O via SSLWrite and SSLRead.
1396 * Interesting error returns:
1398 * errSSLUnknownRootCert: Peer had a valid cert chain, but the root of
1399 * the chain is unknown.
1401 * errSSLNoRootCert: Peer had a cert chain which did not end in a root.
1403 * errSSLCertExpired: Peer's cert chain had one or more expired certs.
1405 * errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e.,
1406 * signature verification within the chain failed, or no certs
1409 * In all of the above errors, the handshake was aborted; the peer's
1410 * cert chain is available via SSLCopyPeerTrust or SSLCopyPeerCertificates.
1412 * Other interesting result codes:
1414 * errSSLPeerAuthCompleted: Peer's cert chain is valid, or was ignored if
1415 * cert verification was disabled via SSLSetEnableCertVerify. The application
1416 * may decide to continue with the handshake (by calling SSLHandshake
1417 * again), or close the connection at this point.
1419 * errSSLClientCertRequested: The server has requested a client certificate.
1420 * The client may choose to examine the server's certificate and
1421 * distinguished name list, then optionally call SSLSetCertificate prior
1422 * to resuming the handshake by calling SSLHandshake again.
1424 * A return value of errSSLWouldBlock indicates that SSLHandshake has to be
1425 * called again (and again and again until something else is returned).
1428 SSLHandshake (SSLContextRef context
)
1429 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1432 * Server Only: Request renegotation.
1433 * This will return an error if the server is already renegotiating, or if the session is closed.
1434 * After this return without error, the application should call SSLHandshake() and/or SSLRead() as
1435 * for the original handshake.
1438 SSLReHandshake (SSLContextRef context
)
1439 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_10_0
);
1443 * Normal application-level read/write. On both of these, a errSSLWouldBlock
1444 * return and a partially completed transfer - or even zero bytes transferred -
1445 * are NOT mutually exclusive.
1448 SSLWrite (SSLContextRef context
,
1449 const void * __nullable data
,
1451 size_t *processed
) /* RETURNED */
1452 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1455 * data is mallocd by caller; available size specified in
1456 * dataLength; actual number of bytes read returned in
1460 SSLRead (SSLContextRef context
,
1461 void * data
, /* RETURNED */
1463 size_t *processed
) /* RETURNED */
1464 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1467 * Determine how much data the client can be guaranteed to
1468 * obtain via SSLRead() without blocking or causing any low-level
1469 * read operations to occur.
1472 SSLGetBufferedReadSize (SSLContextRef context
,
1473 size_t *bufSize
) /* RETURNED */
1474 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1477 * Determine how much data the application can be guaranteed to write
1478 * with SSLWrite() without causing fragmentation. The value is based on
1479 * the maximum Datagram Record size defined by the application with
1480 * SSLSetMaxDatagramRecordSize(), minus the DTLS Record header size.
1483 SSLGetDatagramWriteSize (SSLContextRef dtlsContext
,
1485 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
1488 * Terminate current SSL session.
1491 SSLClose (SSLContextRef context
)
1492 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1495 * Set the status of a SSLContextRef. This is to be done after handling
1496 * steps of the SSL handshake such as server certificate validation.
1499 SSLSetError (SSLContextRef context
,
1501 __OSX_AVAILABLE_STARTING(__MAC_10_13
, __IPHONE_11_0
);
1503 CF_IMPLICIT_BRIDGING_DISABLED
1504 CF_ASSUME_NONNULL_END
1510 #endif /* !_SECURITY_SECURETRANSPORT_H_ */