#use wml::openssl-macros area=docs page=SSL_do_handshake

<title>Documents, SSL_do_handshake(3)</title>

<h1>SSL_do_handshake(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
SSL_do_handshake - perform a TLS/SSL handshake

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/ssl.h&gt;
</PRE>
<PRE> int SSL_do_handshake(SSL *ssl);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>SSL_do_handshake()</CODE> will wait for a SSL/TLS handshake to take
place. If the connection is in client mode, the handshake will be started.
The handshake routines may have to be explicitly set in advance using
either
<A HREF="../ssl/SSL_set_connect_state.html#">SSL_set_connect_state(3)</A> or
<EM>SSL_set_accept_state(3)</EM>.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The behaviour of <CODE>SSL_do_handshake()</CODE> depends on the underlying
BIO.

</P>
<P>
If the underlying BIO is <STRONG>blocking</STRONG>, <CODE>SSL_do_handshake()</CODE> will only return once the handshake has
been finished or an error occurred, except for SGC (Server Gated
Cryptography). For SGC, <CODE>SSL_do_handshake()</CODE> may return with -1,
but <CODE>SSL_get_error()</CODE> will yield <STRONG>SSL_ERROR_WANT_READ/WRITE</STRONG> and <CODE>SSL_do_handshake()</CODE> should be called again.

</P>
<P>
If the underlying BIO is <STRONG>non-blocking</STRONG>, <CODE>SSL_do_handshake()</CODE> will also return when the underlying BIO
could not satisfy the needs of <CODE>SSL_do_handshake()</CODE> to continue
the handshake. In this case a call to <CODE>SSL_get_error()</CODE> with the
return value of <CODE>SSL_do_handshake()</CODE> will yield <STRONG>SSL_ERROR_WANT_READ</STRONG> or
<STRONG>SSL_ERROR_WANT_WRITE</STRONG>. The calling process then must repeat the call after taking appropriate
action to satisfy the needs of <CODE>SSL_do_handshake().</CODE> The action
depends on the underlying BIO. When using a non-blocking socket, nothing is
to be done, but <CODE>select()</CODE> can be used to check for the required
condition. When using a buffering BIO, like a BIO pair, data must be
written into or retrieved out of the BIO before being able to continue.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
The following return values can occur:

</P>
<DL>
<DT><STRONG><A NAME="item_1">1</A></STRONG><DD>
<P>
The TLS/SSL handshake was successfully completed, a TLS/SSL connection has
been established.

</P>
<DT><STRONG><A NAME="item_0">0</A></STRONG><DD>
<P>
The TLS/SSL handshake was not successful but was shut down controlled and
by the specifications of the TLS/SSL protocol. Call
<CODE>SSL_get_error()</CODE> with the return value <STRONG>ret</STRONG> to find out the reason.

</P>
<DT><STRONG><A NAME="item_lt0">&lt;0</A></STRONG><DD>
<P>
The TLS/SSL handshake was not successful because a fatal error occurred
either at the protocol level or a connection failure occurred. The shutdown
was not clean. It can also occur of action is need to continue the
operation for non-blocking BIOs. Call <CODE>SSL_get_error()</CODE> with the
return value <STRONG>ret</STRONG>
to find out the reason.

</P>
</DL>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../ssl/SSL_get_error.html#">SSL_get_error(3)</A>, <A HREF="../ssl/SSL_connect.html#">SSL_connect(3)</A>,
<A HREF="../ssl/SSL_accept.html#">SSL_accept(3)</A>, <A HREF="../ssl/ssl.html#">ssl(3)</A>, <A HREF="../crypto/bio.html#">bio(3)</A>,
<A HREF="../ssl/SSL_set_connect_state.html#">SSL_set_connect_state(3)</A>



</P>
:}