1.\" $OpenBSD: SSL_read_early_data.3,v 1.2 2020/09/21 15:18:13 schwarze Exp $ 2.\" content checked up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 3.\" 4.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: September 21 2020 $ 19.Dt SSL_READ_EARLY_DATA 3 20.Os 21.Sh NAME 22.Nm SSL_CTX_set_max_early_data , 23.Nm SSL_set_max_early_data , 24.Nm SSL_SESSION_set_max_early_data , 25.Nm SSL_CTX_get_max_early_data , 26.Nm SSL_get_max_early_data , 27.Nm SSL_SESSION_get_max_early_data , 28.Nm SSL_write_early_data , 29.Nm SSL_read_early_data , 30.Nm SSL_get_early_data_status 31.Nd transmit application data during the handshake 32.Sh SYNOPSIS 33.In openssl/ssl.h 34.Ft int 35.Fo SSL_CTX_set_max_early_data 36.Fa "SSL_CTX *ctx" 37.Fa "uint32_t max_bytes" 38.Fc 39.Ft int 40.Fo SSL_set_max_early_data 41.Fa "SSL *ssl" 42.Fa "uint32_t max_bytes" 43.Fc 44.Ft int 45.Fo SSL_SESSION_set_max_early_data 46.Fa "SSL_SESSION *session" 47.Fa "uint32_t max_bytes" 48.Fc 49.Ft uint32_t 50.Fo SSL_CTX_get_max_early_data 51.Fa "const SSL_CTX *ctx" 52.Fc 53.Ft uint32_t 54.Fo SSL_get_max_early_data 55.Fa "const SSL *ssl" 56.Fc 57.Ft uint32_t 58.Fo SSL_SESSION_get_max_early_data 59.Fa "const SSL_SESSION *session" 60.Fc 61.Ft int 62.Fo SSL_write_early_data 63.Fa "SSL *ssl" 64.Fa "const void *buf" 65.Fa "size_t len" 66.Fa "size_t *written" 67.Fc 68.Ft int 69.Fo SSL_read_early_data 70.Fa "SSL *ssl" 71.Fa "void *buf" 72.Fa "size_t maxlen" 73.Fa "size_t *readbytes" 74.Fc 75.Ft int 76.Fo SSL_get_early_data_status 77.Fa "const SSL *ssl" 78.Fc 79.Sh DESCRIPTION 80In LibreSSL, these functions have no effect. 81They are only provided because some application programs 82expect the API to be available when TLSv1.3 is supported. 83Using these functions is strongly discouraged because they provide 84marginal benefit in the first place even when implemented and 85used as designed, because they have absurdly complicated semantics, 86and because when they are used, inconspicuous oversights are likely 87to cause serious security vulnerabilities. 88.Pp 89If these functions are used, other TLS implementations 90may allow the transfer of application data during the inital handshake. 91Even when used as designed, security of the connection is compromised; 92in particular, application data is exchanged with unauthenticated peers, 93and there is no forward secrecy. 94Other downsides include an increased risk of replay attacks. 95.Pp 96.Fn SSL_CTX_set_max_early_data , 97.Fn SSL_set_max_early_data , 98and 99.Fn SSL_SESSION_set_max_early_data 100are intended to configure the maximum number of bytes per session 101that can be transmitted during the handshake. 102With LibreSSL, all arguments are ignored. 103.Pp 104An endpoint can attempt to send application data with 105.Fn SSL_write_early_data 106during the handshake. 107With LibreSSL, such attempts always fail and set 108.Pf * Fa written 109to 0. 110.Pp 111A server can attempt to read application data from the client using 112.Fn SSL_read_early_data 113during the handshake. 114With LibreSSL, no such data is ever accepted and 115.Pf * Fa readbytes 116is always set to 0. 117.Sh RETURN VALUES 118.Fn SSL_CTX_set_max_early_data , 119.Fn SSL_set_max_early_data , 120and 121.Fn SSL_SESSION_set_max_early_data 122return 1 for success or 0 for failure. 123With LibreSSL, they always succeed. 124.Pp 125.Fn SSL_CTX_get_max_early_data , 126.Fn SSL_get_max_early_data , 127and 128.Fn SSL_SESSION_get_max_early_data 129return the maximum number of bytes of application data 130that will be accepted from the peer during the handshake. 131With LibreSSL, they always return 0. 132.Pp 133.Fn SSL_write_early_data 134returns 1 for success or 0 for failure. 135With LibreSSL, it always fails. 136.Pp 137With LibreSSL, 138.Fn SSL_read_early_data 139always returns 140.Dv SSL_READ_EARLY_DATA_FINISH 141on the server side and 142.Dv SSL_READ_EARLY_DATA_ERROR 143on the client side. 144.Dv SSL_READ_EARLY_DATA_SUCCESS 145can occur with other implementations, but not with LibreSSL. 146.Pp 147With LibreSSL, 148.Fn SSL_get_early_data_status 149always returns 150.Dv SSL_EARLY_DATA_REJECTED . 151With other implementations, it might also return 152.Dv SSL_EARLY_DATA_NOT_SENT 153or 154.Dv SSL_EARLY_DATA_ACCEPTED . 155.Sh SEE ALSO 156.Xr ssl 3 , 157.Xr SSL_read 3 , 158.Xr SSL_write 3 159.Sh STANDARDS 160RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3: 161.Bl -tag -width "section 4.2.10" -compact 162.It Section 2.3 1630-RTT data 164.It Section 4.2.10 165Early Data Indication 166.It Section 8 1670-RTT and Anti-Replay 168.It Appendix E.5 169Replay Attacks on 0-RTT 170.El 171.Sh HISTORY 172These functions first appeared in OpenSSL 1.1.1 173and have been available since 174.Ox 6.9 . 175