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