Function

SSLHandshake

Performs the SSL handshake.

Declaration

OSStatus SSLHandshake(SSLContextRef context);

Parameters

context

An SSL session context reference.

Return Value

A result code. See Secure Transport Result Codes.

Discussion

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

SSLReHandshake

Requests renegotiation of the SSL handshake. Server only.

SSLClose

Terminates the current SSL session.

SSLSetPeerID

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

SSLGetPeerID

Retrieves the current peer ID data.

SSLGetSessionState

Retrieves the state of an SSL session.

SSLSessionState

The flags that represent the state of an SSL session.

SSLSetError

Sets the status of a session context.