Rename SSL_read_early() to SSL_read_early_data()
This is for consistency with the rest of the API where all the functions
are called *early_data*.
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2737)
diff --git a/apps/s_server.c b/apps/s_server.c
index 8d15764..3190eab 100644
--- a/apps/s_server.c
+++ b/apps/s_server.c
@@ -2211,13 +2211,13 @@
}
if (early_data) {
- int write_header = 1, edret = SSL_READ_EARLY_ERROR;
+ int write_header = 1, edret = SSL_READ_EARLY_DATA_ERROR;
size_t readbytes;
- while (edret != SSL_READ_EARLY_FINISH) {
+ while (edret != SSL_READ_EARLY_DATA_FINISH) {
for (;;) {
- edret = SSL_read_early(con, buf, bufsize, &readbytes);
- if (edret != SSL_READ_EARLY_ERROR)
+ edret = SSL_read_early_data(con, buf, bufsize, &readbytes);
+ if (edret != SSL_READ_EARLY_DATA_ERROR)
break;
switch (SSL_get_error(con, 0)) {
diff --git a/doc/man3/SSL_read_early.pod b/doc/man3/SSL_read_early.pod
index 75dee05..232f386 100644
--- a/doc/man3/SSL_read_early.pod
+++ b/doc/man3/SSL_read_early.pod
@@ -8,7 +8,7 @@
SSL_CTX_get_max_early_data,
SSL_SESSION_get_max_early_data,
SSL_write_early,
-SSL_read_early,
+SSL_read_early_data,
SSL_get_early_data_status
- functions for sending and receiving early data
@@ -24,7 +24,7 @@
int SSL_write_early(SSL *s, const void *buf, size_t num, size_t *written);
- int SSL_read_early(SSL *s, void *buf, size_t num, size_t *readbytes);
+ int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes);
int SSL_get_early_data_status(const SSL *s);
@@ -94,60 +94,62 @@
was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function
may be called by either the client or the server.
-A server uses the SSL_read_early() function to receive early data on a
+A server uses the SSL_read_early_data() function to receive early data on a
connection. As for SSL_write_early() this must be the first IO function called
on a connection, i.e. it must occur before any calls to L<SSL_write_ex(3)>,
L<SSL_read_ex(3)>, L<SSL_accept(3)>, L<SSL_do_handshake(3)>, or other similar
functions.
-SSL_read_early() works in the same way as L<SSL_read_ex(3)> except for the
+SSL_read_early_data() works in the same way as L<SSL_read_ex(3)> except for the
differences noted here. Refer to the L<SSL_read_ex(3)> documentation for full
details.
-SSL_read_early() may return 3 possible values:
+SSL_read_early_data() may return 3 possible values:
=over 4
-=item SSL_READ_EARLY_ERROR
+=item SSL_READ_EARLY_DATA_ERROR
This indicates an IO or some other error occured. This should be treated in the
same way as a 0 return value from L<SSL_read_ex(3)>.
-=item SSL_READ_EARLY_SUCCESS
+=item SSL_READ_EARLY_DATA_SUCCESS
This indicates that early data was successfully read. This should be treated in
the same way as a 1 return value from L<SSL_read_ex(3)>. You should continue to
-call SSL_read_early() to read more data.
+call SSL_read_early_data() to read more data.
-=item SSL_READ_EARLY_FINISH
+=item SSL_READ_EARLY_DATA_FINISH
This indicates that no more early data can be read. It may be returned on the
-first call to SSL_read_early() if the client has not sent any early data, or
-if the early data was rejected.
+first call to SSL_read_early_data() if the client has not sent any early data,
+or if the early data was rejected.
=back
Once the initial SSL_write_early() call has completed successfully the client
may interleave calls to L<SSL_write_ex(3)> and L<SSL_write(3)> with calls to
-SSL_read_early() as required. As noted above data sent via L<SSL_write_ex(3)> or
-L<SSL_write(3)> in this way is sent to an unauthenticated client.
+SSL_read_early_data() as required. As noted above data sent via
+L<SSL_write_ex(3)> or L<SSL_write(3)> in this way is sent to an unauthenticated
+client.
-Servers must not call L<SSL_read_ex(3)> or L<SSL_read(3)> until SSL_read_early()
-has returned with SSL_READ_EARLY_FINISH. Once it has done so the connection to
-the client still needs to be completed. Complete the connection by calling a
-function such as L<SSL_accept(3)> or L<SSL_do_handshake(3)>. Alternatively you
-can call a standard read function such as L<SSL_read_ex(3)>, which will
-transparently complete the connection and read the requested data. Note that it
-is an error to attempt to complete the connection before SSL_read_early() has
-returned SSL_READ_EARLY_FINISH.
+Servers must not call L<SSL_read_ex(3)> or L<SSL_read(3)> until
+SSL_read_early_data() has returned with SSL_READ_EARLY_DATA_FINISH. Once it has
+done so the connection to the client still needs to be completed. Complete the
+connection by calling a function such as L<SSL_accept(3)> or
+L<SSL_do_handshake(3)>. Alternatively you can call a standard read function such
+as L<SSL_read_ex(3)>, which will transparently complete the connection and read
+the requested data. Note that it is an error to attempt to complete the
+connection before SSL_read_early_data() has returned SSL_READ_EARLY_DATA_FINISH.
-Only servers may call SSL_read_early().
+Only servers may call SSL_read_early_data().
-Calls to SSL_read_early() may, in certain circumstances, complete the connection
-immediately without further need to call a function such as L<SSL_accept(3)>.
-Applications can test for this by calling L<SSL_is_init_finished(3)>.
-Alternatively, applications may choose to call L<SSL_accept(3)> anway. Such a
-call will successfully return immediately with no further action taken.
+Calls to SSL_read_early_data() may, in certain circumstances, complete the
+connection immediately without further need to call a function such as
+L<SSL_accept(3)>. Applications can test for this by calling
+L<SSL_is_init_finished(3)>. Alternatively, applications may choose to call
+L<SSL_accept(3)> anway. Such a call will successfully return immediately with no
+further action taken.
When a session is created between a server and a client the server will specify
the maximum amount of any early data that it will accept on any future
@@ -167,10 +169,10 @@
SSL_write_early() returns 1 for success or 0 for failure. In the event of a
failure call L<SSL_get_error(3)> to determine the correct course of action.
-SSL_read_early() returns SSL_READ_EARLY_ERROR for failure,
-SSL_READ_EARLY_SUCCESS for success with more data to read and
-SSL_READ_EARLY_FINISH for no more to data be read. In the event of a failure
-call L<SSL_get_error(3)> to determine the correct course of action.
+SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
+SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
+SSL_READ_EARLY_DATA_FINISH for no more to data be read. In the event of a
+failure call L<SSL_get_error(3)> to determine the correct course of action.
SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and
SSL_SESSION_get_max_early_data() return the maximum number of early data bytes
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index 8445ccd..1829c5b 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -1615,11 +1615,12 @@
__owur int SSL_read(SSL *ssl, void *buf, int num);
__owur int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
-# define SSL_READ_EARLY_ERROR 0
-# define SSL_READ_EARLY_SUCCESS 1
-# define SSL_READ_EARLY_FINISH 2
+# define SSL_READ_EARLY_DATA_ERROR 0
+# define SSL_READ_EARLY_DATA_SUCCESS 1
+# define SSL_READ_EARLY_DATA_FINISH 2
-__owur int SSL_read_early(SSL *s, void *buf, size_t num, size_t *readbytes);
+__owur int SSL_read_early_data(SSL *s, void *buf, size_t num,
+ size_t *readbytes);
__owur int SSL_peek(SSL *ssl, void *buf, int num);
__owur int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
__owur int SSL_write(SSL *ssl, const void *buf, int num);
@@ -2270,7 +2271,7 @@
# define SSL_F_SSL_PEEK_EX 432
# define SSL_F_SSL_PEEK_INTERNAL 522
# define SSL_F_SSL_READ 223
-# define SSL_F_SSL_READ_EARLY 529
+# define SSL_F_SSL_READ_EARLY_DATA 529
# define SSL_F_SSL_READ_EX 434
# define SSL_F_SSL_READ_INTERNAL 523
# define SSL_F_SSL_RENEGOTIATE 516
diff --git a/ssl/ssl_err.c b/ssl/ssl_err.c
index c622ef3..0a23218 100644
--- a/ssl/ssl_err.c
+++ b/ssl/ssl_err.c
@@ -206,7 +206,7 @@
{ERR_FUNC(SSL_F_SSL_PEEK_EX), "SSL_peek_ex"},
{ERR_FUNC(SSL_F_SSL_PEEK_INTERNAL), "ssl_peek_internal"},
{ERR_FUNC(SSL_F_SSL_READ), "SSL_read"},
- {ERR_FUNC(SSL_F_SSL_READ_EARLY), "SSL_read_early"},
+ {ERR_FUNC(SSL_F_SSL_READ_EARLY_DATA), "SSL_read_early_data"},
{ERR_FUNC(SSL_F_SSL_READ_EX), "SSL_read_ex"},
{ERR_FUNC(SSL_F_SSL_READ_INTERNAL), "ssl_read_internal"},
{ERR_FUNC(SSL_F_SSL_RENEGOTIATE), "SSL_renegotiate"},
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 5ec116e..9635989 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -1607,20 +1607,21 @@
return ret;
}
-int SSL_read_early(SSL *s, void *buf, size_t num, size_t *readbytes)
+int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes)
{
int ret;
if (!s->server) {
- SSLerr(SSL_F_SSL_READ_EARLY, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED);
- return SSL_READ_EARLY_ERROR;
+ SSLerr(SSL_F_SSL_READ_EARLY_DATA, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED);
+ return SSL_READ_EARLY_DATA_ERROR;
}
switch (s->early_data_state) {
case SSL_EARLY_DATA_NONE:
if (!SSL_in_before(s)) {
- SSLerr(SSL_F_SSL_READ_EARLY, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED);
- return SSL_READ_EARLY_ERROR;
+ SSLerr(SSL_F_SSL_READ_EARLY_DATA,
+ ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED);
+ return SSL_READ_EARLY_DATA_ERROR;
}
/* fall through */
@@ -1630,7 +1631,7 @@
if (ret <= 0) {
/* NBIO or error */
s->early_data_state = SSL_EARLY_DATA_ACCEPT_RETRY;
- return SSL_READ_EARLY_ERROR;
+ return SSL_READ_EARLY_DATA_ERROR;
}
/* fall through */
@@ -1646,17 +1647,18 @@
if (ret > 0 || (ret <= 0 && s->early_data_state
!= SSL_EARLY_DATA_FINISHED_READING)) {
s->early_data_state = SSL_EARLY_DATA_READ_RETRY;
- return ret > 0 ? SSL_READ_EARLY_SUCCESS : SSL_READ_EARLY_ERROR;
+ return ret > 0 ? SSL_READ_EARLY_DATA_SUCCESS
+ : SSL_READ_EARLY_DATA_ERROR;
}
} else {
s->early_data_state = SSL_EARLY_DATA_FINISHED_READING;
}
*readbytes = 0;
- return SSL_READ_EARLY_FINISH;
+ return SSL_READ_EARLY_DATA_FINISH;
default:
- SSLerr(SSL_F_SSL_READ_EARLY, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED);
- return SSL_READ_EARLY_ERROR;
+ SSLerr(SSL_F_SSL_READ_EARLY_DATA, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED);
+ return SSL_READ_EARLY_DATA_ERROR;
}
}
diff --git a/test/sslapitest.c b/test/sslapitest.c
index 331790b..1cd850c 100644
--- a/test/sslapitest.c
+++ b/test/sslapitest.c
@@ -1610,8 +1610,8 @@
goto end;
}
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_SUCCESS
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_SUCCESS
|| readbytes != strlen(MSG1)
|| memcmp(MSG1, buf, strlen(MSG1))) {
printf("Failed reading early data message 1\n");
@@ -1648,8 +1648,8 @@
}
/* Server should still be able read early data after writing normal data */
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_SUCCESS
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_SUCCESS
|| readbytes != strlen(MSG3)
|| memcmp(MSG3, buf, strlen(MSG3))) {
printf("Failed reading early data message 3\n");
@@ -1686,8 +1686,8 @@
}
/* Server should be told that there is no more early data */
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_FINISH
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_FINISH
|| readbytes != 0) {
printf("Failed finishing read of early data\n");
goto end;
@@ -1707,8 +1707,8 @@
}
ERR_clear_error();
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_ERROR) {
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_ERROR) {
printf("Unexpected success reading early data\n");
goto end;
}
@@ -1751,8 +1751,8 @@
goto end;
}
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_SUCCESS
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_SUCCESS
|| readbytes != strlen(MSG1)
|| memcmp(MSG1, buf, strlen(MSG1))) {
printf("Failed reading early data message 1\n");
@@ -1785,8 +1785,8 @@
}
ERR_clear_error();
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_ERROR) {
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_ERROR) {
printf("Unexpected success reading early data (2)\n");
goto end;
}
@@ -1854,8 +1854,8 @@
}
/* Server should reject the early data and skip over it */
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_FINISH
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_FINISH
|| readbytes != 0) {
printf("Failed reading early data\n");
goto end;
@@ -1926,8 +1926,8 @@
}
/* Server should detect that early data has not been sent */
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_FINISH
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_FINISH
|| readbytes != 0) {
printf("Failed reading early data\n");
goto end;
@@ -2106,11 +2106,11 @@
/*
* Server should do TLSv1.2 handshake. First it will block waiting for more
- * messages from client after ServerDone. Then SSL_read_early should finish
- * and detect that early data has not been sent
+ * messages from client after ServerDone. Then SSL_read_early_data should
+ * finish and detect that early data has not been sent
*/
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_ERROR) {
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_ERROR) {
printf("Unexpected success reading early data\n");
goto end;
}
@@ -2124,8 +2124,8 @@
goto end;
}
- if (SSL_read_early(serverssl, buf, sizeof(buf), &readbytes)
- != SSL_READ_EARLY_FINISH
+ if (SSL_read_early_data(serverssl, buf, sizeof(buf), &readbytes)
+ != SSL_READ_EARLY_DATA_FINISH
|| readbytes != 0) {
printf("Failed reading early data\n");
goto end;
diff --git a/util/libssl.num b/util/libssl.num
index fdc66d7..e288625 100644
--- a/util/libssl.num
+++ b/util/libssl.num
@@ -429,6 +429,6 @@
SSL_get_max_early_data 430 1_1_1 EXIST::FUNCTION:
SSL_CTX_get_max_early_data 431 1_1_1 EXIST::FUNCTION:
SSL_write_early 432 1_1_1 EXIST::FUNCTION:
-SSL_read_early 433 1_1_1 EXIST::FUNCTION:
+SSL_read_early_data 433 1_1_1 EXIST::FUNCTION:
SSL_get_early_data_status 434 1_1_1 EXIST::FUNCTION:
SSL_SESSION_get_max_early_data 435 1_1_1 EXIST::FUNCTION:
