202 lines
8.8 KiB
HTML
Executable File
202 lines
8.8 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>SSL_CTX_set_mode</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>SSL_CTX_set_mode, SSL_CTX_clear_mode, SSL_set_mode, SSL_clear_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
|
|
long SSL_CTX_clear_mode(SSL_CTX *ctx, long mode);
|
|
long SSL_set_mode(SSL *ssl, long mode);
|
|
long SSL_clear_mode(SSL *ssl, long mode);</pre>
|
|
<pre>
|
|
long SSL_CTX_get_mode(SSL_CTX *ctx);
|
|
long SSL_get_mode(SSL *ssl);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p><code>SSL_CTX_set_mode()</code> adds the mode set via bit-mask in <strong>mode</strong> to <strong>ctx</strong>.
|
|
Options already set before are not cleared.
|
|
<code>SSL_CTX_clear_mode()</code> removes the mode set via bit-mask in <strong>mode</strong> from <strong>ctx</strong>.</p>
|
|
<p><code>SSL_set_mode()</code> adds the mode set via bit-mask in <strong>mode</strong> to <strong>ssl</strong>.
|
|
Options already set before are not cleared.
|
|
<code>SSL_clear_mode()</code> removes the mode set via bit-mask in <strong>mode</strong> from <strong>ssl</strong>.</p>
|
|
<p><code>SSL_CTX_get_mode()</code> returns the mode set for <strong>ctx</strong>.</p>
|
|
<p><code>SSL_get_mode()</code> returns the mode set for <strong>ssl</strong>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>The following mode changes are available:</p>
|
|
<dl>
|
|
<dt><strong><a name="ssl_mode_enable_partial_write" class="item">SSL_MODE_ENABLE_PARTIAL_WRITE</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Allow SSL_write_ex(..., n, &r) to return with 0 < r < n (i.e. report success
|
|
when just a single record has been written). This works in a similar way for
|
|
<code>SSL_write()</code>. When not set (the default), <code>SSL_write_ex()</code> or <code>SSL_write()</code> will only
|
|
report success once the complete chunk was written. Once <code>SSL_write_ex()</code> or
|
|
<code>SSL_write()</code> returns successful, <strong>r</strong> bytes have been written and the next call
|
|
to <code>SSL_write_ex()</code> or <code>SSL_write()</code> must only send the n-r bytes left, imitating
|
|
the behaviour of <code>write()</code>.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_accept_moving_write_buffer" class="item">SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Make it possible to retry <code>SSL_write_ex()</code> or <code>SSL_write()</code> with changed buffer
|
|
location (the buffer contents must stay the same). This is not the default to
|
|
avoid the misconception that non-blocking <code>SSL_write()</code> behaves like
|
|
non-blocking <code>write()</code>.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_auto_retry" class="item">SSL_MODE_AUTO_RETRY</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>During normal operations, non-application data records might need to be sent or
|
|
received that the application is not aware of.
|
|
If a non-application data record was processed,
|
|
<em>SSL_read_ex(3)</em> and <em>SSL_read(3)</em> can return with a failure and indicate the
|
|
need to retry with <strong>SSL_ERROR_WANT_READ</strong>.
|
|
If such a non-application data record was processed, the flag
|
|
<strong>SSL_MODE_AUTO_RETRY</strong> causes it to try to process the next record instead of
|
|
returning.</p>
|
|
<p>In a non-blocking environment applications must be prepared to handle
|
|
incomplete read/write operations.
|
|
Setting <strong>SSL_MODE_AUTO_RETRY</strong> for a non-blocking <strong>BIO</strong> will process
|
|
non-application data records until either no more data is available or
|
|
an application data record has been processed.</p>
|
|
<p>In a blocking environment, applications are not always prepared to
|
|
deal with the functions returning intermediate reports such as retry
|
|
requests, and setting the <strong>SSL_MODE_AUTO_RETRY</strong> flag will cause the functions
|
|
to only return after successfully processing an application data record or a
|
|
failure.</p>
|
|
<p>Turning off <strong>SSL_MODE_AUTO_RETRY</strong> can be useful with blocking <strong>BIO</strong>s in case
|
|
they are used in combination with something like <code>select()</code> or <code>poll()</code>.
|
|
Otherwise the call to <code>SSL_read()</code> or <code>SSL_read_ex()</code> might hang when a
|
|
non-application record was sent and no application data was sent.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_release_buffers" class="item">SSL_MODE_RELEASE_BUFFERS</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>When we no longer need a read buffer or a write buffer for a given SSL,
|
|
then release the memory we were using to hold it.
|
|
Using this flag can
|
|
save around 34k per idle SSL connection.
|
|
This flag has no effect on SSL v2 connections, or on DTLS connections.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_send_fallback_scsv" class="item">SSL_MODE_SEND_FALLBACK_SCSV</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Send TLS_FALLBACK_SCSV in the ClientHello.
|
|
To be set only by applications that reconnect with a downgraded protocol
|
|
version; see draft-ietf-tls-downgrade-scsv-00 for details.</p>
|
|
<p>DO NOT ENABLE THIS if your application attempts a normal handshake.
|
|
Only use this in explicit fallback retries, following the guidance
|
|
in draft-ietf-tls-downgrade-scsv-00.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_async" class="item">SSL_MODE_ASYNC</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Enable asynchronous processing. TLS I/O operations may indicate a retry with
|
|
SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
|
|
used to perform cryptographic operations. See <em>SSL_get_error(3)</em>.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_no_ktls_tx" class="item">SSL_MODE_NO_KTLS_TX</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Disable the use of the kernel TLS egress data-path.
|
|
By default kernel TLS is enabled if it is supported by the negotiated ciphersuites
|
|
and extensions and OpenSSL has been compiled with support for it.
|
|
The kernel TLS data-path implements the record layer,
|
|
and the crypto algorithm. The kernel will utilize the best hardware
|
|
available for crypto. Using the kernel data-path should reduce the memory
|
|
footprint of OpenSSL because no buffering is required. Also, the throughput
|
|
should improve because data copy is avoided when user data is encrypted into
|
|
kernel memory instead of the usual encrypt than copy to kernel.</p>
|
|
<p>Kernel TLS might not support all the features of OpenSSL. For instance,
|
|
renegotiation, and setting the maximum fragment size is not possible as of
|
|
Linux 4.20.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_mode_dtls_sctp_label_length_bug" class="item">SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Older versions of OpenSSL had a bug in the computation of the label length
|
|
used for computing the endpoint-pair shared secret. The bug was that the
|
|
terminating zero was included in the length of the label. Setting this option
|
|
enables this behaviour to allow interoperability with such broken
|
|
implementations. Please note that setting this option breaks interoperability
|
|
with correct implementations. This option only applies to DTLS over SCTP.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>All modes are off by default except for SSL_MODE_AUTO_RETRY which is on by
|
|
default since 1.1.1.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>SSL_CTX_set_mode()</code> and <code>SSL_set_mode()</code> return the new mode bit-mask
|
|
after adding <strong>mode</strong>.</p>
|
|
<p><code>SSL_CTX_get_mode()</code> and <code>SSL_get_mode()</code> return the current bit-mask.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ssl(7)</em>, <em>SSL_read_ex(3)</em>, <em>SSL_read(3)</em>, <em>SSL_write_ex(3)</em> or
|
|
<em>SSL_write(3)</em>, <em>SSL_get_error(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>SSL_MODE_ASYNC was added in OpenSSL 1.1.0.
|
|
SSL_MODE_NO_KTLS_TX was added in OpenSSL 3.0.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|