summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EC_GROUP_copy.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EC_GROUP_copy.3')
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_copy.3492
1 files changed, 0 insertions, 492 deletions
diff --git a/src/lib/libcrypto/man/EC_GROUP_copy.3 b/src/lib/libcrypto/man/EC_GROUP_copy.3
deleted file mode 100644
index 2e5e798236..0000000000
--- a/src/lib/libcrypto/man/EC_GROUP_copy.3
+++ /dev/null
@@ -1,492 +0,0 @@
1.\" $OpenBSD: EC_GROUP_copy.3,v 1.16 2025/03/08 16:40:59 tb Exp $
2.\" full merge up to: OpenSSL d900a015 Oct 8 14:40:42 2015 +0200
3.\" selective merge up to: OpenSSL 24c23e1f Aug 22 10:51:25 2019 +0530
4.\"
5.\" This file was written by Matt Caswell <matt@openssl.org>,
6.\" Dr. Stephen Henson <steve@openssl.org>,
7.\" and Jayaram X Matta <jayaramx.matta@intel.com>.
8.\" Copyright (c) 2013, 2015, 2019 The OpenSSL Project. All rights reserved.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\"
14.\" 1. Redistributions of source code must retain the above copyright
15.\" notice, this list of conditions and the following disclaimer.
16.\"
17.\" 2. Redistributions in binary form must reproduce the above copyright
18.\" notice, this list of conditions and the following disclaimer in
19.\" the documentation and/or other materials provided with the
20.\" distribution.
21.\"
22.\" 3. All advertising materials mentioning features or use of this
23.\" software must display the following acknowledgment:
24.\" "This product includes software developed by the OpenSSL Project
25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
26.\"
27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
28.\" endorse or promote products derived from this software without
29.\" prior written permission. For written permission, please contact
30.\" openssl-core@openssl.org.
31.\"
32.\" 5. Products derived from this software may not be called "OpenSSL"
33.\" nor may "OpenSSL" appear in their names without prior written
34.\" permission of the OpenSSL Project.
35.\"
36.\" 6. Redistributions of any form whatsoever must retain the following
37.\" acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
40.\"
41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
52.\" OF THE POSSIBILITY OF SUCH DAMAGE.
53.\"
54.Dd $Mdocdate: March 8 2025 $
55.Dt EC_GROUP_COPY 3
56.Os
57.Sh NAME
58.Nm EC_GROUP_copy ,
59.Nm EC_GROUP_dup ,
60.Nm EC_GROUP_set_generator ,
61.Nm EC_GROUP_get0_generator ,
62.Nm EC_GROUP_get_order ,
63.Nm EC_GROUP_order_bits ,
64.Nm EC_GROUP_get_cofactor ,
65.Nm EC_GROUP_set_curve_name ,
66.Nm EC_GROUP_get_curve_name ,
67.Nm EC_GROUP_set_asn1_flag ,
68.Nm EC_GROUP_get_asn1_flag ,
69.Nm EC_GROUP_set_point_conversion_form ,
70.Nm EC_GROUP_get_point_conversion_form ,
71.Nm EC_GROUP_get0_seed ,
72.Nm EC_GROUP_get_seed_len ,
73.Nm EC_GROUP_set_seed ,
74.Nm EC_GROUP_get_degree ,
75.Nm EC_GROUP_check ,
76.Nm EC_GROUP_check_discriminant ,
77.Nm EC_GROUP_cmp ,
78.Nm EC_GROUP_get_basis_type
79.Nd manipulate EC_GROUP objects
80.Sh SYNOPSIS
81.In openssl/ec.h
82.In openssl/bn.h
83.Ft int
84.Fo EC_GROUP_copy
85.Fa "EC_GROUP *dst"
86.Fa "const EC_GROUP *src"
87.Fc
88.Ft EC_GROUP *
89.Fo EC_GROUP_dup
90.Fa "const EC_GROUP *src"
91.Fc
92.Ft int
93.Fo EC_GROUP_set_generator
94.Fa "EC_GROUP *group"
95.Fa "const EC_POINT *generator"
96.Fa "const BIGNUM *order"
97.Fa "const BIGNUM *cofactor"
98.Fc
99.Ft const EC_POINT *
100.Fo EC_GROUP_get0_generator
101.Fa "const EC_GROUP *group"
102.Fc
103.Ft int
104.Fo EC_GROUP_get_order
105.Fa "const EC_GROUP *group"
106.Fa "BIGNUM *order"
107.Fa "BN_CTX *ctx"
108.Fc
109.Ft int
110.Fo EC_GROUP_order_bits
111.Fa "const EC_GROUP *group"
112.Fc
113.Ft int
114.Fo EC_GROUP_get_cofactor
115.Fa "const EC_GROUP *group"
116.Fa "BIGNUM *cofactor"
117.Fa "BN_CTX *ctx"
118.Fc
119.Ft void
120.Fo EC_GROUP_set_curve_name
121.Fa "EC_GROUP *group"
122.Fa "int nid"
123.Fc
124.Ft int
125.Fo EC_GROUP_get_curve_name
126.Fa "const EC_GROUP *group"
127.Fc
128.Ft void
129.Fo EC_GROUP_set_asn1_flag
130.Fa "EC_GROUP *group"
131.Fa "int flag"
132.Fc
133.Ft int
134.Fo EC_GROUP_get_asn1_flag
135.Fa "const EC_GROUP *group"
136.Fc
137.Ft void
138.Fo EC_GROUP_set_point_conversion_form
139.Fa "EC_GROUP *group"
140.Fa "point_conversion_form_t form"
141.Fc
142.Ft point_conversion_form_t
143.Fo EC_GROUP_get_point_conversion_form
144.Fa "const EC_GROUP *"
145.Fc
146.Ft unsigned char *
147.Fo EC_GROUP_get0_seed
148.Fa "const EC_GROUP *x"
149.Fc
150.Ft size_t
151.Fo EC_GROUP_get_seed_len
152.Fa "const EC_GROUP *"
153.Fc
154.Ft size_t
155.Fo EC_GROUP_set_seed
156.Fa "EC_GROUP *"
157.Fa "const unsigned char *"
158.Fa "size_t len"
159.Fc
160.Ft int
161.Fo EC_GROUP_get_degree
162.Fa "const EC_GROUP *group"
163.Fc
164.Ft int
165.Fo EC_GROUP_check
166.Fa "const EC_GROUP *group"
167.Fa "BN_CTX *ctx"
168.Fc
169.Ft int
170.Fo EC_GROUP_check_discriminant
171.Fa "const EC_GROUP *group"
172.Fa "BN_CTX *ctx"
173.Fc
174.Ft int
175.Fo EC_GROUP_cmp
176.Fa "const EC_GROUP *a"
177.Fa "const EC_GROUP *b"
178.Fa "BN_CTX *ctx"
179.Fc
180.Ft int
181.Fo EC_GROUP_get_basis_type
182.Fa "const EC_GROUP *"
183.Fc
184.Sh DESCRIPTION
185These functions operate on
186.Vt EC_GROUP
187objects created by the functions described in
188.Xr EC_GROUP_new 3 .
189.Pp
190.Fn EC_GROUP_copy
191copies the curve
192.Fa src
193into
194.Fa dst .
195Both
196.Fa src
197and
198.Fa dst
199must use the same
200.Vt EC_METHOD .
201.Pp
202.Fn EC_GROUP_dup
203creates a new
204.Vt EC_GROUP
205object and copies the content from
206.Fa src
207to the newly created
208.Vt EC_GROUP
209object.
210.Pp
211.Fn EC_GROUP_set_generator
212sets curve parameters that must be agreed by all participants using
213the curve.
214These parameters include the
215.Fa generator ,
216the
217.Fa order
218and the
219.Fa cofactor .
220The
221.Fa generator
222is a well defined point on the curve chosen for cryptographic
223operations.
224Integers used for point multiplications will be between 0 and
225.Fa order No - 1 .
226The
227.Fa order
228multiplied by the
229.Fa cofactor
230gives the number of points on the curve.
231.Pp
232.Fn EC_GROUP_get0_generator
233returns the generator for the identified
234.Fa group .
235.Pp
236.Fn EC_GROUP_get_order
237retrieves the order of the
238.Fa group
239and copies its value into
240.Fa order .
241It fails if the order of the
242.Fa group
243is not set or set to zero.
244.Pp
245.Fn EC_GROUP_get_cofactor
246retrieves the cofactor of the
247.Fa group
248and copies its value into
249.Fa cofactor .
250It fails if the cofactor of the
251.Fa group
252is not set or set to zero.
253.Pp
254The functions
255.Fn EC_GROUP_set_curve_name
256and
257.Fn EC_GROUP_get_curve_name
258set and get the NID for the curve, respectively (see
259.Xr EC_GROUP_new 3 ) .
260If a curve does not have a NID associated with it, then
261.Fn EC_GROUP_get_curve_name
262will return
263.Dv NID_undef .
264.Pp
265The asn1_flag value is used to determine whether the curve encoding
266uses explicit parameters or a named curve using an ASN.1 OID:
267many applications only support the latter form.
268If asn1_flag is the default value
269.Dv OPENSSL_EC_NAMED_CURVE ,
270then the named curve form is used and the parameters must have a
271corresponding named curve NID set.
272If asn1_flags is
273.Dv OPENSSL_EC_EXPLICIT_CURVE ,
274the parameters are explicitly encoded.
275The functions
276.Fn EC_GROUP_get_asn1_flag
277and
278.Fn EC_GROUP_set_asn1_flag
279get and set the status of the asn1_flag for the curve.
280.Pp
281The point_conversion_form for a curve controls how
282.Vt EC_POINT
283data is encoded as ASN.1 as defined in X9.62 (ECDSA).
284.Vt point_conversion_form_t
285is an enum defined as follows:
286.Bd -literal
287typedef enum {
288 /** the point is encoded as z||x, where the octet z specifies
289 * which solution of the quadratic equation y is */
290 POINT_CONVERSION_COMPRESSED = 2,
291 /** the point is encoded as z||x||y, where z is the octet 0x04 */
292 POINT_CONVERSION_UNCOMPRESSED = 4,
293 /** the point is encoded as z||x||y, where the octet z specifies
294 * which solution of the quadratic equation y is */
295 POINT_CONVERSION_HYBRID = 6
296} point_conversion_form_t;
297.Ed
298.Pp
299For
300.Dv POINT_CONVERSION_UNCOMPRESSED
301the point is encoded as an octet signifying the UNCOMPRESSED form
302has been used followed by the octets for x, followed by the octets
303for y.
304.Pp
305For any given x coordinate for a point on a curve it is possible to
306derive two possible y values.
307For
308.Dv POINT_CONVERSION_COMPRESSED
309the point is encoded as an octet signifying that the COMPRESSED
310form has been used AND which of the two possible solutions for y
311has been used, followed by the octets for x.
312.Pp
313For
314.Dv POINT_CONVERSION_HYBRID
315the point is encoded as an octet signifying the HYBRID form has
316been used AND which of the two possible solutions for y has been
317used, followed by the octets for x, followed by the octets for y.
318.Pp
319The functions
320.Fn EC_GROUP_set_point_conversion_form
321and
322.Fn EC_GROUP_get_point_conversion_form
323set and get the point_conversion_form for the curve, respectively.
324.Pp
325ANSI X9.62 (ECDSA standard) defines a method of generating the curve
326parameter b from a random number.
327This provides advantages in that a parameter obtained in this way is
328highly unlikely to be susceptible to special purpose attacks, or have
329any trapdoors in it.
330If the seed is present for a curve then the b parameter was generated in
331a verifiable fashion using that seed.
332The OpenSSL EC library does not use this seed value but does enable you
333to inspect it using
334.Fn EC_GROUP_get0_seed .
335This returns a pointer to a memory block containing the seed that was
336used.
337The length of the memory block can be obtained using
338.Fn EC_GROUP_get_seed_len .
339A number of the builtin curves within the library provide seed values
340that can be obtained.
341It is also possible to set a custom seed using
342.Fn EC_GROUP_set_seed
343and passing a pointer to a memory block, along with the length of
344the seed.
345Again, the EC library will not use this seed value, although it will be
346preserved in any ASN.1 based communications.
347.Pp
348.Fn EC_GROUP_get_degree
349gets the degree of the field.
350For Fp fields this will be the number of bits in p.
351For F2^m fields this will be the value m.
352.Pp
353The function
354.Fn EC_GROUP_check_discriminant
355calculates the discriminant for the curve and verifies that it is
356valid.
357For a curve defined over Fp the discriminant is given by the formula
3584*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b.
359In either case for the curve to be valid the discriminant must be
360non-zero.
361.Pp
362The function
363.Fn EC_GROUP_check
364performs a number of checks on a curve to verify that it is valid.
365Checks performed include verifying that the discriminant is non-zero;
366that a generator has been defined; that the generator is on the curve
367and has the correct order.
368.Pp
369.Fn EC_GROUP_cmp
370compares
371.Fa a
372and
373.Fa b
374to determine whether they represent the same curve or not.
375.Pp
376.Fn EC_GROUP_get_basis_type
377always returns 0 and is only provided for compatibility.
378.Sh RETURN VALUES
379The following functions return 1 on success or 0 on error:
380.Fn EC_GROUP_copy ,
381.Fn EC_GROUP_set_generator ,
382.Fn EC_GROUP_check ,
383and
384.Fn EC_GROUP_check_discriminant .
385.Pp
386.Fn EC_GROUP_dup
387returns a pointer to the duplicated curve or
388.Dv NULL
389on error.
390.Pp
391.Fn EC_GROUP_get0_generator
392returns the generator for the given curve or
393.Dv NULL
394on error.
395.Pp
396.Fn EC_GROUP_get_order
397returns 0 if the order is not set or set to zero for the
398.Fa group
399or if copying into
400.Fa order
401fails, or 1 otherwise.
402.Pp
403.Fn EC_GROUP_order_bits
404returns the number of bits in the group order.
405.Pp
406.Fn EC_GROUP_get_cofactor
407returns 0 if the cofactor is not set or set to zero for the
408.Fa group
409or if copying into
410.Fa cofactor
411fails, or 1 otherwise.
412.Pp
413.Fn EC_GROUP_get_curve_name
414returns the curve name (NID) for the
415.Fa group
416or
417.Dv NID_undef
418if no curve name is associated.
419.Pp
420.Fn EC_GROUP_get_asn1_flag
421returns the ASN.1 flag for the specified
422.Fa group .
423.Pp
424.Fn EC_GROUP_get_point_conversion_form
425returns the point_conversion_form for the
426.Fa group .
427.Pp
428.Fn EC_GROUP_get_degree
429returns the degree for the
430.Fa group
431or 0 if the operation is not supported
432by the underlying group implementation.
433.Pp
434.Fn EC_GROUP_get0_seed
435returns a pointer to the seed that was used to generate the parameter
436b, or
437.Dv NULL
438if the seed is not specified.
439.Fn EC_GROUP_get_seed_len
440returns the length of the seed or 0 if the seed is not specified.
441.Pp
442.Fn EC_GROUP_set_seed
443returns the length of the seed that has been set.
444If the supplied seed is
445.Dv NULL
446or the supplied seed length is 0, the return value will be 1.
447On error 0 is returned.
448.Pp
449.Fn EC_GROUP_cmp
450returns 0 if the curves are equal, 1 if they are not equal,
451or -1 on error.
452.Pp
453.Fn EC_GROUP_get_basis_type
454always returns 0.
455.Sh SEE ALSO
456.Xr d2i_ECPKParameters 3 ,
457.Xr EC_GROUP_new 3 ,
458.Xr EC_KEY_new 3 ,
459.Xr EC_POINT_add 3 ,
460.Xr EC_POINT_new 3
461.Sh HISTORY
462.Fn EC_GROUP_copy ,
463.Fn EC_GROUP_set_generator ,
464.Fn EC_GROUP_get0_generator ,
465.Fn EC_GROUP_get_order ,
466and
467.Fn EC_GROUP_get_cofactor
468first appeared in OpenSSL 0.9.7 and have been available since
469.Ox 3.2 .
470.Pp
471.Fn EC_GROUP_dup ,
472.Fn EC_GROUP_set_curve_name ,
473.Fn EC_GROUP_get_curve_name ,
474.Fn EC_GROUP_set_asn1_flag ,
475.Fn EC_GROUP_get_asn1_flag ,
476.Fn EC_GROUP_set_point_conversion_form ,
477.Fn EC_GROUP_get_point_conversion_form ,
478.Fn EC_GROUP_get0_seed ,
479.Fn EC_GROUP_get_seed_len ,
480.Fn EC_GROUP_set_seed ,
481.Fn EC_GROUP_get_degree ,
482.Fn EC_GROUP_check ,
483.Fn EC_GROUP_check_discriminant ,
484.Fn EC_GROUP_cmp ,
485and
486.Fn EC_GROUP_get_basis_type
487first appeared in OpenSSL 0.9.8 and have been available since
488.Ox 4.5 .
489.Pp
490.Fn EC_GROUP_order_bits
491first appeared in OpenSSL 1.1.0 and has been available since
492.Ox 7.0 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:08:22 +0000