Security-59306.41.2.tar.gz

[apple/security.git] / OSX / libsecurity_ssl / lib / SecureTransport.h

/*
 * Copyright (c) 1999-2002,2005-2019 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/SecProtocolOptions.h>
#include <Security/CipherSuite.h>
#include <Security/SecTrust.h>
#include <Security/SecBase.h>
#include <sys/types.h>
#include <Availability.h>

#ifdef __cplusplus
extern "C" {
#endif

CF_ASSUME_NONNULL_BEGIN
CF_IMPLICIT_BRIDGING_ENABLED

#define __SECURETRANSPORT_API_DEPRECATED(...) \
    __API_DEPRECATED("No longer supported. Use Network.framework.", __VA_ARGS__)

/***********************
 *** Common typedefs ***
 ***********************/

/* Opaque reference to an SSL session context */
struct SSLContext;
typedef struct CF_BRIDGED_TYPE(id) SSLContext *SSLContextRef;

/* Opaque reference to an I/O connection (socket, endpoint, etc.) */
typedef const void *SSLConnectionRef;

/* SSL session options */
typedef CF_ENUM(int, SSLSessionOption) {
        /*
         * 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 CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 0,
        /*
         * Set this option to enable returning from SSLHandshake (with a result of
         * errSSLClientCertRequested) when the server requests a client certificate.
         */
        kSSLSessionOptionBreakOnCertRequested CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 1,
    /*
     * 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 CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 2,
    /*
     * Enable/Disable TLS False Start
     * When enabled, False Start will only be performed if a adequate cipher-suite is
     * negotiated.
     */
    kSSLSessionOptionFalseStart CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 3,
    /*
     * 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 CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 4,
    /*
     * Allow/Disallow server identity change on renegotiation. Disallow by default
     * to avoid Triple Handshake attack.
     */
    kSSLSessionOptionAllowServerIdentityChange CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 5,
    /*
     * Enable fallback countermeasures. Use this option when retyring a SSL connection
     * with a lower protocol version because of failure to connect.
     */
    kSSLSessionOptionFallback CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 6,
    /*
     * Set this option to break from a client hello in order to check for SNI
     */
    kSSLSessionOptionBreakOnClientHello CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 7,
    /*
     * Set this option to Allow renegotations. False by default.
     */
    kSSLSessionOptionAllowRenegotiation CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 8,
    /*
     * Set this option to enable session tickets. False by default.
     */
    kSSLSessionOptionEnableSessionTickets CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0) = 9,
};

/* State of an SSLSession */
typedef CF_CLOSED_ENUM(int, SSLSessionState) {
        kSSLIdle CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),        /* no I/O performed yet */
        kSSLHandshake CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),       /* SSL handshake in progress */
        kSSLConnected CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),       /* Handshake complete, ready for normal I/O */
        kSSLClosed CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),          /* connection closed normally */
        kSSLAborted     CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0)              /* connection aborted */
};

/*
 * Status of client certificate exchange (which is optional
 * for both server and client).
 */
typedef CF_ENUM(int, SSLClientCertificateState) {
        /* Server hasn't asked for a cert. Client hasn't sent one. */
        kSSLClientCertNone CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),
        /* Server has asked for a cert, but client didn't send it. */
        kSSLClientCertRequested CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),
        /*
         * Server side: We asked for a cert, client sent one, we validated
         *                              it OK. App can inspect the cert via
         *                              SSLCopyPeerCertificates().
         * Client side: server asked for one, we sent it.
         */
        kSSLClientCertSent CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),
        /*
         * Client sent a cert but failed validation. Server side only.
         * Server app can inspect the cert via SSLCopyPeerCertificates().
         */
        kSSLClientCertRejected CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0)
};

/*
 * 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 */

/* DEPRECATED aliases for errSSLPeerAuthCompleted */
#define errSSLServerAuthCompleted       errSSLPeerAuthCompleted
#define errSSLClientAuthCompleted       errSSLPeerAuthCompleted

/* DEPRECATED alias for the end of the error range */
#define errSSLLast errSSLUnexpectedRecord

typedef CF_CLOSED_ENUM(int, SSLProtocolSide)
{
    kSSLServerSide CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),
    kSSLClientSide CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0)
};

typedef CF_ENUM(int, SSLConnectionType)
{
    kSSLStreamType CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0),
    kSSLDatagramType CF_ENUM_DEPRECATED(10_2, 10_15, 2_0, 13_0)
};

/*
 * Predefined TLS configuration constants
 */

