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@

4 files changed, 152 insertions, 70 deletions

diff --git a/lib/libcrypto/man/EVP_PKEY_CTX_new.3 b/lib/libcrypto/man/EVP_PKEY_CTX_new.3
index befe1bd92f9..8f6a0a65132 100644
--- a/lib/libcrypto/man/EVP_PKEY_CTX_new.3
+++ b/lib/libcrypto/man/EVP_PKEY_CTX_new.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: EVP_PKEY_CTX_new.3,v 1.10 2019/11/01 19:51:09 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_CTX_new.3,v 1.11 2020/06/24 19:55:55 schwarze Exp $
 .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2019, 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
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 1 2019 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt EVP_PKEY_CTX_NEW 3
 .Os
 .Sh NAME
@@ -123,23 +123,13 @@ It is normally used when no
 .Vt EVP_PKEY
 structure is associated with the operations, for example during
 parameter generation of key generation for some algorithms.
-The following
+The
 .Fa id
-constants are supported:
-.Dv EVP_PKEY_CMAC ,
-.Dv EVP_PKEY_DH ,
-.Dv EVP_PKEY_DSA ,
-.Dv EVP_PKEY_EC ,
-.Dv EVP_PKEY_GOSTIMIT ,
-.Dv EVP_PKEY_GOSTR01 ,
-.Dv EVP_PKEY_HMAC ,
-.Dv EVP_PKEY_RSA ,
+argument can be any of the constants that
+.Xr EVP_PKEY_base_id 3
 and
-.Dv EVP_PKEY_RSA_PSS .
-Application programs can define additional
-.Fa id
-values using
-.Xr EVP_PKEY_meth_new 3 .
+.Xr EVP_PKEY_id 3
+may return.
 .Pp
 .Fn EVP_PKEY_CTX_dup
 duplicates the context
@@ -166,6 +156,7 @@ if an error occurred.
 .Sh SEE ALSO
 .Xr EVP_DigestSignInit 3 ,
 .Xr EVP_DigestVerifyInit 3 ,
+.Xr EVP_PKEY_base_id 3 ,
 .Xr EVP_PKEY_CTX_ctrl 3 ,
 .Xr EVP_PKEY_decrypt 3 ,
 .Xr EVP_PKEY_derive 3 ,
diff --git a/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3 b/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3
index 11692ffd433..c14420ba5d3 100644
--- a/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3
+++ b/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: EVP_PKEY_asn1_get_count.3,v 1.4 2019/06/06 01:06:58 schwarze Exp $
-.\" full merge up to: OpenSSL 751148e2 Oct 27 00:11:11 2017 +0200
+.\" $OpenBSD: EVP_PKEY_asn1_get_count.3,v 1.5 2020/06/24 19:55:54 schwarze Exp $
+.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000
 .\"
-.\" This file was written by Richard Levitte <levitte@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 Richard Levitte <levitte@openssl.org>.
 .\" Copyright (c) 2017 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt EVP_PKEY_ASN1_GET_COUNT 3
 .Os
 .Sh NAME
@@ -93,7 +110,7 @@
 .Fc
 .Sh DESCRIPTION
 .Fn EVP_PKEY_asn1_get_count
-returns a count of the number of public key ASN.1 methods available.
+returns the number of public key ASN.1 methods available.
 It includes standard methods and any methods added by the application.
 .Pp
 .Fn EVP_PKEY_asn1_get0
@@ -107,7 +124,12 @@ must be in the range from zero to
 .Pp
 .Fn EVP_PKEY_asn1_find
 looks up the method with NID
-.Fa type .
+.Fa type ,
+which can be any of the values that
+.Xr EVP_PKEY_base_id 3
+and
+.Xr EVP_PKEY_id 3
+may return.
 If
 .Fa pe
 is not
@@ -121,6 +143,9 @@ is set to that engine and the method from that engine is returned instead.
 .Fn EVP_PKEY_asn1_find_str
 looks up the method with PEM type string
 .Fa str .
