summaryrefslogtreecommitdiff
path: root/src/lib/libssl/doc/SSL_write.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl/doc/SSL_write.3')
-rw-r--r--src/lib/libssl/doc/SSL_write.3175
1 files changed, 0 insertions, 175 deletions
diff --git a/src/lib/libssl/doc/SSL_write.3 b/src/lib/libssl/doc/SSL_write.3
deleted file mode 100644
index f020b8b59c..0000000000
--- a/src/lib/libssl/doc/SSL_write.3
+++ /dev/null
@@ -1,175 +0,0 @@
1.\"
2.\" $OpenBSD: SSL_write.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
3.\"
4.Dd $Mdocdate: December 2 2014 $
5.Dt SSL_WRITE 3
6.Os
7.Sh NAME
8.Nm SSL_write
9.Nd write bytes to a TLS/SSL connection
10.Sh SYNOPSIS
11.In openssl/ssl.h
12.Ft int
13.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
14.Sh DESCRIPTION
15.Fn SSL_write
16writes
17.Fa num
18bytes from the buffer
19.Fa buf
20into the specified
21.Fa ssl
22connection.
23.Sh NOTES
24If necessary,
25.Fn SSL_write
26will negotiate a TLS/SSL session, if not already explicitly performed by
27.Xr SSL_connect 3
28or
29.Xr SSL_accept 3 .
30If the peer requests a re-negotiation,
31it will be performed transparently during the
32.Fn SSL_write
33operation.
34The behaviour of
35.Fn SSL_write
36depends on the underlying
37.Vt BIO .
38.Pp
39For the transparent negotiation to succeed, the
40.Fa ssl
41must have been initialized to client or server mode.
42This is being done by calling
43.Xr SSL_set_connect_state 3
44or
45.Xr SSL_set_accept_state 3
46before the first call to an
47.Xr SSL_read 3
48or
49.Fn SSL_write
50function.
51.Pp
52If the underlying
53.Vt BIO
54is
55.Em blocking ,
56.Fn SSL_write
57will only return once the write operation has been finished or an error
58occurred, except when a renegotiation take place, in which case a
59.Dv SSL_ERROR_WANT_READ
60may occur.
61This behaviour can be controlled with the
62.Dv SSL_MODE_AUTO_RETRY
63flag of the
64.Xr SSL_CTX_set_mode 3
65call.
66.Pp
67If the underlying
68.Vt BIO
69is
70.Em non-blocking ,
71.Fn SSL_write
72will also return when the underlying
73.Vt BIO
74could not satisfy the needs of
75.Fn SSL_write
76to continue the operation.
77In this case a call to
78.Xr SSL_get_error 3
79with the return value of
80.Fn SSL_write
81will yield
82.Dv SSL_ERROR_WANT_READ
83or
84.Dv SSL_ERROR_WANT_WRITE .
85As at any time a re-negotiation is possible, a call to
86.Fn SSL_write
87can also cause read operations!
88The calling process then must repeat the call after taking appropriate action
89to satisfy the needs of
90.Fn SSL_write .
91The action depends on the underlying
92.Vt BIO .
93When using a non-blocking socket, nothing is to be done, but
94.Xr select 2
95can be used to check for the required condition.
96When using a buffering
97.Vt BIO ,
98like a
99.Vt BIO
100pair, data must be written into or retrieved out of the BIO before being able
101to continue.
102.Pp
103.Fn SSL_write
104will only return with success, when the complete contents of
105.Fa buf
106of length
107.Fa num
108have been written.
109This default behaviour can be changed with the
110.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
111option of
112.Xr SSL_CTX_set_mode 3 .
113When this flag is set,
114.Fn SSL_write
115will also return with success when a partial write has been successfully
116completed.
117In this case the
118.Fn SSL_write
119operation is considered completed.
120The bytes are sent and a new
121.Fn SSL_write
122operation with a new buffer (with the already sent bytes removed) must be
123started.
124A partial write is performed with the size of a message block, which is 16kB
125for SSLv3/TLSv1.
126.Sh WARNING
127When an
128.Fn SSL_write
129operation has to be repeated because of
130.Dv SSL_ERROR_WANT_READ
131or
132.Dv SSL_ERROR_WANT_WRITE ,
133it must be repeated with the same arguments.
134.Pp
135When calling
136.Fn SSL_write
137with
138.Fa num Ns
139=0 bytes to be sent the behaviour is undefined.
140.Sh RETURN VALUES
141The following return values can occur:
142.Bl -tag -width Ds
143.It >0
144The write operation was successful.
145The return value is the number of bytes actually written to the TLS/SSL
146connection.
147.It 0
148The write operation was not successful.
149Probably the underlying connection was closed.
150Call
151.Xr SSL_get_error 3
152with the return value to find out whether an error occurred or the connection
153was shut down cleanly
154.Pq Dv SSL_ERROR_ZERO_RETURN .
155.Pp
156SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only
157be detected whether the underlying connection was closed.
158It cannot be checked why the closure happened.
159.It <0
160The write operation was not successful, because either an error occurred or
161action must be taken by the calling process.
162Call
163.Xr SSL_get_error 3
164with the return value to find out the reason.
165.El
166.Sh SEE ALSO
167.Xr bio 3 ,
168.Xr ssl 3 ,
169.Xr SSL_accept 3 ,
170.Xr SSL_connect 3 ,
171.Xr SSL_CTX_new 3 ,
172.Xr SSL_CTX_set_mode 3 ,
173.Xr SSL_get_error 3 ,
174.Xr SSL_read 3 ,
175.Xr SSL_set_connect_state 3