/* Default configuration (has 3DES, no RC4) */
extern const CFStringRef kSSLSessionConfig_default
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.13), ios(5.0, 11.0));

/* ATS v1 Config: TLS v1.2, only PFS ciphersuites */
extern const CFStringRef kSSLSessionConfig_ATSv1
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* ATS v1 Config without PFS: TLS v1.2, include non PFS ciphersuites */
extern const CFStringRef kSSLSessionConfig_ATSv1_noPFS
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* TLS v1.2 to TLS v1.0, with default ciphersuites (no 3DES, no RC4) */
extern const CFStringRef kSSLSessionConfig_standard
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* TLS v1.2 to TLS v1.0, with default ciphersuites + RC4 + 3DES */
extern const CFStringRef kSSLSessionConfig_RC4_fallback
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.13), ios(5.0, 11.0));

/* TLS v1.0 only, with default ciphersuites + fallback SCSV */
extern const CFStringRef kSSLSessionConfig_TLSv1_fallback
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* TLS v1.0, with default ciphersuites + RC4 + 3DES + fallback SCSV */
extern const CFStringRef kSSLSessionConfig_TLSv1_RC4_fallback
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.13), ios(5.0, 11.0));

/* TLS v1.2 to TLS v1.0, defaults + RC4 + DHE ciphersuites */
extern const CFStringRef kSSLSessionConfig_legacy
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* TLS v1.2 to TLS v1.0, default + RC4 + DHE ciphersuites */
extern const CFStringRef kSSLSessionConfig_legacy_DHE
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* TLS v1.2, anonymous ciphersuites only */
extern const CFStringRef kSSLSessionConfig_anonymous
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/* TLS v1.2 to TLS v1.0, has 3DES, no RC4 */
extern const CFStringRef kSSLSessionConfig_3DES_fallback
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.13), ios(5.0, 11.0));

/* TLS v1.0, with default ciphersuites + 3DES, no RC4 */
extern const CFStringRef kSSLSessionConfig_TLSv1_3DES_fallback
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.13), ios(5.0, 11.0));


/******************
 *** 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.
 */

/*
 * @function SSLContextGetTypeID
 * @abstract Return the CFTypeID for SSLContext objects.
 * @return CFTypeId for SSLContext objects.
 */
CFTypeID
SSLContextGetTypeID(void)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLCreateContext
 * @abstract Create a new instance of an SSLContextRef using the specified allocator.
 * @param alloc Allocator to use for memory.
 * @param protooclSide Client or server indication.
 * @param connectionType Type of connection.
 * @return A newly allocated SSLContextRef, or NULL on error.
 */
__nullable
SSLContextRef
SSLCreateContext(CFAllocatorRef __nullable alloc, SSLProtocolSide protocolSide, SSLConnectionType connectionType)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));


#if TARGET_OS_OSX
/*
 * @function SSLNewContext
 * @abstract Create a new session context.
 * @note
 *
 * ==========================
 * 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.
 *
 * @param isServer Flag indicating if the context is for the server (true) or client (false).
 * @param contextPtr Pointer to SSLContextRef where result will be stored.
 * @return errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLNewContext                           (Boolean                        isServer,
                                                         SSLContextRef          * __nonnull CF_RETURNS_RETAINED contextPtr)     /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLDisposeContext
 * @abstract Dispose of a session context.
 * @note
 *
 * ==========================
 * 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.
 *
 * @param context A SSLContextRef to deallocate and destroy.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLDisposeContext                       (SSLContextRef          context)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

#endif /* MAC OS X */

/*
 * @function SSLGetSessionState
 * @abstract Determine the state of an SSL/DTLS session.
 * @param context A valid SSLContextRef.
 * @param state Output pointer to store the SSLSessionState.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetSessionState                      (SSLContextRef          context,
                                                         SSLSessionState        *state)         /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetSessionOption
 * @abstract Set options for an SSL session. Must be called prior to SSLHandshake();
 *   subsequently cannot be called while session is active.
 * @param context A valid SSLContextRef.
 * @param option An option enumeration value.
 * @param value Value of the SSLSessionOption.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetSessionOption                     (SSLContextRef          context,
                                                         SSLSessionOption       option,
                                                         Boolean                        value)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.6, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetSessionOption
 * @abstract Determine current value for the specified option in a given SSL session.
 * @param context A valid SSLContextRef.
 * @param option An option enumeration value.
 * @param value Pointer to a Boolean where the SSLSessionOption value is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetSessionOption                     (SSLContextRef          context,
                                                         SSLSessionOption       option,
                                                         Boolean                        *value)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.6, 10.15), ios(5.0, 13.0));

/********************************************************************
 *** Session context configuration, common to client and servers. ***
 ********************************************************************/