+The PEM type strings supported by default are listed in the
+.Xr EVP_PKEY_base_id 3
+manual page.
 Just like
 .Fn EVP_PKEY_asn1_find ,
 if
@@ -130,10 +155,14 @@ is not
 methods from engines are preferred.
 .Pp
 .Fn EVP_PKEY_asn1_get0_info
-retrieves the public key ID, the base public key ID (both NIDs), any flags,
-the method description and the PEM type string associated with the public
-key ASN.1 method
-.Sy *ameth .
+retrieves the public key ID as returned by
+.Xr EVP_PKEY_id 3 ,
+the base public key ID as returned by
+.Xr EVP_PKEY_base_id 3
+.Pq both NIDs ,
+any flags, the method description,
+and the PEM type string associated with
+.Fa ameth .
 .Pp
 .Fn EVP_PKEY_asn1_get_count ,
 .Fn EVP_PKEY_asn1_get0 ,
diff --git a/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 b/lib/libcrypto/man/EVP_PKEY_set1_RSA.3
index 9851538c413..99faf8dabbf 100644
--- a/lib/libcrypto/man/EVP_PKEY_set1_RSA.3
+++ b/lib/libcrypto/man/EVP_PKEY_set1_RSA.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.16 2019/09/01 09:10:09 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.17 2020/06/24 19:55:54 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2019, 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
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 1 2019 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt EVP_PKEY_SET1_RSA 3
 .Os
 .Sh NAME
@@ -89,10 +89,10 @@
 .Nm EVP_PKEY_assign_EC_KEY ,
 .Nm EVP_PKEY_assign_GOST ,
 .Nm EVP_PKEY_assign ,
-.Nm EVP_PKEY_set_type ,
 .Nm EVP_PKEY_base_id ,
 .Nm EVP_PKEY_id ,
-.Nm EVP_PKEY_type
+.Nm EVP_PKEY_type ,
+.Nm EVP_PKEY_set_type
 .Nd EVP_PKEY assignment functions
 .Sh SYNOPSIS
 .In openssl/evp.h
@@ -189,11 +189,6 @@
 .Fa "void *key"
 .Fc
 .Ft int
-.Fo EVP_PKEY_set_type
-.Fa "EVP_PKEY *pkey"
-.Fa "int type"
-.Fc
-.Ft int
 .Fo EVP_PKEY_base_id
 .Fa "EVP_PKEY *pkey"
 .Fc
@@ -205,6 +200,11 @@
 .Fo EVP_PKEY_type
 .Fa "int type"
 .Fc
+.Ft int
+.Fo EVP_PKEY_set_type
+.Fa "EVP_PKEY *pkey"
+.Fa "int type"
+.Fc
 .Sh DESCRIPTION
 .Fn EVP_PKEY_set1_RSA ,
 .Fn EVP_PKEY_set1_DSA ,
@@ -286,38 +286,51 @@ The following types are supported:
 and
 .Dv EVP_PKEY_GOSTR01 .
 .Pp
-.Fn EVP_PKEY_set_type
-frees the key referenced in
-.Fa pkey ,
-if any, and sets the key type of
-.Fa pkey
-to
-.Fa type
-without referencing a new key from
-.Fa pkey
-yet.
-.Pp
 .Fn EVP_PKEY_base_id
 returns the type of
