document X509_get_pubkey_parameters(3) in a new manual page

5 files changed, 114 insertions, 7 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_cmp.3 b/src/lib/libcrypto/man/EVP_PKEY_cmp.3
index e377ccdb50..e00147dc82 100644
--- a/src/lib/libcrypto/man/EVP_PKEY_cmp.3
+++ b/src/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/src/lib/libcrypto/man/EVP_PKEY_new.3 b/src/lib/libcrypto/man/EVP_PKEY_new.3
index 939d5f0d8a..76eb345941 100644
--- a/src/lib/libcrypto/man/EVP_PKEY_new.3
+++ b/src/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/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 907ae2d988..9c84d130c5 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/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 <bsd.own.mk>
 
@@ -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/src/lib/libcrypto/man/X509_get_pubkey_parameters.3 b/src/lib/libcrypto/man/X509_get_pubkey_parameters.3
new file mode 100644
index 0000000000..7cb163e751
--- /dev/null
+++ b/src/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 <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: 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/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3
index 02f6d8bebe..d95bc30478 100644
--- a/src/lib/libcrypto/man/X509_new.3
+++ b/src/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 ,