1.\" $OpenBSD: SSL_CTX_set_mode.3,v 1.4 2018/03/21 21:20:26 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: March 21 2018 $ 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 73adds the mode set via bitmask in 74.Fa mode 75to 76.Fa ctx . 77Options already set before are not cleared. 78.Pp 79.Fn SSL_set_mode 80adds the mode set via bitmask in 81.Fa mode 82to 83.Fa ssl . 84Options already set before are not cleared. 85.Pp 86.Fn SSL_CTX_get_mode 87returns the mode set for 88.Fa ctx . 89.Pp 90.Fn SSL_get_mode 91returns the mode set for 92.Fa ssl . 93.Sh NOTES 94The following mode changes are available: 95.Bl -tag -width Ds 96.It Dv SSL_MODE_ENABLE_PARTIAL_WRITE 97Allow 98.Fn SSL_write ... n 99to return 100.Ms r 101with 102.EQ 1030 < r < n 104.EN 105(i.e., report success when just a single record has been written). 106When not set (the default), 107.Xr SSL_write 3 108will only report success once the complete chunk was written. 109Once 110.Xr SSL_write 3 111returns with 112.Ms r , 113.Ms r 114bytes have been successfully written and the next call to 115.Xr SSL_write 3 116must only send the 117.Ms n \(mi r 118bytes left, imitating the behaviour of 119.Xr write 2 . 120.It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 121Make it possible to retry 122.Xr SSL_write 3 123with changed buffer location (the buffer contents must stay the same). 124This is not the default to avoid the misconception that non-blocking 125.Xr SSL_write 3 126behaves like non-blocking 127.Xr write 2 . 128.It Dv SSL_MODE_AUTO_RETRY 129Never bother the application with retries if the transport is blocking. 130If a renegotiation take place during normal operation, a 131.Xr SSL_read 3 132or 133.Xr SSL_write 3 134would return 135with \(mi1 and indicate the need to retry with 136.Dv SSL_ERROR_WANT_READ . 137In a non-blocking environment applications must be prepared to handle 138incomplete read/write operations. 139In a blocking environment, applications are not always prepared to deal with 140read/write operations returning without success report. 141The flag 142.Dv SSL_MODE_AUTO_RETRY 143will cause read/write operations to only return after the handshake and 144successful completion. 145.It Dv SSL_MODE_RELEASE_BUFFERS 146When we no longer need a read buffer or a write buffer for a given 147.Vt SSL , 148then release the memory we were using to hold it. 149Using this flag can save around 34k per idle SSL connection. 150This flag has no effect on SSL v2 connections, or on DTLS connections. 151.El 152.Sh RETURN VALUES 153.Fn SSL_CTX_set_mode 154and 155.Fn SSL_set_mode 156return the new mode bitmask after adding 157.Fa mode . 158.Pp 159.Fn SSL_CTX_get_mode 160and 161.Fn SSL_get_mode 162return 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.Fn SSL_CTX_set_mode , 169.Fn SSL_set_mode , 170.Fn SSL_CTX_get_mode , 171and 172.Fn SSL_get_mode 173first appeared in OpenSSL 0.9.4 and have been available since 174.Ox 2.6 . 175.Pp 176.Dv SSL_MODE_AUTO_RETRY 177was added in OpenSSL 0.9.6. 178