/*
 * @function SSLSetIOFuncs
 * @abstract Specify functions which do the network I/O. Must be called prior
 *    to SSLHandshake(); subsequently cannot be called while a session is
 *    active.
 * @param context A valid SSLContextRef.
 * @param readFunc Pointer to a SSLReadFunc.
 * @param writeFunc Pointer to a SSLWriteFunc.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetIOFuncs                           (SSLContextRef          context,
                                                         SSLReadFunc            readFunc,
                                                         SSLWriteFunc           writeFunc)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));


/*
 * @function SSLSetSessionConfig
 * @absttact Set a predefined configuration for the SSL Session
 * @note This currently affect enabled protocol versions,
 *   enabled ciphersuites, and the kSSLSessionOptionFallback
 *   session option.
 * @param context A valid SSLContextRef.
 * @param config String name of constant TLS handshake configuration, e.g., kSSLSessionConfig_standard.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetSessionConfig(SSLContextRef context,
                    CFStringRef config)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.12, 10.15), ios(10.0, 13.0));

/*
 * @function SSLSetProtocolVersionMin
 * @abstract Set the minimum SSL protocol version allowed. Optional.
 *   The default is the lower supported protocol.
 * @note 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
 * @param context A valid SSLContextRef.
 * @param minVersion Minimum TLS protocol version.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetProtocolVersionMin  (SSLContextRef      context,
                           SSLProtocol        minVersion)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetProtocolVersionMin
 * @abstract Get minimum protocol version allowed
 * @param context A valid SSLContextRef.
 * @param minVersion Pointer to SSLProtocol value where the minimum protocol version is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetProtocolVersionMin  (SSLContextRef      context,
                           SSLProtocol        *minVersion)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetProtocolVersionMax
 * @abstract Set the maximum SSL protocol version allowed. Optional.
 *   The default is the highest supported protocol.
 * @note
 *   This can only be called when no session is active.
 *
 *   For TLS contexts, legal values for maxVersion are :
 *              kSSLProtocol3
 *              kTLSProtocol1
 *              kTLSProtocol11
 *              kTLSProtocol12
 *
 *   For DTLS contexts, legal values for maxVersion are :
 *      kDTLSProtocol1
 * @param context A valid SSLContextRef.
 * @param maxVersion Maximum TLS protocol version.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetProtocolVersionMax  (SSLContextRef      context,
                           SSLProtocol        maxVersion)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetProtocolVersionMax
 * @abstract Get maximum protocol version allowed
 * @param context A valid SSLContextRef.
 * @param maxVersion Pointer to SSLProtocol value where the maximum protocol version is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetProtocolVersionMax  (SSLContextRef      context,
                           SSLProtocol        *maxVersion)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));


#if TARGET_OS_OSX
/*
 * @function SSLSetProtocolVersionEnabled
 * @abstract Set allowed SSL protocol versions. Optional.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param protocol A SSLProtocol enumerated value.
 * @param enable Boolean to enable or disable the designated protocol.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetProtocolVersionEnabled (SSLContextRef     context,
                                                         SSLProtocol            protocol,
                                                         Boolean                        enable)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * 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 */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLSetProtocolVersion
 * @abstract 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.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param protocol A SSLProtocol enumerated value.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetProtocolVersion           (SSLContextRef          context,
                                                         SSLProtocol            version)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.8));

/*
 * @function SSLGetProtocolVersion
 * @abstract Obtain the protocol version specified in SSLSetProtocolVersion.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param protocol A SSLProtocol enumerated value pointer to store the protocol version.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetProtocolVersion           (SSLContextRef          context,
                                                         SSLProtocol            *protocol)      /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.8));

#endif /* MAC OS X */

