NAME
SSL_renegotiate,
SSL_renegotiate_abbreviated,
SSL_renegotiate_pending —
initiate a new TLS handshake
SYNOPSIS
#include
<openssl/ssl.h>
int
SSL_renegotiate(SSL *ssl);
int
SSL_renegotiate_abbreviated(SSL
*ssl);
int
SSL_renegotiate_pending(SSL
*ssl);
DESCRIPTION
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.
RETURN VALUES
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.
SEE ALSO
ssl(3), SSL_do_handshake(3), SSL_num_renegotiations(3), SSL_read(3), SSL_write(3)
HISTORY
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.