From ad4874fadfa35738e12337ee35d409fda6b91472 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 13 Dec 2021 18:55:22 +0000 Subject: [PATCH] new manual page PEM_write_bio_ASN1_stream(3); certainly not perfect, but arguably better than the even terser PEM_write_bio_CMS_stream(3) and PEM_write_bio_PKCS7_stream(3) --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/PEM_write_bio_ASN1_stream.3 | 90 +++++++++++++++++++ lib/libcrypto/man/PEM_write_bio_CMS_stream.3 | 5 +- .../man/PEM_write_bio_PKCS7_stream.3 | 5 +- lib/libcrypto/man/i2d_ASN1_bio_stream.3 | 3 +- 5 files changed, 100 insertions(+), 6 deletions(-) create mode 100644 lib/libcrypto/man/PEM_write_bio_ASN1_stream.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 88610412cc1..131b8eea1dd 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.225 2021/12/13 17:24:39 schwarze Exp $ +# $OpenBSD: Makefile,v 1.226 2021/12/13 18:55:22 schwarze Exp $ .include @@ -228,6 +228,7 @@ MAN= \ PEM_bytes_read_bio.3 \ PEM_read.3 \ PEM_read_bio_PrivateKey.3 \ + PEM_write_bio_ASN1_stream.3 \ PEM_write_bio_CMS_stream.3 \ PEM_write_bio_PKCS7_stream.3 \ PKCS12_SAFEBAG_new.3 \ diff --git a/lib/libcrypto/man/PEM_write_bio_ASN1_stream.3 b/lib/libcrypto/man/PEM_write_bio_ASN1_stream.3 new file mode 100644 index 00000000000..7b965e7b764 --- /dev/null +++ b/lib/libcrypto/man/PEM_write_bio_ASN1_stream.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: PEM_write_bio_ASN1_stream.3,v 1.1 2021/12/13 18:55:22 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 PEM_WRITE_BIO_ASN1_STREAM 3 +.Os +.Sh NAME +.Nm PEM_write_bio_ASN1_stream +.Nd generic PEM encoder +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft int +.Fo PEM_write_bio_ASN1_stream +.Fa "BIO *out_bio" +.Fa "ASN1_VALUE *val_in" +.Fa "BIO *in_bio" +.Fa "int flags" +.Fa "const char *hdr" +.Fa "const ASN1_ITEM *it" +.Fc +.Sh DESCRIPTION +.Fn PEM_write_bio_ASN1_stream +writes the +.Fa val_in +argument of type +.Fa it +to +.Fa out_bio +in PEM format, that is, BER- and base64-encoded and surrounded by +.Qq -----BEGIN ...----- +and +.Qq -----END ...----- +lines with the +.Fa hdr +argument in place of the ellipses. +.Pp +The +.Fa flags +are passed through to +.Xr i2d_ASN1_bio_stream 3 . +In particular, if the bit +.Dv SMIME_STREAM +is set, streaming is performed, reading the content from +.Fa in_bio . +Streaming is only supported if +.Fa val_in +is of the type +.Vt CMS_ContentInfo +or +.Vt PKCS7 . +.Pp +If the bit +.Dv SMIME_STREAM +is not set, the arguments +.Fa in_bio +and +.Fa flags +are ignored and distinguished encoding rules (DER) are used. +.Sh RETURN VALUES +.Fn PEM_write_bio_ASN1_stream +is intended to return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr ASN1_item_i2d_bio 3 , +.Xr BIO_f_base64 3 , +.Xr BIO_new 3 , +.Xr i2d_ASN1_bio_stream 3 , +.Xr PEM_write_bio 3 , +.Xr PEM_write_bio_CMS_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 +.Sh HISTORY +.Fn PEM_write_bio_ASN1_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/PEM_write_bio_CMS_stream.3 b/lib/libcrypto/man/PEM_write_bio_CMS_stream.3 index 0a6b4d31d81..bd17e410bbc 100644 --- a/lib/libcrypto/man/PEM_write_bio_CMS_stream.3 +++ b/lib/libcrypto/man/PEM_write_bio_CMS_stream.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PEM_write_bio_CMS_stream.3,v 1.4 2019/11/02 15:39:46 schwarze Exp $ +.\" $OpenBSD: PEM_write_bio_CMS_stream.3,v 1.5 2021/12/13 18:55:22 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 PEM_WRITE_BIO_CMS_STREAM 3 .Os .Sh NAME @@ -87,6 +87,7 @@ returns 1 for success or 0 for failure. .Xr ERR_get_error 3 , .Xr i2d_CMS_bio_stream 3 , .Xr PEM_write 3 , +.Xr PEM_write_bio_ASN1_stream 3 , .Xr SMIME_write_CMS 3 .Sh HISTORY .Fn PEM_write_bio_CMS_stream diff --git a/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 b/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 index dba2a42a70e..5b4175e4f35 100644 --- a/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 +++ b/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.10 2020/06/03 13:41:27 schwarze Exp $ +.\" $OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.11 2021/12/13 18:55:22 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: June 3 2020 $ +.Dd $Mdocdate: December 13 2021 $ .Dt PEM_WRITE_BIO_PKCS7_STREAM 3 .Os .Sh NAME @@ -80,6 +80,7 @@ otherwise 0 is returned and an error code can be retrieved with .Sh SEE ALSO .Xr BIO_new 3 , .Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_ASN1_stream 3 , .Xr PEM_write_PKCS7 3 , .Xr PKCS7_final 3 , .Xr PKCS7_new 3 , diff --git a/lib/libcrypto/man/i2d_ASN1_bio_stream.3 b/lib/libcrypto/man/i2d_ASN1_bio_stream.3 index 82908bb10fa..17ac95778c7 100644 --- a/lib/libcrypto/man/i2d_ASN1_bio_stream.3 +++ b/lib/libcrypto/man/i2d_ASN1_bio_stream.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: i2d_ASN1_bio_stream.3,v 1.2 2021/12/13 17:24:39 schwarze Exp $ +.\" $OpenBSD: i2d_ASN1_bio_stream.3,v 1.3 2021/12/13 18:55:22 schwarze Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -83,6 +83,7 @@ is intended to return 1 on success or 0 on failure. .Xr BIO_push 3 , .Xr i2d_CMS_bio_stream 3 , .Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_ASN1_stream 3 , .Xr SMIME_crlf_copy 3 , .Xr SMIME_write_ASN1 3 .Sh HISTORY -- 2.20.1