xref: /openbsd-src/lib/libssl/man/SSL_connect.3 (revision 10e00d1796876719ecd5784348f9f4f2b3dd83c5)
1*10e00d17Sschwarze.\"	$OpenBSD: SSL_connect.3,v 1.6 2018/03/27 17:35:50 schwarze Exp $
23124f983Sschwarze.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3f1a3c524Sschwarze.\"
43124f983Sschwarze.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
53124f983Sschwarze.\" Copyright (c) 2000, 2001, 2002, 2003 The OpenSSL Project.
63124f983Sschwarze.\" All rights reserved.
7f1a3c524Sschwarze.\"
83124f983Sschwarze.\" Redistribution and use in source and binary forms, with or without
93124f983Sschwarze.\" modification, are permitted provided that the following conditions
103124f983Sschwarze.\" are met:
113124f983Sschwarze.\"
123124f983Sschwarze.\" 1. Redistributions of source code must retain the above copyright
133124f983Sschwarze.\"    notice, this list of conditions and the following disclaimer.
143124f983Sschwarze.\"
153124f983Sschwarze.\" 2. Redistributions in binary form must reproduce the above copyright
163124f983Sschwarze.\"    notice, this list of conditions and the following disclaimer in
173124f983Sschwarze.\"    the documentation and/or other materials provided with the
183124f983Sschwarze.\"    distribution.
193124f983Sschwarze.\"
203124f983Sschwarze.\" 3. All advertising materials mentioning features or use of this
213124f983Sschwarze.\"    software must display the following acknowledgment:
223124f983Sschwarze.\"    "This product includes software developed by the OpenSSL Project
233124f983Sschwarze.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
243124f983Sschwarze.\"
253124f983Sschwarze.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
263124f983Sschwarze.\"    endorse or promote products derived from this software without
273124f983Sschwarze.\"    prior written permission. For written permission, please contact
283124f983Sschwarze.\"    openssl-core@openssl.org.
293124f983Sschwarze.\"
303124f983Sschwarze.\" 5. Products derived from this software may not be called "OpenSSL"
313124f983Sschwarze.\"    nor may "OpenSSL" appear in their names without prior written
323124f983Sschwarze.\"    permission of the OpenSSL Project.
333124f983Sschwarze.\"
343124f983Sschwarze.\" 6. Redistributions of any form whatsoever must retain the following
353124f983Sschwarze.\"    acknowledgment:
363124f983Sschwarze.\"    "This product includes software developed by the OpenSSL Project
373124f983Sschwarze.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
383124f983Sschwarze.\"
393124f983Sschwarze.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
403124f983Sschwarze.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
413124f983Sschwarze.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
423124f983Sschwarze.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
433124f983Sschwarze.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
443124f983Sschwarze.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
453124f983Sschwarze.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
463124f983Sschwarze.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
473124f983Sschwarze.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
483124f983Sschwarze.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
493124f983Sschwarze.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
503124f983Sschwarze.\" OF THE POSSIBILITY OF SUCH DAMAGE.
513124f983Sschwarze.\"
52*10e00d17Sschwarze.Dd $Mdocdate: March 27 2018 $
53f1a3c524Sschwarze.Dt SSL_CONNECT 3
54f1a3c524Sschwarze.Os
55f1a3c524Sschwarze.Sh NAME
56f1a3c524Sschwarze.Nm SSL_connect
57f1a3c524Sschwarze.Nd initiate the TLS/SSL handshake with a TLS/SSL server
58f1a3c524Sschwarze.Sh SYNOPSIS
59f1a3c524Sschwarze.In openssl/ssl.h
60f1a3c524Sschwarze.Ft int
61f1a3c524Sschwarze.Fn SSL_connect "SSL *ssl"
62f1a3c524Sschwarze.Sh DESCRIPTION
63f1a3c524Sschwarze.Fn SSL_connect
64f1a3c524Sschwarzeinitiates the TLS/SSL handshake with a server.
65f1a3c524SschwarzeThe communication channel must already have been set and assigned to the
66f1a3c524Sschwarze.Fa ssl
67f1a3c524Sschwarzeby setting an underlying
68f1a3c524Sschwarze.Vt BIO .
693124f983Sschwarze.Pp
70f1a3c524SschwarzeThe behaviour of
71f1a3c524Sschwarze.Fn SSL_connect
72f1a3c524Sschwarzedepends on the underlying
73f1a3c524Sschwarze.Vt BIO .
74f1a3c524Sschwarze.Pp
75f1a3c524SschwarzeIf the underlying
76f1a3c524Sschwarze.Vt BIO
77f1a3c524Sschwarzeis
78f1a3c524Sschwarze.Em blocking ,
79f1a3c524Sschwarze.Fn SSL_connect
80f1a3c524Sschwarzewill only return once the handshake has been finished or an error occurred.
81f1a3c524Sschwarze.Pp
82f1a3c524SschwarzeIf the underlying
83f1a3c524Sschwarze.Vt BIO
84f1a3c524Sschwarzeis
85f1a3c524Sschwarze.Em non-blocking ,
86f1a3c524Sschwarze.Fn SSL_connect
87f1a3c524Sschwarzewill also return when the underlying
88f1a3c524Sschwarze.Vt BIO
89f1a3c524Sschwarzecould not satisfy the needs of
90f1a3c524Sschwarze.Fn SSL_connect
91f1a3c524Sschwarzeto continue the handshake, indicating the problem with the return value \(mi1.
92f1a3c524SschwarzeIn this case a call to
93f1a3c524Sschwarze.Xr SSL_get_error 3
94f1a3c524Sschwarzewith the return value of
95f1a3c524Sschwarze.Fn SSL_connect
96f1a3c524Sschwarzewill yield
97f1a3c524Sschwarze.Dv SSL_ERROR_WANT_READ
98f1a3c524Sschwarzeor
99f1a3c524Sschwarze.Dv SSL_ERROR_WANT_WRITE .
100f1a3c524SschwarzeThe calling process then must repeat the call after taking appropriate action
101f1a3c524Sschwarzeto satisfy the needs of
102f1a3c524Sschwarze.Fn SSL_connect .
103f1a3c524SschwarzeThe action depends on the underlying
104f1a3c524Sschwarze.Vt BIO .
105f1a3c524SschwarzeWhen using a non-blocking socket, nothing is to be done, but
106f1a3c524Sschwarze.Xr select 2
107f1a3c524Sschwarzecan be used to check for the required condition.
108f1a3c524SschwarzeWhen using a buffering
109f1a3c524Sschwarze.Vt BIO ,
110f1a3c524Sschwarzelike a
111f1a3c524Sschwarze.Vt BIO
112f1a3c524Sschwarzepair, data must be written into or retrieved out of the
113f1a3c524Sschwarze.Vt BIO
114f1a3c524Sschwarzebefore being able to continue.
115f1a3c524Sschwarze.Sh RETURN VALUES
116f1a3c524SschwarzeThe following return values can occur:
117f1a3c524Sschwarze.Bl -tag -width Ds
118f1a3c524Sschwarze.It 0
119f1a3c524SschwarzeThe TLS/SSL handshake was not successful but was shut down controlled and
120f1a3c524Sschwarzeby the specifications of the TLS/SSL protocol.
121f1a3c524SschwarzeCall
122f1a3c524Sschwarze.Xr SSL_get_error 3
123f1a3c524Sschwarzewith the return value
124f1a3c524Sschwarze.Fa ret
125f1a3c524Sschwarzeto find out the reason.
126f1a3c524Sschwarze.It 1
127f1a3c524SschwarzeThe TLS/SSL handshake was successfully completed,
128f1a3c524Sschwarzeand a TLS/SSL connection has been established.
129f1a3c524Sschwarze.It <0
130f1a3c524SschwarzeThe TLS/SSL handshake was not successful, because either a fatal error occurred
131f1a3c524Sschwarzeat the protocol level or a connection failure occurred.
132f1a3c524SschwarzeThe shutdown was not clean.
133f1a3c524SschwarzeIt can also occur if action is needed to continue the operation for
134f1a3c524Sschwarzenon-blocking
135f1a3c524Sschwarze.Vt BIO Ns s .
136f1a3c524SschwarzeCall
137f1a3c524Sschwarze.Xr SSL_get_error 3
138f1a3c524Sschwarzewith the return value
139f1a3c524Sschwarze.Fa ret
140f1a3c524Sschwarzeto find out the reason.
141f1a3c524Sschwarze.El
142f1a3c524Sschwarze.Sh SEE ALSO
1435bee811bSschwarze.Xr BIO_new 3 ,
144f1a3c524Sschwarze.Xr ssl 3 ,
145f1a3c524Sschwarze.Xr SSL_accept 3 ,
146f1a3c524Sschwarze.Xr SSL_CTX_new 3 ,
147f1a3c524Sschwarze.Xr SSL_do_handshake 3 ,
148f1a3c524Sschwarze.Xr SSL_get_error 3 ,
149f1a3c524Sschwarze.Xr SSL_set_connect_state 3 ,
150f1a3c524Sschwarze.Xr SSL_shutdown 3
1518fba1ec8Sschwarze.Sh HISTORY
1528fba1ec8Sschwarze.Fn SSL_connect
153*10e00d17Sschwarzeappeared in SSLeay 0.4 or earlier and has been available since
1548fba1ec8Sschwarze.Ox 2.4 .
155