1.\" $OpenBSD: EC_KEY_METHOD_new.3,v 1.1 2019/08/16 16:15:50 schwarze 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: August 16 2019 $
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.In openssl/ecdsa.h
70.Ft void
71.Fo EC_KEY_METHOD_set_sign
72.Fa "EC_KEY_METHOD *meth"
73.Fa "int (*sign)(int type, const unsigned char *dgst, int dgstlen,\
74 unsigned char *sig, unsigned int *siglen,\
75 const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)"
76.Fa "int (*sign_setup)(EC_KEY *eckey, BN_CTX *ctx,\
77 BIGNUM **kinv, BIGNUM **rp)"
78.Fa "ECDSA_SIG *(*sign_sig)(const unsigned char *dgst, int dgstlen,\
79 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)"
80.Fc
81.Ft void
82.Fo EC_KEY_METHOD_get_sign
83.Fa "const EC_KEY_METHOD *meth"
84.Fa "int (**psign)(int type, const unsigned char *dgst, int dgstlen,\
85 unsigned char *sig, unsigned int *siglen,\
86 const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)"
87.Fa "int (**psign_setup)(EC_KEY *eckey, BN_CTX *ctx,\
88 BIGNUM **kinv, BIGNUM **rp)"
89.Fa "ECDSA_SIG *(**psign_sig)(const unsigned char *dgst, int dgstlen,\
90 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)"
91.Fc
92.Ft void
93.Fo EC_KEY_METHOD_set_verify
94.Fa "EC_KEY_METHOD *meth"
95.Fa "int (*verify)(int type, const unsigned char *dgst, int dgst_len,\
96 const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)"
97.Fa "int (*verify_sig)(const unsigned char *dgst, int dgst_len,\
98 const ECDSA_SIG *sig, EC_KEY *eckey)"
99.Fc
100.Ft void
101.Fo EC_KEY_METHOD_get_verify
102.Fa "const EC_KEY_METHOD *meth"
103.Fa "int (**pverify)(int type, const unsigned char *dgst, int dgst_len,\
104 const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)"
105.Fa "int (**pverify_sig)(const unsigned char *dgst, int dgst_len,\
106 const ECDSA_SIG *sig, EC_KEY *eckey)"
107.Fc
108.In openssl/ec.h
109.Ft void
110.Fo EC_KEY_METHOD_set_keygen
111.Fa "EC_KEY_METHOD *meth"
112.Fa "int (*keygen)(EC_KEY *key)"
113.Fc
114.Ft void
115.Fo EC_KEY_METHOD_get_keygen
116.Fa "const EC_KEY_METHOD *meth"
117.Fa "int (**pkeygen)(EC_KEY *key)"
118.Fc
119.Ft void
120.Fo EC_KEY_METHOD_set_compute_key
121.Fa "EC_KEY_METHOD *meth"
122.Fa "int (*ckey)(void *out, size_t outlen,\
123 const EC_POINT *pub_key, EC_KEY *ecdh,\
124 void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))"
125.Fc
126.Ft void
127.Fo EC_KEY_METHOD_get_compute_key
128.Fa "const EC_KEY_METHOD *meth"
129.Fa "int (**pck)(void *out, size_t outlen,\
130 const EC_POINT *pub_key, EC_KEY *ecdh,\
131 void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))"
132.Fc
133.Ft const EC_KEY_METHOD *
134.Fn EC_KEY_OpenSSL void
135.Ft void
136.Fo EC_KEY_set_default_method
137.Fa "const EC_KEY_METHOD *meth"
138.Fc
139.Ft const EC_KEY_METHOD *
140.Fn EC_KEY_get_default_method void
141.Ft EC_KEY *
142.Fo EC_KEY_new_method
143.Fa "ENGINE *engine"
144.Fc
145.Ft int
146.Fo EC_KEY_set_method
147.Fa "EC_KEY *key"
148.Fa "const EC_KEY_METHOD *meth"
149.Fc
150.Ft const EC_KEY_METHOD *
151.Fo EC_KEY_get_method
152.Fa "const EC_KEY *key"
153.Fc
154.Sh DESCRIPTION
155An
156.Vt EC_KEY_METHOD
157object holds function pointers used for
158.Vt EC_KEY
159operations.
160.Pp
161.Fn EC_KEY_METHOD_new
162creates a shallow copy of
163.Fa meth ,
164or an empty
165.Vt EC_KEY_METHOD
166object if
167.Fa meth
168is
169.Dv NULL .
170.Pp
171.Fn EC_KEY_METHOD_free
172frees
173.Fa meth .
174If
175.Fa meth
176is
177.Dv NULL
178or the return value of
179.Fn EC_KEY_OpenSSL ,
180no action occurs.
181.Pp
182.Fn EC_KEY_METHOD_set_init
183and
184.Fn EC_KEY_METHOD_get_init
185set and retrieve optional callback functions called at the following places:
186.Pp
187.Bl -tag -width set_private -compact
188.It Fa init
189at the end of
190.Fn EC_KEY_new_method
191and
192.Fn EC_KEY_set_method
193.It Fa finish
194at the beginning of
195.Xr EC_KEY_free 3 ,
196.Xr EC_KEY_copy 3 ,
197and
198.Fn EC_KEY_set_method
199.It Fa copy
200at the end of
201.Xr EC_KEY_copy 3
202.It Fa set_group
203at the end of
204.Xr EC_KEY_set_group 3
205and
206.Xr EC_KEY_new_by_curve_name 3
207.It Fa set_private
208at the beginning of
209.Xr EC_KEY_set_private_key 3
210.It Fa set_public
211at the beginning of
212.Xr EC_KEY_set_public_key 3
213.El
214.Pp
215If any of these callbacks returns 0, the calling function fails.
216By default, all these callbacks are
217.Dv NULL .
218Arguments of
219.Fn EC_KEY_METHOD_get_init
220can be set to
221.Dv NULL
222to selectively retrieve callback function pointers.
223.Pp
224.Fn EC_KEY_METHOD_set_sign
225and
226.Fn EC_KEY_METHOD_get_sign
227set and retrieve the functions implementing
228.Xr ECDSA_sign_ex 3 ,
229.Xr ECDSA_sign_setup 3 ,
230and
231.Xr ECDSA_do_sign_ex 3 .
232.Pp
233.Fn EC_KEY_METHOD_set_verify
234and
235.Fn EC_KEY_METHOD_get_verify
236set and retrieve the functions implementing
237.Xr ECDSA_verify 3
238and
239.Xr ECDSA_do_verify 3 .
240.Pp
241.Fn EC_KEY_METHOD_set_keygen
242and
243.Fn EC_KEY_METHOD_get_keygen
244set and retrieve the function implementing
245.Xr EC_KEY_generate_key 3 .
246.Pp
247.Fn EC_KEY_METHOD_set_compute_key
248and
249.Fn EC_KEY_METHOD_get_compute_key
250set and retrieve the function implementing
251.Xr ECDH_compute_key 3 .
252.Pp
253.Fn EC_KEY_set_default_method
254chooses the
255.Fa meth
256to be used for the creation of new
257.Vt EC_KEY
258objects by future invocations of
259.Fn EC_KEY_new_method ,
260or reverts to the default implementation if
261.Fa meth
262is
263.Dv NULL .
264.Pp
265.Fn EC_KEY_new_method
266creates and initializes a new
267.Vt EC_KEY
268object using the given
269.Fa engine ,
270or the using the
271.Vt EC_KEY_METHOD
272set with
273.Fn EC_KEY_set_default_method
274if
275.Fa engine
276is
277.Dv NULL ,
278or using the default EC_KEY implementation by default.
279.Pp
280.Fn EC_KEY_set_method
281dissociates the
282.Fa key
283from the
284.Vt ENGINE
285it is using, if any, and causes it to use
286.Fa meth
287in the future.
288.Sh RETURN VALUES
289.Fn EC_KEY_METHOD_new
290returns the newly allocated
291.Vt EC_KEY_METHOD
292object or
293.Dv NULL
294if an error occurs.
295.Pp
296.Fn EC_KEY_OpenSSL
297returns a static object representing the default EC_KEY implementation.
298.Pp
299.Fn EC_KEY_get_default_method
300returns the
301.Vt EC_KEY_METHOD
302that
303.Fn EC_KEY_new_method
304will use for the creation of new
305.Vt EC_KEY
306objects in the future.
307.Pp
308.Fn EC_KEY_new_method
309returns the newly allocated
310.Vt EC_KEY
311object or NULL if an error occurs.
312.Pp
313.Fn EC_KEY_set_method
314returns 1 for success or 0 for failure.
315.Pp
316.Fn EC_KEY_get_method
317returns the EC_KEY implementation used by the given
318.Fa key .
319.Sh SEE ALSO
320.Xr EC_KEY_new 3 ,
321.Xr ECDSA_sign 3
322.Sh HISTORY
323These functions first appeared in OpenSSL 1.1.0
324and have been available since
325.Ox 6.5 .
326