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

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()

Returns the Core Foundation type ID for context objects.

Context Options

func SSLSetSessionOption(SSLContext, SSLSessionOption, Bool)

Specifies options for a specific session.

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

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)

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)

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

func SSLSetClientSideAuthenticate(SSLContext, SSLAuthenticate)

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?)

Specifies an I/O connection for a specific session.

func SSLGetConnection(SSLContext, UnsafeMutablePointer<SSLConnectionRef?>)

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 SSLHandshake(SSLContext)

Performs the SSL handshake.

func SSLReHandshake(SSLContext)

Requests renegotiation of the SSL handshake. Server only.

func SSLClose(SSLContext)

Terminates the current SSL session.

func SSLSetPeerID(SSLContext, UnsafeRawPointer?, Int)

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.

Read Operations

func SSLGetBufferedReadSize(SSLContext, UnsafeMutablePointer<Int>)

Determines how much data is available to be read.

Write Operations

func SSLWrite(SSLContext, UnsafeRawPointer?, Int, UnsafeMutablePointer<Int>)

Performs a normal application-level write operation.

func SSLGetDatagramWriteSize(SSLContext, UnsafeMutablePointer<Int>)

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

func SSLGetMaxDatagramRecordSize(SSLContext, UnsafeMutablePointer<Int>)

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

func SSLSetMaxDatagramRecordSize(SSLContext, Int)

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

func SSLSetDatagramHelloCookie(SSLContext, UnsafeRawPointer?, Int)

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

The Peer Domain Name

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

Specifies the fully qualified domain name of the peer.

func SSLGetPeerDomainNameLength(SSLContext, UnsafeMutablePointer<Int>)

Determines the length of a previously set peer domain name.

func SSLCopyRequestedPeerNameLength(SSLContext, UnsafeMutablePointer<Int>)

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

Versions

func SSLSetProtocolVersionMax(SSLContext, SSLProtocol)

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

func SSLSetProtocolVersionMin(SSLContext, SSLProtocol)

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

func SSLGetProtocolVersionMax(SSLContext, UnsafeMutablePointer<SSLProtocol>)

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

func SSLGetProtocolVersionMin(SSLContext, UnsafeMutablePointer<SSLProtocol>)

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

func SSLGetNegotiatedProtocolVersion(SSLContext, UnsafeMutablePointer<SSLProtocol>)

Obtains the negotiated protocol version of the active session.

enum SSLProtocol

An enumeration of valid SSL protocol versions.

Ciphers

func SSLGetNumberSupportedCiphers(SSLContext, UnsafeMutablePointer<Int>)

Determines the number of cipher suites supported.

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

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

func SSLGetNumberEnabledCiphers(SSLContext, UnsafeMutablePointer<Int>)

Determines the number of cipher suites currently enabled.

func SSLGetNegotiatedCipher(SSLContext, UnsafeMutablePointer<SSLCipherSuite>)

Retrieves the cipher suite negotiated for this session.

func SSLSetDiffieHellmanParams(SSLContext, UnsafeRawPointer?, Int)

Specifies Diffie-Hellman parameters for a given context.

typealias SSLCipherSuite

A type for storing cipher suite values.

SSL Cipher Suite Values

Recognize the set of valid SSL cipher suite values.

Root Certificates

func SSLSetCertificateAuthorities(SSLContext, CFTypeRef, Bool)

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

func SSLCopyCertificateAuthorities(SSLContext, UnsafeMutablePointer<CFArray?>)

Retrieves the current list of certification authorities.

Authentication

func SSLAddDistinguishedName(SSLContext, UnsafeRawPointer?, Int)

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?>)

Retrieves the distinguished names of acceptable certification authorities.

func SSLSetCertificate(SSLContext, CFArray?)

Specifies this connection’s certificate or certificates.

func SSLCopyPeerTrust(SSLContext, UnsafeMutablePointer<SecTrust?>)

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

enum 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

func SSLSetEncryptionCertificate(SSLContext, CFArray)

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.