From 4dec832179bf3d0537e7251363a28b4f02692426 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 24 Jun 2020 19:55:55 +0000 Subject: 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@ --- src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 | 27 +++---- src/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3 | 49 +++++++++--- src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 | 102 +++++++++++++++--------- src/lib/libcrypto/man/X509_get0_signature.3 | 44 +++++++++- 4 files changed, 152 insertions(+), 70 deletions(-) (limited to 'src') diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 index befe1bd92f..8f6a0a6513 100644 --- a/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 +++ b/src/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 +.\" Copyright (c) 2019, 2020 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 @@ -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/src/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3 b/src/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3 index 11692ffd43..c14420ba5d 100644 --- a/src/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3 +++ b/src/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 . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020 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. +.\" +.\" The original file was written by Richard Levitte . .\" 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/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 b/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 index 9851538c41..99faf8dabb 100644 --- a/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 +++ b/src/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 +.\" Copyright (c) 2019, 2020 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 @@ -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/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 . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020 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. +.\" +.\" The original file was written by Dr. Stephen Henson . .\" 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 -- cgit v1.2.3-55-g6feb