/*
 * @function SSLSetCertificate
 * @abstract Specify this connection's certificate(s).
 * @discussion This is mandatory for server connections,and 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.
 * @param context A valid SSLContextRef.
 * @param certRefs An array of SecCertificateRef instances.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetCertificate                       (SSLContextRef          context,
                                                         CFArrayRef                     _Nullable certRefs)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetConnection
 * @abstract Specify I/O connection - a socket, endpoint, etc., which is
 * managed by caller.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param connection A SSLConnectionRef.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetConnection                        (SSLContextRef                  context,
                                                         SSLConnectionRef __nullable    connection)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetConnection
 * @abstract Retrieve the I/O connection managed managed by the caller.
 * @param context A valid SSLContextRef.
 * @param connection A SSLConnectionRef pointer.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetConnection                        (SSLContextRef          context,
                                                         SSLConnectionRef       * __nonnull CF_RETURNS_NOT_RETAINED connection)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetPeerDomainName
 * @abstract Specify the fully qualified doman name of the peer, e.g., "store.apple.com."
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param peerName A C string carrying the peer domain name.
 * @param peerNameLen Length of the peer domain name string.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetPeerDomainName            (SSLContextRef          context,
                                                         const char                     * __nullable peerName,
                                                         size_t                         peerNameLen)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetPeerDomainNameLength
 * @abstract Determine the buffer size needed for SSLGetPeerDomainName().
 * @param context A valid SSLContextRef.
 * @param peerNameLen Pointer to where the length of the peer domain name string is stored
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetPeerDomainNameLength      (SSLContextRef          context,
                                                         size_t                         *peerNameLen)   // RETURNED
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetPeerDomainName
 * @abstract Obtain the value specified in SSLSetPeerDomainName().
 * @param context A valid SSLContextRef.
 * @param peerName Pointer to where the peer domain name is stored.
 * @param peerNameLen Pointer to where the length of the peer domain name string is stored,
 *        up to the length specified by peerNameLen (on input).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetPeerDomainName            (SSLContextRef          context,
                                                         char                           *peerName,              // returned here
                                                         size_t                         *peerNameLen)   // IN/OUT
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLCopyRequestedPeerNameLength
 * @abstract [Server Only] obtain the hostname specified by the client in the ServerName extension (SNI)
 * @param context A valid SSLContextRef.
 * @param peerNameLen Pointer to where the length of the requested peer domain name string
 *        is stored, up to the length specified by peerNameLen (on input).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyRequestedPeerNameLength  (SSLContextRef  ctx,
                                 size_t         *peerNameLen)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.11, 10.15), ios(9.0, 13.0));

/*
 * @function SSLCopyRequestedPeerName
 * @abstract Determine the buffer size needed for SSLCopyRequestedPeerNameLength().
 * @param context A valid SSLContextRef.
 * @param peerName Pointer to where the requested peer domain name is stored.
 * @param peerNameLen Pointer to where the length of the requested peer domain name string
 *        is stored, up to the length specified by peerNameLen (on input).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyRequestedPeerName    (SSLContextRef      context,
                             char               *peerName,
                             size_t             *peerNameLen)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.11, 10.15), ios(9.0, 13.0));


/*
 * @function SSLSetDatagramHelloCookie
 * @abstract Specify the Datagram TLS Hello Cookie.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param cookie Pointer to opaque cookie data.
 * @param cookieLen Length of cookie data.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetDatagramHelloCookie       (SSLContextRef          dtlsContext,
                             const void         * __nullable cookie,
                             size_t             cookieLen)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetMaxDatagramRecordSize
 * @abstract Specify the maximum record size, including all DTLS record headers.
 * @discussion This should be set appropriately to avoid fragmentation
 *   of Datagrams during handshake, as fragmented datagrams may
 *   be dropped by some network.
 * @note This is for Datagram TLS only
 * @param context A valid SSLContextRef.
 * @param maxSize Maximum size of datagram record(s).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetMaxDatagramRecordSize (SSLContextRef              dtlsContext,
                             size_t             maxSize)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetMaxDatagramRecordSize
 * @abstract Get the maximum record size, including all Datagram TLS record headers.
 * @note This is for Datagram TLS only
 * @param context A valid SSLContextRef.
 * @param maxSize Pointer where maximum size of datagram record(s) is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetMaxDatagramRecordSize (SSLContextRef              dtlsContext,
                             size_t             *maxSize)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetNegotiatedProtocolVersion
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param protocol Pointer where negotiated SSLProtocol is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetNegotiatedProtocolVersion         (SSLContextRef          context,
                                                                         SSLProtocol            *protocol)      /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetNumberSupportedCiphers
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param numCiphers Pointer where number of supported ciphers is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetNumberSupportedCiphers (SSLContextRef                     context,
                                                          size_t                                *numCiphers)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetSupportedCiphers
 * @abstract Get the supported ciphers.
 * @param context A valid SSLContextRef.
 * @param ciphers Pointer to array of SSLCipherSuite values where supported ciphersuites
 *                are stored. This array size is specified by the input value of numCiphers.
 * @param numCiphers Pointer where number of supported ciphers is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetSupportedCiphers           (SSLContextRef                 context,
                                                          SSLCipherSuite                *ciphers,               /* RETURNED */
                                                          size_t                                *numCiphers)    /* IN/OUT */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetNumberEnabledCiphers
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param numCiphers Pointer where number of enabled ciphers is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetNumberEnabledCiphers     (SSLContextRef       context,
                                size_t              *numCiphers)
__SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetEnabledCiphers
 * @abstract 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().
 * @param context A valid SSLContextRef.
 * @param ciphers Array of enabled SSLCipherSuite values. This array size is specified
 *                by the input value of numCiphers.
 * @param numCiphers Pointer where number of enabled ciphers is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetEnabledCiphers            (SSLContextRef                  context,
                                                         const SSLCipherSuite   *ciphers,
                                                         size_t                                 numCiphers)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetEnabledCiphers
 * @abstract Get the set of supported ciphersuites.
 * @param context A valid SSLContextRef.
 * @param ciphers Pointer to array of SSLCipherSuite values where enabled ciphersuites
 *                are stored. This array size is specified by the input value of numCiphers.
 * @param numCiphers Pointer where number of enabled ciphers is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetEnabledCiphers            (SSLContextRef                  context,
                                                         SSLCipherSuite                 *ciphers,               /* RETURNED */
                                                         size_t                                 *numCiphers)    /* IN/OUT */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetSessionTicketsEnabled
 * @abstract Forcibly enable or disable session ticket resumption.
 * @note By default, session tickets are disabled.
 * @param context A valid SSLContextRef.
 * @param enabled Boolean indicating if ticket support is enabled (true) or not (false).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetSessionTicketsEnabled     (SSLContextRef          context,
                                 Boolean                enabled)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.13, 10.15), ios(11.0, 13.0));


#if TARGET_OS_OSX
/*
 * @function SSLSetEnableCertVerify
 * @abstract Enable/disable peer certificate chain validation. Default is enabled.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param enableVerify Boolean indicating if certificate verifiation is enabled (true) or disabled (false).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetEnableCertVerify          (SSLContextRef                  context,
                                                         Boolean                                enableVerify)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLGetEnableCertVerify
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param enableVerify Pointer to Boolean where enable bit is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetEnableCertVerify          (SSLContextRef                  context,
                                                         Boolean                                *enableVerify)  /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLSetAllowsExpiredCerts
 * @abstract Specify the option of ignoring certificates' "expired" times.
 * @discussion 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);
 * @param context A valid SSLContextRef.
 * @param allowsExpired Boolean indicating if expired certificates are allowed (true) or not (false).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetAllowsExpiredCerts        (SSLContextRef          context,
                                                         Boolean                        allowsExpired)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLGetAllowsExpiredCerts
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param allowsExpired Pointer to Boolean where the expired certificate allowance Boolean is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetAllowsExpiredCerts        (SSLContextRef          context,
                                                         Boolean                        *allowsExpired) /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLSetAllowsExpiredRoots
 * @abstract Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the
 *    option of ignoring "expired" status for root certificates only.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param allowsExpired Boolean indicating if expired roots are allowed.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetAllowsExpiredRoots        (SSLContextRef          context,
                                                         Boolean                        allowsExpired)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLGetAllowsExpiredRoots
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param allowsExpired Pointer to Boolean where the expired root certificate allowance
 *                      Boolean is stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetAllowsExpiredRoots        (SSLContextRef          context,
                                                         Boolean                        *allowsExpired) /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLSetAllowsAnyRoot
 * @abstract 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.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param anyRoot Boolean indicating if any root is allowed (true) or not (false).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetAllowsAnyRoot                     (SSLContextRef          context,
                                                         Boolean                        anyRoot)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLGetAllowsAnyRoot
 * @abstract 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.
 * @param context A valid SSLContextRef.
 * @param anyRoot Pointer to Boolean to store any root allowance Boolean.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetAllowsAnyRoot                     (SSLContextRef          context,
                                                         Boolean                        *anyRoot) /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLSetTrustedRoots
 * @abstract Augment or replace the system's default trusted root certificate set
 * for this session.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param trustedRoots Array of SecCertificateRef roots.
 * @param replaceExisting Boolean indicating if provided roots should override all others for this connection.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetTrustedRoots                      (SSLContextRef          context,
                                                         CFArrayRef             trustedRoots,
                                                         Boolean                        replaceExisting)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLCopyTrustedRoots
 * @abstract Obtain an array of SecCertificateRefs representing the current
 *    set of trusted roots.
 * @discussion 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).
 * @param context A valid SSLContextRef.
 * @param trustedRoots Array of SecCertificateRef roots.
 * @param replaceExisting Boolean indicating if provided roots should override all others for this connection.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyTrustedRoots                     (SSLContextRef          context,
                                                         CFArrayRef             * __nonnull CF_RETURNS_RETAINED trustedRoots)   /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.5, 10.9));

/*
 * @function SSLCopyPeerCertificates
 * @abstract Request peer certificates. Valid anytime, subsequent to a handshake attempt.
 * @discussion 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).
 * @param context A valid SSLContextRef.
 * @param certs Pointer to CFArrayRef that will store a reference to the peer's certificates.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyPeerCertificates         (SSLContextRef          context,
                                                         CFArrayRef                     * __nonnull CF_RETURNS_RETAINED certs)          /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.5, 10.9));

#endif /* MAC OS X */

