X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/80e2389990082500d76eb566d4946be3e786c3ef..d8f41ccd20de16f8ebe2ccc84d47bf1cb2b26bbb:/libsecurity_ssl/lib/SecureTransport.h diff --git a/libsecurity_ssl/lib/SecureTransport.h b/libsecurity_ssl/lib/SecureTransport.h deleted file mode 100644 index e0a5cf48..00000000 --- a/libsecurity_ssl/lib/SecureTransport.h +++ /dev/null @@ -1,1353 +0,0 @@ -/* - * Copyright (c) 1999-2002,2005-2012 Apple Inc. All Rights Reserved. - * - * @APPLE_LICENSE_HEADER_START@ - * - * This file contains Original Code and/or Modifications of Original Code - * as defined in and that are subject to the Apple Public Source License - * Version 2.0 (the 'License'). You may not use this file except in - * compliance with the License. Please obtain a copy of the License at - * http://www.opensource.apple.com/apsl/ and read it before using this - * file. - * - * The Original Code and all software distributed under the License are - * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER - * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, - * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. - * Please see the License for the specific language governing rights and - * limitations under the License. - * - * @APPLE_LICENSE_HEADER_END@ - */ - -/* - * SecureTransport.h - Public API for Apple SSL/TLS Implementation - */ - -#ifndef _SECURITY_SECURETRANSPORT_H_ -#define _SECURITY_SECURETRANSPORT_H_ - -/* - * This file describes the public API for an implementation of the - * Secure Socket Layer, V. 3.0, Transport Layer Security, V. 1.0 to V. 1.2 - * and Datagram Transport Layer Security V. 1.0 - * - * There are no transport layer dependencies in this library; - * it can be used with sockets, Open Transport, etc. Applications using - * this library provide callback functions which do the actual I/O - * on underlying network connections. Applications are also responsible - * for setting up raw network connections; the application passes in - * an opaque reference to the underlying (connected) entity at the - * start of an SSL session in the form of an SSLConnectionRef. - * - * Some terminology: - * - * A "client" is the initiator of an SSL Session. The canonical example - * of a client is a web browser, when it's talking to an https URL. - * - * A "server" is an entity which accepts requests for SSL sessions made - * by clients. E.g., a secure web server. - - * An "SSL Session", or "session", is bounded by calls to SSLHandshake() - * and SSLClose(). An "Active session" is in some state between these - * two calls, inclusive. - * - * An SSL Session Context, or SSLContextRef, is an opaque reference in this - * library to the state associated with one session. A SSLContextRef cannot - * be reused for multiple sessions. - */ - -#include -#include -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -/*********************** - *** Common typedefs *** - ***********************/ - -/* Opaque reference to an SSL session context */ -struct SSLContext; -typedef struct SSLContext *SSLContextRef; - -/* Opaque reference to an I/O connection (socket, endpoint, etc.) */ -typedef const void * SSLConnectionRef; - -/* SSL Protocol version */ -typedef enum { - kSSLProtocolUnknown = 0, /* no protocol negotiated/specified; use default */ - kSSLProtocol3 = 2, /* SSL 3.0 */ - kTLSProtocol1 = 4, /* TLS 1.0 */ - kTLSProtocol11 = 7, /* TLS 1.1 */ - kTLSProtocol12 = 8, /* TLS 1.2 */ - kDTLSProtocol1 = 9, /* DTLS 1.0 */ - - /* DEPRECATED on iOS */ - kSSLProtocol2 = 1, /* SSL 2.0 */ - kSSLProtocol3Only = 3, /* SSL 3.0 Only */ - kTLSProtocol1Only = 5, /* TLS 1.0 Only */ - kSSLProtocolAll = 6, /* All TLS supported protocols */ - -} SSLProtocol; - -/* SSL session options */ -typedef enum { - /* - * Set this option to enable returning from SSLHandshake (with a result of - * errSSLServerAuthCompleted) when the server authentication portion of the - * handshake is complete. This disable certificate verification and - * provides an opportunity to perform application-specific server - * verification before deciding to continue. - */ - kSSLSessionOptionBreakOnServerAuth, - /* - * Set this option to enable returning from SSLHandshake (with a result of - * errSSLClientCertRequested) when the server requests a client certificate. - */ - kSSLSessionOptionBreakOnCertRequested, - /* - * This option is the same as kSSLSessionOptionBreakOnServerAuth but applies - * to the case where SecureTransport is the server and the client has presented - * its certificates allowing the server to verify whether these should be - * allowed to authenticate. - */ - kSSLSessionOptionBreakOnClientAuth, - /* - * Enable/Disable TLS False Start - * When enabled, False Start will only be performed if a adequate cipher-suite is - * negotiated. - */ - kSSLSessionOptionFalseStart, - /* - * Enable/Disable 1/n-1 record splitting for BEAST attack mitigation. - * When enabled, record splitting will only be performed for TLS 1.0 connections - * using a block cipher. - */ - kSSLSessionOptionSendOneByteRecord, - /* - * Allow/Disallow server identity change on renegotiation. Disallow by default - * to avoid Triple Handshake attack. - */ - kSSLSessionOptionAllowServerIdentityChange, - -} SSLSessionOption; - -/* State of an SSLSession */ -typedef enum { - kSSLIdle, /* no I/O performed yet */ - kSSLHandshake, /* SSL handshake in progress */ - kSSLConnected, /* Handshake complete, ready for normal I/O */ - kSSLClosed, /* connection closed normally */ - kSSLAborted /* connection aborted */ -} SSLSessionState; - -/* - * Status of client certificate exchange (which is optional - * for both server and client). - */ -typedef enum { - /* Server hasn't asked for a cert. Client hasn't sent one. */ - kSSLClientCertNone, - /* Server has asked for a cert, but client didn't send it. */ - kSSLClientCertRequested, - /* - * Server side: We asked for a cert, client sent one, we validated - * it OK. App can inspect the cert via - * SSLGetPeerCertificates(). - * Client side: server asked for one, we sent it. - */ - kSSLClientCertSent, - /* - * Client sent a cert but failed validation. Server side only. - * Server app can inspect the cert via SSLGetPeerCertificates(). - */ - kSSLClientCertRejected -} SSLClientCertificateState; - -/* - * R/W functions. The application using this library provides - * these functions via SSLSetIOFuncs(). - * - * Data's memory is allocated by caller; on entry to these two functions - * the *length argument indicates both the size of the available data and the - * requested byte count. Number of bytes actually transferred is returned in - * *length. - * - * The application may configure the underlying connection to operate - * in a non-blocking manner; in such a case, a read operation may - * well return errSSLWouldBlock, indicating "I transferred less data than - * you requested (maybe even zero bytes), nothing is wrong, except - * requested I/O hasn't completed". This will be returned back up to - * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(), - * etc. - */ -typedef OSStatus -(*SSLReadFunc) (SSLConnectionRef connection, - void *data, /* owned by - * caller, data - * RETURNED */ - size_t *dataLength); /* IN/OUT */ -typedef OSStatus -(*SSLWriteFunc) (SSLConnectionRef connection, - const void *data, - size_t *dataLength); /* IN/OUT */ - - -/************************************************* - *** OSStatus values unique to SecureTransport *** - *************************************************/ - -/* - Note: the comments that appear after these errors are used to create SecErrorMessages.strings. - The comments must not be multi-line, and should be in a form meaningful to an end user. If - a different or additional comment is needed, it can be put in the header doc format, or on a - line that does not start with errZZZ. -*/ - -enum { - errSSLProtocol = -9800, /* SSL protocol error */ - errSSLNegotiation = -9801, /* Cipher Suite negotiation failure */ - errSSLFatalAlert = -9802, /* Fatal alert */ - errSSLWouldBlock = -9803, /* I/O would block (not fatal) */ - errSSLSessionNotFound = -9804, /* attempt to restore an unknown session */ - errSSLClosedGraceful = -9805, /* connection closed gracefully */ - errSSLClosedAbort = -9806, /* connection closed via error */ - errSSLXCertChainInvalid = -9807, /* invalid certificate chain */ - errSSLBadCert = -9808, /* bad certificate format */ - errSSLCrypto = -9809, /* underlying cryptographic error */ - errSSLInternal = -9810, /* Internal error */ - errSSLModuleAttach = -9811, /* module attach failure */ - errSSLUnknownRootCert = -9812, /* valid cert chain, untrusted root */ - errSSLNoRootCert = -9813, /* cert chain not verified by root */ - errSSLCertExpired = -9814, /* chain had an expired cert */ - errSSLCertNotYetValid = -9815, /* chain had a cert not yet valid */ - errSSLClosedNoNotify = -9816, /* server closed session with no notification */ - errSSLBufferOverflow = -9817, /* insufficient buffer provided */ - errSSLBadCipherSuite = -9818, /* bad SSLCipherSuite */ - - /* fatal errors detected by peer */ - errSSLPeerUnexpectedMsg = -9819, /* unexpected message received */ - errSSLPeerBadRecordMac = -9820, /* bad MAC */ - errSSLPeerDecryptionFail = -9821, /* decryption failed */ - errSSLPeerRecordOverflow = -9822, /* record overflow */ - errSSLPeerDecompressFail = -9823, /* decompression failure */ - errSSLPeerHandshakeFail = -9824, /* handshake failure */ - errSSLPeerBadCert = -9825, /* misc. bad certificate */ - errSSLPeerUnsupportedCert = -9826, /* bad unsupported cert format */ - errSSLPeerCertRevoked = -9827, /* certificate revoked */ - errSSLPeerCertExpired = -9828, /* certificate expired */ - errSSLPeerCertUnknown = -9829, /* unknown certificate */ - errSSLIllegalParam = -9830, /* illegal parameter */ - errSSLPeerUnknownCA = -9831, /* unknown Cert Authority */ - errSSLPeerAccessDenied = -9832, /* access denied */ - errSSLPeerDecodeError = -9833, /* decoding error */ - errSSLPeerDecryptError = -9834, /* decryption error */ - errSSLPeerExportRestriction = -9835, /* export restriction */ - errSSLPeerProtocolVersion = -9836, /* bad protocol version */ - errSSLPeerInsufficientSecurity = -9837, /* insufficient security */ - errSSLPeerInternalError = -9838, /* internal error */ - errSSLPeerUserCancelled = -9839, /* user canceled */ - errSSLPeerNoRenegotiation = -9840, /* no renegotiation allowed */ - - /* non-fatal result codes */ - errSSLPeerAuthCompleted = -9841, /* peer cert is valid, or was ignored if verification disabled */ - errSSLClientCertRequested = -9842, /* server has requested a client cert */ - - /* more errors detected by us */ - errSSLHostNameMismatch = -9843, /* peer host name mismatch */ - errSSLConnectionRefused = -9844, /* peer dropped connection before responding */ - errSSLDecryptionFail = -9845, /* decryption failure */ - errSSLBadRecordMac = -9846, /* bad MAC */ - errSSLRecordOverflow = -9847, /* record overflow */ - errSSLBadConfiguration = -9848, /* configuration error */ - errSSLUnexpectedRecord = -9849, /* unexpected (skipped) record in DTLS */ -}; - -/* DEPRECATED aliases for errSSLPeerAuthCompleted */ -#define errSSLServerAuthCompleted errSSLPeerAuthCompleted -#define errSSLClientAuthCompleted errSSLPeerAuthCompleted - -/* DEPRECATED alias for the end of the error range */ -#define errSSLLast errSSLUnexpectedRecord - -typedef enum -{ - kSSLServerSide, - kSSLClientSide -} SSLProtocolSide; - -typedef enum -{ - kSSLStreamType, - kSSLDatagramType -} SSLConnectionType; - -/****************** - *** Public API *** - ******************/ - -/* - * Secure Transport APIs require a SSLContextRef, which is an opaque - * reference to the SSL session and its parameters. On Mac OS X 10.7 - * and earlier versions, a new context is created using SSLNewContext, - * and is disposed by calling SSLDisposeContext. - * - * On i0S 5.0 and later, as well as Mac OS X versions after 10.7, the - * SSLContextRef is a true CFType object with retain-release semantics. - * New code should create a new context using SSLCreateContext (instead - * of SSLNewContext), and dispose the context by calling CFRelease - * (instead of SSLDisposeContext) when finished with it. - */ - -/* - * Return the CFTypeID for SSLContext objects. - */ -CFTypeID -SSLContextGetTypeID(void) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Create a new instance of an SSLContextRef using the specified allocator. - */ -SSLContextRef -SSLCreateContext(CFAllocatorRef alloc, SSLProtocolSide protocolSide, SSLConnectionType connectionType) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - - -#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) -/* - * Create a new session context. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. Your code should use SSLCreateContext instead. - */ -OSStatus -SSLNewContext (Boolean isServer, - SSLContextRef *contextPtr) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Dispose of a session context. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. Your code should use CFRelease to dispose a session - * created with SSLCreateContext. - */ -OSStatus -SSLDisposeContext (SSLContextRef context) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -#endif /* MAC OS X */ - -/* - * Determine the state of an SSL/DTLS session. - */ -OSStatus -SSLGetSessionState (SSLContextRef context, - SSLSessionState *state) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Set options for an SSL session. Must be called prior to SSLHandshake(); - * subsequently cannot be called while session is active. - */ -OSStatus -SSLSetSessionOption (SSLContextRef context, - SSLSessionOption option, - Boolean value) - __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); - -/* - * Determine current value for the specified option in a given SSL session. - */ -OSStatus -SSLGetSessionOption (SSLContextRef context, - SSLSessionOption option, - Boolean *value) - __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); - -/******************************************************************** - *** Session context configuration, common to client and servers. *** - ********************************************************************/ - -/* - * Specify functions which do the network I/O. Must be called prior - * to SSLHandshake(); subsequently cannot be called while a session is - * active. - */ -OSStatus -SSLSetIOFuncs (SSLContextRef context, - SSLReadFunc readFunc, - SSLWriteFunc writeFunc) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Set the minimum SSL protocol version allowed. Optional. - * The default is the lower supported protocol. - * - * This can only be called when no session is active. - * - * For TLS contexts, legal values for minVersion are : - * kSSLProtocol3 - * kTLSProtocol1 - * kTLSProtocol11 - * kTLSProtocol12 - * - * For DTLS contexts, legal values for minVersion are : - * kDTLSProtocol1 - */ -OSStatus -SSLSetProtocolVersionMin (SSLContextRef context, - SSLProtocol minVersion) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Get minimum protocol version allowed - */ -OSStatus -SSLGetProtocolVersionMin (SSLContextRef context, - SSLProtocol *minVersion) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Set the maximum SSL protocol version allowed. Optional. - * The default is the highest supported protocol. - * - * This can only be called when no session is active. - * - * For TLS contexts, legal values for minVersion are : - * kSSLProtocol3 - * kTLSProtocol1 - * kTLSProtocol11 - * kTLSProtocol12 - * - * For DTLS contexts, legal values for minVersion are : - * kDTLSProtocol1 - */ -OSStatus -SSLSetProtocolVersionMax (SSLContextRef context, - SSLProtocol maxVersion) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Get maximum protocol version allowed - */ -OSStatus -SSLGetProtocolVersionMax (SSLContextRef context, - SSLProtocol *maxVersion) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - - -#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) -/* - * Set allowed SSL protocol versions. Optional. - * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in - * specified 'enable' boolean to be applied to all supported protocols. - * The default is "all supported protocols are enabled". - * This can only be called when no session is active. - * - * Legal values for protocol are : - * kSSLProtocol2 - * kSSLProtocol3 - * kTLSProtocol1 - * kSSLProtocolAll - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. You can use SSLSetProtocolVersionMin and/or - * SSLSetProtocolVersionMax to specify which protocols are enabled. - */ -OSStatus -SSLSetProtocolVersionEnabled (SSLContextRef context, - SSLProtocol protocol, - Boolean enable) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Obtain a value specified in SSLSetProtocolVersionEnabled. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. You can use SSLGetProtocolVersionMin and/or - * SSLGetProtocolVersionMax to check whether a protocol is enabled. - */ -OSStatus -SSLGetProtocolVersionEnabled(SSLContextRef context, - SSLProtocol protocol, - Boolean *enable) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown, - * in which case the highest possible version is attempted, but a lower - * version is accepted if the peer requires it. - * SSLSetProtocolVersion cannot be called when a session is active. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8. - * Use SSLSetProtocolVersionMin and/or SSLSetProtocolVersionMax to specify - * which protocols are enabled. - */ -OSStatus -SSLSetProtocolVersion (SSLContextRef context, - SSLProtocol version) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA); - -/* - * Obtain the protocol version specified in SSLSetProtocolVersion. - * If SSLSetProtocolVersionEnabled() has been called for this session, - * SSLGetProtocolVersion() may return errSecParam if the protocol enable - * state can not be represented by the SSLProtocol enums (e.g., - * SSL2 and TLS1 enabled, SSL3 disabled). - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8. - * Use SSLGetProtocolVersionMin and/or SSLGetProtocolVersionMax to check - * whether a protocol is enabled. - */ -OSStatus -SSLGetProtocolVersion (SSLContextRef context, - SSLProtocol *protocol) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA); - -#endif /* MAC OS X */ - -/* - * Specify this connection's certificate(s). This is mandatory for - * server connections, optional for clients. Specifying a certificate - * for a client enables SSL client-side authentication. The end-entity - * cert is in certRefs[0]. Specifying a root cert is optional; if it's - * not specified, the root cert which verifies the cert chain specified - * here must be present in the system-wide set of trusted anchor certs. - * - * The certRefs argument is a CFArray containing SecCertificateRefs, - * except for certRefs[0], which is a SecIdentityRef. - * - * Must be called prior to SSLHandshake(), or immediately after - * SSLHandshake has returned errSSLClientCertRequested (i.e. before the - * handshake is resumed by calling SSLHandshake again.) - * - * SecureTransport assumes the following: - * - * -- The certRef references remain valid for the lifetime of the session. - * -- The certificate specified in certRefs[0] is capable of signing. - * -- The required capabilities of the certRef[0], and of the optional cert - * specified in SSLSetEncryptionCertificate (see below), are highly - * dependent on the application. For example, to work as a server with - * Netscape clients, the cert specified here must be capable of both - * signing and encrypting. - */ -OSStatus -SSLSetCertificate (SSLContextRef context, - CFArrayRef certRefs) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Specify I/O connection - a socket, endpoint, etc., which is - * managed by caller. On the client side, it's assumed that communication - * has been established with the desired server on this connection. - * On the server side, it's assumed that an incoming client request - * has been established. - * - * Must be called prior to SSLHandshake(); subsequently can only be - * called when no session is active. - */ -OSStatus -SSLSetConnection (SSLContextRef context, - SSLConnectionRef connection) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -OSStatus -SSLGetConnection (SSLContextRef context, - SSLConnectionRef *connection) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Specify the fully qualified doman name of the peer, e.g., "store.apple.com." - * Optional; used to verify the common name field in peer's certificate. - * Name is in the form of a C string; NULL termination optional, i.e., - * peerName[peerNameLen+1] may or may not have a NULL. In any case peerNameLen - * is the number of bytes of the peer domain name. - */ -OSStatus -SSLSetPeerDomainName (SSLContextRef context, - const char *peerName, - size_t peerNameLen) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Determine the buffer size needed for SSLGetPeerDomainName(). - */ -OSStatus -SSLGetPeerDomainNameLength (SSLContextRef context, - size_t *peerNameLen) // RETURNED - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Obtain the value specified in SSLSetPeerDomainName(). - */ -OSStatus -SSLGetPeerDomainName (SSLContextRef context, - char *peerName, // returned here - size_t *peerNameLen) // IN/OUT - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Specify the Datagram TLS Hello Cookie. - * This is to be called for server side only and is optional. - * The default is a zero len cookie. The maximum cookieLen is 32 bytes. - */ -OSStatus -SSLSetDatagramHelloCookie (SSLContextRef dtlsContext, - const void *cookie, - size_t cookieLen) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Specify the maximum record size, including all DTLS record headers. - * This should be set appropriately to avoid fragmentation - * of Datagrams during handshake, as fragmented datagrams may - * be dropped by some network. - * This is for Datagram TLS only - */ -OSStatus -SSLSetMaxDatagramRecordSize (SSLContextRef dtlsContext, - size_t maxSize) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Get the maximum record size, including all Datagram TLS record headers. - * This is for Datagram TLS only - */ -OSStatus -SSLGetMaxDatagramRecordSize (SSLContextRef dtlsContext, - size_t *maxSize) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Obtain the actual negotiated protocol version of the active - * session, which may be different that the value specified in - * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no - * SSL session is in progress. - */ -OSStatus -SSLGetNegotiatedProtocolVersion (SSLContextRef context, - SSLProtocol *protocol) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Determine number and values of all of the SSLCipherSuites we support. - * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in - * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow - * will be returned. - */ -OSStatus -SSLGetNumberSupportedCiphers (SSLContextRef context, - size_t *numCiphers) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -OSStatus -SSLGetSupportedCiphers (SSLContextRef context, - SSLCipherSuite *ciphers, /* RETURNED */ - size_t *numCiphers) /* IN/OUT */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Specify a (typically) restricted set of SSLCipherSuites to be enabled by - * the current SSLContext. Can only be called when no session is active. Default - * set of enabled SSLCipherSuites is the same as the complete set of supported - * SSLCipherSuites as obtained by SSLGetSupportedCiphers(). - */ -OSStatus -SSLSetEnabledCiphers (SSLContextRef context, - const SSLCipherSuite *ciphers, - size_t numCiphers) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Determine number and values of all of the SSLCipherSuites currently enabled. - * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in - * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow - * will be returned. - */ -OSStatus -SSLGetNumberEnabledCiphers (SSLContextRef context, - size_t *numCiphers) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -OSStatus -SSLGetEnabledCiphers (SSLContextRef context, - SSLCipherSuite *ciphers, /* RETURNED */ - size_t *numCiphers) /* IN/OUT */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - - -#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) -/* - * Enable/disable peer certificate chain validation. Default is enabled. - * If caller disables, it is the caller's responsibility to call - * SSLCopyPeerCertificates() upon successful completion of the handshake - * and then to perform external validation of the peer certificate - * chain before proceeding with data transfer. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To disable peer certificate chain validation, you - * can instead use SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth - * to true. This will disable verification and cause SSLHandshake to return with - * an errSSLServerAuthCompleted result when the peer certificates have been - * received; at that time, you can choose to evaluate peer trust yourself, or - * simply call SSLHandshake again to proceed with the handshake. - */ -OSStatus -SSLSetEnableCertVerify (SSLContextRef context, - Boolean enableVerify) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Check whether peer certificate chain validation is enabled. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To check whether peer certificate chain validation - * is enabled in a context, call SSLGetSessionOption to obtain the value of - * the kSSLSessionOptionBreakOnServerAuth session option flag. If the value - * of this option flag is true, then verification is disabled. - */ -OSStatus -SSLGetEnableCertVerify (SSLContextRef context, - Boolean *enableVerify) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Specify the option of ignoring certificates' "expired" times. - * This is a common failure in the real SSL world. Default setting for this - * flag is false, meaning expired certs result in an errSSLCertExpired error. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To ignore expired certificate errors, first disable - * Secure Transport's automatic verification of peer certificates by calling - * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When - * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, - * your code should obtain the SecTrustRef for the peer's certificates and - * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). - * The SecTrustSetOptions function allows you to specify that the expiration - * status of certificates should be ignored for this evaluation. - * - * Example: - * - * status = SSLSetSessionOption(ctx, kSSLSessionOptionBreakOnServerAuth, true); - * do { - * status = SSLHandshake(ctx); - * - * if (status == errSSLServerAuthCompleted) { - * SecTrustRef peerTrust = NULL; - * status = SSLCopyPeerTrust(ctx, &peerTrust); - * if (status == errSecSuccess) { - * SecTrustResultType trustResult; - * // set flag to allow expired certificates - * SecTrustSetOptions(peerTrust, kSecTrustOptionAllowExpired); - * status = SecTrustEvaluate(peerTrust, &trustResult); - * if (status == errSecSuccess) { - * // A "proceed" result means the cert is explicitly trusted, - * // e.g. "Always Trust" was clicked; - * // "Unspecified" means the cert has no explicit trust settings, - * // but is implicitly OK since it chains back to a trusted root. - * // Any other result means the cert is not trusted. - * // - * if (trustResult == kSecTrustResultProceed || - * trustResult == kSecTrustResultUnspecified) { - * // certificate is trusted - * status = errSSLWouldBlock; // so we call SSLHandshake again - * } else if (trustResult == kSecTrustResultRecoverableTrustFailure) { - * // not trusted, for some reason other than being expired; - * // could ask the user whether to allow the connection here - * // - * status = errSSLXCertChainInvalid; - * } else { - * // cannot use this certificate (fatal) - * status = errSSLBadCert; - * } - * } - * if (peerTrust) { - * CFRelease(peerTrust); - * } - * } - * } // errSSLServerAuthCompleted - * - * } while (status == errSSLWouldBlock); - * - */ -OSStatus -SSLSetAllowsExpiredCerts (SSLContextRef context, - Boolean allowsExpired) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Obtain the current value of an SSLContext's "allowExpiredCerts" flag. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. - */ -OSStatus -SSLGetAllowsExpiredCerts (SSLContextRef context, - Boolean *allowsExpired) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the - * option of ignoring "expired" status for root certificates only. - * Default setting is false, i.e., expired root certs result in an - * errSSLCertExpired error. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To ignore expired certificate errors, first disable - * Secure Transport's automatic verification of peer certificates by calling - * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When - * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, - * your code should obtain the SecTrustRef for the peer's certificates and - * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). - * The SecTrustSetOptions function allows you to specify that the expiration - * status of certificates should be ignored for this evaluation. - * - * See the description of the SSLSetAllowsExpiredCerts function (above) - * for a code example. The kSecTrustOptionAllowExpiredRoot option can be used - * instead of kSecTrustOptionAllowExpired to allow expired roots only. - */ -OSStatus -SSLSetAllowsExpiredRoots (SSLContextRef context, - Boolean allowsExpired) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Obtain the current value of an SSLContext's "allow expired roots" flag. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. - */ -OSStatus -SSLGetAllowsExpiredRoots (SSLContextRef context, - Boolean *allowsExpired) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Specify option of allowing for an unknown root cert, i.e., one which - * this software can not verify as one of a list of known good root certs. - * Default for this flag is false, in which case one of the following two - * errors may occur: - * -- The peer returns a cert chain with a root cert, and the chain - * verifies to that root, but the root is not one of our trusted - * roots. This results in errSSLUnknownRootCert on handshake. - * -- The peer returns a cert chain which does not contain a root cert, - * and we can't verify the chain to one of our trusted roots. This - * results in errSSLNoRootCert on handshake. - * - * Both of these error conditions are ignored when the AllowAnyRoot flag is - * true, allowing connection to a totally untrusted peer. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To ignore unknown root cert errors, first disable - * Secure Transport's automatic verification of peer certificates by calling - * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When - * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, - * your code should obtain the SecTrustRef for the peer's certificates and - * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). - * - * See the description of the SSLSetAllowsExpiredCerts function (above) - * for a code example. Note that an unknown root certificate will cause - * SecTrustEvaluate to report kSecTrustResultRecoverableTrustFailure as the - * trust result. - */ -OSStatus -SSLSetAllowsAnyRoot (SSLContextRef context, - Boolean anyRoot) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Obtain the current value of an SSLContext's "allow any root" flag. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. - */ -OSStatus -SSLGetAllowsAnyRoot (SSLContextRef context, - Boolean *anyRoot) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Augment or replace the system's default trusted root certificate set - * for this session. If replaceExisting is true, the specified roots will - * be the only roots which are trusted during this session. If replaceExisting - * is false, the specified roots will be added to the current set of trusted - * root certs. If this function has never been called, the current trusted - * root set is the same as the system's default trusted root set. - * Successive calls with replaceExisting false result in accumulation - * of additional root certs. - * - * The trustedRoots array contains SecCertificateRefs. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To trust specific roots in a session, first disable - * Secure Transport's automatic verification of peer certificates by calling - * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When - * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, - * your code should obtain the SecTrustRef for the peer's certificates and - * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). - * - * See the description of the SSLSetAllowsExpiredCerts function (above) - * for a code example. You can call SecTrustSetAnchorCertificates to - * augment the system's trusted root set, or SecTrustSetAnchorCertificatesOnly - * to make these the only trusted roots, prior to calling SecTrustEvaluate. - */ -OSStatus -SSLSetTrustedRoots (SSLContextRef context, - CFArrayRef trustedRoots, - Boolean replaceExisting) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Obtain an array of SecCertificateRefs representing the current - * set of trusted roots. If SSLSetTrustedRoots() has never been called - * for this session, this returns the system's default root set. - * - * Caller must CFRelease the returned CFArray. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To get the current set of trusted roots, call the - * SSLCopyPeerTrust function to obtain the SecTrustRef for the peer certificate - * chain, then SecTrustCopyCustomAnchorCertificates (see SecTrust.h). - */ -OSStatus -SSLCopyTrustedRoots (SSLContextRef context, - CFArrayRef *trustedRoots) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -/* - * Request peer certificates. Valid anytime, subsequent to a handshake attempt. - * - * The certs argument is a CFArray containing SecCertificateRefs. - * Caller must CFRelease the returned array. - * - * The cert at index 0 of the returned array is the subject (end - * entity) cert; the root cert (or the closest cert to it) is at - * the end of the returned array. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. To get peer certificates, call SSLCopyPeerTrust - * to obtain the SecTrustRef for the peer certificate chain, then use the - * SecTrustGetCertificateCount and SecTrustGetCertificateAtIndex functions - * to retrieve individual certificates in the chain (see SecTrust.h). - */ -OSStatus -SSLCopyPeerCertificates (SSLContextRef context, - CFArrayRef *certs) /* RETURNED */ - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -#endif /* MAC OS X */ - -/* - * Obtain a SecTrustRef representing peer certificates. Valid anytime, - * subsequent to a handshake attempt. Caller must CFRelease the returned - * trust reference. - * - * The returned trust reference will have already been evaluated for you, - * unless one of the following is true: - * - Your code has disabled automatic certificate verification, by calling - * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. - * - Your code has called SSLSetPeerID, and this session has been resumed - * from an earlier cached session. - * - * In these cases, your code should call SecTrustEvaluate prior to - * examining the peer certificate chain or trust results (see SecTrust.h). - * - * NOTE: if you have not called SSLHandshake at least once prior to - * calling this function, the returned trust reference will be NULL. - */ -OSStatus -SSLCopyPeerTrust (SSLContextRef context, - SecTrustRef *trust) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); - -/* - * Specify some data, opaque to this library, which is sufficient - * to uniquely identify the peer of the current session. An example - * would be IP address and port, stored in some caller-private manner. - * To be optionally called prior to SSLHandshake for the current - * session. This is mandatory if this session is to be resumable. - * - * SecureTransport allocates its own copy of the incoming peerID. The - * data provided in *peerID, while opaque to SecureTransport, is used - * in a byte-for-byte compare to other previous peerID values set by the - * current application. Matching peerID blobs result in SecureTransport - * attempting to resume an SSL session with the same parameters as used - * in the previous session which specified the same peerID bytes. - */ -OSStatus -SSLSetPeerID (SSLContextRef context, - const void *peerID, - size_t peerIDLen) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Obtain current PeerID. Returns NULL pointer, zero length if - * SSLSetPeerID has not been called for this context. - */ -OSStatus -SSLGetPeerID (SSLContextRef context, - const void **peerID, - size_t *peerIDLen) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated - * for this session. Only valid when a session is active. - */ -OSStatus -SSLGetNegotiatedCipher (SSLContextRef context, - SSLCipherSuite *cipherSuite) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - - -/******************************************************** - *** Session context configuration, server side only. *** - ********************************************************/ - -/* - * Specify this connection's encryption certificate(s). This is - * used in one of the following cases: - * - * -- The end-entity certificate specified in SSLSetCertificate() is - * not capable of encryption. - * - * -- The end-entity certificate specified in SSLSetCertificate() - * contains a key which is too large (i.e., too strong) for legal - * encryption in this session. In this case a weaker cert is - * specified here and is used for server-initiated key exchange. - * - * The certRefs argument is a CFArray containing SecCertificateRefs, - * except for certRefs[0], which is a SecIdentityRef. - * - * The following assumptions are made: - * - * -- The certRefs references remains valid for the lifetime of the - * connection. - * -- The specified certRefs[0] is capable of encryption. - * - * Can only be called when no session is active. - * - * Notes: - * ------ - * - * -- SSL servers which enforce the SSL3 spec to the letter will - * not accept encryption certs with RSA keys larger than 512 - * bits for exportable ciphers. Apps which wish to use encryption - * certs with key sizes larger than 512 bits should disable the - * use of exportable ciphers via the SSLSetEnabledCiphers() call. - */ -OSStatus -SSLSetEncryptionCertificate (SSLContextRef context, - CFArrayRef certRefs) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Specify requirements for client-side authentication. - * Optional; Default is kNeverAuthenticate. - * - * Can only be called when no session is active. - */ -typedef enum { - kNeverAuthenticate, /* skip client authentication */ - kAlwaysAuthenticate, /* require it */ - kTryAuthenticate /* try to authenticate, but not an error - * if client doesn't have a cert */ -} SSLAuthenticate; - -OSStatus -SSLSetClientSideAuthenticate (SSLContextRef context, - SSLAuthenticate auth) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Add a DER-encoded distinguished name to list of acceptable names - * to be specified in requests for client certificates. - */ -OSStatus -SSLAddDistinguishedName (SSLContextRef context, - const void *derDN, - size_t derDNLen) - __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_5_0); - - -#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) -/* - * Add a SecCertificateRef, or a CFArray of them, to a server's list - * of acceptable Certificate Authorities (CAs) to present to the client - * when client authentication is performed. - * - * If replaceExisting is true, the specified certificate(s) will replace - * a possible existing list of acceptable CAs. If replaceExisting is - * false, the specified certificate(s) will be appended to the existing - * list of acceptable CAs, if any. - * - * Returns errSecParam if this is called on a SSLContextRef which - * is configured as a client, or when a session is active. - * - * NOTE: this function is currently not available on iOS. - */ -OSStatus -SSLSetCertificateAuthorities(SSLContextRef context, - CFTypeRef certificateOrArray, - Boolean replaceExisting) - __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); - -/* - * Obtain the certificates specified in SSLSetCertificateAuthorities(), - * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not - * been called. - * Caller must CFRelease the returned array. - * - * NOTE: this function is currently not available on iOS. - */ -OSStatus -SSLCopyCertificateAuthorities(SSLContextRef context, - CFArrayRef *certificates) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); - -#endif /* MAC OS X */ - -/* - * Obtain the list of acceptable distinguished names as provided by - * a server (if the SSLContextRef is configured as a client), or as - * specified by SSLSetCertificateAuthorities (if the SSLContextRef - * is configured as a server). - * The returned array contains CFDataRefs, each of which represents - * one DER-encoded RDN. - * - * Caller must CFRelease the returned array. - */ -OSStatus -SSLCopyDistinguishedNames (SSLContextRef context, - CFArrayRef *names) - __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_5_0); - -/* - * Obtain client certificate exchange status. Can be called - * any time. Reflects the *last* client certificate state change; - * subsequent to a renegotiation attempt by either peer, the state - * is reset to kSSLClientCertNone. - */ -OSStatus -SSLGetClientCertificateState (SSLContextRef context, - SSLClientCertificateState *clientState) - __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_5_0); - - -#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) -/* - * Specify Diffie-Hellman parameters. Optional; if we are configured to allow - * for D-H ciphers and a D-H cipher is negotiated, and this function has not - * been called, a set of process-wide parameters will be calculated. However - * that can take a long time (30 seconds). - * - * NOTE: this function is currently not available on iOS. - */ -OSStatus SSLSetDiffieHellmanParams (SSLContextRef context, - const void *dhParams, - size_t dhParamsLen) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); - -/* - * Return parameter block specified in SSLSetDiffieHellmanParams. - * Returned data is not copied and belongs to the SSLContextRef. - * - * NOTE: this function is currently not available on iOS. - */ -OSStatus SSLGetDiffieHellmanParams (SSLContextRef context, - const void **dhParams, - size_t *dhParamsLen) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); - -/* - * Enable/Disable RSA blinding. This feature thwarts a known timing - * attack to which RSA keys are vulnerable; enabling it is a tradeoff - * between performance and security. The default for RSA blinding is - * enabled. - * - * ========================== - * MAC OS X ONLY (DEPRECATED) - * ========================== - * NOTE: this function is not available on iOS, and should be considered - * deprecated on Mac OS X. RSA blinding is enabled unconditionally, as - * it prevents a known way for an attacker to recover the private key, - * and the performance gain of disabling it is negligible. - */ -OSStatus SSLSetRsaBlinding (SSLContextRef context, - Boolean blinding) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -OSStatus SSLGetRsaBlinding (SSLContextRef context, - Boolean *blinding) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); - -#endif /* MAC OS X */ - -/******************************* - ******** I/O Functions ******** - *******************************/ - -/* - * Note: depending on the configuration of the underlying I/O - * connection, all SSL I/O functions can return errSSLWouldBlock, - * indicating "not complete, nothing is wrong, except required - * I/O hasn't completed". Caller may need to repeat I/Os as necessary - * if the underlying connection has been configured to behave in - * a non-blocking manner. - */ - -/* - * Perform the SSL handshake. On successful return, session is - * ready for normal secure application I/O via SSLWrite and SSLRead. - * - * Interesting error returns: - * - * errSSLUnknownRootCert: Peer had a valid cert chain, but the root of - * the chain is unknown. - * - * errSSLNoRootCert: Peer had a cert chain which did not end in a root. - * - * errSSLCertExpired: Peer's cert chain had one or more expired certs. - * - * errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e., - * signature verification within the chain failed, or no certs - * were found). - * - * In all of the above errors, the handshake was aborted; the peer's - * cert chain is available via SSLCopyPeerTrust or SSLCopyPeerCertificates. - * - * Other interesting result codes: - * - * errSSLPeerAuthCompleted: Peer's cert chain is valid, or was ignored if - * cert verification was disabled via SSLSetEnableCertVerify. The application - * may decide to continue with the handshake (by calling SSLHandshake - * again), or close the connection at this point. - * - * errSSLClientCertRequested: The server has requested a client certificate. - * The client may choose to examine the server's certificate and - * distinguished name list, then optionally call SSLSetCertificate prior - * to resuming the handshake by calling SSLHandshake again. - * - * A return value of errSSLWouldBlock indicates that SSLHandshake has to be - * called again (and again and again until something else is returned). - */ -OSStatus -SSLHandshake (SSLContextRef context) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Normal application-level read/write. On both of these, a errSSLWouldBlock - * return and a partially completed transfer - or even zero bytes transferred - - * are NOT mutually exclusive. - */ -OSStatus -SSLWrite (SSLContextRef context, - const void * data, - size_t dataLength, - size_t *processed) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * data is mallocd by caller; available size specified in - * dataLength; actual number of bytes read returned in - * *processed. - */ -OSStatus -SSLRead (SSLContextRef context, - void * data, /* RETURNED */ - size_t dataLength, - size_t *processed) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Determine how much data the client can be guaranteed to - * obtain via SSLRead() without blocking or causing any low-level - * read operations to occur. - */ -OSStatus -SSLGetBufferedReadSize (SSLContextRef context, - size_t *bufSize) /* RETURNED */ - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -/* - * Determine how much data the application can be guaranteed to write - * with SSLWrite() without causing fragmentation. The value is based on - * the maximum Datagram Record size defined by the application with - * SSLSetMaxDatagramRecordSize(), minus the DTLS Record header size. - */ -OSStatus -SSLGetDatagramWriteSize (SSLContextRef dtlsContext, - size_t *bufSize) - __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); - -/* - * Terminate current SSL session. - */ -OSStatus -SSLClose (SSLContextRef context) - __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); - -#ifdef __cplusplus -} -#endif - -#endif /* !_SECURITY_SECURETRANSPORT_H_ */