document and deprecate the macros X509_extract_key(3)

and X509_REQ_extract_key(3), using feedback from tb@ and jsing@

diff --git a/lib/libcrypto/man/X509_get_pubkey.3 b/lib/libcrypto/man/X509_get_pubkey.3
index ad9c1ab..dc1f6a9 100644 (file)
--- a/lib/libcrypto/man/X509_get_pubkey.3
+++ b/lib/libcrypto/man/X509_get_pubkey.3
@@ -1,11 +1,11 @@
-.\" $OpenBSD: X509_get_pubkey.3,v 1.8 2020/06/19 14:31:29 schwarze Exp $
+.\" $OpenBSD: X509_get_pubkey.3,v 1.9 2021/06/30 10:06:43 schwarze Exp $
 .\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\" X509_REQ_get0_pubkey and X509_REQ_get_X509_PUBKEY not yet in LibreSSL
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2020, 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
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 19 2020 $
+.Dd $Mdocdate: June 30 2021 $
 .Dt X509_GET_PUBKEY 3
 .Os
 .Sh NAME
@@ -76,7 +76,9 @@
 .Nm X509_get_X509_PUBKEY ,
 .Nm X509_get0_pubkey_bitstr ,
 .Nm X509_REQ_get_pubkey ,
-.Nm X509_REQ_set_pubkey
+.Nm X509_REQ_set_pubkey ,
+.Nm X509_extract_key ,
+.Nm X509_REQ_extract_key
 .Nd get or set certificate or certificate request public key
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -110,6 +112,14 @@
 .Fa "X509_REQ *x"
 .Fa "EVP_PKEY *pkey"
 .Fc
+.Ft EVP_PKEY *
+.Fo X509_extract_key
+.Fa "X509 *x"
+.Fc
+.Ft EVP_PKEY *
+.Fo X509_REQ_extract_key
+.Fa "X509_REQ *req"
+.Fc
 .Sh DESCRIPTION
 .Fn X509_get_pubkey
 attempts to decode the public key for certificate
@@ -158,13 +168,24 @@ The first time a public key is decoded, the
 structure is cached in the certificate or certificate request itself.
 Subsequent calls return the cached structure with its reference count
 incremented to improve performance.
+.Pp
+.Fn X509_extract_key
+and
+.Fn X509_REQ_extract_key
+are deprecated aliases for
+.Fn X509_get_pubkey
+and
+.Fn X509_REQ_get_pubkey ,
+respectively, implemented as macros.
 .Sh RETURN VALUES
 .Fn X509_get_pubkey ,
 .Fn X509_get0_pubkey ,
 .Fn X509_get_X509_PUBKEY ,
 .Fn X509_get0_pubkey_bitstr ,
+.Fn X509_REQ_get_pubkey ,
+.Fn X509_extract_key ,
 and
-.Fn X509_REQ_get_pubkey
+.Fn X509_REQ_extract_key
 return a public key or
 .Dv NULL
 if an error occurred.
@@ -185,8 +206,10 @@ the reason can be determined with
 .Sh ERRORS
 .Fn X509_get_pubkey ,
 .Fn X509_get0_pubkey ,
+.Fn X509_REQ_get_pubkey ,
+.Fn X509_extract_key ,
 and
-.Fn X509_REQ_get_pubkey
+.Fn X509_REQ_extract_key
 provide diagnostics as documented for
 .Xr X509_PUBKEY_get 3 .
 If
@@ -239,6 +262,12 @@ section 4.1 Basic Certificate Fields
 RFC 2986: PKCS #10: Certification Request Syntax Specification,
 section 4.1 CertificationRequestInfo
 .Sh HISTORY
+.Fn X509_extract_key
+and
+.Fn X509_REQ_extract_key
+first appeared in SSLeay 0.5.1 but returned a pointer to an
+.Vt RSA
+object before SSLeay 0.6.0.
 .Fn X509_get_pubkey ,
 .Fn X509_set_pubkey ,
 .Fn X509_REQ_get_pubkey ,