From 0a1dcbe05d21795b7042ce242cc0c6b8a960f3a2 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 16 May 2020 00:11:55 +0000 Subject: document PKCS7_set_type(3); OK beck@, who was amused by the "darkly comic value of reading" it --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PKCS7_new.3 | 5 +- src/lib/libcrypto/man/PKCS7_set_type.3 | 118 +++++++++++++++++++++++++++++++++ 3 files changed, 123 insertions(+), 3 deletions(-) create mode 100644 src/lib/libcrypto/man/PKCS7_set_type.3 (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index a50e9594c5..5cb80ee5c3 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/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 @@ -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/src/lib/libcrypto/man/PKCS7_new.3 b/src/lib/libcrypto/man/PKCS7_new.3 index d77ab73f75..324c96cfc9 100644 --- a/src/lib/libcrypto/man/PKCS7_new.3 +++ b/src/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 .\" @@ -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/src/lib/libcrypto/man/PKCS7_set_type.3 b/src/lib/libcrypto/man/PKCS7_set_type.3 new file mode 100644 index 0000000000..a666b866ff --- /dev/null +++ b/src/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 +.\" +.\" 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. -- cgit v1.2.3-55-g6feb