From ec68b3c458cb9b261befcead91da134bda457815 Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 19 Oct 2021 17:42:49 +0000 Subject: [PATCH] document X509_get_pubkey_parameters(3) in a new manual page --- lib/libcrypto/man/EVP_PKEY_cmp.3 | 5 +- lib/libcrypto/man/EVP_PKEY_new.3 | 7 +- lib/libcrypto/man/Makefile | 3 +- .../man/X509_get_pubkey_parameters.3 | 103 ++++++++++++++++++ lib/libcrypto/man/X509_new.3 | 3 +- 5 files changed, 114 insertions(+), 7 deletions(-) create mode 100644 lib/libcrypto/man/X509_get_pubkey_parameters.3 diff --git a/lib/libcrypto/man/EVP_PKEY_cmp.3 b/lib/libcrypto/man/EVP_PKEY_cmp.3 index e377ccdb500..e00147dc826 100644 --- a/lib/libcrypto/man/EVP_PKEY_cmp.3 +++ b/lib/libcrypto/man/EVP_PKEY_cmp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_PKEY_cmp.3,v 1.11 2021/10/19 16:27:47 schwarze Exp $ +.\" $OpenBSD: EVP_PKEY_cmp.3,v 1.12 2021/10/19 17:42:49 schwarze Exp $ .\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 .\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" @@ -159,7 +159,8 @@ are different and -2 if the operation is not supported. .Xr EVP_PKEY_asn1_set_public 3 , .Xr EVP_PKEY_CTX_new 3 , .Xr EVP_PKEY_keygen 3 , -.Xr EVP_PKEY_new 3 +.Xr EVP_PKEY_new 3 , +.Xr X509_get_pubkey_parameters 3 .Sh HISTORY .Fn EVP_PKEY_missing_parameters and diff --git a/lib/libcrypto/man/EVP_PKEY_new.3 b/lib/libcrypto/man/EVP_PKEY_new.3 index 939d5f0d8ad..76eb3459413 100644 --- a/lib/libcrypto/man/EVP_PKEY_new.3 +++ b/lib/libcrypto/man/EVP_PKEY_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_PKEY_new.3,v 1.13 2021/03/31 16:48:43 tb Exp $ +.\" $OpenBSD: EVP_PKEY_new.3,v 1.14 2021/10/19 17:42:49 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 .\" @@ -50,7 +50,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 31 2021 $ +.Dd $Mdocdate: October 19 2021 $ .Dt EVP_PKEY_NEW 3 .Os .Sh NAME @@ -190,7 +190,8 @@ returns 1 for success or 0 for failure. .Xr EVP_PKEY_get_default_digest_nid 3 , .Xr EVP_PKEY_meth_new 3 , .Xr EVP_PKEY_print_private 3 , -.Xr EVP_PKEY_set1_RSA 3 +.Xr EVP_PKEY_set1_RSA 3 , +.Xr X509_get_pubkey_parameters 3 .Sh HISTORY .Fn EVP_PKEY_new and diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 907ae2d9889..9c84d130c58 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.192 2021/10/19 10:55:57 schwarze Exp $ +# $OpenBSD: Makefile,v 1.193 2021/10/19 17:42:49 schwarze Exp $ .include @@ -323,6 +323,7 @@ MAN= \ X509_digest.3 \ X509_find_by_subject.3 \ X509_get_pubkey.3 \ + X509_get_pubkey_parameters.3 \ X509_get_serialNumber.3 \ X509_get_subject_name.3 \ X509_get_version.3 \ diff --git a/lib/libcrypto/man/X509_get_pubkey_parameters.3 b/lib/libcrypto/man/X509_get_pubkey_parameters.3 new file mode 100644 index 00000000000..7cb163e7518 --- /dev/null +++ b/lib/libcrypto/man/X509_get_pubkey_parameters.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: X509_get_pubkey_parameters.3,v 1.1 2021/10/19 17:42:49 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: October 19 2021 $ +.Dt X509_GET_PUBKEY_PARAMETERS 3 +.Os +.Sh NAME +.Nm X509_get_pubkey_parameters +.Nd copy public key parameters from a chain +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_get_pubkey_parameters +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *chain" +.Fc +.Sh DESCRIPTION +.Fn X509_get_pubkey_parameters +copies public key parameters from the first appropriate certificate in the +.Fa chain . +.Pp +If +.Fa pkey +is not +.Dv NULL +and already contains complete public key parameters or uses an +algorithm that does not use any parameters, no action occurs and +the function indicates success without inspecting the existing +parameters, without inspecting the +.Fa chain , +and without comparing any parameters. +.Pp +Otherwise, all public key parameters are copied +from the first certificate in the +.Fa chain +that contains complete public key parameters +to each certificate preceding it in the +.Fa chain . +Unless +.Fa pkey +is a +.Dv NULL +pointer, the same parameters are also copied to +.Fa pkey . +.Sh RETURN VALUES +.Fn X509_get_pubkey_parameters +returns 1 for success or 0 for failure. +.Sh ERRORS +The following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv X509_R_UNABLE_TO_GET_CERTS_PUBLIC_KEY Qq unable to get certs public key +Retrieving the public key from a certificate in the +.Fa chain +failed before a certificate containing complete public key parameters +could be found. +.It Xo +.Dv X509_R_UNABLE_TO_FIND_PARAMETERS_IN_CHAIN +.Qq unable to find parameters in chain +.Xc +None of the certificates in the chain +contain complete public key parameters. +.El +.Sh SEE ALSO +.Xr EVP_PKEY_copy_parameters 3 , +.Xr EVP_PKEY_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn X509_get_pubkey_parameters +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Sh BUGS +If an error occurs while copying parameters with +.Xr EVP_PKEY_copy_parameters 3 , +.Fn X509_get_pubkey_parameters +indicates success regardless. +In this case, it is possible that a part of the parameters was copied +while another part remained in its former state, or that nothing got +copied at all. +.Pp +Some errors of this kind, for example some kinds of key type +mismatches and some kinds of memory allocation failures, can be +detected by inspecting the error stack after +.Fn X509_get_pubkey_parameters +returns successfully, but some other kinds of algorithm-specific +copying failures might be impossible to detect at all. diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index 02f6d8bebe4..d95bc304785 100644 --- a/lib/libcrypto/man/X509_new.3 +++ b/lib/libcrypto/man/X509_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_new.3,v 1.31 2021/10/19 10:39:33 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.32 2021/10/19 17:42:49 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file is a derived work. @@ -188,6 +188,7 @@ if an error occurs. .Xr X509_get1_email 3 , .Xr X509_get_ex_new_index 3 , .Xr X509_get_pubkey 3 , +.Xr X509_get_pubkey_parameters 3 , .Xr X509_get_serialNumber 3 , .Xr X509_get_subject_name 3 , .Xr X509_get_version 3 , -- 2.20.1