From b1e7bc5bdfc73ef841afa30ac321975b0d63219a Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Mon, 11 Jul 2022 19:55:10 +0200 Subject: [PATCH] BIO_f_base64.pod and openssl-enc.pod.in: improve description on newline handling Reviewed-by: Neil Horman Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/18783) --- doc/man1/openssl-enc.pod.in | 11 ++++++++++- doc/man3/BIO_f_base64.pod | 24 +++++++++++++----------- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in index 14066a3185..0f514672ec 100644 --- a/doc/man1/openssl-enc.pod.in +++ b/doc/man1/openssl-enc.pod.in @@ -98,13 +98,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 @@ -463,6 +469,9 @@ or =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 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 c865f0a17a..7d10df933c 100644 --- 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 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 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 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 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.