From 3c97a7c50200d5ef4681d620bf76fcea2ce72811 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 28 Dec 2016 02:48:59 +0000 Subject: Full rewrite. Also document d2i_PKCS8_bio(3), i2d_PKCS8_bio(3), d2i_PKCS8_fp(3), and i2d_PKCS8_fp(3) while here, listed in and in OpenSSL doc/man3/d2i_X509.pod. No, these functions have nothing to do with the many other d2i_PKCS8*(3) functions all around, and nothing with PKCS#8 at all in the first place. Read the BUGS section. I couldn't make this stuff up. --- src/lib/libcrypto/man/d2i_X509_SIG.3 | 183 +++++++++++++++++++++++------------ 1 file changed, 123 insertions(+), 60 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/d2i_X509_SIG.3 b/src/lib/libcrypto/man/d2i_X509_SIG.3 index 33676b6df0..bf050ce23d 100644 --- a/src/lib/libcrypto/man/d2i_X509_SIG.3 +++ b/src/lib/libcrypto/man/d2i_X509_SIG.3 @@ -1,82 +1,145 @@ -.\" $OpenBSD: d2i_X509_SIG.3,v 1.5 2016/12/25 22:15:10 schwarze Exp $ +.\" $OpenBSD: d2i_X509_SIG.3,v 1.6 2016/12/28 02:48:59 schwarze Exp $ .\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 .\" -.\" This file was written by Dr. Stephen Henson . -.\" Copyright (c) 2002, 2015 The OpenSSL Project. All rights reserved. +.\" Copyright (c) 2016 Ingo Schwarze .\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: +.\" 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. .\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. +.\" 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. .\" -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in -.\" the documentation and/or other materials provided with the -.\" distribution. -.\" -.\" 3. All advertising materials mentioning features or use of this -.\" software must display the following acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" -.\" -.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to -.\" endorse or promote products derived from this software without -.\" prior written permission. For written permission, please contact -.\" openssl-core@openssl.org. -.\" -.\" 5. Products derived from this software may not be called "OpenSSL" -.\" nor may "OpenSSL" appear in their names without prior written -.\" permission of the OpenSSL Project. -.\" -.\" 6. Redistributions of any form whatsoever must retain the following -.\" acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY -.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR -.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -.\" OF THE POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd $Mdocdate: December 25 2016 $ +.Dd $Mdocdate: December 28 2016 $ .Dt D2I_X509_SIG 3 .Os .Sh NAME .Nm d2i_X509_SIG , -.Nm i2d_X509_SIG -.Nd DigestInfo functions +.Nm i2d_X509_SIG , +.Nm d2i_PKCS8_bio , +.Nm i2d_PKCS8_bio , +.Nm d2i_PKCS8_fp , +.Nm i2d_PKCS8_fp +.\" In the next line, the number "7" is not a typo. +.\" These functions are misnamed. +.Nd decode and encode PKCS#7 digest information .Sh SYNOPSIS .In openssl/x509.h .Ft X509_SIG * .Fo d2i_X509_SIG -.Fa "X509_SIG **a" -.Fa "unsigned char **pp" +.Fa "X509_SIG **val_out" +.Fa "unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_X509_SIG -.Fa "X509_SIG *a" -.Fa "unsigned char **pp" +.Fa "X509_SIG *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_SIG * +.Fo d2i_PKCS8_bio +.Fa "BIO *in_bio" +.Fa "X509_SIG **val_out" +.Fc +.Ft int +.Fo i2d_PKCS8_bio +.Fa "BIO *out_bio" +.Fa "X509_SIG *val_in" +.Fc +.Ft X509_SIG * +.Fo d2i_PKCS8_fp +.Fa "FILE *in_fp" +.Fa "X509_SIG **val_out" +.Fc +.Ft int +.Fo i2d_PKCS8_fp +.Fa "FILE *out_fp" +.Fa "X509_SIG *val_in" .Fc .Sh DESCRIPTION -These functions decode and encode an -.Vt X509_SIG -structure, which is equivalent to the +.Fn d2i_X509_SIG +and +.Fn i2d_X509_SIG +decode and encode an ASN.1 .Vt DigestInfo -structure defined in PKCS#1 and PKCS#7. -They otherwise behave in a way similar to -.Xr d2i_X509 3 +structure defined in RFC 2315 section 9.4 +and equivalently in RFC 8017 section 9.2. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_PKCS8_bio +and +.Fn d2i_PKCS8_fp +are similar to +.Fn d2i_X509_SIG +except that they read from a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn i2d_PKCS8_bio +and +.Fn i2d_PKCS8_fp +are similar to +.Fn i2d_X509_SIG +except that they write to a +.Vt BIO +or +.Vt FILE +pointer. +.Sh RETURN VALUES +.Fn d2i_X509_SIG , +.Fn d2i_PKCS8_bio , and -.Xr i2d_X509 3 . +.Fn d2i_PKCS8_fp +return a +.Vt X509_SIG +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_SIG +returns the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_PKCS8_bio +and +.Fn i2d_PKCS8_fp +return 1 for success or 0 if an error occurs. .Sh SEE ALSO -.Xr d2i_X509 3 +.Xr ASN1_item_d2i 3 , +.Xr PKCS7_new 3 , +.Xr RSA_sign 3 , +.Xr X509_SIG_new 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax, +section 9: Signed-data content type +.Pp +RFC 8017: PKCS #1: RSA Cryptography Specifications, +section 9: Encoding Methods for Signatures +.Sh BUGS +.Fn d2i_PKCS8_bio , +.Fn i2d_PKCS8_bio , +.Fn d2i_PKCS8_fp , +and +.Fn i2d_PKCS8_fp +are severely misnamed and should have been called +.Dq d2i_X509_SIG_bio +and so on. +.Pp +Or arguably, the +.Vt X509_SIG +object is misnamed itself, considering that it represents +.Vt DigestInfo +from PKCS#7 and PKCS#1. +Then again, calling it +.Dq PKCS8 +instead clearly isn't an improvement. +.Pp +Either way, these names just don't fit. -- cgit v1.2.3-55-g6feb