| blob | 25a111753831be5adc970841334b1f0a8c7275cd |
1 .\" $OpenBSD: SSL_CTX_set_mode.3,v 1.3 2017/04/10 14:00:51 schwarze Exp $
2 .\" OpenSSL 8671b898 Jun 3 02:48:34 2008 +0000
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> and
5 .\" Ben Laurie <ben@openssl.org>.
6 .\" Copyright (c) 2001, 2008 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: April 10 2017 $
53 .Dt SSL_CTX_SET_MODE 3
54 .Os
55 .Sh NAME
56 .Nm SSL_CTX_set_mode ,
57 .Nm SSL_set_mode ,
58 .Nm SSL_CTX_get_mode ,
59 .Nm SSL_get_mode
60 .Nd manipulate SSL engine mode
61 .Sh SYNOPSIS
62 .In openssl/ssl.h
63 .Ft long
64 .Fn SSL_CTX_set_mode "SSL_CTX *ctx" "long mode"
65 .Ft long
66 .Fn SSL_set_mode "SSL *ssl" "long mode"
67 .Ft long
68 .Fn SSL_CTX_get_mode "SSL_CTX *ctx"
69 .Ft long
70 .Fn SSL_get_mode "SSL *ssl"
71 .Sh DESCRIPTION
72 .Fn SSL_CTX_set_mode
73 adds the mode set via bitmask in
74 .Fa mode
75 to
76 .Fa ctx .
77 Options already set before are not cleared.
78 .Pp
79 .Fn SSL_set_mode
80 adds the mode set via bitmask in
81 .Fa mode
82 to
83 .Fa ssl .
84 Options already set before are not cleared.
85 .Pp
86 .Fn SSL_CTX_get_mode
87 returns the mode set for
88 .Fa ctx .
89 .Pp
90 .Fn SSL_get_mode
91 returns the mode set for
92 .Fa ssl .
93 .Sh NOTES
94 The following mode changes are available:
95 .Bl -tag -width Ds
96 .It Dv SSL_MODE_ENABLE_PARTIAL_WRITE
97 Allow
98 .Fn SSL_write ... n
99 to return
100 .Ms r
101 with
102 .EQ
103 0 < r < n
104 .EN
105 (i.e., report success when just a single record has been written).
106 When not set (the default),
107 .Xr SSL_write 3
108 will only report success once the complete chunk was written.
109 Once
110 .Xr SSL_write 3
111 returns with
112 .Ms r ,
113 .Ms r
114 bytes have been successfully written and the next call to
115 .Xr SSL_write 3
116 must only send the
117 .Ms n \(mi r
118 bytes left, imitating the behaviour of
119 .Xr write 2 .
120 .It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
121 Make it possible to retry
122 .Xr SSL_write 3
123 with changed buffer location (the buffer contents must stay the same).
124 This is not the default to avoid the misconception that non-blocking
125 .Xr SSL_write 3
126 behaves like non-blocking
127 .Xr write 2 .
128 .It Dv SSL_MODE_AUTO_RETRY
129 Never bother the application with retries if the transport is blocking.
130 If a renegotiation take place during normal operation, a
131 .Xr SSL_read 3
132 or
133 .Xr SSL_write 3
134 would return
135 with \(mi1 and indicate the need to retry with
136 .Dv SSL_ERROR_WANT_READ .
137 In a non-blocking environment applications must be prepared to handle
138 incomplete read/write operations.
139 In a blocking environment, applications are not always prepared to deal with
140 read/write operations returning without success report.
141 The flag
142 .Dv SSL_MODE_AUTO_RETRY
143 will cause read/write operations to only return after the handshake and
144 successful completion.
145 .It Dv SSL_MODE_RELEASE_BUFFERS
146 When we no longer need a read buffer or a write buffer for a given
147 .Vt SSL ,
148 then release the memory we were using to hold it.
149 Using this flag can save around 34k per idle SSL connection.
150 This flag has no effect on SSL v2 connections, or on DTLS connections.
151 .El
152 .Sh RETURN VALUES
153 .Fn SSL_CTX_set_mode
154 and
155 .Fn SSL_set_mode
156 return the new mode bitmask after adding
157 .Fa mode .
158 .Pp
159 .Fn SSL_CTX_get_mode
160 and
161 .Fn SSL_get_mode
162 return the current bitmask.
163 .Sh SEE ALSO
164 .Xr SSL_CTX_ctrl 3 ,
165 .Xr SSL_read 3 ,
166 .Xr SSL_write 3
167 .Sh HISTORY
168 .Dv SSL_MODE_AUTO_RETRY
169 was added in OpenSSL 0.9.6.