diff --git a/crypto/bio/bio_lib.c b/crypto/bio/bio_lib.c index 3fa8ff4f16..9f25376e95 100644 --- 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 abaf4cb6a4..3b89b25a34 100644 --- 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 a line of data up to the next '\n' +or the maximum length B is reached and places the data in B. +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 bytes from B to BIO B. @@ -46,11 +58,18 @@ BIO_puts() attempts to write a NUL-terminated string B to BIO 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 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 -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 to the chain. =head1 SEE ALSO @@ -82,9 +101,11 @@ L =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 66ebfc5c7e..4e2fbb5f07 100644 --- 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 67bf50af4d..f83bb186e2 100644 --- 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: