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