From: Nicola Tuveri Date: Fri, 18 Oct 2019 13:24:08 +0000 (+0300) Subject: Improve formatting for man3/EC_GROUP_new.pod X-Git-Tag: openssl-3.0.0-alpha1~1092 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=4fc55c1da972a13caf93814c4e3672bec993b95e;p=oweals%2Fopenssl.git Improve formatting for man3/EC_GROUP_new.pod - Use `()` to qualify function names, consistently - Limit line width to 80 chars Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/9874) --- diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod index 2d85e91d19..39dd352af4 100644 --- a/doc/man3/EC_GROUP_new.pod +++ b/doc/man3/EC_GROUP_new.pod @@ -66,55 +66,68 @@ L: =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. All such curves with OpenSSL -use a trinomial or a pentanomial for this parameter. +Operations in a binary field are performed relative to an +B. 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_ex, using the implementation provided by B (see -L) and associated with the library context B -(see L). -The B parameter may be NULL in which case the default library context is used. +A new curve can be constructed by calling EC_GROUP_new_ex(), using the +implementation provided by B (see L) and +associated with the library context B (see L). +The B parameter may be NULL in which case the default library context is +used. 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 and -EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B. +EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK +B. -EC_GROUP_new is the same as EC_GROUP_new_ex() except that the library context +EC_GROUP_new() is the same as EC_GROUP_new_ex() except that the library context used is always the default library context. -EC_GROUP_set_curve() sets the curve parameters B

, B and B. For a curve over Fp B -is the prime for the field. For a curve over F2^m B

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. +EC_GROUP_set_curve() sets the curve parameters B

, B and B. For a curve +over Fp B is the prime for the field. For a curve over F2^m B

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. 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 should be an array of EC_builtin_curve structures of size B. The function -will populate the B array with information about the built-in curves. If B is less than the total number of -curves available, then the first B 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 or -not). Passing a NULL B, or setting B 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 should be an array of +EC_builtin_curve structures of size B. The function will populate the +B array with information about the built-in curves. If B is less than +the total number of curves available, then the first B 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 or not). Passing a NULL B, or setting B 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 { @@ -122,31 +135,37 @@ 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), and a human readable comment string describing the curve. +Each EC_builtin_curve item has a unique integer id (B), and a human +readable comment string describing the curve. -In order to construct a built-in curve use the function EC_GROUP_new_by_curve_name_ex and provide the B of the curve to -be constructed and the associated library context to be used in B (see L). -The B value may be NULL in which case the default library context is used. +In order to construct a built-in curve use the function +EC_GROUP_new_by_curve_name_ex() and provide the B of the curve to be +constructed and the associated library context to be used in B (see +L). The B value may be NULL in which case the default +library context is used. -EC_GROUP_new_by_curve_name is the same as EC_GROUP_new_by_curve_name_ex except -that the default library context is always used. +EC_GROUP_new_by_curve_name() is the same as EC_GROUP_new_by_curve_name_ex() +except that the default library context is always used. -EC_GROUP_free frees the memory associated with the EC_GROUP. +EC_GROUP_free() frees the memory associated with the EC_GROUP. If B is NULL nothing is done. -EC_GROUP_clear_free is deprecated: it was meant to destroy any sensitive data +EC_GROUP_clear_free() is deprecated: it was meant to destroy any sensitive data held within the EC_GROUP and then free its memory, but since all the data stored in the EC_GROUP is public anyway, this function is unnecessary. -Its use can be safely replaced with EC_GROUP_free. +Its use can be safely replaced with EC_GROUP_free(). If B 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 built-in curves that are available. +EC_get_builtin_curves() returns the number of built-in 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 @@ -161,11 +180,12 @@ L =item * -EC_GROUP_new_ex and EC_GROUP_new_by_curve_name_ex were added in OpenSSL 3.0. +EC_GROUP_new_ex() and EC_GROUP_new_by_curve_name_ex() were added in OpenSSL 3.0. =item * -EC_GROUP_clear_free() was deprecated in OpenSSL 3.0; use EC_GROUP_free() instead. +EC_GROUP_clear_free() was deprecated in OpenSSL 3.0; use EC_GROUP_free() +instead. =back