.\"
.\"	$OpenBSD: SSL_CTX_set_mode.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
.\"
.Dd $Mdocdate: December 2 2014 $
.Dt SSL_CTX_SET_MODE 3
.Os
.Sh NAME
.Nm SSL_CTX_set_mode ,
.Nm SSL_set_mode ,
.Nm SSL_CTX_get_mode ,
.Nm SSL_get_mode
.Nd manipulate SSL engine mode
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft long
.Fn SSL_CTX_set_mode "SSL_CTX *ctx" "long mode"
.Ft long
.Fn SSL_set_mode "SSL *ssl" "long mode"
.Ft long
.Fn SSL_CTX_get_mode "SSL_CTX *ctx"
.Ft long
.Fn SSL_get_mode "SSL *ssl"
.Sh DESCRIPTION
.Fn SSL_CTX_set_mode
adds the mode set via bitmask in
.Fa mode
to
.Fa ctx .
Options already set before are not cleared.
.Pp
.Fn SSL_set_mode
adds the mode set via bitmask in
.Fa mode
to
.Fa ssl .
Options already set before are not cleared.
.Pp
.Fn SSL_CTX_get_mode
returns the mode set for
.Fa ctx .
.Pp
.Fn SSL_get_mode
returns the mode set for
.Fa ssl .
.Sh NOTES
The following mode changes are available:
.Bl -tag -width Ds
.It Dv SSL_MODE_ENABLE_PARTIAL_WRITE
Allow
.Fn SSL_write ... n
to return
.Ms r
with
.EQ
0 < r < n
.EN
(i.e., report success when just a single record has been written).
When not set (the default),
.Xr SSL_write 3
will only report success once the complete chunk was written.
Once
.Xr SSL_write 3
returns with
.Ms r ,
.Ms r
bytes have been successfully written and the next call to
.Xr SSL_write 3
must only send the
.Ms n \(mi r
bytes left, imitating the behaviour of
.Xr write 2 .
.It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
Make it possible to retry
.Xr SSL_write 3
with changed buffer location (the buffer contents must stay the same).
This is not the default to avoid the misconception that non-blocking
.Xr SSL_write 3
behaves like non-blocking
.Xr write 2 .
.It Dv SSL_MODE_AUTO_RETRY
Never bother the application with retries if the transport is blocking.
If a renegotiation take place during normal operation, a
.Xr SSL_read 3
or
.Xr SSL_write 3
would return
with \(mi1 and indicate the need to retry with
.Dv SSL_ERROR_WANT_READ .
In a non-blocking environment applications must be prepared to handle
incomplete read/write operations.
In a blocking environment, applications are not always prepared to deal with
read/write operations returning without success report.
The flag
.Dv SSL_MODE_AUTO_RETRY
will cause read/write operations to only return after the handshake and
successful completion.
.It Dv SSL_MODE_RELEASE_BUFFERS
When we no longer need a read buffer or a write buffer for a given
.Vt SSL ,
then release the memory we were using to hold it.
Released memory is either appended to a list of unused RAM chunks on the
.Vt SSL_CTX ,
or simply freed if the list of unused chunks would become longer than
.Va "SSL_CTX->freelist_max_len" ,
which defaults to 32.
Using this flag can save around 34k per idle SSL connection.
This flag has no effect on SSL v2 connections, or on DTLS connections.
.El
.Sh RETURN VALUES
.Fn SSL_CTX_set_mode
and
.Fn SSL_set_mode
return the new mode bitmask after adding
.Fa mode .
.Pp
.Fn SSL_CTX_get_mode
and
.Fn SSL_get_mode
return the current bitmask.
.Sh SEE ALSO
.Xr ssl 3 ,
.Xr SSL_read 3 ,
.Xr SSL_write 3
.Sh HISTORY
.Dv SSL_MODE_AUTO_RETRY
was added in OpenSSL 0.9.6.