/*
 * @function SSLCopyPeerTrust
 * @abstract Obtain a SecTrustRef representing peer certificates. Valid anytime,
 *    subsequent to a handshake attempt. Caller must CFRelease the returned
 *    trust reference.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param trust Pointer to SecTrustRef where peer's SecTrustRef is copied (retained).
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyPeerTrust                        (SSLContextRef          context,
                                                         SecTrustRef            * __nonnull CF_RETURNS_RETAINED trust)          /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.6, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetPeerID
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param peerID Opaque peer ID.
 * @param peerIDLen Length of opaque peer ID.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetPeerID                            (SSLContextRef          context,
                                                         const void             * __nullable peerID,
                                                         size_t                         peerIDLen)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetPeerID
 * @abstract Obtain current PeerID. Returns NULL pointer, zero length if
 *    SSLSetPeerID has not been called for this context.
 * @param context A valid SSLContextRef.
 * @param peerID Pointer to storage for the peer ID.
 * @param peerIDLen Pointer to storage for the peer ID length.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetPeerID                            (SSLContextRef          context,
                                                         const void             * __nullable * __nonnull peerID,
                                                         size_t                         *peerIDLen)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetNegotiatedCipher
 * @abstract Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated
 *    for this session. Only valid when a session is active.
 * @param context A valid SSLContextRef.
 * @param cipherSuite Pointer to storage for negotiated SSLCipherSuite.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetNegotiatedCipher          (SSLContextRef          context,
                                                         SSLCipherSuite         *cipherSuite)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetALPNProtocols
 * @abstract Set the ALPN protocols to be passed in the ALPN negotiation.
 * @discussion This is the list of supported application-layer protocols supported.
 *
 *    The protocols parameter must be an array of CFStringRef values
 *    with ASCII-encoded reprensetations of the supported protocols, e.g., "http/1.1".
 *
 * @note See RFC 7301 for more information.
 * @param context A valid SSLContextRef.
 * @param protocols Array of CFStringRefs carrying application protocols.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetALPNProtocols         (SSLContextRef      context,
                             CFArrayRef         protocols)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.13, 10.15), ios(11.0, 13.0));

/*
 * @function SSLCopyALPNProtocols
 * @abstract Get the ALPN protocols associated with this SSL context.
 * @discussion This is the list of supported application-layer protocols supported.
 *
 *    The resultant protocols array will contain CFStringRef values containing
 *    ASCII-encoded representations of the supported protocols, e.g., "http/1.1".
 *
 *    See RFC 7301 for more information.
 *
 * @note The `protocols` pointer must be NULL, otherwise the copy will fail.
 *    This function will allocate memory for the CFArrayRef container
 *    if there is data to provide. Otherwise, the pointer will remain NULL.
 * @param context A valid SSLContextRef.
 * @param protocols Pointer to a CFArrayRef where peer ALPN protocols are stored.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyALPNProtocols        (SSLContextRef      context,
                             CFArrayRef         __nullable * __nonnull protocols)           /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.13, 10.15), ios(11.0, 13.0));

/*
 * @function SSLSetOCSPResponse
 * @abstract Set the OCSP response for the given SSL session.
 * @discussion The response parameter must be a non-NULL CFDataRef containing the
 *    bytes of the OCSP response.
 * @param context A valid SSLContextRef.
 * @param response CFDataRef carrying OCSP response.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetOCSPResponse          (SSLContextRef      context,
                             CFDataRef          __nonnull response)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.13, 10.15), ios(11.0, 13.0));

/********************************************************
 *** Session context configuration, server side only. ***
 ********************************************************/

