document PKCS7_set_type(3);

OK beck@, who was amused by the "darkly comic value of reading" it

3 files changed, 123 insertions, 3 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index a50e9594c5d..5cb80ee5c3a 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.160 2019/11/02 15:12:31 schwarze Exp $
+# $OpenBSD: Makefile,v 1.161 2020/05/16 00:11:55 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -217,6 +217,7 @@ MAN=	\
 	PKCS7_decrypt.3 \
 	PKCS7_encrypt.3 \
 	PKCS7_new.3 \
+	PKCS7_set_type.3 \
 	PKCS7_sign.3 \
 	PKCS7_sign_add_signer.3 \
 	PKCS7_verify.3 \
diff --git a/lib/libcrypto/man/PKCS7_new.3 b/lib/libcrypto/man/PKCS7_new.3
index d77ab73f759..324c96cfc9e 100644
--- a/lib/libcrypto/man/PKCS7_new.3
+++ b/lib/libcrypto/man/PKCS7_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: PKCS7_new.3,v 1.6 2019/06/10 09:49:48 schwarze Exp $
+.\" $OpenBSD: PKCS7_new.3,v 1.7 2020/05/16 00:11:55 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -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: June 10 2019 $
+.Dd $Mdocdate: May 16 2020 $
 .Dt PKCS7_NEW 3
 .Os
 .Sh NAME
@@ -249,6 +249,7 @@ frees
 .Xr PKCS7_decrypt 3 ,
 .Xr PKCS7_encrypt 3 ,
 .Xr PKCS7_ISSUER_AND_SERIAL_digest 3 ,
+.Xr PKCS7_set_type 3 ,
 .Xr PKCS7_sign 3 ,
 .Xr PKCS7_sign_add_signer 3 ,
 .Xr PKCS7_verify 3 ,
diff --git a/lib/libcrypto/man/PKCS7_set_type.3 b/lib/libcrypto/man/PKCS7_set_type.3
new file mode 100644
index 00000000000..a666b866ffb
--- /dev/null
+++ b/lib/libcrypto/man/PKCS7_set_type.3
@@ -0,0 +1,118 @@
+.\" $OpenBSD: PKCS7_set_type.3,v 1.1 2020/05/16 00:11:55 schwarze Exp $
+.\"
+.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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: May 16 2020 $
+.Dt PKCS7_SET_TYPE 3
+.Os
+.Sh NAME
+.Nm PKCS7_set_type ,
+.Nm PKCS7_set0_type_other
+.Nd initialize type of PKCS#7 ContentInfo
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft int
+.Fo PKCS7_set_type
+.Fa "PKCS7 *p7"
+.Fa "int type"
+.Fc
+.Ft int
+.Fo PKCS7_set0_type_other
+.Fa "PKCS7 *p7"
+.Fa "int type"
+.Fa "ASN1_TYPE *content"
+.Fc
+.Sh DESCRIPTION
+These functions set the
+.Fa type
+of an unused
+.Vt ContentInfo
+structure
+.Fa p7 .
+.Pp
+The function
+.Fn PKCS7_set_type
+also allocates and initializes an empty child object in
+.Fa p7 .
+The
+.Fa type
+argument can be any of these NIDs,
+creating a child object of the indicated data type:
+.Pp
+.Bl -column NID_pkcs7_signedAndEnveloped PKCS7_SIGN_ENVELOPE n.a. -compact
+.It Fa type No argument             Ta data type of child     Ta version
+.It Dv NID_pkcs7_data               Ta Vt ASN1_OCTET_STRING   Ta n.a.
+.It Dv NID_pkcs7_digest             Ta Vt PKCS7_DIGEST        Ta 0
+.It Dv NID_pkcs7_encrypted          Ta Vt PKCS7_ENCRYPT       Ta 0
+.It Dv NID_pkcs7_enveloped          Ta Vt PKCS7_ENVELOPE      Ta 0
+.It Dv NID_pkcs7_signed             Ta Vt PKCS7_SIGNED        Ta 1
+.It Dv NID_pkcs7_signedAndEnveloped Ta Vt PKCS7_SIGN_ENVELOPE Ta 1
+.El
+.Pp
+If the provided
+.Fa type
+is invalid,
+.Fa p7
+remains unchanged and
+.Fn PKCS7_set_type
+fails.
+.Pp
+If memory allocation fails,
+.Fn PKCS7_set_type
+fails and
+.Fa p7
+may remain in an inconsistent state.
+.Pp
+The function
+.Fn PKCS7_set0_type_other
+accepts an arbitrary NID as the
+.Fa type
+and also sets the
+.Fa content ,
+neither checking it in any way nor copying it.
+.Pp
+For both functions, the rest of the internal state of
+.Fa p7
+remains unchanged.
+.Sh RETURN VALUES
+The function
+.Fn PKCS7_set_type
+returns 1 on success or 0 on failure.
+.Pp
+The function
+.Fn PKCS7_set0_type_other
+does no error handling at all and always returns 1.
+.Sh SEE ALSO
+.Xr ASN1_OCTET_STRING_new 3 ,
+.Xr ASN1_TYPE_new 3 ,
+.Xr PKCS7_encrypt 3 ,
+.Xr PKCS7_new 3 ,
+.Xr PKCS7_sign 3
+.Sh HISTORY
+The function
+.Fn PKCS7_set_type
+first appeared in SSLeay 0.8.1 and
+.Fn PKCS7_set0_type_other
+in OpenSSL 0.9.8.
+Both have been available since
+.Ox 2.4 .
+.Sh CAVEATS
+If
+.Fa p7
+has already been in use before being passed to one of these functions,
+it will report success even though it leaks memory.
+Later on, if other functions try to use
+.Fa p7
+in its former role, they are likely to misbehave.