OpenBSD manual page server

NAME

SSL_CTX_set_max_early_data, SSL_set_max_early_data, SSL_SESSION_set_max_early_data, SSL_CTX_get_max_early_data, SSL_get_max_early_data, SSL_SESSION_get_max_early_data, SSL_write_early_data, SSL_read_early_data, SSL_get_early_data_status — transmit application data during the handshake

SYNOPSIS

#include <openssl/ssl.h>

int
SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_bytes);

int
SSL_set_max_early_data(SSL *ssl, uint32_t max_bytes);

int
SSL_SESSION_set_max_early_data(SSL_SESSION *session, uint32_t max_bytes);

uint32_t
SSL_CTX_get_max_early_data(const SSL_CTX *ctx);

uint32_t
SSL_get_max_early_data(const SSL *ssl);

uint32_t
SSL_SESSION_get_max_early_data(const SSL_SESSION *session);

int
SSL_write_early_data(SSL *ssl, const void *buf, size_t len, size_t *written);

int
SSL_read_early_data(SSL *ssl, void *buf, size_t maxlen, size_t *readbytes);

int
SSL_get_early_data_status(const SSL *ssl);

DESCRIPTION

In LibreSSL, these functions have no effect. They are only provided because some application programs expect the API to be available when TLSv1.3 is supported. Using these functions is strongly discouraged because they provide marginal benefit in the first place even when implemented and used as designed, because they have absurdly complicated semantics, and because when they are used, inconspicuous oversights are likely to cause serious security vulnerabilities.

If these functions are used, other TLS implementations may allow the transfer of application data during the initial handshake. Even when used as designed, security of the connection is compromised; in particular, application data is exchanged with unauthenticated peers, and there is no forward secrecy. Other downsides include an increased risk of replay attacks.

SSL_CTX_set_max_early_data(), SSL_set_max_early_data(), and SSL_SESSION_set_max_early_data() are intended to configure the maximum number of bytes per session that can be transmitted during the handshake. With LibreSSL, all arguments are ignored.

An endpoint can attempt to send application data with SSL_write_early_data() during the handshake. With LibreSSL, such attempts always fail and set *written to 0.

A server can attempt to read application data from the client using SSL_read_early_data() during the handshake. With LibreSSL, no such data is ever accepted and *readbytes is always set to 0.

RETURN VALUES

SSL_CTX_set_max_early_data(), SSL_set_max_early_data(), and SSL_SESSION_set_max_early_data() return 1 for success or 0 for failure. With LibreSSL, they always succeed.

SSL_CTX_get_max_early_data(), SSL_get_max_early_data(), and SSL_SESSION_get_max_early_data() return the maximum number of bytes of application data that will be accepted from the peer during the handshake. With LibreSSL, they always return 0.

SSL_write_early_data() returns 1 for success or 0 for failure. With LibreSSL, it always fails.

With LibreSSL, SSL_read_early_data() always returns SSL_READ_EARLY_DATA_FINISH on the server side and SSL_READ_EARLY_DATA_ERROR on the client side. SSL_READ_EARLY_DATA_SUCCESS can occur with other implementations, but not with LibreSSL.

With LibreSSL, SSL_get_early_data_status() always returns SSL_EARLY_DATA_REJECTED. With other implementations, it might also return SSL_EARLY_DATA_NOT_SENT or SSL_EARLY_DATA_ACCEPTED.

SEE ALSO

ssl(3), SSL_read(3), SSL_write(3)

STANDARDS

RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3:

Section 2.3

0-RTT data

Section 4.2.10

Early Data Indication

Section 8

0-RTT and Anti-Replay

Appendix E.5

Replay Attacks on 0-RTT

HISTORY

These functions first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 7.0.