/*
 * @function SSLSetEncryptionCertificate
 * @discussion This function is deprecated in OSX 10.11 and iOS 9.0 and
 *    has no effect on the TLS handshake since OSX 10.10 and
 *    iOS 8.0. Using separate RSA certificates for encryption
 *    and signing is no longer supported.
 * @param context A valid SSLContextRef.
 * @param certRefs Array of certificates.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetEncryptionCertificate     (SSLContextRef          context,
                                                         CFArrayRef                     certRefs)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.11), ios(5.0, 9.0));

/*
 * @enum SSLAuthenticate
 * @discussion Optional; Default is kNeverAuthenticate.
 *    Can only be called when no session is active.
 */
typedef CF_ENUM(int, SSLAuthenticate) {
        kNeverAuthenticate,                     /* skip client authentication */
        kAlwaysAuthenticate,            /* require it */
        kTryAuthenticate                        /* try to authenticate, but not an error if client doesn't have a cert */
};

/*
 * @function SSLSetClientSideAuthenticate
 * @abstract Specify requirements for client-side authentication.
 * @param context A valid SSLContextRef.
 * @param auth A SSLAuthenticate enumeration value.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetClientSideAuthenticate    (SSLContextRef          context,
                                                                 SSLAuthenticate        auth)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLAddDistinguishedName
 * @abstract Add a DER-encoded distinguished name to list of acceptable names
 *    to be specified in requests for client certificates.
 * @param context A valid SSLContextRef.
 * @param derDN A DER-encoded Distinguished Name blob.
 * @param derDNLen Length of the Distinguished Name blob.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLAddDistinguishedName         (SSLContextRef          context,
                                                         const void             * __nullable derDN,
                                                         size_t                         derDNLen)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.4, 10.15), ios(5.0, 13.0));


#if TARGET_OS_OSX
/*
 * @function SSLSetCertificateAuthorities
 * @abstract 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.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param certificateOrARray Either a SecCertificateRef (or CFArrayRef of them).
 * @param replaceExisting Boolean indicating if existing CAs should be overruled for this connection.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetCertificateAuthorities(SSLContextRef              context,
                                                         CFTypeRef                      certificateOrArray,
                                                         Boolean                        replaceExisting)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.5, 10.15));

/*
 * @function SSLCopyCertificateAuthorities
 * @abstract Obtain the certificates specified in SSLSetCertificateAuthorities(),
 *    if any. Returns a NULL array if SSLSetCertificateAuthorities() has not been called.
 * @discussion Caller must CFRelease the returned array.
 *
 * @note This function is currently not available on iOS.
 * @param context A valid SSLContextRef.
 * @param certificates Pointer to CFArrayRef storage for retained copy of CAs for this connection.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyCertificateAuthorities(SSLContextRef             context,
                                                          CFArrayRef            * __nonnull CF_RETURNS_RETAINED certificates)   /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.5, 10.15));

#endif /* MAC OS X */

/*
 * @function SSLCopyDistinguishedNames
 * @abstract 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).
 * @discussion The returned array contains CFDataRefs, each of which represents
 *    one DER-encoded RDN. Caller must CFRelease the returned array.
 * @param context A valid SSLContextRef.
 * @param names Pointer to CFArrayRef storage for retained copy of Distinguished Names.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLCopyDistinguishedNames       (SSLContextRef          context,
                                                         CFArrayRef                     * __nonnull CF_RETURNS_RETAINED names)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.5, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetClientCertificateState
 * @abstract Obtain client certificate exchange status.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param clientState Pointer to SSLClientCertificateState storage.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetClientCertificateState    (SSLContextRef                          context,
                                                                 SSLClientCertificateState      *clientState)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.3, 10.15), ios(5.0, 13.0));


#if TARGET_OS_OSX
/*
 * @function SSLSetDiffieHellmanParams
 * @abstract Specify Diffie-Hellman parameters.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param clientState Pointer to SSLClientCertificateState storage.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetDiffieHellmanParams       (SSLContextRef                  context,
                             const void                         * __nullable dhParams,
                             size_t                                     dhParamsLen)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15));

/*
 * @function SSLGetDiffieHellmanParams
 * @abstract Return parameter block specified in SSLSetDiffieHellmanParams.
 * @discussion Returned data is not copied and belongs to the SSLContextRef.
 * @note This function is currently not available on iOS.
 * @param context A valid SSLContextRef.
 * @param dhParams Pointer to storage for DH parameters (if set), of at length most |*dhParamsLen|.
 * @param dhParamsLen (Input and output) length of dhParams.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetDiffieHellmanParams       (SSLContextRef                  context,
                             const void                         * __nullable * __nonnull dhParams,
                             size_t                                     *dhParamsLen)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15));

/*
 * @function SSLSetRsaBlinding
 * @abstract Enable/Disable RSA blinding.
 * @discussion 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.
 * @param context A valid SSLContextRef.
 * @param blinding Boolean indicating if RSA blinding is enabled.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetRsaBlinding                       (SSLContextRef                  context,
                             Boolean                            blinding)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

/*
 * @function SSLGetRsaBlinding
 * @abstract Get RSA blinding state.
 * @discussion See SSLSetRsaBlinding().
 *
 * ==========================
 * MAC OS X ONLY (DEPRECATED)
 * ==========================
 * @note This function is not available on iOS, and should be considered
 *    deprecated on Mac OS X.
 * @param context A valid SSLContextRef.
 * @param blinding Pointer to Boolean storage for RSA blinding state.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetRsaBlinding                       (SSLContextRef                  context,
                             Boolean                            *blinding)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.9));

#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.
 */

