Properly document the return values of EVP_PKEY_base_id(3)

and EVP_PKEY_id(3), then describe the "type" parameters of
various functions more precisely referencing that information.
In particular, document X509_get_signature_type(3) which was
so far missing.
OK tb@

1 files changed, 40 insertions, 4 deletions

diff --git a/src/lib/libcrypto/man/X509_get0_signature.3 b/src/lib/libcrypto/man/X509_get0_signature.3
index a0982f2193..903cc043d9 100644
--- a/src/lib/libcrypto/man/X509_get0_signature.3
+++ b/src/lib/libcrypto/man/X509_get0_signature.3
@@ -1,8 +1,25 @@
-.\" $OpenBSD: X509_get0_signature.3,v 1.5 2018/03/23 23:18:17 schwarze Exp $
+.\" $OpenBSD: X509_get0_signature.3,v 1.6 2020/06/24 19:55:55 schwarze Exp $
 .\" selective merge up to:
 .\" OpenSSL man3/X509_get0_signature 2f7a2520 Apr 25 17:28:08 2017 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2020 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.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -49,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: March 23 2018 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt X509_GET0_SIGNATURE 3
 .Os
 .Sh NAME
@@ -57,6 +74,7 @@
 .Nm X509_REQ_get0_signature ,
 .Nm X509_CRL_get0_signature ,
 .Nm X509_get0_tbs_sigalg ,
+.Nm X509_get_signature_type ,
 .Nm X509_get_signature_nid ,
 .Nm X509_REQ_get_signature_nid ,
 .Nm X509_CRL_get_signature_nid
@@ -86,6 +104,10 @@
 .Fa "const X509 *x"
 .Fc
 .Ft int
+.Fo X509_get_signature_type
+.Fa "const X509 *x"
+.Fc
+.Ft int
 .Fo X509_get_signature_nid
 .Fa "const X509 *x"
 .Fc
@@ -118,6 +140,13 @@ returns the signature algorithm in the signed portion of
 The values returned are internal pointers
 that must not be freed by the caller.
 .Pp
+.Fn X509_get_signature_type
+returns the base NID corresponding to the signature algorithm of
+.Fa x
+just like
+.Xr EVP_PKEY_base_id 3
+does.
+.Pp
 .Fn X509_get_signature_nid ,
 .Fn X509_REQ_get_signature_nid ,
 and
@@ -127,7 +156,9 @@ return the NID corresponding to the signature algorithm of
 .Fa req ,
 or
 .Fa crl ,
-respectively.
+respectively, just like
+.Xr EVP_PKEY_id 3
+does.
 .Pp
 These functions provide lower level access to the signature
 for cases where an application wishes to analyse or generate a
@@ -135,6 +166,7 @@ signature in a form where
 .Xr X509_sign 3
 is not appropriate, for example in a non-standard or unsupported format.
 .Sh SEE ALSO
+.Xr EVP_PKEY_base_id 3 ,
 .Xr OBJ_obj2nid 3 ,
 .Xr X509_ALGOR_new 3 ,
 .Xr X509_CRL_get0_by_serial 3 ,
@@ -147,6 +179,10 @@ is not appropriate, for example in a non-standard or unsupported format.
 .Xr X509_sign 3 ,
 .Xr X509_verify_cert 3
 .Sh HISTORY
+.Fn X509_get_signature_type
+first appeared in SSLeay 0.8.0 and has been available since
+.Ox 2.4 .
+.Pp
 .Fn X509_get0_signature
 and
 .Fn X509_get_signature_nid