From c1f3ff0dbd0a6f4c95a7f1f7f9abf45d19c96442 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 13 Dec 2021 13:46:09 +0000 Subject: [PATCH] new manual pages i2d_ASN1_bio_stream(3) and SMIME_crlf_copy(3) --- lib/libcrypto/man/BIO_new_NDEF.3 | 7 +- lib/libcrypto/man/Makefile | 4 +- lib/libcrypto/man/SMIME_crlf_copy.3 | 96 ++++++++++++++++++++++++ lib/libcrypto/man/i2d_ASN1_bio_stream.3 | 94 +++++++++++++++++++++++ lib/libcrypto/man/i2d_CMS_bio_stream.3 | 5 +- lib/libcrypto/man/i2d_PKCS7_bio_stream.3 | 5 +- 6 files changed, 203 insertions(+), 8 deletions(-) create mode 100644 lib/libcrypto/man/SMIME_crlf_copy.3 create mode 100644 lib/libcrypto/man/i2d_ASN1_bio_stream.3 diff --git a/lib/libcrypto/man/BIO_new_NDEF.3 b/lib/libcrypto/man/BIO_new_NDEF.3 index e6af75f0afb..9a16924773a 100644 --- a/lib/libcrypto/man/BIO_new_NDEF.3 +++ b/lib/libcrypto/man/BIO_new_NDEF.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BIO_new_NDEF.3,v 1.2 2021/12/12 18:15:43 schwarze Exp $ +.\" $OpenBSD: BIO_new_NDEF.3,v 1.3 2021/12/13 13:46:09 schwarze Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: December 12 2021 $ +.Dd $Mdocdate: December 13 2021 $ .Dt BIO_NEW_NDEF 3 .Os .Sh NAME @@ -112,7 +112,8 @@ does not support streaming or if memory allocation fails. .Xr BIO_f_asn1 3 , .Xr BIO_new 3 , .Xr BIO_new_CMS 3 , -.Xr BIO_push 3 +.Xr BIO_push 3 , +.Xr i2d_ASN1_bio_stream 3 .Sh HISTORY .Fn BIO_new_NDEF first appeared in OpenSSL 1.0.0 and has been available since diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index aab725a0e92..2e608bffbb7 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.223 2021/12/12 17:31:18 schwarze Exp $ +# $OpenBSD: Makefile,v 1.224 2021/12/13 13:46:09 schwarze Exp $ .include @@ -278,6 +278,7 @@ MAN= \ RSA_sign_ASN1_OCTET_STRING.3 \ RSA_size.3 \ SHA1.3 \ + SMIME_crlf_copy.3 \ SMIME_read_CMS.3 \ SMIME_read_PKCS7.3 \ SMIME_write_CMS.3 \ @@ -411,6 +412,7 @@ MAN= \ evp.3 \ get_rfc3526_prime_8192.3 \ i2a_ASN1_STRING.3 \ + i2d_ASN1_bio_stream.3 \ i2d_CMS_bio_stream.3 \ i2d_PKCS7_bio_stream.3 \ lh_new.3 \ diff --git a/lib/libcrypto/man/SMIME_crlf_copy.3 b/lib/libcrypto/man/SMIME_crlf_copy.3 new file mode 100644 index 00000000000..defee581fdb --- /dev/null +++ b/lib/libcrypto/man/SMIME_crlf_copy.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: SMIME_crlf_copy.3,v 1.1 2021/12/13 13:46:09 schwarze Exp $ +.\" +.\" Copyright (c) 2021 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: December 13 2021 $ +.Dt SMIME_CRLF_COPY 3 +.Os +.Sh NAME +.Nm SMIME_crlf_copy +.Nd buffered copy between BIOs +.Sh SYNOPSIS +.Ft int +.Fo SMIME_crlf_copy +.Fa "BIO *in_bio" +.Fa "BIO *out_bio" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn SMIME_crlf_copy +copies data from +.Fa in_bio +to +.Fa out_bio . +To avoid many small write operations on +.Fa out_bio , +a buffering BIO created with +.Xr BIO_f_buffer 3 +is temporarily prepended to it. +.Pp +If the bit +.Dv SMIME_BINARY +is set in the +.Fa flags +argument, all the data is copied verbatim using +.Xr BIO_read 3 +and +.Xr BIO_write 3 . +.Pp +Otherwise, the data is read as text. +All trailing carriage return and newline characters are discarded +from every input line and a single pair of carriage return and +newline characters is appended to mark the end of every output line, +except that the last output line will end without such a pair if +the last input line does not have a newline character at the end. +.Pp +If the bit +.Dv SMIME_TEXT +is set in the +.Fa flags +argument and the bit +.Dv SMIME_BINARY +is not set, the line +.Qq Content-Type: text/plain +is prepended to the output +with two pairs of carriage return and newline characters after it. +.Pp +In any case, +.Xr BIO_flush 3 +is called on the output at the end of the function. +.Sh RETURN VALUES +.Fn SMIME_crlf_copy +is intended to return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr BIO_f_buffer 3 , +.Xr BIO_flush 3 , +.Xr BIO_new 3 , +.Xr BIO_push 3 , +.Xr BIO_read 3 , +.Xr i2d_ASN1_bio_stream 3 , +.Xr SMIME_write_ASN1 3 +.Sh HISTORY +.Fn SMIME_crlf_copy +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh BUGS +.Fn SMIME_crlf_copy +silently ignores most errors and may return 1 +even if it lost part or all of the data in transit. +.Pp +Only blocking BIOs are supported. +If any of the +.Vt BIO +arguments is non-blocking, part or all of the data is likely +to be silently lost in transit. diff --git a/lib/libcrypto/man/i2d_ASN1_bio_stream.3 b/lib/libcrypto/man/i2d_ASN1_bio_stream.3 new file mode 100644 index 00000000000..007d8eefd43 --- /dev/null +++ b/lib/libcrypto/man/i2d_ASN1_bio_stream.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: i2d_ASN1_bio_stream.3,v 1.1 2021/12/13 13:46:09 schwarze Exp $ +.\" +.\" Copyright (c) 2021 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: December 13 2021 $ +.Dt I2D_ASN1_BIO_STREAM 3 +.Os +.Sh NAME +.Nm i2d_ASN1_bio_stream +.Nd generic BER streamer +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft int +.Fo i2d_ASN1_bio_stream +.Fa "BIO *out_bio" +.Fa "ASN1_VALUE *val_in" +.Fa "BIO *in_bio" +.Fa "int flags" +.Fa "const ASN1_ITEM *it" +.Fc +.Sh DESCRIPTION +If the bit +.Dv SMIME_STREAM +is not set in the +.Fa flags +argument, +.Fn i2d_ASN1_bio_stream +does the same as +.Xr ASN1_item_i2d_bio 3 , +ignoring the +.Fa in_bio +and +.Fa flags +arguments. +.Pp +If the bit +.Dv SMIME_STREAM +is set, it creates a streaming BIO with +.Xr BIO_new_NDEF 3 , +copies the data from +.Fa in_bio +to it using +.Xr SMIME_crlf_copy 3 , +finalizes the output with +.Xr BIO_flush 3 , +and frees the newly created BIOs up to but not including +.Fa out_bio . +.Pp +If +.Fa it +is +.Va PKCS7_it , +this function behaves exactly as +.Xr i2d_PKCS7_bio_stream 3 ; +for +.Va CMS_ContentInfo_it , +it behaves exactly as +.Xr i2d_CMS_bio_stream 3 . +For other values of +.Fa it , +the function fails. +.Sh RETURN VALUES +.Fn i2d_ASN1_bio_stream +is intended to return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr ASN1_item_i2d_bio 3 , +.Xr ASN1_item_ndef_i2d 3 , +.Xr BIO_flush 3 , +.Xr BIO_new 3 , +.Xr BIO_new_NDEF 3 , +.Xr BIO_push 3 , +.Xr i2d_CMS_bio_stream 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr SMIME_crlf_copy 3 +.Sh HISTORY +.Fn i2d_ASN1_bio_stream +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh BUGS +Many kinds of errors are silently ignored. +This function may return 1 even if it only produced partial output +or no output at all. diff --git a/lib/libcrypto/man/i2d_CMS_bio_stream.3 b/lib/libcrypto/man/i2d_CMS_bio_stream.3 index efb8902faf6..b3c29af3a25 100644 --- a/lib/libcrypto/man/i2d_CMS_bio_stream.3 +++ b/lib/libcrypto/man/i2d_CMS_bio_stream.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: i2d_CMS_bio_stream.3,v 1.4 2019/11/02 15:39:46 schwarze Exp $ +.\" $OpenBSD: i2d_CMS_bio_stream.3,v 1.5 2021/12/13 13:46:09 schwarze Exp $ .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 2 2019 $ +.Dd $Mdocdate: December 13 2021 $ .Dt I2D_CMS_BIO_STREAM 3 .Os .Sh NAME @@ -83,6 +83,7 @@ returns 1 for success or 0 for failure. .Xr CMS_encrypt 3 , .Xr CMS_sign 3 , .Xr ERR_get_error 3 , +.Xr i2d_ASN1_bio_stream 3 , .Xr PEM_write_bio_CMS_stream 3 , .Xr SMIME_write_CMS 3 .Sh HISTORY diff --git a/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 b/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 index a76ee271613..b3416f5d488 100644 --- a/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 +++ b/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: i2d_PKCS7_bio_stream.3,v 1.9 2021/12/09 18:33:34 schwarze Exp $ +.\" $OpenBSD: i2d_PKCS7_bio_stream.3,v 1.10 2021/12/13 13:46:09 schwarze Exp $ .\" OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 9 2021 $ +.Dd $Mdocdate: December 13 2021 $ .Dt I2D_PKCS7_BIO_STREAM 3 .Os .Sh NAME @@ -80,6 +80,7 @@ returns 1 for success or 0 for failure. .Sh SEE ALSO .Xr BIO_new 3 , .Xr ERR_get_error 3 , +.Xr i2d_ASN1_bio_stream 3 , .Xr PEM_write_bio_PKCS7_stream 3 , .Xr PEM_write_PKCS7 3 , .Xr PKCS7_final 3 , -- 2.20.1