Performs the SSL handshake.


OSStatus SSLHandshake(SSLContextRef context);



An SSL session context reference.

Return Value

A result code. See Secure Transport Result Codes.


On successful return, the session is ready for normal secure communication using the functions SSLRead and SSLWrite.

If it finds any problems with the peer’s certificate chain, Secure Transport aborts the handshake. You can use the SSLCopyPeerCertificates function to see the peer’s certificate chain. This function can return a wide variety of result codes, including the following:

  • errSSLUnknownRootCert—The peer has a valid certificate chain, but the root of the chain is not a known anchor certificate.

  • errSSLNoRootCert—The peer’s certificate chain was not verifiable to a root certificate.

  • errSSLCertExpired—The peer’s certificate chain has one or more expired certificates.

  • errSSLXCertChainInvalid—The peer has an invalid certificate chain; for example, signature verification within the chain failed, or no certificates were found.

  • errSSLClientCertRequested—The server has requested a client certificate. This result is returned only if you called the SSLSetSessionOption function to set the kSSLSessionOptionBreakOnCertRequested option. After receiving this result, you must call the SSLSetCertificate function to return the client certificate, and then call SSLHandshake again to resume the handshake. Use the SSLCopyDistinguishedNames function to obtain a list of certificates acceptable to the server.

  • errSSLServerAuthCompleted—The server authentication portion of the handshake is complete. This result is returned only if you called the SSLSetSessionOption function to set the kSSLSessionOptionBreakOnServerAuth option, and provides an opportunity to perform application-specific server verification before calling SSLHandshake again to continue.

    Note that in macOS prior to version 10.8, you must also explicitly call SSLSetEnableCertVerify to disable verification.

A return value of errSSLWouldBlock indicates that the SSLHandshake function must be called again until a different result code is returned.

See Also

Session State


Requests renegotiation of the SSL handshake. Server only.


Terminates the current SSL session.


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


Retrieves the current peer ID data.


Retrieves the state of an SSL session.


The flags that represent the state of an SSL session.


Sets the status of a session context.


Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software