-.Fa pkey .
-For example, an RSA key will return
-.Dv EVP_PKEY_RSA .
+.Fa pkey
+according to the following table:
+.Pp
+.Bl -column -compact -offset 2n EVP_PKEY_GOSTR NID_X9_62_id_ecPublicKey
+.It Sy return value      Ta                               Ta Sy PEM type string
+.It Dv EVP_PKEY_CMAC     Ta = Dv NID_cmac                 Ta CMAC
+.It Dv EVP_PKEY_DH       Ta = Dv NID_dhKeyAgreement       Ta DH
+.It Dv EVP_PKEY_DSA      Ta = Dv NID_dsa                  Ta DSA
+.It Dv EVP_PKEY_EC       Ta = Dv NID_X9_62_id_ecPublicKey Ta EC
+.It Dv EVP_PKEY_GOSTIMIT Ta = Dv NID_id_Gost28147_89_MAC  Ta GOST-MAC
+.It Dv EVP_PKEY_GOSTR01  Ta = Dv NID_id_GostR3410_2001    Ta GOST2001
+.It Dv EVP_PKEY_HMAC     Ta = Dv NID_hmac                 Ta HMAC
+.It Dv EVP_PKEY_RSA      Ta = Dv NID_rsaEncryption        Ta RSA
+.It Dv EVP_PKEY_RSA_PSS  Ta = Dv NID_rsassaPss            Ta RSA-PSS
+.El
+.Pp
+Application programs can support additional key types by calling
+.Xr EVP_PKEY_asn1_add0 3 .
 .Pp
 .Fn EVP_PKEY_id
 returns the actual OID associated with
 .Fa pkey .
 Historically keys using the same algorithm could use different OIDs.
-For example, an RSA key could use the OIDs corresponding to the NIDs
-.Dv NID_rsaEncryption
-(equivalent to
-.Dv EVP_PKEY_RSA )
-or
-.Dv NID_rsa
-(equivalent to
-.Dv EVP_PKEY_RSA2 ) .
-The use of alternative non-standard OIDs is now rare, so
-.Dv EVP_PKEY_RSA2
-et al. are not often seen in practice.
+The following deprecated aliases are still supported:
+.Pp
+.Bl -column -compact -offset 2n EVP_PKEY_GOSTR12_ NID_id_tc26_gost3410_2012_512
+.It Sy return value         Ta                                  Ta Sy alias for
+.It Dv EVP_PKEY_DSA1        Ta = Dv NID_dsa_2                     Ta DSA
+.It Dv EVP_PKEY_DSA2        Ta = Dv NID_dsaWithSHA                Ta DSA
+.It Dv EVP_PKEY_DSA3        Ta = Dv NID_dsaWithSHA1               Ta DSA
+.It Dv EVP_PKEY_DSA4        Ta = Dv NID_dsaWithSHA1_2             Ta DSA
+.It Dv EVP_PKEY_GOSTR12_256 Ta = Dv NID_id_tc26_gost3410_2012_256 Ta GOST2001
+.It Dv EVP_PKEY_GOSTR12_512 Ta = Dv NID_id_tc26_gost3410_2012_512 Ta GOST2001
+.It Dv EVP_PKEY_RSA2        Ta = Dv NID_rsa                       Ta RSA
+.El
+.Pp
+Application programs can support additional alternative OIDs by calling
+.Xr EVP_PKEY_asn1_add_alias 3 .
+.Pp
+Most applications wishing to know a key type will simply call
+.Fn EVP_PKEY_base_id
+and will not care about the actual type,
+which will be identical in almost all cases.
 .Pp
 .Fn EVP_PKEY_type
 returns the underlying type of the NID
@@ -327,10 +340,23 @@ For example,
 will return
 .Dv EVP_PKEY_RSA .
 .Pp
-Most applications wishing to know a key type will simply call
+.Fn EVP_PKEY_set_type
+frees the key referenced in
+.Fa pkey ,
+if any, and sets the key type of
+.Fa pkey
+to
+.Fa type
+without referencing a new key from
+.Fa pkey
+yet.
+For
+.Fa type ,
+any of the possible return values of
 .Fn EVP_PKEY_base_id
-and will not care about the actual type,
-which will be identical in almost all cases.
+and
+.Fn EVP_PKEY_id
+can be passed.
 .Pp
 In accordance with the OpenSSL naming convention, the key obtained from
 or assigned to
diff --git a/lib/libcrypto/man/X509_get0_signature.3 b/lib/libcrypto/man/X509_get0_signature.3
index a0982f2193a..903cc043d9a 100644
--- a/lib/libcrypto/man/X509_get0_signature.3
+++ b/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