+++ /dev/null
-/*
- * 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 <CoreFoundation/CFArray.h>
-#include <Security/CipherSuite.h>
-#include <Security/SecTrust.h>
-#include <sys/types.h>
-#include <Availability.h>
-
-#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_ */
projects / apple / security.git / blobdiff