Performs the SSL handshake.


func SSLHandshake(_ context: SSLContext) -> OSStatus



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

func SSLReHandshake(SSLContext) -> OSStatus

Requests renegotiation of the SSL handshake. Server only.

func SSLClose(SSLContext) -> OSStatus

Terminates the current SSL session.

func SSLSetPeerID(SSLContext, UnsafeRawPointer?, Int) -> OSStatus

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.

func SSLSetError(SSLContext, OSStatus) -> OSStatus

Sets the status of a session context.