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.3, 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

enum SSLProtocolSide

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

enum SSLConnectionType

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

class SSLContext

An opaque type that represents an SSL session context object.

func SSLContextGetTypeID() -> CFTypeID

Returns the Core Foundation type ID for context objects.

Context Options

func SSLGetSessionOption(SSLContext, SSLSessionOption, UnsafeMutablePointer<DarwinBoolean>) -> OSStatus

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

enum SSLSessionOption

The options that can be set for an SSL session.

Context Callbacks

func SSLSetIOFuncs(SSLContext, SSLReadFunc, SSLWriteFunc) -> OSStatus

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

typealias SSLReadFunc

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

typealias SSLWriteFunc

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

Session Configuration

func SSLSetSessionConfig(SSLContext, CFString) -> OSStatus

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

func SSLSetClientSideAuthenticate(SSLContext, SSLAuthenticate) -> OSStatus

Specifies the requirements for client-side authentication.

SSLConfig

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

enum SSLAuthenticate

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

I/O Connections

func SSLSetConnection(SSLContext, SSLConnectionRef?) -> OSStatus

Specifies an I/O connection for a specific session.

func SSLGetConnection(SSLContext, UnsafeMutablePointer<SSLConnectionRef?>) -> OSStatus

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

typealias SSLConnectionRef

A pointer to an opaque I/O connection object.

Session State

func SSLReHandshake(SSLContext) -> OSStatus

Requests renegotiation of the SSL handshake. Server only.

func SSLClose(SSLContext) -> OSStatus

Terminates the current SSL session.

func SSLSetPeerID(SSLContext, UnsafeRawPointer?, Int) -> OSStatus

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

enum SSLSessionState

The flags that represent the state of an SSL session.

func SSLSetError(SSLContext, OSStatus) -> OSStatus

Sets the status of a session context.

Read Operations

Write Operations

func SSLGetDatagramWriteSize(SSLContext, UnsafeMutablePointer<Int>) -> OSStatus

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

func SSLGetMaxDatagramRecordSize(SSLContext, UnsafeMutablePointer<Int>) -> OSStatus

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

func SSLSetMaxDatagramRecordSize(SSLContext, Int) -> OSStatus

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

func SSLSetDatagramHelloCookie(SSLContext, UnsafeRawPointer?, Int) -> OSStatus

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

The Peer Domain Name

func SSLSetPeerDomainName(SSLContext, UnsafePointer<Int8>?, Int) -> OSStatus

Specifies the fully qualified domain name of the peer.

func SSLGetPeerDomainNameLength(SSLContext, UnsafeMutablePointer<Int>) -> OSStatus

Determines the length of a previously set peer domain name.

func SSLCopyRequestedPeerNameLength(SSLContext, UnsafeMutablePointer<Int>) -> OSStatus

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

Versions

func SSLSetProtocolVersionMax(SSLContext, SSLProtocol) -> OSStatus

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

func SSLSetProtocolVersionMin(SSLContext, SSLProtocol) -> OSStatus

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

func SSLGetProtocolVersionMax(SSLContext, UnsafeMutablePointer<SSLProtocol>) -> OSStatus

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

func SSLGetProtocolVersionMin(SSLContext, UnsafeMutablePointer<SSLProtocol>) -> OSStatus

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

enum SSLProtocol

An enumeration of valid SSL protocol versions.

Application Layer Protocols

func SSLSetALPNProtocols(SSLContext, CFArray) -> OSStatus

Sets the list of supported applicaiton layer protocols.

Ciphers

func SSLSetEnabledCiphers(SSLContext, UnsafePointer<SSLCipherSuite>, Int) -> OSStatus

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

func SSLGetNumberEnabledCiphers(SSLContext, UnsafeMutablePointer<Int>) -> OSStatus

Determines the number of cipher suites currently enabled.

func SSLSetDiffieHellmanParams(SSLContext, UnsafeRawPointer?, Int) -> OSStatus

Specifies Diffie-Hellman parameters for a given context.

typealias SSLCipherSuite

A type for storing cipher suite values.

enum SSLCiphersuiteGroup

A mechanism for grouping related cipher suites.

SSL Cipher Suite Values

Recognize the set of valid SSL cipher suite values.

Root Certificates

func SSLSetCertificateAuthorities(SSLContext, CFTypeRef, Bool) -> OSStatus

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

Authentication

func SSLAddDistinguishedName(SSLContext, UnsafeRawPointer?, Int) -> OSStatus

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

func SSLCopyDistinguishedNames(SSLContext, UnsafeMutablePointer<CFArray?>) -> OSStatus

Retrieves the distinguished names of acceptable certification authorities.

func SSLSetCertificate(SSLContext, CFArray?) -> OSStatus

Specifies this connection’s certificate or certificates.

func SSLCopyPeerTrust(SSLContext, UnsafeMutablePointer<SecTrust?>) -> OSStatus

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

enum SSLClientCertificateState

An enumeration of the states of client certificate exchange.

func SSLSetOCSPResponse(SSLContext, CFData) -> OSStatus

Sets the OCSP response for the given SSL session.

func SSLSetSessionTicketsEnabled(SSLContext, Bool) -> OSStatus

Enables or disables session ticket resumption.

Result Codes

Secure Transport Result Codes

Recognize result codes specific to the secure transport API.

Legacy Operations

func SSLSetEncryptionCertificate(SSLContext, CFArray) -> OSStatus

Specifies the encryption certificates used for this connection.

Deprecated

See Also

Secure Data

Keychain Services

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