Secure Transport

Secure network communication using standardized transport layer security mechanisms.

Overview

The Security.SecureTransport API gives you access to Apple's implementation of Secure Sockets Layer version 3.0 (SSLv3), Transport Layer Security (TLS) versions 1.0 through 1.2, and Datagram Transport Layer Security (DTLS) version 1.0.

This API imposes no transport layer dependencies. You can use it with BSD Sockets and other protocols. To use this API, you provide callback functions to perform I/O on the underlying network connections. You are also responsible for setting up raw network connections. You pass in an opaque reference to the underlying (connected) entity at the start of an SSL session in the form of an SSLConnectionRef object.

Topics

First Steps

Using the Secure Socket Layer for Network Communication

Establish Secure Sockets Layer (SSL) sessions to facilitate secure communication between client and server.

Session Context

SSLCreateContext

Allocates and returns a new context.

Deprecated
SSLProtocolSide

The flags that indicate whether a context is for the server or client side of a connection.

SSLConnectionType

The flags that indicate whether a context is to be used for streaming or datagram-based communication.

SSLContextRef

An opaque type that represents an SSL session context object.

SSLContextGetTypeID

Returns the Core Foundation type ID for context objects.

Deprecated

Context Options

SSLSetSessionOption

Specifies options for a specific session.

Deprecated
SSLGetSessionOption

Indicates the current setting of Secure Sockets Layer (SSL) session options.

Deprecated
SSLSessionOption

The options that can be set for an SSL session.

Context Callbacks

SSLSetIOFuncs

Specifies callback functions that perform the network I/O operations.

Deprecated
SSLReadFunc

A pointer to a customized read function that secure transport calls to read data from the connection.

SSLWriteFunc

A pointer to a customized write function that secure transport calls to write data to the connection.

Session Configuration

SSLSetSessionConfig

Sets a predefined configuration for the Secure Sockets Layer (SSL) session.

Deprecated
SSLSetClientSideAuthenticate

Specifies the requirements for client-side authentication.

Deprecated
SSLConfig

Use these constants to configure Transport Layer Security (TLS) sessions.

SSLAuthenticate

The flags that represent the requirements for client-side authentication.

I/O Connections

SSLSetConnection

Specifies an I/O connection for a specific session.

Deprecated
SSLGetConnection

Retrieves an I/O connection—such as a socket or endpoint—for a specific session.

Deprecated
SSLConnectionRef

A pointer to an opaque I/O connection object.

Session State

SSLHandshake

Performs the SSL handshake.

Deprecated
SSLReHandshake

Requests renegotiation of the SSL handshake. Server only.

Deprecated
SSLClose

Terminates the current SSL session.

Deprecated
SSLSetPeerID

Specifies data that is sufficient to uniquely identify the peer of the current session.

Deprecated
SSLGetPeerID

Retrieves the current peer ID data.

Deprecated
SSLGetSessionState

Retrieves the state of an SSL session.

Deprecated
SSLSessionState

The flags that represent the state of an SSL session.

SSLSetError

Sets the status of a session context.

Deprecated

Read Operations

SSLRead

Performs a normal application-level read operation.

Deprecated
SSLGetBufferedReadSize

Determines how much data is available to be read.

Deprecated

Write Operations

SSLWrite

Performs a typical application-level write operation.

Deprecated
SSLGetDatagramWriteSize

Provides the largest packet that the OS guarantees it can send without fragmentation.

Deprecated
SSLGetMaxDatagramRecordSize

Obtains the maximum datagram record size allowed by the application for a given context.

Deprecated
SSLSetMaxDatagramRecordSize

Sets the maximum datagram record size allowed by the application for a given context.

Deprecated
SSLSetDatagramHelloCookie

Sets the cookie value used in the Datagram Transport Layer Security (DTLS) hello message.

Deprecated

The Peer Domain Name

SSLSetPeerDomainName

Specifies the fully qualified domain name of the peer.

Deprecated
SSLGetPeerDomainNameLength

Determines the length of a previously set peer domain name.

Deprecated
SSLGetPeerDomainName

Retrieves the peer domain name specified previously.

Deprecated
SSLCopyRequestedPeerName

Determines the buffer size needed for the peer domain name.

Deprecated
SSLCopyRequestedPeerNameLength

Obtains the hostname specified by the client in the ServerName extension (SNI). Server only.

Deprecated

Versions

SSLSetProtocolVersionMax

Sets the maximum protocol version allowed by the application for a given SSL context.

Deprecated
SSLSetProtocolVersionMin

Sets the minimum protocol version allowed by the application for a given SSL context.

Deprecated
SSLGetProtocolVersionMax

Gets the maximum protocol version allowed by the application for a given SSL context.

Deprecated
SSLGetProtocolVersionMin

Gets the minimum protocol version allowed by the application for a given SSL context.

Deprecated
SSLGetNegotiatedProtocolVersion

