1 files changed, 240 insertions, 0 deletions

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