From 82b7f378b6907ab315a6e50322d2a0a8794a0aa9 Mon Sep 17 00:00:00 2001 From: bentley <> Date: Sun, 12 Oct 2014 09:33:04 +0000 Subject: Convert libssl manpages from pod to mdoc(7). libcrypto has not been started yet. ok schwarze@ miod@ --- src/lib/libssl/doc/SSL_do_handshake.3 | 110 ++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 src/lib/libssl/doc/SSL_do_handshake.3 (limited to 'src/lib/libssl/doc/SSL_do_handshake.3') diff --git a/src/lib/libssl/doc/SSL_do_handshake.3 b/src/lib/libssl/doc/SSL_do_handshake.3 new file mode 100644 index 0000000000..8e6e0a820b --- /dev/null +++ b/src/lib/libssl/doc/SSL_do_handshake.3 @@ -0,0 +1,110 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL_DO_HANDSHAKE 3 +.Os +.Sh NAME +.Nm SSL_do_handshake +.Nd perform a TLS/SSL handshake +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_do_handshake "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_do_handshake +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 +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 . +.Sh NOTES +The behaviour of +.Fn SSL_do_handshake +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_do_handshake +will only return once the handshake has been finished or an error occurred, +except for SGC (Server Gated Cryptography). +For SGC, +.Fn SSL_do_handshake +may return with \(mi1, but +.Xr SSL_get_error 3 +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +and +.Fn SSL_do_handshake +should be called again. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_do_handshake +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_do_handshake +to continue the handshake. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_do_handshake +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_do_handshake . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <0 +The TLS/SSL handshake was not successful because either a fatal error occurred +at the protocol level or a connection failure occurred. +The shutdown was not clean. +It can also occur if action is needed to continue the operation for +non-blocking +.Vt BIO Ns s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 -- cgit v1.2.3-55-g6feb