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.
Language
- Swift
- Objective-C
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(_:)andSSLClose(_:). 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:
Preparing for a session
Call
SSLNewContext(in macOS) orSSLCreateContext(_:_:_:)(in iOS and macOS) to create a new SSL session context.Write the
SSLWrite(_:_:_:_:)andSSLRead(_:_:_:_:)I/O functions and callSSLSetIOFuncs(_:_:_:)to pass them to Secure Transport.Establish a connection using CFNetwork, BSD Sockets, or Open Transport. Then call
SSLSetConnection(_:_:)to specify the connection to which the SSL session context applies.Call
SSLSetPeerDomainName(_:_:_:)to specify the fully-qualified domain name of the peer to which you want to connect (optional but highly recommended).Call
SSLSetCertificate(_:_:)to specify the certificate to be used in authentication (required for server side, optional for client).
Starting a session
Call
SSLHandshake(_:)to perform the SSL handshake and establish a secure session.
Maintaining the session
To transfer data over the secure session, Secure Transport calls your
SSLWrite(_:_:_:_:)andSSLRead(_:_:_:_:)functions as needed (see step 1b).
Ending a session
Call
SSLClose(_:)to close the secure session.Close the connection and dispose of the connection reference (
SSLConnectionRef).If you created the context by calling
SSLNewContext, callSSLDisposeContextto dispose of the SSL session context.If you created the context by calling
SSLCreateContext(_:_:_:), release the SSL session context by callingCFRelease.If you have called
SSLGetPeerCertificatesto obtain any certificates, callCFReleaseto 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.