/*
 * @function SSLHandshake
 * @abstract Perform the SSL handshake.
 * @discussion 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).
 * @param context A valid SSLContextRef.
 * @result errSecSuccess on success, alternative error on failure or incomplete state.
 */
OSStatus
SSLHandshake                            (SSLContextRef          context)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLReHandshake
 * @abstract Server Only: Request renegotation.
 * @discussion This will return an error if the server is already renegotiating, or if the session is closed.
 *    After this return without error, the application should call SSLHandshake() and/or SSLRead() as
 *    for the original handshake.
 * @param context A valid SSLContextRef.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLReHandshake                          (SSLContextRef          context)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.12, 10.15), ios(10.0, 13.0));


/*
 * @function SSLWrite
 * @abstract Normal application-level write.
 * @discussion On both of these, a errSSLWouldBlock return and a partially completed
 *    transfer - or even zero bytes transferred - are NOT mutually exclusive.
 * @param context A valid SSLContextRef.
 * @param data Pointer to data to write.
 * @param dataLength Length of data to write.
 * @param processed Pointer to storage indicating how much data was written.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLWrite                                        (SSLContextRef          context,
                                                         const void *           __nullable data,
                                                         size_t                         dataLength,
                                                         size_t                         *processed)             /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLRead
 * @abstract * @abstract Normal application-level write.
 * @discussion Data is mallocd by caller; available size specified in
 *    dataLength; actual number of bytes read returned in
 *    *processed.
 * @param context A valid SSLContextRef.
 * @param data Pointer to storage where data can be read.
 * @param dataLength Length of data storage.
 * @param processed Pointer to storage indicating how much data was read.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLRead                                         (SSLContextRef          context,
                                                         void *                         data,                   /* RETURNED */
                                                         size_t                         dataLength,
                                                         size_t                         *processed)             /* RETURNED */
    __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetBufferedReadSize
 * @abstract Determine how much data the client can be guaranteed to
 *    obtain via SSLRead() without blocking or causing any low-level
 *    read operations to occur.
 * @param context A valid SSLContextRef.
 * @param bufferSize Pointer to store the amount of buffered data to be read.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetBufferedReadSize          (SSLContextRef context,
                                                         size_t *bufferSize)                            /* RETURNED */
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLGetDatagramWriteSize
 * @abstract 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.
 * @param context A valid SSLContextRef (for DTLS).
 * @param bufferSize Pointer to store the amount of data that can be written.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLGetDatagramWriteSize         (SSLContextRef dtlsContext,
                                                         size_t *bufSize)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.8, 10.15), ios(5.0, 13.0));

/*
 * @function SSLClose
 * @abstract Terminate current SSL session.
 * @param context A valid SSLContextRef.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLClose                                        (SSLContextRef          context)
        __SECURETRANSPORT_API_DEPRECATED(macos(10.2, 10.15), ios(5.0, 13.0));

/*
 * @function SSLSetError
 * @abstract Set the status of a SSLContextRef.
 * @discussion This is to be done after handling steps of the SSL handshake such
 *    as server certificate validation.
 * @param context A valid SSLContextRef.
 * @param status Error status to set internally, which will be translated to an alert.
 * @result errSecSuccess on success, alternative error on failure.
 */
OSStatus
SSLSetError                 (SSLContextRef      context,
                             OSStatus           status)
    __SECURETRANSPORT_API_DEPRECATED(macos(10.13, 10.15), ios(11.0, 13.0));

#undef __SECURETRANSPORT_API_DEPRECATED

CF_IMPLICIT_BRIDGING_DISABLED
CF_ASSUME_NONNULL_END

#ifdef __cplusplus
}
#endif

#endif /* !_SECURITY_SECURETRANSPORT_H_ */