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 */
94 /* DEPRECATED on iOS */
95 kSSLProtocol2
= 1, /* SSL 2.0 */
96 kSSLProtocol3Only
= 3, /* SSL 3.0 Only */
97 kTLSProtocol1Only
= 5, /* TLS 1.0 Only */
98 kSSLProtocolAll
= 6, /* All TLS supported protocols */
102 /* SSL session options */
103 typedef CF_ENUM(int, SSLSessionOption
) {
105 * Set this option to enable returning from SSLHandshake (with a result of
106 * errSSLServerAuthCompleted) when the server authentication portion of the
107 * handshake is complete. This disable certificate verification and
108 * provides an opportunity to perform application-specific server
109 * verification before deciding to continue.
111 kSSLSessionOptionBreakOnServerAuth
= 0,
113 * Set this option to enable returning from SSLHandshake (with a result of
114 * errSSLClientCertRequested) when the server requests a client certificate.
116 kSSLSessionOptionBreakOnCertRequested
= 1,
118 * This option is the same as kSSLSessionOptionBreakOnServerAuth but applies
119 * to the case where SecureTransport is the server and the client has presented
120 * its certificates allowing the server to verify whether these should be
121 * allowed to authenticate.
123 kSSLSessionOptionBreakOnClientAuth
= 2,
125 * Enable/Disable TLS False Start
126 * When enabled, False Start will only be performed if a adequate cipher-suite is
129 kSSLSessionOptionFalseStart
= 3,
131 * Enable/Disable 1/n-1 record splitting for BEAST attack mitigation.
132 * When enabled, record splitting will only be performed for TLS 1.0 connections
133 * using a block cipher.
135 kSSLSessionOptionSendOneByteRecord
= 4,
137 * Allow/Disallow server identity change on renegotiation. Disallow by default
138 * to avoid Triple Handshake attack.
140 kSSLSessionOptionAllowServerIdentityChange
= 5,
142 * Enable fallback countermeasures. Use this option when retyring a SSL connection
143 * with a lower protocol version because of failure to connect.
145 kSSLSessionOptionFallback
= 6,
147 * Set this option to break from a client hello in order to check for SNI
149 kSSLSessionOptionBreakOnClientHello
= 7,
151 * Set this option to Allow renegotations. False by default.
153 kSSLSessionOptionAllowRenegotiation
= 8,
157 /* State of an SSLSession */
158 typedef CF_ENUM(int, SSLSessionState
) {
159 kSSLIdle
, /* no I/O performed yet */
160 kSSLHandshake
, /* SSL handshake in progress */
161 kSSLConnected
, /* Handshake complete, ready for normal I/O */
162 kSSLClosed
, /* connection closed normally */
163 kSSLAborted
/* connection aborted */
167 * Status of client certificate exchange (which is optional
168 * for both server and client).
170 typedef CF_ENUM(int, SSLClientCertificateState
) {
171 /* Server hasn't asked for a cert. Client hasn't sent one. */
173 /* Server has asked for a cert, but client didn't send it. */
174 kSSLClientCertRequested
,
176 * Server side: We asked for a cert, client sent one, we validated
177 * it OK. App can inspect the cert via
178 * SSLCopyPeerCertificates().
179 * Client side: server asked for one, we sent it.
183 * Client sent a cert but failed validation. Server side only.
184 * Server app can inspect the cert via SSLCopyPeerCertificates().
186 kSSLClientCertRejected
190 * R/W functions. The application using this library provides
191 * these functions via SSLSetIOFuncs().
193 * Data's memory is allocated by caller; on entry to these two functions
194 * the *length argument indicates both the size of the available data and the
195 * requested byte count. Number of bytes actually transferred is returned in
198 * The application may configure the underlying connection to operate
199 * in a non-blocking manner; in such a case, a read operation may
200 * well return errSSLWouldBlock, indicating "I transferred less data than
201 * you requested (maybe even zero bytes), nothing is wrong, except
202 * requested I/O hasn't completed". This will be returned back up to
203 * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(),
207 (*SSLReadFunc
) (SSLConnectionRef connection
,
208 void *data
, /* owned by
211 size_t *dataLength
); /* IN/OUT */
213 (*SSLWriteFunc
) (SSLConnectionRef connection
,
215 size_t *dataLength
); /* IN/OUT */
217 /*************************************************
218 *** OSStatus values unique to SecureTransport ***
219 *************************************************/
222 Note: the comments that appear after these errors are used to create SecErrorMessages.strings.
223 The comments must not be multi-line, and should be in a form meaningful to an end user. If
224 a different or additional comment is needed, it can be put in the header doc format, or on a
225 line that does not start with errZZZ.
229 errSSLProtocol
= -9800, /* SSL protocol error */
230 errSSLNegotiation
= -9801, /* Cipher Suite negotiation failure */
231 errSSLFatalAlert
= -9802, /* Fatal alert */
232 errSSLWouldBlock
= -9803, /* I/O would block (not fatal) */
233 errSSLSessionNotFound
= -9804, /* attempt to restore an unknown session */
234 errSSLClosedGraceful
= -9805, /* connection closed gracefully */
235 errSSLClosedAbort
= -9806, /* connection closed via error */
236 errSSLXCertChainInvalid
= -9807, /* invalid certificate chain */
237 errSSLBadCert
= -9808, /* bad certificate format */
238 errSSLCrypto
= -9809, /* underlying cryptographic error */
239 errSSLInternal
= -9810, /* Internal error */
240 errSSLModuleAttach
= -9811, /* module attach failure */
241 errSSLUnknownRootCert
= -9812, /* valid cert chain, untrusted root */
242 errSSLNoRootCert
= -9813, /* cert chain not verified by root */
243 errSSLCertExpired
= -9814, /* chain had an expired cert */
244 errSSLCertNotYetValid
= -9815, /* chain had a cert not yet valid */
245 errSSLClosedNoNotify
= -9816, /* server closed session with no notification */
246 errSSLBufferOverflow
= -9817, /* insufficient buffer provided */
247 errSSLBadCipherSuite
= -9818, /* bad SSLCipherSuite */
249 /* fatal errors detected by peer */
250 errSSLPeerUnexpectedMsg
= -9819, /* unexpected message received */
251 errSSLPeerBadRecordMac
= -9820, /* bad MAC */
252 errSSLPeerDecryptionFail
= -9821, /* decryption failed */
253 errSSLPeerRecordOverflow
= -9822, /* record overflow */
254 errSSLPeerDecompressFail
= -9823, /* decompression failure */
255 errSSLPeerHandshakeFail
= -9824, /* handshake failure */
256 errSSLPeerBadCert
= -9825, /* misc. bad certificate */
257 errSSLPeerUnsupportedCert
= -9826, /* bad unsupported cert format */
258 errSSLPeerCertRevoked
= -9827, /* certificate revoked */
259 errSSLPeerCertExpired
= -9828, /* certificate expired */
260 errSSLPeerCertUnknown
= -9829, /* unknown certificate */
261 errSSLIllegalParam
= -9830, /* illegal parameter */
262 errSSLPeerUnknownCA
= -9831, /* unknown Cert Authority */
263 errSSLPeerAccessDenied
= -9832, /* access denied */
264 errSSLPeerDecodeError
= -9833, /* decoding error */
265 errSSLPeerDecryptError
= -9834, /* decryption error */
266 errSSLPeerExportRestriction
= -9835, /* export restriction */
267 errSSLPeerProtocolVersion
= -9836, /* bad protocol version */
268 errSSLPeerInsufficientSecurity
= -9837, /* insufficient security */
269 errSSLPeerInternalError
= -9838, /* internal error */
270 errSSLPeerUserCancelled
= -9839, /* user canceled */
271 errSSLPeerNoRenegotiation
= -9840, /* no renegotiation allowed */
273 /* non-fatal result codes */
274 errSSLPeerAuthCompleted
= -9841, /* peer cert is valid, or was ignored if verification disabled */
275 errSSLClientCertRequested
= -9842, /* server has requested a client cert */
277 /* more errors detected by us */
278 errSSLHostNameMismatch
= -9843, /* peer host name mismatch */
279 errSSLConnectionRefused
= -9844, /* peer dropped connection before responding */
280 errSSLDecryptionFail
= -9845, /* decryption failure */
281 errSSLBadRecordMac
= -9846, /* bad MAC */
282 errSSLRecordOverflow
= -9847, /* record overflow */
283 errSSLBadConfiguration
= -9848, /* configuration error */
284 errSSLUnexpectedRecord
= -9849, /* unexpected (skipped) record in DTLS */
285 errSSLWeakPeerEphemeralDHKey
= -9850, /* weak ephemeral dh key */
287 /* non-fatal result codes */
288 errSSLClientHelloReceived
= -9851, /* SNI */
291 /* DEPRECATED aliases for errSSLPeerAuthCompleted */
292 #define errSSLServerAuthCompleted errSSLPeerAuthCompleted
293 #define errSSLClientAuthCompleted errSSLPeerAuthCompleted
295 /* DEPRECATED alias for the end of the error range */
296 #define errSSLLast errSSLUnexpectedRecord
298 typedef CF_ENUM(int, SSLProtocolSide
)
304 typedef CF_ENUM(int, SSLConnectionType
)
311 * Predefined TLS configurations constants
314 /* Default configuration - currently same as kSSLSessionConfig_standard */
315 extern const CFStringRef kSSLSessionConfig_default
;
316 /* ATS v1 Config: TLS v1.2, only PFS ciphersuites */
317 extern const CFStringRef kSSLSessionConfig_ATSv1
;
318 /* ATS v1 Config without PFS: TLS v1.2, include non PFS ciphersuites */
319 extern const CFStringRef kSSLSessionConfig_ATSv1_noPFS
;
320 /* TLS v1.2 to TLS v1.0, with default ciphersuites (no RC4) */
321 extern const CFStringRef kSSLSessionConfig_standard
;
322 /* TLS v1.2 to TLS v1.0, with defaults ciphersuites + RC4 */
323 extern const CFStringRef kSSLSessionConfig_RC4_fallback
;
324 /* TLS v1.0 only, with defaults ciphersuites + fallback SCSV */
325 extern const CFStringRef kSSLSessionConfig_TLSv1_fallback
;
326 /* TLS v1.0, with defaults ciphersuites + RC4 + fallback SCSV */
327 extern const CFStringRef kSSLSessionConfig_TLSv1_RC4_fallback
;
328 /* TLS v1.2 to TLS v1.0, defaults + RC4 + DHE ciphersuites */
329 extern const CFStringRef kSSLSessionConfig_legacy
;
330 /* TLS v1.2 to TLS v1.0, defaults + RC4 + DHE ciphersuites */
331 extern const CFStringRef kSSLSessionConfig_legacy_DHE
;
332 /* TLS v1.2, anonymous ciphersuites only */
333 extern const CFStringRef kSSLSessionConfig_anonymous
;
341 * Secure Transport APIs require a SSLContextRef, which is an opaque
342 * reference to the SSL session and its parameters. On Mac OS X 10.7
343 * and earlier versions, a new context is created using SSLNewContext,
344 * and is disposed by calling SSLDisposeContext.
346 * On i0S 5.0 and later, as well as Mac OS X versions after 10.7, the
347 * SSLContextRef is a true CFType object with retain-release semantics.
348 * New code should create a new context using SSLCreateContext (instead
349 * of SSLNewContext), and dispose the context by calling CFRelease
350 * (instead of SSLDisposeContext) when finished with it.
354 * Return the CFTypeID for SSLContext objects.
357 SSLContextGetTypeID(void)
358 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
361 * Create a new instance of an SSLContextRef using the specified allocator.
365 SSLCreateContext(CFAllocatorRef __nullable alloc
, SSLProtocolSide protocolSide
, SSLConnectionType connectionType
)
366 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
369 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
371 * Create a new session context.
373 * ==========================
374 * MAC OS X ONLY (DEPRECATED)
375 * ==========================
376 * NOTE: this function is not available on iOS, and should be considered
377 * deprecated on Mac OS X. Your code should use SSLCreateContext instead.
380 SSLNewContext (Boolean isServer
,
381 SSLContextRef
* __nonnull CF_RETURNS_RETAINED contextPtr
) /* RETURNED */
382 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
385 * Dispose of a session context.
387 * ==========================
388 * MAC OS X ONLY (DEPRECATED)
389 * ==========================
390 * NOTE: this function is not available on iOS, and should be considered
391 * deprecated on Mac OS X. Your code should use CFRelease to dispose a session
392 * created with SSLCreateContext.
395 SSLDisposeContext (SSLContextRef context
)
396 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
398 #endif /* MAC OS X */
401 * Determine the state of an SSL/DTLS session.
404 SSLGetSessionState (SSLContextRef context
,
405 SSLSessionState
*state
) /* RETURNED */
406 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
409 * Set options for an SSL session. Must be called prior to SSLHandshake();
410 * subsequently cannot be called while session is active.
413 SSLSetSessionOption (SSLContextRef context
,
414 SSLSessionOption option
,
416 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_5_0
);
419 * Determine current value for the specified option in a given SSL session.
422 SSLGetSessionOption (SSLContextRef context
,
423 SSLSessionOption option
,
425 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_5_0
);
427 /********************************************************************
428 *** Session context configuration, common to client and servers. ***
429 ********************************************************************/
432 * Specify functions which do the network I/O. Must be called prior
433 * to SSLHandshake(); subsequently cannot be called while a session is
437 SSLSetIOFuncs (SSLContextRef context
,
438 SSLReadFunc readFunc
,
439 SSLWriteFunc writeFunc
)
440 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
444 * Set a predefined configuration for the SSL Session
446 * This currently affect enabled protocol versions,
447 * enabled ciphersuites, and the kSSLSessionOptionFallback
451 SSLSetSessionConfig(SSLContextRef context
,
453 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_10_0
);
456 * Set the minimum SSL protocol version allowed. Optional.
457 * The default is the lower supported protocol.
459 * This can only be called when no session is active.
461 * For TLS contexts, legal values for minVersion are :
467 * For DTLS contexts, legal values for minVersion are :
471 SSLSetProtocolVersionMin (SSLContextRef context
,
472 SSLProtocol minVersion
)
473 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
476 * Get minimum protocol version allowed
479 SSLGetProtocolVersionMin (SSLContextRef context
,
480 SSLProtocol
*minVersion
)
481 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
484 * Set the maximum SSL protocol version allowed. Optional.
485 * The default is the highest supported protocol.
487 * This can only be called when no session is active.
489 * For TLS contexts, legal values for maxVersion are :
495 * For DTLS contexts, legal values for maxVersion are :
499 SSLSetProtocolVersionMax (SSLContextRef context
,
500 SSLProtocol maxVersion
)
501 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
504 * Get maximum protocol version allowed
507 SSLGetProtocolVersionMax (SSLContextRef context
,
508 SSLProtocol
*maxVersion
)
509 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
512 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
514 * Set allowed SSL protocol versions. Optional.
515 * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in
516 * specified 'enable' boolean to be applied to all supported protocols.
517 * The default is "all supported protocols are enabled".
518 * This can only be called when no session is active.
520 * Legal values for protocol are :
526 * ==========================
527 * MAC OS X ONLY (DEPRECATED)
528 * ==========================
529 * NOTE: this function is not available on iOS, and should be considered
530 * deprecated on Mac OS X. You can use SSLSetProtocolVersionMin and/or
531 * SSLSetProtocolVersionMax to specify which protocols are enabled.
534 SSLSetProtocolVersionEnabled (SSLContextRef context
,
535 SSLProtocol protocol
,
537 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
540 * Obtain a value specified in SSLSetProtocolVersionEnabled.
542 * ==========================
543 * MAC OS X ONLY (DEPRECATED)
544 * ==========================
545 * NOTE: this function is not available on iOS, and should be considered
546 * deprecated on Mac OS X. You can use SSLGetProtocolVersionMin and/or
547 * SSLGetProtocolVersionMax to check whether a protocol is enabled.
550 SSLGetProtocolVersionEnabled(SSLContextRef context
,
551 SSLProtocol protocol
,
552 Boolean
*enable
) /* RETURNED */
553 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
556 * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown,
557 * in which case the highest possible version is attempted, but a lower
558 * version is accepted if the peer requires it.
559 * SSLSetProtocolVersion cannot be called when a session is active.
561 * ==========================
562 * MAC OS X ONLY (DEPRECATED)
563 * ==========================
564 * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8.
565 * Use SSLSetProtocolVersionMin and/or SSLSetProtocolVersionMax to specify
566 * which protocols are enabled.
569 SSLSetProtocolVersion (SSLContextRef context
,
571 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_8
,__IPHONE_NA
,__IPHONE_NA
);
574 * Obtain the protocol version specified in SSLSetProtocolVersion.
575 * If SSLSetProtocolVersionEnabled() has been called for this session,
576 * SSLGetProtocolVersion() may return errSecParam if the protocol enable
577 * state can not be represented by the SSLProtocol enums (e.g.,
578 * SSL2 and TLS1 enabled, SSL3 disabled).
580 * ==========================
581 * MAC OS X ONLY (DEPRECATED)
582 * ==========================
583 * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8.
584 * Use SSLGetProtocolVersionMin and/or SSLGetProtocolVersionMax to check
585 * whether a protocol is enabled.
588 SSLGetProtocolVersion (SSLContextRef context
,
589 SSLProtocol
*protocol
) /* RETURNED */
590 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_8
,__IPHONE_NA
,__IPHONE_NA
);
592 #endif /* MAC OS X */
595 * Specify this connection's certificate(s). This is mandatory for
596 * server connections, optional for clients. Specifying a certificate
597 * for a client enables SSL client-side authentication. The end-entity
598 * cert is in certRefs[0]. Specifying a root cert is optional; if it's
599 * not specified, the root cert which verifies the cert chain specified
600 * here must be present in the system-wide set of trusted anchor certs.
602 * The certRefs argument is a CFArray containing SecCertificateRefs,
603 * except for certRefs[0], which is a SecIdentityRef.
605 * Must be called prior to SSLHandshake(), or immediately after
606 * SSLHandshake has returned errSSLClientCertRequested (i.e. before the
607 * handshake is resumed by calling SSLHandshake again.)
609 * SecureTransport assumes the following:
611 * -- The certRef references remain valid for the lifetime of the session.
612 * -- The certificate specified in certRefs[0] is capable of signing.
613 * -- The required capabilities of the certRef[0], and of the optional cert
614 * specified in SSLSetEncryptionCertificate (see below), are highly
615 * dependent on the application. For example, to work as a server with
616 * Netscape clients, the cert specified here must be capable of both
617 * signing and encrypting.
620 SSLSetCertificate (SSLContextRef context
,
621 CFArrayRef _Nullable certRefs
)
622 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
625 * Specify I/O connection - a socket, endpoint, etc., which is
626 * managed by caller. On the client side, it's assumed that communication
627 * has been established with the desired server on this connection.
628 * On the server side, it's assumed that an incoming client request
629 * has been established.
631 * Must be called prior to SSLHandshake(); subsequently can only be
632 * called when no session is active.
635 SSLSetConnection (SSLContextRef context
,
636 SSLConnectionRef __nullable connection
)
637 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
640 SSLGetConnection (SSLContextRef context
,
641 SSLConnectionRef
* __nonnull CF_RETURNS_NOT_RETAINED connection
)
642 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
645 * Specify the fully qualified doman name of the peer, e.g., "store.apple.com."
646 * Optional; used to verify the common name field in peer's certificate.
647 * Name is in the form of a C string; NULL termination optional, i.e.,
648 * peerName[peerNameLen+1] may or may not have a NULL. In any case peerNameLen
649 * is the number of bytes of the peer domain name.
652 SSLSetPeerDomainName (SSLContextRef context
,
653 const char * __nullable peerName
,
655 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
658 * Determine the buffer size needed for SSLGetPeerDomainName().
661 SSLGetPeerDomainNameLength (SSLContextRef context
,
662 size_t *peerNameLen
) // RETURNED
663 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
666 * Obtain the value specified in SSLSetPeerDomainName().
669 SSLGetPeerDomainName (SSLContextRef context
,
670 char *peerName
, // returned here
671 size_t *peerNameLen
) // IN/OUT
672 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
676 * Determine the buffer size needed for SSLCopyRequestedPeerNameLength().
679 SSLCopyRequestedPeerName (SSLContextRef context
,
682 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
685 * Server Only: obtain the hostname specified by the client in the ServerName extension (SNI)
688 SSLCopyRequestedPeerNameLength (SSLContextRef ctx
,
690 __OSX_AVAILABLE_STARTING(__MAC_10_11
, __IPHONE_9_0
);
694 * Specify the Datagram TLS Hello Cookie.
695 * This is to be called for server side only and is optional.
696 * The default is a zero len cookie. The maximum cookieLen is 32 bytes.
699 SSLSetDatagramHelloCookie (SSLContextRef dtlsContext
,
700 const void * __nullable cookie
,
702 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
705 * Specify the maximum record size, including all DTLS record headers.
706 * This should be set appropriately to avoid fragmentation
707 * of Datagrams during handshake, as fragmented datagrams may
708 * be dropped by some network.
709 * This is for Datagram TLS only
712 SSLSetMaxDatagramRecordSize (SSLContextRef dtlsContext
,
714 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
717 * Get the maximum record size, including all Datagram TLS record headers.
718 * This is for Datagram TLS only
721 SSLGetMaxDatagramRecordSize (SSLContextRef dtlsContext
,
723 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
726 * Obtain the actual negotiated protocol version of the active
727 * session, which may be different that the value specified in
728 * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no
729 * SSL session is in progress.
732 SSLGetNegotiatedProtocolVersion (SSLContextRef context
,
733 SSLProtocol
*protocol
) /* RETURNED */
734 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
737 * Determine number and values of all of the SSLCipherSuites we support.
738 * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in
739 * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
743 SSLGetNumberSupportedCiphers (SSLContextRef context
,
745 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
748 SSLGetSupportedCiphers (SSLContextRef context
,
749 SSLCipherSuite
*ciphers
, /* RETURNED */
750 size_t *numCiphers
) /* IN/OUT */
751 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
754 * Specify a (typically) restricted set of SSLCipherSuites to be enabled by
755 * the current SSLContext. Can only be called when no session is active. Default
756 * set of enabled SSLCipherSuites is the same as the complete set of supported
757 * SSLCipherSuites as obtained by SSLGetSupportedCiphers().
760 SSLSetEnabledCiphers (SSLContextRef context
,
761 const SSLCipherSuite
*ciphers
,
763 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
766 * Determine number and values of all of the SSLCipherSuites currently enabled.
767 * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in
768 * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow
772 SSLGetNumberEnabledCiphers (SSLContextRef context
,
774 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
777 SSLGetEnabledCiphers (SSLContextRef context
,
778 SSLCipherSuite
*ciphers
, /* RETURNED */
779 size_t *numCiphers
) /* IN/OUT */
780 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
783 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
785 * Enable/disable peer certificate chain validation. Default is enabled.
786 * If caller disables, it is the caller's responsibility to call
787 * SSLCopyPeerCertificates() upon successful completion of the handshake
788 * and then to perform external validation of the peer certificate
789 * chain before proceeding with data transfer.
791 * ==========================
792 * MAC OS X ONLY (DEPRECATED)
793 * ==========================
794 * NOTE: this function is not available on iOS, and should be considered
795 * deprecated on Mac OS X. To disable peer certificate chain validation, you
796 * can instead use SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth
797 * to true. This will disable verification and cause SSLHandshake to return with
798 * an errSSLServerAuthCompleted result when the peer certificates have been
799 * received; at that time, you can choose to evaluate peer trust yourself, or
800 * simply call SSLHandshake again to proceed with the handshake.
803 SSLSetEnableCertVerify (SSLContextRef context
,
804 Boolean enableVerify
)
805 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
808 * Check whether peer certificate chain validation is enabled.
810 * ==========================
811 * MAC OS X ONLY (DEPRECATED)
812 * ==========================
813 * NOTE: this function is not available on iOS, and should be considered
814 * deprecated on Mac OS X. To check whether peer certificate chain validation
815 * is enabled in a context, call SSLGetSessionOption to obtain the value of
816 * the kSSLSessionOptionBreakOnServerAuth session option flag. If the value
817 * of this option flag is true, then verification is disabled.
820 SSLGetEnableCertVerify (SSLContextRef context
,
821 Boolean
*enableVerify
) /* RETURNED */
822 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
825 * Specify the option of ignoring certificates' "expired" times.
826 * This is a common failure in the real SSL world. Default setting for this
827 * flag is false, meaning expired certs result in an errSSLCertExpired error.
829 * ==========================
830 * MAC OS X ONLY (DEPRECATED)
831 * ==========================
832 * NOTE: this function is not available on iOS, and should be considered
833 * deprecated on Mac OS X. To ignore expired certificate errors, first disable
834 * Secure Transport's automatic verification of peer certificates by calling
835 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
836 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
837 * your code should obtain the SecTrustRef for the peer's certificates and
838 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
839 * The SecTrustSetOptions function allows you to specify that the expiration
840 * status of certificates should be ignored for this evaluation.
844 * status = SSLSetSessionOption(ctx, kSSLSessionOptionBreakOnServerAuth, true);
846 * status = SSLHandshake(ctx);
848 * if (status == errSSLServerAuthCompleted) {
849 * SecTrustRef peerTrust = NULL;
850 * status = SSLCopyPeerTrust(ctx, &peerTrust);
851 * if (status == errSecSuccess) {
852 * SecTrustResultType trustResult;
853 * // set flag to allow expired certificates
854 * SecTrustSetOptions(peerTrust, kSecTrustOptionAllowExpired);
855 * status = SecTrustEvaluate(peerTrust, &trustResult);
856 * if (status == errSecSuccess) {
857 * // A "proceed" result means the cert is explicitly trusted,
858 * // e.g. "Always Trust" was clicked;
859 * // "Unspecified" means the cert has no explicit trust settings,
860 * // but is implicitly OK since it chains back to a trusted root.
861 * // Any other result means the cert is not trusted.
863 * if (trustResult == kSecTrustResultProceed ||
864 * trustResult == kSecTrustResultUnspecified) {
865 * // certificate is trusted
866 * status = errSSLWouldBlock; // so we call SSLHandshake again
867 * } else if (trustResult == kSecTrustResultRecoverableTrustFailure) {
868 * // not trusted, for some reason other than being expired;
869 * // could ask the user whether to allow the connection here
871 * status = errSSLXCertChainInvalid;
873 * // cannot use this certificate (fatal)
874 * status = errSSLBadCert;
878 * CFRelease(peerTrust);
881 * } // errSSLServerAuthCompleted
883 * } while (status == errSSLWouldBlock);
887 SSLSetAllowsExpiredCerts (SSLContextRef context
,
888 Boolean allowsExpired
)
889 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
892 * Obtain the current value of an SSLContext's "allowExpiredCerts" flag.
894 * ==========================
895 * MAC OS X ONLY (DEPRECATED)
896 * ==========================
897 * NOTE: this function is not available on iOS, and should be considered
898 * deprecated on Mac OS X.
901 SSLGetAllowsExpiredCerts (SSLContextRef context
,
902 Boolean
*allowsExpired
) /* RETURNED */
903 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
906 * Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the
907 * option of ignoring "expired" status for root certificates only.
908 * Default setting is false, i.e., expired root certs result in an
909 * errSSLCertExpired error.
911 * ==========================
912 * MAC OS X ONLY (DEPRECATED)
913 * ==========================
914 * NOTE: this function is not available on iOS, and should be considered
915 * deprecated on Mac OS X. To ignore expired certificate errors, first disable
916 * Secure Transport's automatic verification of peer certificates by calling
917 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
918 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
919 * your code should obtain the SecTrustRef for the peer's certificates and
920 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
921 * The SecTrustSetOptions function allows you to specify that the expiration
922 * status of certificates should be ignored for this evaluation.
924 * See the description of the SSLSetAllowsExpiredCerts function (above)
925 * for a code example. The kSecTrustOptionAllowExpiredRoot option can be used
926 * instead of kSecTrustOptionAllowExpired to allow expired roots only.
929 SSLSetAllowsExpiredRoots (SSLContextRef context
,
930 Boolean allowsExpired
)
931 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
934 * Obtain the current value of an SSLContext's "allow expired roots" flag.
936 * ==========================
937 * MAC OS X ONLY (DEPRECATED)
938 * ==========================
939 * NOTE: this function is not available on iOS, and should be considered
940 * deprecated on Mac OS X.
943 SSLGetAllowsExpiredRoots (SSLContextRef context
,
944 Boolean
*allowsExpired
) /* RETURNED */
945 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
948 * Specify option of allowing for an unknown root cert, i.e., one which
949 * this software can not verify as one of a list of known good root certs.
950 * Default for this flag is false, in which case one of the following two
952 * -- The peer returns a cert chain with a root cert, and the chain
953 * verifies to that root, but the root is not one of our trusted
954 * roots. This results in errSSLUnknownRootCert on handshake.
955 * -- The peer returns a cert chain which does not contain a root cert,
956 * and we can't verify the chain to one of our trusted roots. This
957 * results in errSSLNoRootCert on handshake.
959 * Both of these error conditions are ignored when the AllowAnyRoot flag is
960 * true, allowing connection to a totally untrusted peer.
962 * ==========================
963 * MAC OS X ONLY (DEPRECATED)
964 * ==========================
965 * NOTE: this function is not available on iOS, and should be considered
966 * deprecated on Mac OS X. To ignore unknown root cert errors, first disable
967 * Secure Transport's automatic verification of peer certificates by calling
968 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
969 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
970 * your code should obtain the SecTrustRef for the peer's certificates and
971 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
973 * See the description of the SSLSetAllowsExpiredCerts function (above)
974 * for a code example. Note that an unknown root certificate will cause
975 * SecTrustEvaluate to report kSecTrustResultRecoverableTrustFailure as the
979 SSLSetAllowsAnyRoot (SSLContextRef context
,
981 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
984 * Obtain the current value of an SSLContext's "allow any root" flag.
986 * ==========================
987 * MAC OS X ONLY (DEPRECATED)
988 * ==========================
989 * NOTE: this function is not available on iOS, and should be considered
990 * deprecated on Mac OS X.
993 SSLGetAllowsAnyRoot (SSLContextRef context
,
994 Boolean
*anyRoot
) /* RETURNED */
995 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
998 * Augment or replace the system's default trusted root certificate set
999 * for this session. If replaceExisting is true, the specified roots will
1000 * be the only roots which are trusted during this session. If replaceExisting
1001 * is false, the specified roots will be added to the current set of trusted
1002 * root certs. If this function has never been called, the current trusted
1003 * root set is the same as the system's default trusted root set.
1004 * Successive calls with replaceExisting false result in accumulation
1005 * of additional root certs.
1007 * The trustedRoots array contains SecCertificateRefs.
1009 * ==========================
1010 * MAC OS X ONLY (DEPRECATED)
1011 * ==========================
1012 * NOTE: this function is not available on iOS, and should be considered
1013 * deprecated on Mac OS X. To trust specific roots in a session, first disable
1014 * Secure Transport's automatic verification of peer certificates by calling
1015 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When
1016 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result,
1017 * your code should obtain the SecTrustRef for the peer's certificates and
1018 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h).
1020 * See the description of the SSLSetAllowsExpiredCerts function (above)
1021 * for a code example. You can call SecTrustSetAnchorCertificates to
1022 * augment the system's trusted root set, or SecTrustSetAnchorCertificatesOnly
1023 * to make these the only trusted roots, prior to calling SecTrustEvaluate.
1026 SSLSetTrustedRoots (SSLContextRef context
,
1027 CFArrayRef trustedRoots
,
1028 Boolean replaceExisting
)
1029 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1032 * Obtain an array of SecCertificateRefs representing the current
1033 * set of trusted roots. If SSLSetTrustedRoots() has never been called
1034 * for this session, this returns the system's default root set.
1036 * Caller must CFRelease the returned CFArray.
1038 * ==========================
1039 * MAC OS X ONLY (DEPRECATED)
1040 * ==========================
1041 * NOTE: this function is not available on iOS, and should be considered
1042 * deprecated on Mac OS X. To get the current set of trusted roots, call the
1043 * SSLCopyPeerTrust function to obtain the SecTrustRef for the peer certificate
1044 * chain, then SecTrustCopyCustomAnchorCertificates (see SecTrust.h).
1047 SSLCopyTrustedRoots (SSLContextRef context
,
1048 CFArrayRef
* __nonnull CF_RETURNS_RETAINED trustedRoots
) /* RETURNED */
1049 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1052 * Request peer certificates. Valid anytime, subsequent to a handshake attempt.
1054 * The certs argument is a CFArray containing SecCertificateRefs.
1055 * Caller must CFRelease the returned array.
1057 * The cert at index 0 of the returned array is the subject (end
1058 * entity) cert; the root cert (or the closest cert to it) is at
1059 * the end of the returned array.
1061 * ==========================
1062 * MAC OS X ONLY (DEPRECATED)
1063 * ==========================
1064 * NOTE: this function is not available on iOS, and should be considered
1065 * deprecated on Mac OS X. To get peer certificates, call SSLCopyPeerTrust
1066 * to obtain the SecTrustRef for the peer certificate chain, then use the
1067 * SecTrustGetCertificateCount and SecTrustGetCertificateAtIndex functions
1068 * to retrieve individual certificates in the chain (see SecTrust.h).
1071 SSLCopyPeerCertificates (SSLContextRef context
,
1072 CFArrayRef
* __nonnull CF_RETURNS_RETAINED certs
) /* RETURNED */
1073 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1075 #endif /* MAC OS X */
1078 * Obtain a SecTrustRef representing peer certificates. Valid anytime,
1079 * subsequent to a handshake attempt. Caller must CFRelease the returned
1082 * The returned trust reference will have already been evaluated for you,
1083 * unless one of the following is true:
1084 * - Your code has disabled automatic certificate verification, by calling
1085 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true.
1086 * - Your code has called SSLSetPeerID, and this session has been resumed
1087 * from an earlier cached session.
1089 * In these cases, your code should call SecTrustEvaluate prior to
1090 * examining the peer certificate chain or trust results (see SecTrust.h).
1092 * NOTE: if you have not called SSLHandshake at least once prior to
1093 * calling this function, the returned trust reference will be NULL.
1096 SSLCopyPeerTrust (SSLContextRef context
,
1097 SecTrustRef
* __nonnull CF_RETURNS_RETAINED trust
) /* RETURNED */
1098 __OSX_AVAILABLE_STARTING(__MAC_10_6
, __IPHONE_5_0
);
1101 * Specify some data, opaque to this library, which is sufficient
1102 * to uniquely identify the peer of the current session. An example
1103 * would be IP address and port, stored in some caller-private manner.
1104 * To be optionally called prior to SSLHandshake for the current
1105 * session. This is mandatory if this session is to be resumable.
1107 * SecureTransport allocates its own copy of the incoming peerID. The
1108 * data provided in *peerID, while opaque to SecureTransport, is used
1109 * in a byte-for-byte compare to other previous peerID values set by the
1110 * current application. Matching peerID blobs result in SecureTransport
1111 * attempting to resume an SSL session with the same parameters as used
1112 * in the previous session which specified the same peerID bytes.
1115 SSLSetPeerID (SSLContextRef context
,
1116 const void * __nullable peerID
,
1118 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1121 * Obtain current PeerID. Returns NULL pointer, zero length if
1122 * SSLSetPeerID has not been called for this context.
1125 SSLGetPeerID (SSLContextRef context
,
1126 const void * __nullable
* __nonnull peerID
,
1128 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1131 * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated
1132 * for this session. Only valid when a session is active.
1135 SSLGetNegotiatedCipher (SSLContextRef context
,
1136 SSLCipherSuite
*cipherSuite
)
1137 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1140 /********************************************************
1141 *** Session context configuration, server side only. ***
1142 ********************************************************/
1145 * This function is deprecated in OSX 10.11 and iOS 9.0 and
1146 * has no effect on the TLS handshake since OSX 10.10 and
1147 * iOS 8.0. Using separate RSA certificates for encryption
1148 * and signing is no longer supported.
1151 SSLSetEncryptionCertificate (SSLContextRef context
,
1152 CFArrayRef certRefs
)
1153 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
, __MAC_10_11
, __IPHONE_5_0
, __IPHONE_9_0
);
1156 * Specify requirements for client-side authentication.
1157 * Optional; Default is kNeverAuthenticate.
1159 * Can only be called when no session is active.
1161 typedef CF_ENUM(int, SSLAuthenticate
) {
1162 kNeverAuthenticate
, /* skip client authentication */
1163 kAlwaysAuthenticate
, /* require it */
1164 kTryAuthenticate
/* try to authenticate, but not an error
1165 * if client doesn't have a cert */
1169 SSLSetClientSideAuthenticate (SSLContextRef context
,
1170 SSLAuthenticate auth
)
1171 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1174 * Add a DER-encoded distinguished name to list of acceptable names
1175 * to be specified in requests for client certificates.
1178 SSLAddDistinguishedName (SSLContextRef context
,
1179 const void * __nullable derDN
,
1181 __OSX_AVAILABLE_STARTING(__MAC_10_4
, __IPHONE_5_0
);
1184 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
1186 * Add a SecCertificateRef, or a CFArray of them, to a server's list
1187 * of acceptable Certificate Authorities (CAs) to present to the client
1188 * when client authentication is performed.
1190 * If replaceExisting is true, the specified certificate(s) will replace
1191 * a possible existing list of acceptable CAs. If replaceExisting is
1192 * false, the specified certificate(s) will be appended to the existing
1193 * list of acceptable CAs, if any.
1195 * Returns errSecParam if this is called on a SSLContextRef which
1196 * is configured as a client, or when a session is active.
1198 * NOTE: this function is currently not available on iOS.
1201 SSLSetCertificateAuthorities(SSLContextRef context
,
1202 CFTypeRef certificateOrArray
,
1203 Boolean replaceExisting
)
1204 __OSX_AVAILABLE_STARTING(__MAC_10_5
, __IPHONE_NA
);
1207 * Obtain the certificates specified in SSLSetCertificateAuthorities(),
1208 * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not
1210 * Caller must CFRelease the returned array.
1212 * NOTE: this function is currently not available on iOS.
1215 SSLCopyCertificateAuthorities(SSLContextRef context
,
1216 CFArrayRef
* __nonnull CF_RETURNS_RETAINED certificates
) /* RETURNED */
1217 __OSX_AVAILABLE_STARTING(__MAC_10_5
, __IPHONE_NA
);
1219 #endif /* MAC OS X */
1222 * Obtain the list of acceptable distinguished names as provided by
1223 * a server (if the SSLContextRef is configured as a client), or as
1224 * specified by SSLSetCertificateAuthorities (if the SSLContextRef
1225 * is configured as a server).
1226 * The returned array contains CFDataRefs, each of which represents
1227 * one DER-encoded RDN.
1229 * Caller must CFRelease the returned array.
1232 SSLCopyDistinguishedNames (SSLContextRef context
,
1233 CFArrayRef
* __nonnull CF_RETURNS_RETAINED names
)
1234 __OSX_AVAILABLE_STARTING(__MAC_10_5
, __IPHONE_5_0
);
1237 * Obtain client certificate exchange status. Can be called
1238 * any time. Reflects the *last* client certificate state change;
1239 * subsequent to a renegotiation attempt by either peer, the state
1240 * is reset to kSSLClientCertNone.
1243 SSLGetClientCertificateState (SSLContextRef context
,
1244 SSLClientCertificateState
*clientState
)
1245 __OSX_AVAILABLE_STARTING(__MAC_10_3
, __IPHONE_5_0
);
1248 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
1250 * Specify Diffie-Hellman parameters. Optional; if we are configured to allow
1251 * for D-H ciphers and a D-H cipher is negotiated, and this function has not
1252 * been called, a set of process-wide parameters will be calculated. However
1253 * that can take a long time (30 seconds).
1255 * NOTE: this function is currently not available on iOS.
1257 OSStatus
SSLSetDiffieHellmanParams (SSLContextRef context
,
1258 const void * __nullable dhParams
,
1260 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_NA
);
1263 * Return parameter block specified in SSLSetDiffieHellmanParams.
1264 * Returned data is not copied and belongs to the SSLContextRef.
1266 * NOTE: this function is currently not available on iOS.
1268 OSStatus
SSLGetDiffieHellmanParams (SSLContextRef context
,
1269 const void * __nullable
* __nonnull dhParams
,
1270 size_t *dhParamsLen
)
1271 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_NA
);
1274 * Enable/Disable RSA blinding. This feature thwarts a known timing
1275 * attack to which RSA keys are vulnerable; enabling it is a tradeoff
1276 * between performance and security. The default for RSA blinding is
1279 * ==========================
1280 * MAC OS X ONLY (DEPRECATED)
1281 * ==========================
1282 * NOTE: this function is not available on iOS, and should be considered
1283 * deprecated on Mac OS X. RSA blinding is enabled unconditionally, as
1284 * it prevents a known way for an attacker to recover the private key,
1285 * and the performance gain of disabling it is negligible.
1287 OSStatus
SSLSetRsaBlinding (SSLContextRef context
,
1289 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1291 OSStatus
SSLGetRsaBlinding (SSLContextRef context
,
1293 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2
,__MAC_10_9
,__IPHONE_NA
,__IPHONE_NA
);
1295 #endif /* MAC OS X */
1297 /*******************************
1298 ******** I/O Functions ********
1299 *******************************/
1302 * Note: depending on the configuration of the underlying I/O
1303 * connection, all SSL I/O functions can return errSSLWouldBlock,
1304 * indicating "not complete, nothing is wrong, except required
1305 * I/O hasn't completed". Caller may need to repeat I/Os as necessary
1306 * if the underlying connection has been configured to behave in
1307 * a non-blocking manner.
1311 * Perform the SSL handshake. On successful return, session is
1312 * ready for normal secure application I/O via SSLWrite and SSLRead.
1314 * Interesting error returns:
1316 * errSSLUnknownRootCert: Peer had a valid cert chain, but the root of
1317 * the chain is unknown.
1319 * errSSLNoRootCert: Peer had a cert chain which did not end in a root.
1321 * errSSLCertExpired: Peer's cert chain had one or more expired certs.
1323 * errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e.,
1324 * signature verification within the chain failed, or no certs
1327 * In all of the above errors, the handshake was aborted; the peer's
1328 * cert chain is available via SSLCopyPeerTrust or SSLCopyPeerCertificates.
1330 * Other interesting result codes:
1332 * errSSLPeerAuthCompleted: Peer's cert chain is valid, or was ignored if
1333 * cert verification was disabled via SSLSetEnableCertVerify. The application
1334 * may decide to continue with the handshake (by calling SSLHandshake
1335 * again), or close the connection at this point.
1337 * errSSLClientCertRequested: The server has requested a client certificate.
1338 * The client may choose to examine the server's certificate and
1339 * distinguished name list, then optionally call SSLSetCertificate prior
1340 * to resuming the handshake by calling SSLHandshake again.
1342 * A return value of errSSLWouldBlock indicates that SSLHandshake has to be
1343 * called again (and again and again until something else is returned).
1346 SSLHandshake (SSLContextRef context
)
1347 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1350 * Server Only: Request renegotation.
1351 * This will return an error if the server is already renegotiating, or if the session is closed.
1352 * After this return without error, the application should call SSLHandshake() and/or SSLRead() as
1353 * for the original handshake.
1356 SSLReHandshake (SSLContextRef context
)
1357 __OSX_AVAILABLE_STARTING(__MAC_10_12
, __IPHONE_10_0
);
1361 * Normal application-level read/write. On both of these, a errSSLWouldBlock
1362 * return and a partially completed transfer - or even zero bytes transferred -
1363 * are NOT mutually exclusive.
1366 SSLWrite (SSLContextRef context
,
1367 const void * __nullable data
,
1369 size_t *processed
) /* RETURNED */
1370 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1373 * data is mallocd by caller; available size specified in
1374 * dataLength; actual number of bytes read returned in
1378 SSLRead (SSLContextRef context
,
1379 void * data
, /* RETURNED */
1381 size_t *processed
) /* RETURNED */
1382 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1385 * Determine how much data the client can be guaranteed to
1386 * obtain via SSLRead() without blocking or causing any low-level
1387 * read operations to occur.
1390 SSLGetBufferedReadSize (SSLContextRef context
,
1391 size_t *bufSize
) /* RETURNED */
1392 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1395 * Determine how much data the application can be guaranteed to write
1396 * with SSLWrite() without causing fragmentation. The value is based on
1397 * the maximum Datagram Record size defined by the application with
1398 * SSLSetMaxDatagramRecordSize(), minus the DTLS Record header size.
1401 SSLGetDatagramWriteSize (SSLContextRef dtlsContext
,
1403 __OSX_AVAILABLE_STARTING(__MAC_10_8
, __IPHONE_5_0
);
1406 * Terminate current SSL session.
1409 SSLClose (SSLContextRef context
)
1410 __OSX_AVAILABLE_STARTING(__MAC_10_2
, __IPHONE_5_0
);
1412 CF_IMPLICIT_BRIDGING_DISABLED
1413 CF_ASSUME_NONNULL_END
1419 #endif /* !_SECURITY_SECURETRANSPORT_H_ */