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.

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.

Context Options

SSLSetSessionOption

Specifies options for a specific session.

SSLGetSessionOption

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

SSLSessionOption

The options that can be set for an SSL session.

Context Callbacks

SSLSetIOFuncs

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

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.

SSLSetClientSideAuthenticate

Specifies the requirements for client-side authentication.

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.

SSLGetConnection

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

SSLConnectionRef

A pointer to an opaque I/O connection object.

Session State

SSLHandshake

Performs the SSL handshake.

SSLReHandshake

Requests renegotiation of the SSL handshake. Server only.

SSLClose

Terminates the current SSL session.

SSLSetPeerID

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

SSLGetPeerID

Retrieves the current peer ID data.

SSLGetSessionState

Retrieves the state of an SSL session.

SSLSessionState

The flags that represent the state of an SSL session.

Read Operations

SSLRead

Performs a normal application-level read operation.

SSLGetBufferedReadSize

Determines how much data is available to be read.

Write Operations

SSLWrite

Performs a normal application-level write operation.

SSLGetDatagramWriteSize

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

SSLGetMaxDatagramRecordSize

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

SSLSetMaxDatagramRecordSize

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

SSLSetDatagramHelloCookie

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

The Peer Domain Name

SSLSetPeerDomainName

Specifies the fully qualified domain name of the peer.

SSLGetPeerDomainNameLength

Determines the length of a previously set peer domain name.

SSLGetPeerDomainName

Retrieves the peer domain name specified previously.

SSLCopyRequestedPeerName

Determines the buffer size needed for the peer domain name.

SSLCopyRequestedPeerNameLength

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

Versions

SSLSetProtocolVersionMax

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

SSLSetProtocolVersionMin

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

SSLGetProtocolVersionMax

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

SSLGetProtocolVersionMin

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

SSLGetNegotiatedProtocolVersion

Obtains the negotiated protocol version of the active session.

SSLProtocol

An enumeration of valid SSL protocol versions.

Ciphers

SSLGetNumberSupportedCiphers

Determines the number of cipher suites supported.

SSLGetSupportedCiphers

Determines the values of the supported cipher suites.

SSLSetEnabledCiphers

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

SSLGetNumberEnabledCiphers

Determines the number of cipher suites currently enabled.

SSLGetEnabledCiphers

Determines which SSL cipher suites are currently enabled.

SSLGetNegotiatedCipher

Retrieves the cipher suite negotiated for this session.

SSLSetDiffieHellmanParams

Specifies Diffie-Hellman parameters for a given context.

SSLGetDiffieHellmanParams

Retrieves the Diffie-Hellman parameters for a given context.

SSLCipherSuite

A type for storing cipher suite values.

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.

SSLCopyCertificateAuthorities

Retrieves the current list of certification authorities.

Authentication

SSLAddDistinguishedName

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

SSLCopyDistinguishedNames

Retrieves the distinguished names of acceptable certification authorities.

SSLSetCertificate

Specifies this connection’s certificate or certificates.

SSLGetClientCertificateState

Retrieves the exchange status of the client certificate.

SSLCopyPeerTrust

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

SSLClientCertificateState

An enumeration of the states of client certificate exchange.

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

Secure Data

Keychain Services

Securely store small chunks of data on behalf of the user.

Secure Download

Implement Apple's Secure Download System in macOS.