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.
- iOS 5.0+
- macOS 10.2+
- tvOS 9.0+
- watchOS 2.0+
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
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 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
Establish a connection using CFNetwork, BSD Sockets, or Open Transport. Then call
SSLSetto specify the connection to which the SSL session context applies.
SSLSetto specify the fully-qualified domain name of the peer to which you want to connect (optional but highly recommended).
Peer Domain Name(_: _: _:)
SSLSetto specify the certificate to be used in authentication (required for server side, optional for client).
Starting a session
SSLHandshake(_:)to perform the SSL handshake and establish a secure session.
Maintaining the session
Ending a session
SSLClose(_:)to close the secure session.
Close the connection and dispose of the connection reference (
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.