Obtains the negotiated protocol version of the active session.

Deprecated
SSLProtocol

An enumeration of valid SSL protocol versions.

Application Layer Protocols

SSLCopyALPNProtocols

Gets the list of supported application layer protocols.

Deprecated
SSLSetALPNProtocols

Sets the list of supported applicaiton layer protocols.

Deprecated

Ciphers

SSLGetNumberSupportedCiphers

Determines the number of cipher suites supported.

Deprecated
SSLGetSupportedCiphers

Determines the values of the supported cipher suites.

Deprecated
SSLSetEnabledCiphers

Specifies a restricted set of SSL cipher suites to be enabled by the current SSL session context.

Deprecated
SSLGetNumberEnabledCiphers

Determines the number of cipher suites currently enabled.

Deprecated
SSLGetEnabledCiphers

Determines which SSL cipher suites are currently enabled.

Deprecated
SSLGetNegotiatedCipher

Retrieves the cipher suite negotiated for this session.

Deprecated
SSLSetDiffieHellmanParams

Specifies Diffie-Hellman parameters for a given context.

Deprecated
SSLGetDiffieHellmanParams

Retrieves the Diffie-Hellman parameters for a given context.

Deprecated
SSLCipherSuite

A type for storing cipher suite values.

SSLCiphersuiteGroup

A mechanism for grouping related cipher suites.

SSL Cipher Suite Values

Recognize the set of valid SSL cipher suite values.

Root Certificates

SSLSetCertificateAuthorities

Adds one or more certificates to a server's list of certification authorities (CAs) acceptable for client authentication.

Deprecated
SSLCopyCertificateAuthorities

Retrieves the current list of certification authorities.

Deprecated

Authentication

SSLAddDistinguishedName

Adds a DER-encoded distinguished name to a list of acceptable names to be specified in requests for client certificates.

Deprecated
SSLCopyDistinguishedNames

Retrieves the distinguished names of acceptable certification authorities.

Deprecated
SSLSetCertificate

Specifies this connection’s certificate or certificates.

Deprecated
SSLGetClientCertificateState

Retrieves the exchange status of the client certificate.

Deprecated
SSLCopyPeerTrust

Retrieves a trust management object for the certificate used by a session.

Deprecated
SSLClientCertificateState

An enumeration of the states of client certificate exchange.

SSLSetOCSPResponse

Sets the OCSP response for the given SSL session.

Deprecated
SSLSetSessionTicketsEnabled

Enables or disables session ticket resumption.

Deprecated

Result Codes

Secure Transport Result Codes

Recognize result codes specific to the secure transport API.

Legacy Operations

SSLNewContext

Creates a new Secure Sockets Layer (SSL) session context.

Deprecated
SSLDisposeContext

Disposes of a Secure Sockets Layer (SSL) session context.

Deprecated
SSLSetProtocolVersionEnabled

Sets the allowed Secure Sockets Layer (SSL) protocol versions.

Deprecated
SSLGetProtocolVersionEnabled

Retrieves the enabled status of a given protocol.

Deprecated
SSLSetRsaBlinding

Enables or disables RSA blinding.

Deprecated
SSLGetRsaBlinding

Obtains a value indicating whether RSA blinding is enabled.

Deprecated
SSLSetProtocolVersion

Sets the SSL protocol version.

Deprecated
SSLGetProtocolVersion

Gets the SSL protocol version.

Deprecated
SSLSetAllowsAnyRoot

Specifies whether root certificates from unrecognized certification authorities are allowed.

Deprecated
SSLGetAllowsAnyRoot

Obtains a value specifying whether an unknown root is allowed.

Deprecated
SSLSetAllowsExpiredRoots

Specifies whether expired root certificates are allowed.

Deprecated
SSLGetAllowsExpiredRoots

Retrieves the value indicating whether expired roots are allowed.

Deprecated
SSLSetTrustedRoots

Augments or replaces the default set of trusted root certificates for this session.

Deprecated
SSLCopyTrustedRoots

Retrieves the current list of trusted root certificates.

Deprecated
SSLSetAllowsExpiredCerts

Specifies whether certificate expiration times are ignored.

Deprecated
SSLGetAllowsExpiredCerts

Retrieves the value specifying whether expired certificates are allowed.

Deprecated
SSLSetEnableCertVerify

Enables or disables peer certificate chain validation.

Deprecated
SSLGetEnableCertVerify

Determines whether peer certificate chain validation is currently enabled.

Deprecated
SSLSetEncryptionCertificate

Specifies the encryption certificates used for this connection.

Deprecated
SSLCopyPeerCertificates

Retrieves a peer certificate and its certificate chain.

Deprecated

See Also

Legacy Interfaces

Common Security Services Manager

A set of open source modules underpinning the legacy implementation of the Security framework.

Secure Download

Implement Apple's Secure Download System in macOS.