summaryrefslogtreecommitdiff
path: root/src/lib/libssl/doc/SSL_do_handshake.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl/doc/SSL_do_handshake.3')
-rw-r--r--src/lib/libssl/doc/SSL_do_handshake.3113
1 files changed, 0 insertions, 113 deletions
diff --git a/src/lib/libssl/doc/SSL_do_handshake.3 b/src/lib/libssl/doc/SSL_do_handshake.3
deleted file mode 100644
index cc29df2583..0000000000
--- a/src/lib/libssl/doc/SSL_do_handshake.3
+++ /dev/null
@@ -1,113 +0,0 @@
1.\"
2.\" $OpenBSD: SSL_do_handshake.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
3.\"
4.Dd $Mdocdate: December 2 2014 $
5.Dt SSL_DO_HANDSHAKE 3
6.Os
7.Sh NAME
8.Nm SSL_do_handshake
9.Nd perform a TLS/SSL handshake
10.Sh SYNOPSIS
11.In openssl/ssl.h
12.Ft int
13.Fn SSL_do_handshake "SSL *ssl"
14.Sh DESCRIPTION
15.Fn SSL_do_handshake
16will wait for a SSL/TLS handshake to take place.
17If the connection is in client mode, the handshake will be started.
18The handshake routines may have to be explicitly set in advance using either
19.Xr SSL_set_connect_state 3
20or
21.Xr SSL_set_accept_state 3 .
22.Sh NOTES
23The behaviour of
24.Fn SSL_do_handshake
25depends on the underlying
26.Vt BIO .
27.Pp
28If the underlying
29.Vt BIO
30is
31.Em blocking ,
32.Fn SSL_do_handshake
33will only return once the handshake has been finished or an error occurred,
34except for SGC (Server Gated Cryptography).
35For SGC,
36.Fn SSL_do_handshake
37may return with \(mi1, but
38.Xr SSL_get_error 3
39will yield
40.Dv SSL_ERROR_WANT_READ
41or
42.Dv SSL_ERROR_WANT_WRITE
43and
44.Fn SSL_do_handshake
45should be called again.
46.Pp
47If the underlying
48.Vt BIO
49is
50.Em non-blocking ,
51.Fn SSL_do_handshake
52will also return when the underlying
53.Vt BIO
54could not satisfy the needs of
55.Fn SSL_do_handshake
56to continue the handshake.
57In this case a call to
58.Xr SSL_get_error 3
59with the return value of
60.Fn SSL_do_handshake
61will yield
62.Dv SSL_ERROR_WANT_READ
63or
64.Dv SSL_ERROR_WANT_WRITE .
65The calling process then must repeat the call after taking appropriate action
66to satisfy the needs of
67.Fn SSL_do_handshake .
68The action depends on the underlying
69.Vt BIO .
70When using a non-blocking socket, nothing is to be done, but
71.Xr select 2
72can be used to check for the required condition.
73When using a buffering
74.Vt BIO ,
75like a
76.Vt BIO
77pair, data must be written into or retrieved out of the
78.Vt BIO
79before being able to continue.
80.Sh RETURN VALUES
81The following return values can occur:
82.Bl -tag -width Ds
83.It 0
84The TLS/SSL handshake was not successful but was shut down controlled and
85by the specifications of the TLS/SSL protocol.
86Call
87.Xr SSL_get_error 3
88with the return value
89.Fa ret
90to find out the reason.
91.It 1
92The TLS/SSL handshake was successfully completed,
93and a TLS/SSL connection has been established.
94.It <0
95The TLS/SSL handshake was not successful because either a fatal error occurred
96at the protocol level or a connection failure occurred.
97The shutdown was not clean.
98It can also occur if action is needed to continue the operation for
99non-blocking
100.Vt BIO Ns s.
101Call
102.Xr SSL_get_error 3
103with the return value
104.Fa ret
105to find out the reason.
106.El
107.Sh SEE ALSO
108.Xr bio 3 ,
109.Xr ssl 3 ,
110.Xr SSL_accept 3 ,
111.Xr SSL_connect 3 ,
112.Xr SSL_get_error 3 ,
113.Xr SSL_set_connect_state 3