bio_lib: Add BIO_get_line, correct doc of BIO_gets

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12959)

diff --git a/crypto/bio/bio_lib.c b/crypto/bio/bio_lib.c
index 3fa8ff4f16c2b41ce8e12befb5564f52be65aab6..9f25376e9507adcf795cd308eb5621f5c24db67d 100644 (file)
--- a/crypto/bio/bio_lib.c
+++ b/crypto/bio/bio_lib.c
@@ -477,6 +477,37 @@ int BIO_gets(BIO *b, char *buf, int size)
     return ret;
 }
 
+int BIO_get_line(BIO *bio, char *buf, int size)
+{
+    int ret = 0;
+    char *ptr = buf;
+
+    if (buf == NULL) {
+        ERR_raise(ERR_LIB_BIO, ERR_R_PASSED_NULL_PARAMETER);
+        return -1;
+    }
+    if (size <= 0) {
+        ERR_raise(ERR_LIB_BIO, BIO_R_INVALID_ARGUMENT);
+        return -1;
+    }
+    *buf = '\0';
+
+    if (bio == NULL) {
+        ERR_raise(ERR_LIB_BIO, ERR_R_PASSED_NULL_PARAMETER);
+        return -1;
+    }
+    if (!bio->init) {
+        ERR_raise(ERR_LIB_BIO, BIO_R_UNINITIALIZED);
+        return -1;
+    }
+
+    while (size-- > 1 && (ret = BIO_read(bio, ptr, 1)) > 0)
+        if (*ptr++ == '\n')
+            break;
+    *ptr = '\0';
+    return ret > 0 || BIO_eof(bio) ? ptr - buf : ret;
+}
+
 int BIO_indent(BIO *b, int indent, int max)
 {
     if (indent < 0)

diff --git a/doc/man3/BIO_read.pod b/doc/man3/BIO_read.pod
index abaf4cb6a49c1d2f9d2e7291009a47c3c0d0e7c3..3b89b25a342f38909188049dc7692e9b1d8e0e72 100644 (file)
--- a/doc/man3/BIO_read.pod
+++ b/doc/man3/BIO_read.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_puts
+BIO_read_ex, BIO_write_ex, BIO_read, BIO_write,
+BIO_gets, BIO_get_line, BIO_puts
 - BIO I/O functions
 
 =head1 SYNOPSIS
@@ -14,6 +15,7 @@ BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_puts
 
  int BIO_read(BIO *b, void *data, int dlen);
  int BIO_gets(BIO *b, char *buf, int size);
+ int BIO_get_line(BIO *b, char *buf, int size);
  int BIO_write(BIO *b, const void *data, int dlen);
  int BIO_puts(BIO *b, const char *buf);
 
@@ -36,6 +38,16 @@ however; for example, BIO_gets() on a digest BIO will calculate and
 return the digest and other BIOs may not support BIO_gets() at all.
 The returned string is always NUL-terminated and the '\n' is preserved
 if present in the input data.
+On binary input there may be NUL characters within the string;
+in this case the return value (if nonnegative) may give an incorrect length.
+
+BIO_get_line() attempts to read from BIO <b> a line of data up to the next '\n'
+or the maximum length B<size-1> is reached and places the data in B<buf>.
+The returned string is always NUL-terminated and the '\n' is preserved
+if present in the input data.
+On binary input there may be NUL characters within the string;
+in this case the return value (if nonnegative) gives the actual length read.
+For implementing this, unfortunately the data needs to be read byte-by-byte.
 
 BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
 
@@ -46,11 +58,18 @@ BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
 BIO_read_ex() and BIO_write_ex() return 1 if data was successfully read or
 written, and 0 otherwise.
 
+BIO_gets() returns -2 if the "gets" operation is not implemented by the BIO
+or -1 on other errors.
+Otherwise it typically returns the amount of data read,
+but depending on the implementation it may return only the length up to
+the first NUL character contained in the data read.
+In any case the trailing NUL that is added after the data read
+is not included in the length returned.
+
 All other functions return either the amount of data successfully read or
 written (if the return value is positive) or that no data was successfully
 read or written if the result is 0 or -1. If the return value is -2 then
-the operation is not implemented in the specific BIO type.  The trailing
-NUL is not included in the length returned by BIO_gets().
+the operation is not implemented in the specific BIO type.
 
 =head1 NOTES
 
@@ -72,9 +91,9 @@ a retry instead of blocking.
 See L<BIO_should_retry(3)> for details of how to
 determine the cause of a retry and other I/O issues.
 
-If the BIO_gets() function is not supported by a BIO then it possible to
-work around this by adding a buffering BIO L<BIO_f_buffer(3)>
-to the chain.
+If the "gets" method is not supported by a BIO then BIO_get_line() can be used.
+It is also possible to make BIO_gets() usable even if the "gets" method is not
+supported by adding a buffering BIO L<BIO_f_buffer(3)> to the chain.
 
 =head1 SEE ALSO
 
@@ -82,9 +101,11 @@ L<BIO_should_retry(3)>
 
 =head1 HISTORY
 
-BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO does not
+BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO did not
 keep the '\n' at the end of the line in the buffer.
 
+BIO_get_line() was added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/include/openssl/bio.h.in b/include/openssl/bio.h.in
index 66ebfc5c7e166fb0cc46f3a216902c6d7a0a16ea..4e2fbb5f07ff5bc7bb4ab2a1d9bf9166211e87d0 100644 (file)
--- a/include/openssl/bio.h.in
+++ b/include/openssl/bio.h.in
@@ -609,6 +609,7 @@ int BIO_up_ref(BIO *a);
 int BIO_read(BIO *b, void *data, int dlen);
 int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);
 int BIO_gets(BIO *bp, char *buf, int size);
+int BIO_get_line(BIO *bio, char *buf, int size);
 int BIO_write(BIO *b, const void *data, int dlen);
 int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);
 int BIO_puts(BIO *bp, const char *buf);

diff --git a/util/libcrypto.num b/util/libcrypto.num
index 67bf50af4d9dcd2134364cf948590cc52006beeb..f83bb186e239cfdf4ed7ed5c9b334d92e5ad2e7c 100644 (file)
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -5409,6 +5409,7 @@ PKCS5_pbkdf2_set_ex                     ? 3_0_0   EXIST::FUNCTION:
 BIO_new_from_core_bio                   ?      3_0_0   EXIST::FUNCTION:
 BIO_new_ex                              ?      3_0_0   EXIST::FUNCTION:
 BIO_s_core                              ?      3_0_0   EXIST::FUNCTION:
+BIO_get_line                            ?      3_0_0   EXIST::FUNCTION:
 OSSL_LIB_CTX_new_from_dispatch          ?      3_0_0   EXIST::FUNCTION:
 OSSL_LIB_CTX_new_child                  ?      3_0_0   EXIST::FUNCTION:
 OSSL_PROVIDER_get0_dispatch             ?      3_0_0   EXIST::FUNCTION: