From 89182be0bac20f906d76b36e976f0c202eb68f43 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Fri, 16 Aug 2019 16:15:51 +0000 Subject: document the EC_KEY_METHOD function table --- lib/libcrypto/man/ECDSA_SIG_new.3 | 5 +- lib/libcrypto/man/EC_KEY_METHOD_new.3 | 325 ++++++++++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- 3 files changed, 330 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/EC_KEY_METHOD_new.3 diff --git a/lib/libcrypto/man/ECDSA_SIG_new.3 b/lib/libcrypto/man/ECDSA_SIG_new.3 index c5e50d890e3..f2ce4bf26c9 100644 --- a/lib/libcrypto/man/ECDSA_SIG_new.3 +++ b/lib/libcrypto/man/ECDSA_SIG_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ECDSA_SIG_new.3,v 1.13 2019/06/10 09:49:48 schwarze Exp $ +.\" $OpenBSD: ECDSA_SIG_new.3,v 1.14 2019/08/16 16:15:50 schwarze Exp $ .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 .\" selective merge up to: OpenSSL 6da34cfb Jun 2 16:17:32 2018 -0400 .\" @@ -50,7 +50,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: August 16 2019 $ .Dt ECDSA_SIG_NEW 3 .Os .Sh NAME @@ -483,6 +483,7 @@ if (ret == -1) { .Xr d2i_ECPKParameters 3 , .Xr DSA_new 3 , .Xr EC_GROUP_new 3 , +.Xr EC_KEY_METHOD_new 3 , .Xr EC_KEY_new 3 , .Xr ECDSA_set_ex_data 3 , .Xr EVP_DigestSignInit 3 , diff --git a/lib/libcrypto/man/EC_KEY_METHOD_new.3 b/lib/libcrypto/man/EC_KEY_METHOD_new.3 new file mode 100644 index 00000000000..383688b0ef5 --- /dev/null +++ b/lib/libcrypto/man/EC_KEY_METHOD_new.3 @@ -0,0 +1,325 @@ +.\" $OpenBSD: EC_KEY_METHOD_new.3,v 1.1 2019/08/16 16:15:50 schwarze Exp $ +.\" Copyright (c) 2019 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. +.\" +.Dd $Mdocdate: August 16 2019 $ +.Dt EC_KEY_METHOD_NEW 3 +.Os +.Sh NAME +.Nm EC_KEY_METHOD_new , +.Nm EC_KEY_METHOD_free , +.Nm EC_KEY_METHOD_set_init , +.Nm EC_KEY_METHOD_get_init , +.Nm EC_KEY_METHOD_set_sign , +.Nm EC_KEY_METHOD_get_sign , +.Nm EC_KEY_METHOD_set_verify , +.Nm EC_KEY_METHOD_get_verify , +.Nm EC_KEY_METHOD_set_keygen , +.Nm EC_KEY_METHOD_get_keygen , +.Nm EC_KEY_METHOD_set_compute_key , +.Nm EC_KEY_METHOD_get_compute_key , +.Nm EC_KEY_OpenSSL , +.Nm EC_KEY_set_default_method , +.Nm EC_KEY_get_default_method , +.Nm EC_KEY_new_method , +.Nm EC_KEY_set_method , +.Nm EC_KEY_get_method +.Nd custom EC_KEY implementations +.Sh SYNOPSIS +.In openssl/ec.h +.Ft EC_KEY_METHOD * +.Fo EC_KEY_METHOD_new +.Fa "const EC_KEY_METHOD *meth" +.Fc +.Ft void +.Fo EC_KEY_METHOD_free +.Fa "EC_KEY_METHOD *meth" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_init +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*init)(EC_KEY *key)" +.Fa "void (*finish)(EC_KEY *key)" +.Fa "int (*copy)(EC_KEY *dest, const EC_KEY *src)" +.Fa "int (*set_group)(EC_KEY *key, const EC_GROUP *grp)" +.Fa "int (*set_private)(EC_KEY *key, const BIGNUM *priv_key)" +.Fa "int (*set_public)(EC_KEY *key, const EC_POINT *pub_key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_init +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pinit)(EC_KEY *key)" +.Fa "void (**pfinish)(EC_KEY *key)" +.Fa "int (**pcopy)(EC_KEY *dest, const EC_KEY *src)" +.Fa "int (**pset_group)(EC_KEY *key, const EC_GROUP *grp)" +.Fa "int (**pset_private)(EC_KEY *key, const BIGNUM *priv_key)" +.Fa "int (**pset_public)(EC_KEY *key, const EC_POINT *pub_key)" +.Fc +.In openssl/ecdsa.h +.Ft void +.Fo EC_KEY_METHOD_set_sign +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*sign)(int type, const unsigned char *dgst, int dgstlen,\ + unsigned char *sig, unsigned int *siglen,\ + const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)" +.Fa "int (*sign_setup)(EC_KEY *eckey, BN_CTX *ctx,\ + BIGNUM **kinv, BIGNUM **rp)" +.Fa "ECDSA_SIG *(*sign_sig)(const unsigned char *dgst, int dgstlen,\ + const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_sign +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**psign)(int type, const unsigned char *dgst, int dgstlen,\ + unsigned char *sig, unsigned int *siglen,\ + const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)" +.Fa "int (**psign_setup)(EC_KEY *eckey, BN_CTX *ctx,\ + BIGNUM **kinv, BIGNUM **rp)" +.Fa "ECDSA_SIG *(**psign_sig)(const unsigned char *dgst, int dgstlen,\ + const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_verify +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*verify)(int type, const unsigned char *dgst, int dgst_len,\ + const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)" +.Fa "int (*verify_sig)(const unsigned char *dgst, int dgst_len,\ + const ECDSA_SIG *sig, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_verify +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pverify)(int type, const unsigned char *dgst, int dgst_len,\ + const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)" +.Fa "int (**pverify_sig)(const unsigned char *dgst, int dgst_len,\ + const ECDSA_SIG *sig, EC_KEY *eckey)" +.Fc +.In openssl/ec.h +.Ft void +.Fo EC_KEY_METHOD_set_keygen +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*keygen)(EC_KEY *key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_keygen +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pkeygen)(EC_KEY *key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_compute_key +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*ckey)(void *out, size_t outlen,\ + const EC_POINT *pub_key, EC_KEY *ecdh,\ + void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_compute_key +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pck)(void *out, size_t outlen,\ + const EC_POINT *pub_key, EC_KEY *ecdh,\ + void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))" +.Fc +.Ft const EC_KEY_METHOD * +.Fn EC_KEY_OpenSSL void +.Ft void +.Fo EC_KEY_set_default_method +.Fa "const EC_KEY_METHOD *meth" +.Fc +.Ft const EC_KEY_METHOD * +.Fn EC_KEY_get_default_method void +.Ft EC_KEY * +.Fo EC_KEY_new_method +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo EC_KEY_set_method +.Fa "EC_KEY *key" +.Fa "const EC_KEY_METHOD *meth" +.Fc +.Ft const EC_KEY_METHOD * +.Fo EC_KEY_get_method +.Fa "const EC_KEY *key" +.Fc +.Sh DESCRIPTION +An +.Vt EC_KEY_METHOD +object holds function pointers used for +.Vt EC_KEY +operations. +.Pp +.Fn EC_KEY_METHOD_new +creates a shallow copy of +.Fa meth , +or an empty +.Vt EC_KEY_METHOD +object if +.Fa meth +is +.Dv NULL . +.Pp +.Fn EC_KEY_METHOD_free +frees +.Fa meth . +If +.Fa meth +is +.Dv NULL +or the return value of +.Fn EC_KEY_OpenSSL , +no action occurs. +.Pp +.Fn EC_KEY_METHOD_set_init +and +.Fn EC_KEY_METHOD_get_init +set and retrieve optional callback functions called at the following places: +.Pp +.Bl -tag -width set_private -compact +.It Fa init +at the end of +.Fn EC_KEY_new_method +and +.Fn EC_KEY_set_method +.It Fa finish +at the beginning of +.Xr EC_KEY_free 3 , +.Xr EC_KEY_copy 3 , +and +.Fn EC_KEY_set_method +.It Fa copy +at the end of +.Xr EC_KEY_copy 3 +.It Fa set_group +at the end of +.Xr EC_KEY_set_group 3 +and +.Xr EC_KEY_new_by_curve_name 3 +.It Fa set_private +at the beginning of +.Xr EC_KEY_set_private_key 3 +.It Fa set_public +at the beginning of +.Xr EC_KEY_set_public_key 3 +.El +.Pp +If any of these callbacks returns 0, the calling function fails. +By default, all these callbacks are +.Dv NULL . +Arguments of +.Fn EC_KEY_METHOD_get_init +can be set to +.Dv NULL +to selectively retrieve callback function pointers. +.Pp +.Fn EC_KEY_METHOD_set_sign +and +.Fn EC_KEY_METHOD_get_sign +set and retrieve the functions implementing +.Xr ECDSA_sign_ex 3 , +.Xr ECDSA_sign_setup 3 , +and +.Xr ECDSA_do_sign_ex 3 . +.Pp +.Fn EC_KEY_METHOD_set_verify +and +.Fn EC_KEY_METHOD_get_verify +set and retrieve the functions implementing +.Xr ECDSA_verify 3 +and +.Xr ECDSA_do_verify 3 . +.Pp +.Fn EC_KEY_METHOD_set_keygen +and +.Fn EC_KEY_METHOD_get_keygen +set and retrieve the function implementing +.Xr EC_KEY_generate_key 3 . +.Pp +.Fn EC_KEY_METHOD_set_compute_key +and +.Fn EC_KEY_METHOD_get_compute_key +set and retrieve the function implementing +.Xr ECDH_compute_key 3 . +.Pp +.Fn EC_KEY_set_default_method +chooses the +.Fa meth +to be used for the creation of new +.Vt EC_KEY +objects by future invocations of +.Fn EC_KEY_new_method , +or reverts to the default implementation if +.Fa meth +is +.Dv NULL . +.Pp +.Fn EC_KEY_new_method +creates and initializes a new +.Vt EC_KEY +object using the given +.Fa engine , +or the using the +.Vt EC_KEY_METHOD +set with +.Fn EC_KEY_set_default_method +if +.Fa engine +is +.Dv NULL , +or using the default EC_KEY implementation by default. +.Pp +.Fn EC_KEY_set_method +dissociates the +.Fa key +from the +.Vt ENGINE +it is using, if any, and causes it to use +.Fa meth +in the future. +.Sh RETURN VALUES +.Fn EC_KEY_METHOD_new +returns the newly allocated +.Vt EC_KEY_METHOD +object or +.Dv NULL +if an error occurs. +.Pp +.Fn EC_KEY_OpenSSL +returns a static object representing the default EC_KEY implementation. +.Pp +.Fn EC_KEY_get_default_method +returns the +.Vt EC_KEY_METHOD +that +.Fn EC_KEY_new_method +will use for the creation of new +.Vt EC_KEY +objects in the future. +.Pp +.Fn EC_KEY_new_method +returns the newly allocated +.Vt EC_KEY +object or NULL if an error occurs. +.Pp +.Fn EC_KEY_set_method +returns 1 for success or 0 for failure. +.Pp +.Fn EC_KEY_get_method +returns the EC_KEY implementation used by the given +.Fa key . +.Sh SEE ALSO +.Xr EC_KEY_new 3 , +.Xr ECDSA_sign 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.5 . diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index a9adb07f27d..e347c3dc988 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.148 2019/03/21 14:15:13 schwarze Exp $ +# $OpenBSD: Makefile,v 1.149 2019/08/16 16:15:50 schwarze Exp $ .include @@ -95,6 +95,7 @@ MAN= \ EC_GFp_simple_method.3 \ EC_GROUP_copy.3 \ EC_GROUP_new.3 \ + EC_KEY_METHOD_new.3 \ EC_KEY_new.3 \ EC_POINT_add.3 \ EC_POINT_new.3 \ -- cgit v1.2.3