SSL_RENEGOTIATE(3) | Library Functions Manual | SSL_RENEGOTIATE(3)

# NAME

`SSL_renegotiate`, `SSL_renegotiate_abbreviated`, `SSL_renegotiate_pending` — initiate a new TLS handshake

# SYNOPSIS

library “libssl” libcrypto
`#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.

June 8, 2025 | Debian