Secure Transport

This document describes the Apple platforms implementation of the following cryptographic protocols: 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.

Overview

There are no transport layer dependencies in this API. You can use it with BSD Sockets and other protocols. To use this API, you must 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.

The following terms are used in this document:

  • A client is the initiator of an SSL session. The canonical example of a client is a web browser communicating with an HTTPS URL.

  • A server is an entity that accepts requests for SSL sessions made by clients. An example is a secure web server.

  • An SSL session is bounded by calls to the functions SSLHandshake(_:) and SSLClose(_:). An active session is in some state between these two calls, inclusive.

  • An SSL session context, or SSLContext, is an opaque reference to the state associated with one session. A session context cannot be reused for multiple sessions.

Most applications need only a few of the functions in this API, which are normally called in the following sequence:

  1. Preparing for a session

    1. Call SSLNewContext (in macOS) or SSLCreateContext(_:_:_:) (in iOS and macOS) to create a new SSL session context.

    2. Write the SSLWrite(_:_:_:_:) andSSLRead(_:_:_:_:) I/O functions and call SSLSetIOFuncs(_:_:_:) to pass them to Secure Transport.

    3. Establish a connection using CFNetwork, BSD Sockets, or Open Transport. Then call SSLSetConnection(_:_:) to specify the connection to which the SSL session context applies.

    4. Call SSLSetPeerDomainName(_:_:_:) to specify the fully-qualified domain name of the peer to which you want to connect (optional but highly recommended).

    5. Call SSLSetCertificate(_:_:) to specify the certificate to be used in authentication (required for server side, optional for client).

  2. Starting a session

    • Call SSLHandshake(_:) to perform the SSL handshake and establish a secure session.

  3. Maintaining the session

  4. Ending a session

    1. Call SSLClose(_:) to close the secure session.

    2. Close the connection and dispose of the connection reference (SSLConnectionRef).

    3. If you created the context by calling SSLNewContext, call SSLDisposeContext to dispose of the SSL session context.

      If you created the context by calling SSLCreateContext(_:_:_:), release the SSL session context by calling CFRelease.

    4. If you have called SSLGetPeerCertificates to obtain any certificates, call CFRelease to release the certificate reference objects.

In many cases, it is easier to use the CFNetwork API than Secure Transport to implement a simple connection to a secure (HTTPS) URL. See CFNetwork Programming Guide for documentation of the CFNetwork API and the CFNetworkHTTPDownload sample code for an example of code that downloads data from a URL. If you specify an HTTPS URL, this routine automatically uses Secure Transport to encrypt the data stream.

For functions to manage and evaluate certificates, see Certificate, Key, and Trust Services and Certificate, Key, and Trust Services Programming Guide.

Symbols

Configuring an SSL Session

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.

func SSLSetSessionOption(SSLContext, SSLSessionOption, Bool)

Specifies an option for a specific session.

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

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

func SSLSetIOFuncs(SSLContext, SSLReadFunc, SSLWriteFunc)

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

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.

Managing an SSL Session

func SSLHandshake(SSLContext)

Performs the SSL handshake.

func SSLReHandshake(SSLContext)

Requests renegotiation of the SSL handshake. Server only.

func SSLGetNegotiatedProtocolVersion(SSLContext, UnsafeMutablePointer<SSLProtocol>)

Obtains the negotiated protocol version of the active session.

func SSLSetPeerID(SSLContext, UnsafeRawPointer?, Int)

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

func SSLGetBufferedReadSize(SSLContext, UnsafeMutablePointer<Int>)

Determines how much data is available to be read.

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

Performs a normal application-level write operation.

func SSLClose(SSLContext)

Terminates the current SSL session.

Managing 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.

Managing 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.

Managing 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 SSLSetEncryptionCertificate(SSLContext, CFArray)

Specifies the encryption certificates used for this connection.

Deprecated
func SSLCopyPeerTrust(SSLContext, UnsafeMutablePointer<SecTrust?>)

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

Managing 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.

iOS-Specific SSL Context Functions

func SSLContextGetTypeID()

Returns the CFTypeID for SSLContext objects

func SSLCreateContext(CFAllocator?, SSLProtocolSide, SSLConnectionType)

Allocates and returns a new SSLContextRef object.

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 (including all Datagram TLS record headers) 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 SSLSetDatagramHelloCookie(SSLContext, UnsafeRawPointer?, Int)

Sets the cookie value used in the Datagram TLS hello message.

func SSLSetMaxDatagramRecordSize(SSLContext, Int)

Obtains the maximum datagram record size (including all Datagram TLS record headers) allowed by the application for a given SSL context.

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.

Callbacks

SSLReadFunc

Defines a pointer to a customized read function that Secure Transport calls to read data from the connection.

SSLWriteFunc

Defines a pointer to a customized write function that Secure Transport calls to write data to the connection.

