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: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2737)

apps/s_server.c

@@ -2211,13 +2211,13 @@ static int sv_body(int s, int stype, unsigned char *context)
     }
 
     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)) {

doc/man3/SSL_read_early.pod

@@ -8,7 +8,7 @@ SSL_get_max_early_data,
 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 @@ SSL_get_early_data_status
 
  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 @@ SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it
 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.
-
-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.
-
-Only servers may call SSL_read_early().
-
-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.
+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_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_data().
+
+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 @@ with then the lower of the two values will apply.
 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

include/openssl/ssl.h

@@ -1615,11 +1615,12 @@ __owur int SSL_connect(SSL *ssl);
 __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 @@ int ERR_load_SSL_strings(void);
 # 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

ssl/ssl_err.c

@@ -206,7 +206,7 @@ static ERR_STRING_DATA SSL_str_functs[] = {
     {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"},

ssl/ssl_lib.c

@@ -1607,20 +1607,21 @@ int SSL_read_ex(SSL *s, void *buf, size_t num, size_t *readbytes)
     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 @@ int SSL_read_early(SSL *s, void *buf, size_t num, size_t *readbytes)
         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 @@ int SSL_read_early(SSL *s, void *buf, size_t num, size_t *readbytes)
             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;
     }
 }
 

test/sslapitest.c

@@ -1610,8 +1610,8 @@ static int test_early_data_read_write(void)
         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 @@ static int test_early_data_read_write(void)
     }
 
     /* 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 @@ static int test_early_data_read_write(void)
     }
 
     /* 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 @@ static int test_early_data_read_write(void)
     }
     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 @@ static int test_early_data_read_write(void)
         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 @@ static int test_early_data_read_write(void)
     }
     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 @@ static int test_early_data_skip(void)
     }
 
     /* 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 @@ static int test_early_data_not_sent(void)
     }
 
     /* 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 @@ static int test_early_data_tls1_2(void)
 
     /*
      * 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 @@ static int test_early_data_tls1_2(void)
         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;

util/libssl.num

@@ -429,6 +429,6 @@ SSL_CTX_set_max_early_data              429	1_1_1	EXIST::FUNCTION:
 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: