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.