From 90c573eba184fe31184d14ce10367f810fa1d417 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 2 Nov 2016 11:57:56 +0000 Subject: convert DSA and EC manuals from pod to mdoc --- src/lib/libcrypto/man/EC_GROUP_new.3 | 240 +++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 src/lib/libcrypto/man/EC_GROUP_new.3 (limited to 'src/lib/libcrypto/man/EC_GROUP_new.3') diff --git a/src/lib/libcrypto/man/EC_GROUP_new.3 b/src/lib/libcrypto/man/EC_GROUP_new.3 new file mode 100644 index 0000000000..00690dfc07 --- /dev/null +++ b/src/lib/libcrypto/man/EC_GROUP_new.3 @@ -0,0 +1,240 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt EC_GROUP_NEW 3 +.Os +.Sh NAME +.Nm EC_GROUP_new , +.Nm EC_GROUP_free , +.Nm EC_GROUP_clear_free , +.Nm EC_GROUP_new_curve_GFp , +.Nm EC_GROUP_new_curve_GF2m , +.Nm EC_GROUP_new_by_curve_name , +.Nm EC_GROUP_set_curve_GFp , +.Nm EC_GROUP_get_curve_GFp , +.Nm EC_GROUP_set_curve_GF2m , +.Nm EC_GROUP_get_curve_GF2m , +.Nm EC_get_builtin_curves +.Nd create and destroy EC_GROUP objects +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft EC_GROUP * +.Fo EC_GROUP_new +.Fa "const EC_METHOD *meth" +.Fc +.Ft void +.Fo EC_GROUP_free +.Fa "EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_clear_free +.Fa "EC_GROUP *group" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GFp +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GF2m +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_by_curve_name +.Fa "int nid" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GFp +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GFp +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GF2m +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GF2m +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft size_t +.Fo EC_get_builtin_curves +.Fa "EC_builtin_curve *r" +.Fa "size_t nitems" +.Fc +.Sh DESCRIPTION +Within the library there are two forms of elliptic curves 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 +.Fa p +is a prime number. +This gives us a revised elliptic curve equation as follows: +.Pp +.Dl y^2 mod p = x^3 +ax + b mod p +.Pp +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: +.Pp +.Dl y^2 + xy = x^3 + ax^2 + b (where b != 0) +.Pp +Operations in a binary field are performed relative to an irreducible +polynomial. +All such curves with OpenSSL use a trinomial or a pentanomial for this +parameter. +.Pp +A new curve can be constructed by calling +.Fn EC_GROUP_new , +using the implementation provided by +.Fa meth +(see +.Xr EC_GFp_simple_method 3 ) . +It is then necessary to call either +.Fn EC_GROUP_set_curve_GFp +or +.Fn EC_GROUP_set_curve_GF2m +as appropriate to create a curve defined over Fp or over F2^m, respectively. +.Pp +.Fn EC_GROUP_set_curve_GFp +sets the curve parameters +.Fa p , +.Fa a , +and +.Fa b +for a curve over Fp stored in +.Fa group . +.Fn EC_group_get_curve_GFp +obtains the previously set curve parameters. +.Pp +.Fn EC_GROUP_set_curve_GF2m +sets the equivalent curve parameters for a curve over F2^m. +In this case +.Fa 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. +.Fn EC_group_get_curve_GF2m +obtains the previously set curve parameters. +.Pp +The functions +.Fn EC_GROUP_new_curve_GFp +and +.Fn EC_GROUP_new_curve_GF2m +are shortcuts for calling +.Fn EC_GROUP_new +and the appropriate +.Fn EC_GROUP_set_curve_* +function. +An appropriate default implementation method will be used. +.Pp +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 +.Fn EC_get_builtin_curves . +The parameter +.Fa r +should be an array of +.Vt EC_builtin_cure +structures of size +.Fa nitems . +The function will populate the +.Fa r +array with information about the builtin curves. +If +.Fa nitems +is less than the total number of curves available, then the first +.Fa 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 +.Fa r +or not). +Passing a +.Dv NULL +.Fa r , +or setting +.Fa nitems +to 0, will do nothing other than return the total number of curves +available. +The +.Vt EC_builtin_curve +structure is defined as follows: +.Bd -literal +typedef struct { + int nid; + const char *comment; +} EC_builtin_curve; +.Ed +.Pp +Each +.Vt EC_builtin_curve +item has a unique integer id +.Pq Fa nid +and a human readable comment string describing the curve. +.Pp +In order to construct a builtin curve use the function +.Fn EC_GROUP_new_by_curve_name +and provide the +.Fa nid +of the curve to be constructed. +.Pp +.Fn EC_GROUP_free +frees the memory associated with the +.Vt EC_GROUP . +.Pp +.Fn EC_GROUP_clear_free +destroys any sensitive data held within the +.Vt EC_GROUP +and then frees its memory. +.Sh RETURN VALUES +All +.Fn EC_GROUP_new* +functions return a pointer to the newly constructed group or +.Dv NULL +on error. +.Pp +.Fn EC_get_builtin_curves +returns the number of builtin curves that are available. +.Pp +.Fn EC_GROUP_set_curve_GFp , +.Fn EC_GROUP_get_curve_GFp , +.Fn EC_GROUP_set_curve_GF2m , +and +.Fn EC_GROUP_get_curve_GF2m +return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr ec 3 , +.Xr EC_GFp_simple_method 3 , +.Xr EC_GROUP_copy 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_new 3 -- cgit v1.2.3-55-g6feb