From ff57b9764545ea9d58b1f7eb642e5974b8728f92 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 1 Sep 2019 09:10:09 +0000 Subject: Document EVP_PKEY_get0(3), EVP_PKEY_assign_GOST(3), EVP_PKEY_assign(3), and EVP_PKEY_set_type(3). While here, clarify a few points regarding reference count and type checking. --- src/lib/libcrypto/man/EVP_PKEY_asn1_new.3 | 8 +- src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 | 139 ++++++++++++++++++++++++------ 2 files changed, 116 insertions(+), 31 deletions(-) diff --git a/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3 b/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3 index 5cb53772b6..5d915d0183 100644 --- a/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3 +++ b/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.4 2019/06/06 01:06:58 schwarze Exp $ +.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.5 2019/09/01 09:10:09 schwarze Exp $ .\" selective merge up to: .\" OpenSSL man3/EVP_PKEY_ASN1_METHOD b0004708 Nov 1 00:45:24 2017 +0800 .\" @@ -49,7 +49,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: September 1 2019 $ .Dt EVP_PKEY_ASN1_METHOD 3 .Os .Sh NAME @@ -344,10 +344,10 @@ method helps freeing the internals of .Fa pkey . It is called by .Xr EVP_PKEY_free 3 , -.Fn EVP_PKEY_set_type , +.Xr EVP_PKEY_set_type 3 , .Fn EVP_PKEY_set_type_str , and -.Fn EVP_PKEY_assign . +.Xr EVP_PKEY_assign 3 . .Bd -unfilled .Ft int Fo (*pkey_ctrl) .Fa "EVP_PKEY *pkey" diff --git a/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 b/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 index 948bec4fb3..9851538c41 100644 --- a/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 +++ b/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 @@ -1,8 +1,24 @@ -.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.15 2019/03/18 04:01:53 schwarze Exp $ -.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 -.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.16 2019/09/01 09:10:09 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" -.\" 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) 2019 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 by Dr. Stephen Henson <steve@openssl.org>. .\" Copyright (c) 2002, 2015, 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -49,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: March 18 2019 $ +.Dd $Mdocdate: September 1 2019 $ .Dt EVP_PKEY_SET1_RSA 3 .Os .Sh NAME @@ -66,10 +82,14 @@ .Nm EVP_PKEY_get0_DH , .Nm EVP_PKEY_get0_EC_KEY , .Nm EVP_PKEY_get0_hmac , +.Nm EVP_PKEY_get0 , .Nm EVP_PKEY_assign_RSA , .Nm EVP_PKEY_assign_DSA , .Nm EVP_PKEY_assign_DH , .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 @@ -133,6 +153,10 @@ .Fa "const EVP_PKEY *pkey" .Fa "size_t *len" .Fc +.Ft void * +.Fo EVP_PKEY_get0 +.Fa "const EVP_PKEY *pkey" +.Fc .Ft int .Fo EVP_PKEY_assign_RSA .Fa "EVP_PKEY *pkey" @@ -154,6 +178,22 @@ .Fa "EC_KEY *key" .Fc .Ft int +.Fo EVP_PKEY_assign_GOST +.Fa "EVP_PKEY *pkey" +.Fa "GOST_KEY *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign +.Fa "EVP_PKEY *pkey" +.Fa "int type" +.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 @@ -174,7 +214,10 @@ and set the key referenced by .Fa pkey to -.Fa key . +.Fa key +and increment the reference count of +.Fa key +by 1 in case of success. .Pp .Fn EVP_PKEY_get1_RSA , .Fn EVP_PKEY_get1_DSA , @@ -190,8 +233,9 @@ if the key is not of the correct type. .Fn EVP_PKEY_get0_RSA , .Fn EVP_PKEY_get0_DSA , .Fn EVP_PKEY_get0_DH , +.Fn EVP_PKEY_get0_EC_KEY , and -.Fn EVP_PKEY_get0_EC_KEY +.Fn EVP_PKEY_get0 are identical except that they do not increment the reference count. Consequently, the returned key must not be freed by the caller. .Pp @@ -213,17 +257,45 @@ becomes unspecified. .Fn EVP_PKEY_assign_RSA , .Fn EVP_PKEY_assign_DSA , .Fn EVP_PKEY_assign_DH , +.Fn EVP_PKEY_assign_EC_KEY , +.Fn EVP_PKEY_assign_GOST , and -.Fn EVP_PKEY_assign_EC_KEY +.Fn EVP_PKEY_assign also set the referenced key to .Fa key ; however these use the supplied .Fa key -internally and so +internally without incrementing its reference count, such that .Fa key will be freed when the parent .Fa pkey is freed. +If the +.Fa key +is of the wrong type, these functions report success even though +.Fa pkey +ends up in a corrupted state. +Even the functions explicitly containing the type in their name are +.Em not +type safe because they are implemented as macros. +The following types are supported: +.Dv EVP_PKEY_RSA , +.Dv EVP_PKEY_DSA , +.Dv EVP_PKEY_DH , +.Dv EVP_PKEY_EC , +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 @@ -267,19 +339,19 @@ using the .Sy 1 functions must be freed as well as .Fa pkey . -.Pp -.Fn EVP_PKEY_assign_RSA , -.Fn EVP_PKEY_assign_DSA , -.Fn EVP_PKEY_assign_DH , -and -.Fn EVP_PKEY_assign_EC_KEY -are implemented as macros. .Sh RETURN VALUES .Fn EVP_PKEY_set1_RSA , .Fn EVP_PKEY_set1_DSA , .Fn EVP_PKEY_set1_DH , +.Fn EVP_PKEY_set1_EC_KEY , +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +.Fn EVP_PKEY_assign_EC_KEY , +.Fn EVP_PKEY_assign_GOST , +.Fn EVP_PKEY_assign , and -.Fn EVP_PKEY_set1_EC_KEY +.Fn EVP_PKEY_set_type return 1 for success or 0 for failure. .Pp .Fn EVP_PKEY_get1_RSA , @@ -290,18 +362,24 @@ return 1 for success or 0 for failure. .Fn EVP_PKEY_get0_DSA , .Fn EVP_PKEY_get0_DH , .Fn EVP_PKEY_get0_EC_KEY , +.Fn EVP_PKEY_get0_hmac , and -.Fn EVP_PKEY_get0_hmac +.Fn EVP_PKEY_get0 return the referenced key or .Dv NULL if an error occurred. -.Pp -.Fn EVP_PKEY_assign_RSA , -.Fn EVP_PKEY_assign_DSA , -.Fn EVP_PKEY_assign_DH , -and -.Fn EVP_PKEY_assign_EC_KEY -return 1 for success and 0 for failure. +For +.Fn EVP_PKEY_get0 , +the return value points to an +.Vt RSA , +.Vt DSA , +.Vt DH , +.Vt EC_KEY , +.Vt GOST_KEY , +or +.Vt ASN1_OCTET_STRING +object depending on the type of +.Fa pkey . .Pp .Fn EVP_PKEY_base_id , .Fn EVP_PKEY_id , @@ -323,6 +401,7 @@ on error. .Fn EVP_PKEY_assign_RSA , .Fn EVP_PKEY_assign_DSA , .Fn EVP_PKEY_assign_DH , +.Fn EVP_PKEY_assign , and .Fn EVP_PKEY_type first appeared in SSLeay 0.8.0 and have been available since @@ -345,12 +424,18 @@ and first appeared in OpenSSL 0.9.8 and have been available since .Ox 4.5 . .Pp -.Fn EVP_PKEY_id +.Fn EVP_PKEY_get0 , +.Fn EVP_PKEY_set_type , +.Fn EVP_PKEY_base_id , and -.Fn EVP_PKEY_base_id +.Fn EVP_PKEY_id first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . .Pp +.Fn EVP_PKEY_assign_GOST +first appeared in +.Ox 5.7 . +.Pp .Fn EVP_PKEY_get0_RSA , .Fn EVP_PKEY_get0_DSA , .Fn EVP_PKEY_get0_DH , -- cgit v1.2.3-55-g6feb