Add more complete support for libctx/propq in the EC code
[openssl.git] / doc / man3 / EC_GROUP_new.pod
index fa61275..76fed3b 100644 (file)
@@ -11,7 +11,7 @@ EC_GROUP_free,
 EC_GROUP_clear_free,
 EC_GROUP_new_curve_GFp,
 EC_GROUP_new_curve_GF2m,
-EC_GROUP_new_by_curve_name_ex,
+EC_GROUP_new_by_curve_name_with_libctx,
 EC_GROUP_new_by_curve_name,
 EC_GROUP_set_curve,
 EC_GROUP_get_curve,
@@ -34,7 +34,8 @@ objects
                                   const BIGNUM *b, BN_CTX *ctx);
  EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
                                    const BIGNUM *b, BN_CTX *ctx);
- EC_GROUP *EC_GROUP_new_by_curve_name_ex(OPENSSL_CTX *libctx, int nid);
+ EC_GROUP *EC_GROUP_new_by_curve_name_with_libctx(OPENSSL_CTX *libctx,
+                                                  const char *propq, int nid);
  EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
 
  int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
@@ -83,24 +84,24 @@ pentanomial for this parameter.
 
 Although deprecated since OpenSSL 3.0 and should no longer be used,
 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)>) and
-associated with the library context B<ctx> (see L<OPENSSL_CTX(3)>).
-The B<ctx> parameter may be NULL in which case the default library context is
+implementation provided by I<meth> (see L<EC_GFp_simple_method(3)>) and
+associated with the library context I<ctx> (see L<OPENSSL_CTX(3)>).
+The I<ctx> 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.
 Applications should instead use one of the other EC_GROUP_new_* constructors.
 
 EC_GROUP_new_from_ecparameters() will create a group from the
-specified B<params> and
+specified I<params> and
 EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK
-B<params>.
+I<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
+EC_GROUP_set_curve() sets the curve parameters I<p>, I<a> and I<b>. For a curve
+over Fp I<p> is the prime for the field. For a curve over F2^m I<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
+In either case, I<a> and I<b> represents the coefficients a and b from the
 relevant equation introduced above.
 
 EC_group_get_curve() obtains the previously set curve parameters.
@@ -120,13 +121,13 @@ 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 built-in curves. If B<nitems> is less than
-the total number of curves available, then the first B<nitems> curves will be
+EC_get_builtin_curves(). The parameter I<r> should be an array of
+EC_builtin_curve structures of size I<nitems>. The function will populate the
+I<r> array with information about the built-in curves. If I<nitems> is less than
+the total number of curves available, then the first I<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
+populated in I<r> or not). Passing a NULL I<r>, or setting I<nitems> to 0 will
 do nothing other than return the total number of curves available.
 The EC_builtin_curve structure is defined as follows:
 
@@ -135,26 +136,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
+Each EC_builtin_curve item has a unique integer id (I<nid>), 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<nid> of the curve to be
-constructed and the associated library context to be used in B<ctx> (see
-L<OPENSSL_CTX(3)>).  The B<ctx> value may be NULL in which case the default
-library context is used.
+EC_GROUP_new_by_curve_name_with_libctx() and provide the I<nid> of the curve to
+be constructed, the associated library context to be used in I<ctx> (see
+L<OPENSSL_CTX(3)>) and any property query string in I<propq>. The I<ctx> value
+may be NULL in which case the default library context is used. The I<propq>
+value may also be NULL.
 
-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_with_libctx() except that the default library context
+is always used along with a NULL property query string.
 
 EC_GROUP_free() frees the memory associated with the EC_GROUP.
-If B<group> is NULL nothing is done.
+If I<group> is NULL nothing is done.
 
 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().
-If B<group> is NULL nothing is done.
+If I<group> is NULL nothing is done.
 
 =head1 RETURN VALUES
 
@@ -182,7 +185,7 @@ L<OPENSSL_CTX(3)>
 
 EC_GROUP_new() was deprecated in OpenSSL 3.0.
 
-EC_GROUP_new_by_curve_name_ex() was added in OpenSSL 3.0.
+EC_GROUP_new_by_curve_name_with_libctx() was added in OpenSSL 3.0.
 
 =item *