1.\" $OpenBSD: EC_KEY_METHOD_new.3,v 1.4 2024/07/21 08:36:43 tb Exp $ 2.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: July 21 2024 $ 17.Dt EC_KEY_METHOD_NEW 3 18.Os 19.Sh NAME 20.Nm EC_KEY_METHOD_new , 21.Nm EC_KEY_METHOD_free , 22.Nm EC_KEY_METHOD_set_init , 23.Nm EC_KEY_METHOD_get_init , 24.Nm EC_KEY_METHOD_set_sign , 25.Nm EC_KEY_METHOD_get_sign , 26.Nm EC_KEY_METHOD_set_verify , 27.Nm EC_KEY_METHOD_get_verify , 28.Nm EC_KEY_METHOD_set_keygen , 29.Nm EC_KEY_METHOD_get_keygen , 30.Nm EC_KEY_METHOD_set_compute_key , 31.Nm EC_KEY_METHOD_get_compute_key , 32.Nm EC_KEY_OpenSSL , 33.Nm EC_KEY_set_default_method , 34.Nm EC_KEY_get_default_method , 35.Nm EC_KEY_new_method , 36.Nm EC_KEY_set_method , 37.Nm EC_KEY_get_method 38.Nd custom EC_KEY implementations 39.Sh SYNOPSIS 40.In openssl/ec.h 41.Ft EC_KEY_METHOD * 42.Fo EC_KEY_METHOD_new 43.Fa "const EC_KEY_METHOD *meth" 44.Fc 45.Ft void 46.Fo EC_KEY_METHOD_free 47.Fa "EC_KEY_METHOD *meth" 48.Fc 49.Ft void 50.Fo EC_KEY_METHOD_set_init 51.Fa "EC_KEY_METHOD *meth" 52.Fa "int (*init)(EC_KEY *key)" 53.Fa "void (*finish)(EC_KEY *key)" 54.Fa "int (*copy)(EC_KEY *dest, const EC_KEY *src)" 55.Fa "int (*set_group)(EC_KEY *key, const EC_GROUP *grp)" 56.Fa "int (*set_private)(EC_KEY *key, const BIGNUM *priv_key)" 57.Fa "int (*set_public)(EC_KEY *key, const EC_POINT *pub_key)" 58.Fc 59.Ft void 60.Fo EC_KEY_METHOD_get_init 61.Fa "const EC_KEY_METHOD *meth" 62.Fa "int (**pinit)(EC_KEY *key)" 63.Fa "void (**pfinish)(EC_KEY *key)" 64.Fa "int (**pcopy)(EC_KEY *dest, const EC_KEY *src)" 65.Fa "int (**pset_group)(EC_KEY *key, const EC_GROUP *grp)" 66.Fa "int (**pset_private)(EC_KEY *key, const BIGNUM *priv_key)" 67.Fa "int (**pset_public)(EC_KEY *key, const EC_POINT *pub_key)" 68.Fc 69.Ft void 70.Fo EC_KEY_METHOD_set_sign 71.Fa "EC_KEY_METHOD *meth" 72.Fa "int (*sign)(int type, const unsigned char *dgst, int dgstlen,\ 73 unsigned char *sig, unsigned int *siglen,\ 74 const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)" 75.Fa "int (*sign_setup)(EC_KEY *eckey, BN_CTX *ctx,\ 76 BIGNUM **kinv, BIGNUM **rp)" 77.Fa "ECDSA_SIG *(*sign_sig)(const unsigned char *dgst, int dgstlen,\ 78 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)" 79.Fc 80.Ft void 81.Fo EC_KEY_METHOD_get_sign 82.Fa "const EC_KEY_METHOD *meth" 83.Fa "int (**psign)(int type, const unsigned char *dgst, int dgstlen,\ 84 unsigned char *sig, unsigned int *siglen,\ 85 const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)" 86.Fa "int (**psign_setup)(EC_KEY *eckey, BN_CTX *ctx,\ 87 BIGNUM **kinv, BIGNUM **rp)" 88.Fa "ECDSA_SIG *(**psign_sig)(const unsigned char *dgst, int dgstlen,\ 89 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)" 90.Fc 91.Ft void 92.Fo EC_KEY_METHOD_set_verify 93.Fa "EC_KEY_METHOD *meth" 94.Fa "int (*verify)(int type, const unsigned char *dgst, int dgst_len,\ 95 const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)" 96.Fa "int (*verify_sig)(const unsigned char *dgst, int dgst_len,\ 97 const ECDSA_SIG *sig, EC_KEY *eckey)" 98.Fc 99.Ft void 100.Fo EC_KEY_METHOD_get_verify 101.Fa "const EC_KEY_METHOD *meth" 102.Fa "int (**pverify)(int type, const unsigned char *dgst, int dgst_len,\ 103 const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)" 104.Fa "int (**pverify_sig)(const unsigned char *dgst, int dgst_len,\ 105 const ECDSA_SIG *sig, EC_KEY *eckey)" 106.Fc 107.Ft void 108.Fo EC_KEY_METHOD_set_keygen 109.Fa "EC_KEY_METHOD *meth" 110.Fa "int (*keygen)(EC_KEY *key)" 111.Fc 112.Ft void 113.Fo EC_KEY_METHOD_get_keygen 114.Fa "const EC_KEY_METHOD *meth" 115.Fa "int (**pkeygen)(EC_KEY *key)" 116.Fc 117.Ft void 118.Fo EC_KEY_METHOD_set_compute_key 119.Fa "EC_KEY_METHOD *meth" 120.Fa "int (*ckey)(void *out, size_t outlen,\ 121 const EC_POINT *pub_key, EC_KEY *ecdh,\ 122 void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))" 123.Fc 124.Ft void 125.Fo EC_KEY_METHOD_get_compute_key 126.Fa "const EC_KEY_METHOD *meth" 127.Fa "int (**pck)(void *out, size_t outlen,\ 128 const EC_POINT *pub_key, EC_KEY *ecdh,\ 129 void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))" 130.Fc 131.Ft const EC_KEY_METHOD * 132.Fn EC_KEY_OpenSSL void 133.Ft void 134.Fo EC_KEY_set_default_method 135.Fa "const EC_KEY_METHOD *meth" 136.Fc 137.Ft const EC_KEY_METHOD * 138.Fn EC_KEY_get_default_method void 139.Ft EC_KEY * 140.Fo EC_KEY_new_method 141.Fa "ENGINE *engine" 142.Fc 143.Ft int 144.Fo EC_KEY_set_method 145.Fa "EC_KEY *key" 146.Fa "const EC_KEY_METHOD *meth" 147.Fc 148.Ft const EC_KEY_METHOD * 149.Fo EC_KEY_get_method 150.Fa "const EC_KEY *key" 151.Fc 152.Sh DESCRIPTION 153An 154.Vt EC_KEY_METHOD 155object holds function pointers used for 156.Vt EC_KEY 157operations. 158.Pp 159.Fn EC_KEY_METHOD_new 160creates a shallow copy of 161.Fa meth , 162or an empty 163.Vt EC_KEY_METHOD 164object if 165.Fa meth 166is 167.Dv NULL . 168.Pp 169.Fn EC_KEY_METHOD_free 170frees 171.Fa meth . 172If 173.Fa meth 174is 175.Dv NULL 176or the return value of 177.Fn EC_KEY_OpenSSL , 178no action occurs. 179.Pp 180.Fn EC_KEY_METHOD_set_init 181and 182.Fn EC_KEY_METHOD_get_init 183set and retrieve optional callback functions called at the following places: 184.Pp 185.Bl -tag -width set_private -compact 186.It Fa init 187at the end of 188.Fn EC_KEY_new_method 189and 190.Fn EC_KEY_set_method 191.It Fa finish 192at the beginning of 193.Xr EC_KEY_free 3 , 194.Xr EC_KEY_copy 3 , 195and 196.Fn EC_KEY_set_method 197.It Fa copy 198at the end of 199.Xr EC_KEY_copy 3 200.It Fa set_group 201at the end of 202.Xr EC_KEY_set_group 3 203and 204.Xr EC_KEY_new_by_curve_name 3 205.It Fa set_private 206at the beginning of 207.Xr EC_KEY_set_private_key 3 208.It Fa set_public 209at the beginning of 210.Xr EC_KEY_set_public_key 3 211.El 212.Pp 213If any of these callbacks returns 0, the calling function fails. 214By default, all these callbacks are 215.Dv NULL . 216Arguments of 217.Fn EC_KEY_METHOD_get_init 218can be set to 219.Dv NULL 220to selectively retrieve callback function pointers. 221.Pp 222.Fn EC_KEY_METHOD_set_sign 223and 224.Fn EC_KEY_METHOD_get_sign 225set and retrieve the functions implementing 226.Xr ECDSA_sign 3 227and 228.Xr ECDSA_do_sign 3 . 229.Pp 230.Fn EC_KEY_METHOD_set_verify 231and 232.Fn EC_KEY_METHOD_get_verify 233set and retrieve the functions implementing 234.Xr ECDSA_verify 3 235and 236.Xr ECDSA_do_verify 3 . 237.Pp 238.Fn EC_KEY_METHOD_set_keygen 239and 240.Fn EC_KEY_METHOD_get_keygen 241set and retrieve the function implementing 242.Xr EC_KEY_generate_key 3 . 243.Pp 244.Fn EC_KEY_METHOD_set_compute_key 245and 246.Fn EC_KEY_METHOD_get_compute_key 247set and retrieve the function implementing 248.Xr ECDH_compute_key 3 . 249.Pp 250.Fn EC_KEY_set_default_method 251chooses the 252.Fa meth 253to be used for the creation of new 254.Vt EC_KEY 255objects by future invocations of 256.Fn EC_KEY_new_method , 257or reverts to the default implementation if 258.Fa meth 259is 260.Dv NULL . 261.Pp 262.Fn EC_KEY_new_method 263creates and initializes a new 264.Vt EC_KEY 265object using the 266.Vt EC_KEY_METHOD 267set with 268.Fn EC_KEY_set_default_method . 269The 270.Fa ENGINE *engine 271argument is always ignored and passing 272.Dv NULL 273is recommended. 274.Pp 275.Fn EC_KEY_set_method 276dissociates the 277.Fa key 278from the 279.Vt ENGINE 280it is using, if any, and causes it to use 281.Fa meth 282in the future. 283.Sh RETURN VALUES 284.Fn EC_KEY_METHOD_new 285returns the newly allocated 286.Vt EC_KEY_METHOD 287object or 288.Dv NULL 289if an error occurs. 290.Pp 291.Fn EC_KEY_OpenSSL 292returns a static object representing the default EC_KEY implementation. 293.Pp 294.Fn EC_KEY_get_default_method 295returns the 296.Vt EC_KEY_METHOD 297that 298.Fn EC_KEY_new_method 299will use for the creation of new 300.Vt EC_KEY 301objects in the future. 302.Pp 303.Fn EC_KEY_new_method 304returns the newly allocated 305.Vt EC_KEY 306object or NULL if an error occurs. 307.Pp 308.Fn EC_KEY_set_method 309returns 1 for success or 0 for failure. 310.Pp 311.Fn EC_KEY_get_method 312returns the EC_KEY implementation used by the given 313.Fa key . 314.Sh SEE ALSO 315.Xr EC_KEY_new 3 , 316.Xr ECDSA_sign 3 317.Sh HISTORY 318These functions first appeared in OpenSSL 1.1.0 319and have been available since 320.Ox 6.5 . 321