lib/libssl/man/SSL_write.3

   1 .\"     $OpenBSD: SSL_write.3,v 1.3 2016/12/06 12:24:33 schwarze Exp $
   2 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2000, 2001, 2002 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: December 6 2016 $
  52 .Dt SSL_WRITE 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_write
  56 .Nd write bytes to a TLS/SSL connection
  57 .Sh SYNOPSIS
  58 .In openssl/ssl.h
  59 .Ft int
  60 .Fn SSL_write "SSL *ssl" "const void *buf" "int num"
  61 .Sh DESCRIPTION
  62 .Fn SSL_write
  63 writes
  64 .Fa num
  65 bytes from the buffer
  66 .Fa buf
  67 into the specified
  68 .Fa ssl
  69 connection.
  70 .Pp
  71 If necessary,
  72 .Fn SSL_write
  73 will negotiate a TLS/SSL session, if not already explicitly performed by
  74 .Xr SSL_connect 3
  75 or
  76 .Xr SSL_accept 3 .
  77 If the peer requests a re-negotiation,
  78 it will be performed transparently during the
  79 .Fn SSL_write
  80 operation.
  81 The behaviour of
  82 .Fn SSL_write
  83 depends on the underlying
  84 .Vt BIO .
  85 .Pp
  86 For the transparent negotiation to succeed, the
  87 .Fa ssl
  88 must have been initialized to client or server mode.
  89 This is being done by calling
  90 .Xr SSL_set_connect_state 3
  91 or
  92 .Xr SSL_set_accept_state 3
  93 before the first call to an
  94 .Xr SSL_read 3
  95 or
  96 .Fn SSL_write
  97 function.
  98 .Pp
  99 If the underlying
 100 .Vt BIO
 101 is
 102 .Em blocking ,
 103 .Fn SSL_write
 104 will only return once the write operation has been finished or an error
 105 occurred, except when a renegotiation take place, in which case a
 106 .Dv SSL_ERROR_WANT_READ
 107 may occur.
 108 This behaviour can be controlled with the
 109 .Dv SSL_MODE_AUTO_RETRY
 110 flag of the
 111 .Xr SSL_CTX_set_mode 3
 112 call.
 113 .Pp
 114 If the underlying
 115 .Vt BIO
 116 is
 117 .Em non-blocking ,
 118 .Fn SSL_write
 119 will also return when the underlying
 120 .Vt BIO
 121 could not satisfy the needs of
 122 .Fn SSL_write
 123 to continue the operation.
 124 In this case a call to
 125 .Xr SSL_get_error 3
 126 with the return value of
 127 .Fn SSL_write
 128 will yield
 129 .Dv SSL_ERROR_WANT_READ
 130 or
 131 .Dv SSL_ERROR_WANT_WRITE .
 132 As at any time a re-negotiation is possible, a call to
 133 .Fn SSL_write
 134 can also cause read operations!
 135 The calling process then must repeat the call after taking appropriate action
 136 to satisfy the needs of
 137 .Fn SSL_write .
 138 The action depends on the underlying
 139 .Vt BIO .
 140 When using a non-blocking socket, nothing is to be done, but
 141 .Xr select 2
 142 can be used to check for the required condition.
 143 When using a buffering
 144 .Vt BIO ,
 145 like a
 146 .Vt BIO
 147 pair, data must be written into or retrieved out of the BIO before being able
 148 to continue.
 149 .Pp
 150 .Fn SSL_write
 151 will only return with success when the complete contents of
 152 .Fa buf
 153 of length
 154 .Fa num
 155 have been written.
 156 This default behaviour can be changed with the
 157 .Dv SSL_MODE_ENABLE_PARTIAL_WRITE
 158 option of
 159 .Xr SSL_CTX_set_mode 3 .
 160 When this flag is set,
 161 .Fn SSL_write
 162 will also return with success when a partial write has been successfully
 163 completed.
 164 In this case the
 165 .Fn SSL_write
 166 operation is considered completed.
 167 The bytes are sent and a new
 168 .Fn SSL_write
 169 operation with a new buffer (with the already sent bytes removed) must be
 170 started.
 171 A partial write is performed with the size of a message block,
 172 which is 16kB.
 173 .Pp
 174 When an
 175 .Fn SSL_write
 176 operation has to be repeated because
 177 .Xr SSL_get_error 3
 178 returned
 179 .Dv SSL_ERROR_WANT_READ
 180 or
 181 .Dv SSL_ERROR_WANT_WRITE ,
 182 it must be repeated with the same arguments.
 183 .Pp
 184 When calling
 185 .Fn SSL_write
 186 with
 187 .Fa num Ns =0
 188 bytes to be sent, the behaviour is undefined.
 189 .Sh RETURN VALUES
 190 The following return values can occur:
 191 .Bl -tag -width Ds
 192 .It >0
 193 The write operation was successful.
 194 The return value is the number of bytes actually written to the TLS/SSL
 195 connection.
 196 .It 0
 197 The write operation was not successful.
 198 Probably the underlying connection was closed.
 199 Call
 200 .Xr SSL_get_error 3
 201 with the return value to find out whether an error occurred or the connection
 202 was shut down cleanly
 203 .Pq Dv SSL_ERROR_ZERO_RETURN .
 204 .It <0
 205 The write operation was not successful, because either an error occurred or
 206 action must be taken by the calling process.
 207 Call
 208 .Xr SSL_get_error 3
 209 with the return value to find out the reason.
 210 .El
 211 .Sh SEE ALSO
 212 .Xr BIO_new 3 ,
 213 .Xr ssl 3 ,
 214 .Xr SSL_accept 3 ,
 215 .Xr SSL_connect 3 ,
 216 .Xr SSL_CTX_new 3 ,
 217 .Xr SSL_CTX_set_mode 3 ,
 218 .Xr SSL_get_error 3 ,
 219 .Xr SSL_read 3 ,
 220 .Xr SSL_set_connect_state 3