summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authortb <>2023-04-27 09:08:08 +0000
committertb <>2023-04-27 09:08:08 +0000
commit98ea769790652330d056bb03d3ed331920aa002e (patch)
tree468a4ebc14b08d80561443ea62dfea93f62f6980 /src
parent615553546a209bd77eed9250cc088e6a93bfdc92 (diff)
downloadopenbsd-98ea769790652330d056bb03d3ed331920aa002e.tar.gz
openbsd-98ea769790652330d056bb03d3ed331920aa002e.tar.bz2
openbsd-98ea769790652330d056bb03d3ed331920aa002e.zip
Remove BN_GF2m_add.3
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/man/BN_GF2m_add.3514
-rw-r--r--src/lib/libcrypto/man/Makefile3
2 files changed, 1 insertions, 516 deletions
diff --git a/src/lib/libcrypto/man/BN_GF2m_add.3 b/src/lib/libcrypto/man/BN_GF2m_add.3
deleted file mode 100644
index 5b143cb438..0000000000
--- a/src/lib/libcrypto/man/BN_GF2m_add.3
+++ /dev/null
@@ -1,514 +0,0 @@
1.\" $OpenBSD: BN_GF2m_add.3,v 1.5 2022/12/06 02:12:05 jsg Exp $
2.\"
3.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: December 6 2022 $
18.Dt BN_GF2M_ADD 3
19.Os
20.Sh NAME
21.Nm BN_GF2m_add ,
22.Nm BN_GF2m_sub ,
23.Nm BN_GF2m_cmp ,
24.Nm BN_GF2m_mod_arr ,
25.Nm BN_GF2m_mod ,
26.Nm BN_GF2m_mod_mul_arr ,
27.Nm BN_GF2m_mod_mul ,
28.Nm BN_GF2m_mod_sqr_arr ,
29.Nm BN_GF2m_mod_sqr ,
30.Nm BN_GF2m_mod_inv ,
31.Nm BN_GF2m_mod_inv_arr ,
32.Nm BN_GF2m_mod_div ,
33.Nm BN_GF2m_mod_div_arr ,
34.Nm BN_GF2m_mod_exp_arr ,
35.Nm BN_GF2m_mod_exp ,
36.Nm BN_GF2m_mod_sqrt_arr ,
37.Nm BN_GF2m_mod_sqrt ,
38.Nm BN_GF2m_mod_solve_quad_arr ,
39.Nm BN_GF2m_mod_solve_quad ,
40.Nm BN_GF2m_poly2arr ,
41.Nm BN_GF2m_arr2poly
42.Nd arithmetic in Galois fields of power-of-2 order
43.Sh SYNOPSIS
44.In openssl/bn.h
45.Ft int
46.Fo BN_GF2m_add
47.Fa "BIGNUM *r"
48.Fa "const BIGNUM *a"
49.Fa "const BIGNUM *b"
50.Fc
51.Ft int
52.Fo BN_GF2m_sub
53.Fa "BIGNUM *r"
54.Fa "const BIGNUM *a"
55.Fa "const BIGNUM *b"
56.Fc
57.Ft int
58.Fo BN_GF2m_cmp
59.Fa "const BIGNUM *a"
60.Fa "const BIGNUM *b"
61.Fc
62.Ft int
63.Fo BN_GF2m_mod_arr
64.Fa "BIGNUM *r"
65.Fa "const BIGNUM *a"
66.Fa "const int p[]"
67.Fc
68.Ft int
69.Fo BN_GF2m_mod
70.Fa "BIGNUM *r"
71.Fa "const BIGNUM *a"
72.Fa "const BIGNUM *p"
73.Fc
74.Ft int
75.Fo BN_GF2m_mod_mul_arr
76.Fa "BIGNUM *r"
77.Fa "const BIGNUM *a"
78.Fa "const BIGNUM *b"
79.Fa "const int p[]"
80.Fa "BN_CTX *ctx"
81.Fc
82.Ft int
83.Fo BN_GF2m_mod_mul
84.Fa "BIGNUM *r"
85.Fa "const BIGNUM *a"
86.Fa "const BIGNUM *b"
87.Fa "const BIGNUM *p"
88.Fa "BN_CTX *ctx"
89.Fc
90.Ft int
91.Fo BN_GF2m_mod_sqr_arr
92.Fa "BIGNUM *r"
93.Fa "const BIGNUM *a"
94.Fa "const int p[]"
95.Fa "BN_CTX *ctx"
96.Fc
97.Ft int
98.Fo BN_GF2m_mod_sqr
99.Fa "BIGNUM *r"
100.Fa "const BIGNUM *a"
101.Fa "const BIGNUM *p"
102.Fa "BN_CTX *ctx"
103.Fc
104.Ft int
105.Fo BN_GF2m_mod_inv
106.Fa "BIGNUM *r"
107.Fa "const BIGNUM *b"
108.Fa "const BIGNUM *p"
109.Fa "BN_CTX *ctx"
110.Fc
111.Ft int
112.Fo BN_GF2m_mod_inv_arr
113.Fa "BIGNUM *r"
114.Fa "const BIGNUM *b"
115.Fa "const int p[]"
116.Fa "BN_CTX *ctx"
117.Fc
118.Ft int
119.Fo BN_GF2m_mod_div
120.Fa "BIGNUM *r"
121.Fa "const BIGNUM *a"
122.Fa "const BIGNUM *b"
123.Fa "const BIGNUM *p"
124.Fa "BN_CTX *ctx"
125.Fc
126.Ft int
127.Fo BN_GF2m_mod_div_arr
128.Fa "BIGNUM *r"
129.Fa "const BIGNUM *a"
130.Fa "const BIGNUM *b"
131.Fa "const int p[]"
132.Fa "BN_CTX *ctx"
133.Fc
134.Ft int
135.Fo BN_GF2m_mod_exp_arr
136.Fa "BIGNUM *r"
137.Fa "const BIGNUM *a"
138.Fa "const BIGNUM *exponent"
139.Fa "const int p[]"
140.Fa "BN_CTX *ctx"
141.Fc
142.Ft int
143.Fo BN_GF2m_mod_exp
144.Fa "BIGNUM *r"
145.Fa "const BIGNUM *a"
146.Fa "const BIGNUM *exponent"
147.Fa "const BIGNUM *p"
148.Fa "BN_CTX *ctx"
149.Fc
150.Ft int
151.Fo BN_GF2m_mod_sqrt_arr
152.Fa "BIGNUM *r"
153.Fa "const BIGNUM *a"
154.Fa "const int p[]"
155.Fa "BN_CTX *ctx"
156.Fc
157.Ft int
158.Fo BN_GF2m_mod_sqrt
159.Fa "BIGNUM *r"
160.Fa "const BIGNUM *a"
161.Fa "const BIGNUM *p"
162.Fa "BN_CTX *ctx"
163.Fc
164.Ft int
165.Fo BN_GF2m_mod_solve_quad_arr
166.Fa "BIGNUM *r"
167.Fa "const BIGNUM *a"
168.Fa "const int p[]"
169.Fa "BN_CTX *ctx"
170.Fc
171.Ft int
172.Fo BN_GF2m_mod_solve_quad
173.Fa "BIGNUM *r"
174.Fa "const BIGNUM *a"
175.Fa "const BIGNUM *p"
176.Fa "BN_CTX *ctx"
177.Fc
178.Ft int
179.Fo BN_GF2m_poly2arr
180.Fa "const BIGNUM *poly_in"
181.Fa "int arr_out[]"
182.Fa "int arr_size"
183.Fc
184.Ft int
185.Fo BN_GF2m_arr2poly
186.Fa "const int arr_in[]"
187.Fa "BIGNUM *poly_out"
188.Fc
189.Sh DESCRIPTION
190Two fields containing the same, finite number of elements are isomorphic,
191and the number of elements is called their order.
192The unique field of a given finite order is called the Galois field
193of that order.
194.EQ
195delim $$
196.EN
197The following functions perform arithmetic operations
198on $roman GF left ( 2 sup m right )$, the Galois fields of order $2 sup m$,
199where $m$ is a natural number.
200.Pp
201The $2 sup m$ elements of $roman GF left ( 2 sup m right )$
202are usually represented by the $2 sup m$ polynomials
203of a degrees less than $m$ with binary coefficients.
204Such a polynomial can either be specified by storing the coefficients
205in a
206.Vt BIGNUM
207object, using the $m$ lowest bits with bit numbers corresponding to degrees,
208or by storing the degrees that have
209coefficients of 1 in an integer array of at most $m + 1$ elements.
210For the functions below, the array needs to be sorted in decreasing
211order and terminated by the delimiter element \-1.
212.Pp
213A specific representation of $roman GF left ( 2 sup m right )$
214is selected by choosing a polynomial of degree $m$ that is irreducible
215with binary coefficients, called the reducing polynomial.
216Making sure that $p$ is of the correct degree and indeed irreducible
217is the responsibility of the user.
218Typically, the following functions silently produce nonsensical results
219when given a
220.Fa p
221argument that is of the wrong degree or that is reducible.
222Storing the reducing polynomial requires $m + 1$ bits in a
223.Vt BIGNUM
224object or an
225.Vt int
226array of up to $m + 2$ elements, including the terminating \-1 element.
227.Pp
228All functions produce correct results even if some or all of the arguments
229.Fa r ,
230.Fa a ,
231and
232.Fa b
233point to the same object.
234.Pp
235.Fn BN_GF2m_add
236adds the two polynomials
237.Fa a
238and
239.Fa b
240with binary coefficients, which is equivalent to a pairwise exclusive OR
241operation on the coefficients, and places the result into
242.Fa r .
243In particular, if
244.Fa a
245and
246.Fa b
247are elements of the same representation
248of the same $roman GF left ( 2 sup m right )$ field,
249the sum of both in that representation of that field is computed
250.Po
251$r = a + b$
252.Pc .
253In contrast to most of the other functions described here, no modulo
254operation is performed.
255Consequently, if the degree of at least one of the arguments may be larger
256than or equal to $m$, a follow-up call to
257.Fn BN_GF2m_mod_arr
258or
259.Fn BN_GF2m_mod
260may occasionally be useful.
261.Pp
262.Fn BN_GF2m_sub
263calculates the difference of
264.Fa a
265and
266.Fa b
267.Po
268$r = a - b = a + b$
269.Pc .
270Since \-1 is the same as 1 in binary arithmetic,
271.Fn BN_GF2m_sub
272does exactly the same as
273.Fn BN_GF2m_add .
274It is implemented as a macro.
275.Pp
276.Fn BN_GF2m_cmp
277is an alias for
278.Xr BN_ucmp 3 .
279Despite its name, it does not attempt to find out whether the two
280polynomials belong to the same congruence class with respect to some
281Galois field.
282.Pp
283.Fn BN_GF2m_mod_arr
284and its wrapper
285.Fn BN_GF2m_mod
286divide the polynomial with binary coefficients
287.Fa a
288by the polynomial with binary coefficients
289.Fa p
290and place the remainder into
291.Fa r
292.Po
293$r = a ( roman mod p )$
294.Pc .
295If
296.Fa r
297and
298.Fa a
299point to the same object, the modular reduction is done in place.
300.Pp
301.Fn BN_GF2m_mod_mul_arr
302and its wrapper
303.Fn BN_GF2m_mod_mul
304multiply
305.Fa a
306and
307.Fa b ,
308divide the result by
309.Fa p ,
310and place the remainder in
311.Fa r
312.Po
313$r = a * b ( roman mod p )$
314.Pc .
315.Pp
316.Fn BN_GF2m_mod_sqr_arr
317and its wrapper
318.Fn BN_GF2m_mod_sqr
319divide the square of
320.Fa a
321by
322.Fa p
323and place the remainder in
324.Fa r
325.Po
326$r = a * a ( roman mod p )$
327.Pc .
328.Pp
329.Fn BN_GF2m_mod_inv
330and its wrapper
331.Fn BN_GF2m_mod_inv_arr
332reduce
333.Fa b
334modulo
335.Fa p ,
336find the multiplicative inverse element
337in $roman GF left ( 2 sup m right )$ using the reducing polynomial $p$,
338and place the result into
339.Fa r
340.Po
341$r = 1 / b ( roman mod p )$
342.Pc .
343.Pp
344.Fn BN_GF2m_mod_div
345and its wrapper
346.Fn BN_GF2m_mod_div_arr
347reduce
348.Fa a
349and
350.Fa b
351modulo
352.Fa p ,
353compute their quotient
354in $roman GF left ( 2 sup m right )$ using the reducing polynomial $p$,
355and place the result into
356.Fa r
357.Po
358$r = a / b ( roman mod p )$
359.Pc .
360.Pp
361.Fn BN_GF2m_mod_exp_arr
362and its wrapper
363.Fn BN_GF2m_mod_exp
364reduce
365.Fa a
366modulo
367.Fa p ,
368raise it to the power of
369.Fa exponent
370in $roman GF left ( 2 sup m right )$ using the reducing polynomial $p$,
371and place the result into
372.Fa r
373.Po
374$r = a sup exponent ( roman mod p )$
375.Pc .
376.Pp
377.Fn BN_GF2m_mod_sqrt_arr
378and its wrapper
379.Fn BN_GF2m_mod_sqrt
380reduce
381.Fa a
382modulo
383.Fa p ,
384calculate the square root
385in $roman GF left ( 2 sup m right )$ using the reducing polynomial $p$
386by raising it to the power of $2 sup { m - 1 }$,
387and place the result into
388.Fa r
389.Po
390$r = sqrt a ( roman mod p )$
391.Pc .
392This works because of the identity $a sup {2 sup m} = a$
393which holds for all field elements $a$.
394.Pp
395.Fn BN_GF2m_mod_solve_quad_arr
396and its wrapper
397.Fn BN_GF2m_mod_solve_quad
398reduce
399.Fa a
400modulo
401.Fa p ,
402solve the quadratic equation $r sup 2 + r = a ( roman mod p )$
403in $roman GF left ( 2 sup m right )$ using the reducing polynomial $p$,
404and place the solution into
405.Fa r .
406.Pp
407.Fn BN_GF2m_poly2arr
408converts a polynomial from a bit string stored in the
409.Vt BIGNUM
410object
411.Fa poly_in
412to an array containing the degrees of the non-zero terms.
413It is the responsibility of the caller to provide an array
414.Fa arr_out
415of sufficient size and to provide the number of elements
416that can be stored in the array as the
417.Fa arr_size
418argument.
419The array is filled with the degrees in decreasing order,
420followed by an element with the value \-1.
421.Pp
422.Fn BN_GF2m_arr2poly
423converts a polynomial from the array
424.Fa arr_in
425containing degrees to a bit string placed in the
426.Vt BIGNUM
427object
428.Ft poly_out .
429It is the responsibility of the caller to provide the storage for
430.Fa poly_out
431and to make sure that
432.Fa arr_in
433is terminated with a \-1 element.
434.Sh RETURN VALUES
435.Fn BN_GF2m_cmp
436interprets
437.Fa a
438and
439.Fa b
440as integer numbers and returns
441\-1 if $left | a right | < left | b right |$,
4420 if $left | a right | = left | b right |$,
443or 1 if $left | a right | > left | b right |$.
444.Pp
445.Fn BN_GF2m_poly2arr
446returns:
447.Bl -bullet -compact -offset 2n -width 1n
448.It
4490 if
450.Fa poly_in
451has the value 0;
452.It
453a number in the range from 2 to
454.Fa arr_size ,
455inclusive, in case of success, specifying the number of elements
456that have been stored into the array;
457.It
458a number greater than
459.Fa arr_size
460if the function failed because the array was too small,
461specifying the array size that would have been needed.
462.El
463.Pp
464The other functions return 1 for success or 0 for failure.
465.Sh ERRORS
466After some cases of failure, the following diagnostics can be retrieved with
467.Xr ERR_get_error 3 ,
468.Xr ERR_GET_REASON 3 ,
469and
470.Xr ERR_reason_error_string 3 :
471.Bl -tag -width Ds
472.It Dv BN_R_NO_SOLUTION Qq "no solution"
473No solution exists for the equation that
474.Fn BN_GF2m_mod_solve_quad_arr
475or
476.Fn BN_GF2m_mod_solve_quad
477attempted to solve.
478.It Dv BN_R_INVALID_LENGTH Qq "invalid length"
479In one of the functions wrapping an
480.Fn *_arr
481variant, the
482.Fa "BIGNUM *p"
483argument had a value of zero.
484.El
485.Sh SEE ALSO
486.Xr BN_add 3 ,
487.Xr BN_CTX_new 3 ,
488.Xr BN_new 3 ,
489.Xr BN_set_bit 3 ,
490.Xr EC_POINT_new 3
491.Rs
492.%A Darrel Hankerson
493.%A Julio L\('opez Hernandez
494.%A Alfred Menezes
495.%T Software Implementation of Elliptic Curve Cryptography over Binary Fields
496.%B CHES 2000: International Workshop on Cryptographic Hardware\
497 and Embedded Systems
498.%U https://doi.org/10.1007/3-540-44499-8_1
499.%C Worcester, MA, USA
500.%D August 2000
501.%I Springer
502.%J Lecture Notes in Computer Science
503.%V vol 1965
504.%O Algorithm 10: Modified Almost Inverse Algorithm for inversion in FP(2\(ham)
505.Re
506.Rs
507.%V IEEE Standard 1363
508.%B Specifications for Public-Key Cryptography
509.%D August 29, 2000
510.%U https://doi.org/10.1109/IEEESTD.2000.92292
511.%O square-and-multiply algorithm A.5.1 for exponentiation,\
512 exponentiation algorithm A.4.1 for square roots, and\
513 algorithms A.4.7 and A.4.6 for the quadratic equation
514.Re
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 85f6feea44..d20c8d8ed5 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.246 2023/04/27 06:54:09 tb Exp $ 1# $OpenBSD: Makefile,v 1.247 2023/04/27 09:08:08 tb Exp $
2 2
3.include <bsd.own.mk> 3.include <bsd.own.mk>
4 4
@@ -75,7 +75,6 @@ MAN= \
75 BN_cmp.3 \ 75 BN_cmp.3 \
76 BN_copy.3 \ 76 BN_copy.3 \
77 BN_generate_prime.3 \ 77 BN_generate_prime.3 \
78 BN_GF2m_add.3 \
79 BN_kronecker.3 \ 78 BN_kronecker.3 \
80 BN_mod_inverse.3 \ 79 BN_mod_inverse.3 \
81 BN_mod_mul_montgomery.3 \ 80 BN_mod_mul_montgomery.3 \
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-24 04:40:44 +0000