Data Types

SSLConnectionRef

Represents a pointer to an opaque I/O connection object.

SSLContext

Represents a pointer to an opaque SSL session context object.

Constants

SSLAuthenticate

Represents the requirements for client-side authentication.

SSLCipherSuite

Represents the cipher suites available.

SSLClientCertificateState

Represents the status of client certificate exchange.

SSLProtocol

Represents the SSL protocol version.

SSLSessionState

Represents the state of an SSL session.

SSLSessionOption

Options that can be set for an SSL session with the SSLSetSessionOption(_:_:_:) function.

SSLProtocolSide

Specifies whether a new SSL context created by SSLCreateContext(_:_:_:) should describe the server side or client side of a connection.

SSLConnectionType

Specifies whether a new SSL context created by SSLCreateContext(_:_:_:) is intended for use in stream-based or datagram-based communication.

Result Codes

The most common result codes returned by Secure Transport functions are listed in the table below.

Errors in the range of –9819 through –9840 are fatal errors that are detected by the peer.

var errSSLProtocol: OSStatus

SSL protocol error.

var errSSLNegotiation: OSStatus

The cipher suite negotiation failed.

var errSSLFatalAlert: OSStatus

A fatal alert was encountered.

var errSSLWouldBlock: OSStatus

Function is blocked; waiting for I/O. This is not fatal.

var errSSLSessionNotFound: OSStatus

An attempt to restore an unknown session failed.

var errSSLClosedGraceful: OSStatus

The connection closed gracefully.

var errSSLClosedAbort: OSStatus

The connection closed due to an error.

var errSSLXCertChainInvalid: OSStatus

Invalid certificate chain.

var errSSLBadCert: OSStatus

Bad certificate format.

var errSSLCrypto: OSStatus

An underlying cryptographic error was encountered.

var errSSLModuleAttach: OSStatus

Module attach failure.

var errSSLUnknownRootCert: OSStatus

Certificate chain is valid, but root is not trusted.

var errSSLNoRootCert: OSStatus

No root certificate for the certificate chain.

var errSSLCertExpired: OSStatus

The certificate chain had an expired certificate.

var errSSLCertNotYetValid: OSStatus

The certificate chain had a certificate that is not yet valid.

var errSSLClosedNoNotify: OSStatus

The server closed the session with no notification.

var errSSLBufferOverflow: OSStatus

An insufficient buffer was provided.

var errSSLBadCipherSuite: OSStatus

A bad SSL cipher suite was encountered.

var errSSLPeerUnexpectedMsg: OSStatus

An unexpected message was received.

var errSSLPeerBadRecordMac: OSStatus

A record with a bad message authentication code (MAC) was encountered.

var errSSLPeerRecordOverflow: OSStatus

A record overflow occurred.

var errSSLPeerBadCert: OSStatus

A bad certificate was encountered.

var errSSLPeerUnsupportedCert: OSStatus

An unsupported certificate format was encountered.

var errSSLPeerCertRevoked: OSStatus

The certificate was revoked.

var errSSLPeerCertExpired: OSStatus

The certificate expired.

var errSSLPeerCertUnknown: OSStatus

The certificate is unknown.

var errSSLIllegalParam: OSStatus

An illegal parameter was encountered.

var errSSLPeerUnknownCA: OSStatus

An unknown certificate authority was encountered.

var errSSLPeerDecodeError: OSStatus

A decoding error occurred.

var errSSLPeerDecryptError: OSStatus

A decryption error occurred.

var errSSLPeerExportRestriction: OSStatus

An export restriction occurred.

var errSSLPeerProtocolVersion: OSStatus

A bad protocol version was encountered.

var errSSLPeerInsufficientSecurity: OSStatus

There is insufficient security for this operation.

var errSSLPeerInternalError: OSStatus

An internal error occurred.

var errSSLPeerUserCancelled: OSStatus

The user canceled the operation.

var errSSLPeerNoRenegotiation: OSStatus

No renegotiation is allowed.

var errSSLClientCertRequested: OSStatus

The server has requested a client certificate.

var errSSLHostNameMismatch: OSStatus

The host name you connected with does not match any of the host names allowed by the certificate. This is commonly caused by an incorrect value for the kCFStreamSSLPeerName property within the dictionary associated with the stream’s kCFStreamPropertySSLSettings key.

var errSSLConnectionRefused: OSStatus

The peer dropped the connection before responding.

var errSSLDecryptionFail: OSStatus

Decryption failed. Among other causes, this may be caused by invalid data coming from the remote host, a damaged crypto key, or insufficient permission to use a key that is stored in the keychain.

var errSSLBadRecordMac: OSStatus

A record with a bad message authentication code (MAC) was encountered.

var errSSLRecordOverflow: OSStatus

A record overflow occurred.

var errSSLBadConfiguration: OSStatus

A configuration error occurred.