BIO_f_base64.pod and openssl-enc.pod.in: improve description on newline handling

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

(cherry picked from commit b1e7bc5bdfc73ef841afa30ac321975b0d63219a)

diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in
index e6d5103bd91a2592897d0ea83ae192e96b9a580b..f4551d3685079746e85c03633655e190da413aa8 100644 (file)
--- a/doc/man1/openssl-enc.pod.in
+++ b/doc/man1/openssl-enc.pod.in
@@ -97,13 +97,19 @@ Base64 process the data. This means that if encryption is taking place
 the data is base64 encoded after encryption. If decryption is set then
 the input data is base64 decoded before being decrypted.
 
+When the B<-A> option not given,
+on encoding a newline is inserted after each 64 characters, and
+on decoding a newline is expected among the first 1024 bytes of input.
+
 =item B<-base64>
 
 Same as B<-a>
 
 =item B<-A>
 
-If the B<-a> option is set then base64 process the data on one line.
+If the B<-a> option is set then base64 encoding produces output without any
+newline character, and base64 decoding does not require any newlines.
+Therefore it can be helpful to use the B<-A> option when decoding unknown input.
 
 =item B<-k> I<password>
 
@@ -434,6 +440,9 @@ Base64 decode a file then decrypt it using a password supplied in a file:
 =head1 BUGS
 
 The B<-A> option when used with large files doesn't work properly.
+On the other hand, when base64 decoding without the B<-A> option,
+if the first 1024 bytes of input do not include a newline character
+the first two lines of input are ignored.
 
 The B<openssl enc> command only supports a fixed number of algorithms with
 certain parameters. So if, for example, you want to use RC2 with a

diff --git a/doc/man3/BIO_f_base64.pod b/doc/man3/BIO_f_base64.pod
index c865f0a17ac169261f494110036e67bd7e4e5901..7d10df933c51b8c0b1f906ebbd0f6ef22a7266dd 100644 (file)
--- a/doc/man3/BIO_f_base64.pod
+++ b/doc/man3/BIO_f_base64.pod
@@ -21,25 +21,23 @@ any data read through it.
 
 Base64 BIOs do not support BIO_gets() or BIO_puts().
 
-For writing, output is by default divided to lines of length 64
-characters and there is always a newline at the end of output.
+For writing, by default output is divided to lines of length 64
+characters and there is a newline at the end of output.
+This behavior can be changed with B<BIO_FLAGS_BASE64_NO_NL> flag.
 
-For reading, first line should be at most 1024
-characters long. If it is longer then it is ignored completely.
-Other input lines can be of any length. There must be a newline
-at the end of input.
-
-This behavior can be changed with BIO_FLAGS_BASE64_NO_NL flag.
+For reading, first line should be at most 1024 bytes long including newline
+unless the flag B<BIO_FLAGS_BASE64_NO_NL> is set.
+Further input lines can be of any length (i.e., newlines may appear anywhere
+in the input) and a newline at the end of input is not needed.
 
 BIO_flush() on a base64 BIO that is being written through is
 used to signal that no more data is to be encoded: this is used
 to flush the final block through the BIO.
 
-The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags().
+The flag B<BIO_FLAGS_BASE64_NO_NL> can be set with BIO_set_flags().
 For writing, it causes all data to be written on one line without
 newline at the end.
-For reading, it expects the data to be all on one line (with or
-without a trailing newline).
+For reading, it removes all expectations on newlines in the input data.
 
 =head1 NOTES
 
@@ -85,6 +83,10 @@ data to standard output:
 
 =head1 BUGS
 
+On decoding, if the flag B<BIO_FLAGS_BASE64_NO_NL> is not set and
+the first 1024 bytes of input do not include a newline character
+the first two lines of input are ignored.
+
 The ambiguity of EOF in base64 encoded data can cause additional
 data following the base64 encoded block to be misinterpreted.