SSL_RENEGOTIATE(3) | Library Functions Manual | SSL_RENEGOTIATE(3) |
SSL_renegotiate
,
SSL_renegotiate_abbreviated
,
SSL_renegotiate_pending
—
initiate a new TLS handshake
#include
<openssl/ssl.h>
int
SSL_renegotiate
(SSL *ssl);
int
SSL_renegotiate_abbreviated
(SSL
*ssl);
int
SSL_renegotiate_pending
(SSL
*ssl);
When called from the client side,
SSL_renegotiate
()
schedules a completely new handshake over an existing TLS connection. The
next time an I/O operation such as
SSL_read
()
or
SSL_write
()
takes place on the connection, a check is performed to confirm that it is a
suitable time to start a renegotiation. If so, a new handshake is initiated
immediately. An existing session associated with the connection is not
resumed.
This function is automatically called by SSL_read(3) and SSL_write(3) whenever the renegotiation byte count set by BIO_set_ssl_renegotiate_bytes(3) or the timeout set by BIO_set_ssl_renegotiate_timeout(3) are exceeded.
When called from the client side,
SSL_renegotiate_abbreviated
()
is similar to SSL_renegotiate
() except that resuming
the session associated with the current connection is attempted in the new
handshake.
When called from the server side,
SSL_renegotiate
()
and SSL_renegotiate_abbreviated
() behave
identically. They both schedule a request for a new handshake to be sent to
the client. The next time an I/O operation is performed, the same checks as
on the client side are performed and then, if appropriate, the request is
sent. The client may or may not respond with a new handshake and it may or
may not attempt to resume an existing session. If a new handshake is
started, it is handled transparently during any I/O function.
If a LibreSSL client receives a renegotiation request from a server, it is also handled transparently during any I/O function. The client attempts to resume the current session in the new handshake. For historical reasons, DTLS clients do not attempt to resume the session in the new handshake.
SSL_renegotiate
() and
SSL_renegotiate_abbreviated
() return 1 on success or
0 on error.
SSL_renegotiate_pending
() returns 1 if a
renegotiation or renegotiation request has been scheduled but not yet acted
on, or 0 otherwise.
ssl(3), SSL_do_handshake(3), SSL_num_renegotiations(3), SSL_read(3), SSL_write(3)
SSL_renegotiate
() first appeared in SSLeay
0.8.0 and has been available since OpenBSD 2.4.
SSL_renegotiate_pending
() first appeared
in OpenSSL 0.9.7 and has been available since OpenBSD
3.2.
SSL_renegotiate_abbreviated
() first
appeared in OpenSSL 1.0.1 and has been available since
OpenBSD 5.3.
June 12, 2019 | OpenBSD-current |