**diff options**

author | Jung-uk Kim <jkim@FreeBSD.org> | 2020-03-20 21:43:08 +0000 |
---|---|---|

committer | Jung-uk Kim <jkim@FreeBSD.org> | 2020-03-20 21:43:08 +0000 |

commit | 737493770cbfb0e6144e7c1eddebbe9160394a0f (patch) | |

tree | 041bf5f9d13b214279a3737b71d9ed65826ac7a6 /crypto/openssl/doc/man3/EC_GROUP_new.pod | |

parent | 29b5aa1b8efcee2c420239594c8840a0e465e8dd (diff) | |

download | src-737493770cbfb0e6144e7c1eddebbe9160394a0f.tar.gz src-737493770cbfb0e6144e7c1eddebbe9160394a0f.zip |

MFC: r359060, r359061, r359066

Merge OpenSSL 1.1.1e.

Notes

Notes:
svn path=/stable/12/; revision=359186

Diffstat (limited to 'crypto/openssl/doc/man3/EC_GROUP_new.pod')

-rw-r--r-- | crypto/openssl/doc/man3/EC_GROUP_new.pod | 102 |

1 files changed, 60 insertions, 42 deletions

diff --git a/crypto/openssl/doc/man3/EC_GROUP_new.pod b/crypto/openssl/doc/man3/EC_GROUP_new.pod index 1eee494927f5..c80b191785c4 100644 --- a/crypto/openssl/doc/man3/EC_GROUP_new.pod +++ b/crypto/openssl/doc/man3/EC_GROUP_new.pod @@ -57,49 +57,63 @@ objects =head1 DESCRIPTION -Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the -prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised +Within the library there are two forms of elliptic curve that are of interest. +The first form is those defined over the prime field Fp. The elements of Fp are +the integers 0 to p-1, where p is a prime number. This gives us a revised elliptic curve equation as follows: y^2 mod p = x^3 +ax + b mod p -The second form is those defined over a binary field F2^m where the elements of the field are integers of length at -most m bits. For this form the elliptic curve equation is modified to: +The second form is those defined over a binary field F2^m where the elements of +the field are integers of length at most m bits. For this form the elliptic +curve equation is modified to: y^2 + xy = x^3 + ax^2 + b (where b != 0) -Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL -use a trinomial or a pentanomial for this parameter. - -A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see -L<EC_GFp_simple_method(3)>). It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. -EC_GROUP_new_from_ecparameters() will create a group from the -specified B<params> and -EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>. - -EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve over Fp B<b> -is the prime for the field. For a curve over F2^m B<p> represents the irreducible polynomial - each bit -represents a term in the polynomial. Therefore there will either be three or five bits set dependent on whether -the polynomial is a trinomial or a pentanomial. +Operations in a binary field are performed relative to an B<irreducible +polynomial>. All such curves with OpenSSL use a trinomial or a pentanomial for +this parameter. + +A new curve can be constructed by calling EC_GROUP_new(), using the +implementation provided by B<meth> (see L<EC_GFp_simple_method(3)>). It is then +necessary to call EC_GROUP_set_curve() to set the curve parameters. +EC_GROUP_new_from_ecparameters() will create a group from the specified +B<params> and EC_GROUP_new_from_ecpkparameters() will create a group from the +specific PK B<params>. + +EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve +over Fp B<p> is the prime for the field. For a curve over F2^m B<p> represents +the irreducible polynomial - each bit represents a term in the polynomial. +Therefore there will either be three or five bits set dependent on whether the +polynomial is a trinomial or a pentanomial. +In either case, B<a> and B<b> represents the coefficients a and b from the +relevant equation introduced above. EC_group_get_curve() obtains the previously set curve parameters. -EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for EC_GROUP_set_curve(). They are defined for -backwards compatibility only and should not be used. - -EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for EC_GROUP_get_curve(). They are defined for -backwards compatibility only and should not be used. - -The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and then the -EC_GROUP_set_curve function. An appropriate default implementation method will be used. - -Whilst the library can be used to create any curve using the functions described above, there are also a number of -predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function -EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function -will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of -curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be -provided. The return value is the total number of curves available (whether that number has been populated in B<r> or -not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available. +EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for +EC_GROUP_set_curve(). They are defined for backwards compatibility only and +should not be used. + +EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for +EC_GROUP_get_curve(). They are defined for backwards compatibility only and +should not be used. + +The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are +shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function. +An appropriate default implementation method will be used. + +Whilst the library can be used to create any curve using the functions described +above, there are also a number of predefined curves that are available. In order +to obtain a list of all of the predefined curves, call the function +EC_get_builtin_curves(). The parameter B<r> should be an array of +EC_builtin_curve structures of size B<nitems>. The function will populate the +B<r> array with information about the builtin curves. If B<nitems> is less than +the total number of curves available, then the first B<nitems> curves will be +returned. Otherwise the total number of curves will be provided. The return +value is the total number of curves available (whether that number has been +populated in B<r> or not). Passing a NULL B<r>, or setting B<nitems> to 0 will +do nothing other than return the total number of curves available. The EC_builtin_curve structure is defined as follows: typedef struct { @@ -107,24 +121,28 @@ The EC_builtin_curve structure is defined as follows: const char *comment; } EC_builtin_curve; -Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. +Each EC_builtin_curve item has a unique integer id (B<nid>), and a human +readable comment string describing the curve. -In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to +In order to construct a builtin curve use the function +EC_GROUP_new_by_curve_name() and provide the B<nid> of the curve to be constructed. -EC_GROUP_free frees the memory associated with the EC_GROUP. +EC_GROUP_free() frees the memory associated with the EC_GROUP. If B<group> is NULL nothing is done. -EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. -If B<group> is NULL nothing is done. +EC_GROUP_clear_free() destroys any sensitive data held within the EC_GROUP and +then frees its memory. If B<group> is NULL nothing is done. =head1 RETURN VALUES -All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. +All EC_GROUP_new* functions return a pointer to the newly constructed group, or +NULL on error. -EC_get_builtin_curves returns the number of builtin curves that are available. +EC_get_builtin_curves() returns the number of builtin curves that are available. -EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. +EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), +EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error. =head1 SEE ALSO @@ -134,7 +152,7 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> =head1 COPYRIGHT -Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-2019 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy |