Add documentation for new EC functions

Document the new EC functions that are OPENSSL_CTX aware.

Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/9380)

diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod
index 87c3adaf3306d3e857bd4e153f329093634a7db1..6ac8e4aa83a5ae070c381999d955528e2b8ffde2 100644 (file)
--- a/doc/man3/EC_GROUP_new.pod
+++ b/doc/man3/EC_GROUP_new.pod
@@ -4,6 +4,7 @@
 
 EC_GROUP_get_ecparameters,
 EC_GROUP_get_ecpkparameters,
+EC_GROUP_new_ex,
 EC_GROUP_new,
 EC_GROUP_new_from_ecparameters,
 EC_GROUP_new_from_ecpkparameters,
@@ -11,6 +12,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,
 EC_GROUP_set_curve,
 EC_GROUP_get_curve,
@@ -25,6 +27,7 @@ objects
 
  #include <openssl/ec.h>
 
+ EC_GROUP *EC_GROUP_new_ex(OPENSSL_CTX *libctx, const EC_METHOD *meth);
  EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
  EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
  EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
@@ -35,6 +38,7 @@ 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(int nid);
 
  int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
@@ -71,12 +75,18 @@ 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.
+A new curve can be constructed by calling EC_GROUP_new_ex, 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 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<params> and
 EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
 
+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<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
@@ -109,8 +119,12 @@ The EC_builtin_curve structure is defined as follows:
 
 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
-be constructed.
+In order to construct a builtin 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 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.
 If B<group> is NULL nothing is done.
@@ -130,7 +144,12 @@ EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROU
 
 L<crypto(7)>, L<EC_GROUP_copy(3)>,
 L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
+L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>,
+L<OPENSSL_CTX(3)>
+
+=head1 HISTORY
+
+EC_GROUP_new_ex and EC_GROUP_new_by_curve_name_ex were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/EC_KEY_new.pod b/doc/man3/EC_KEY_new.pod
index 04ab2d5f57a8647fed6608aaffbfe806f7e8eb52..ff4373ea351ba1eb8d74bc27b52360da49d3b4e1 100644 (file)
--- a/doc/man3/EC_KEY_new.pod
+++ b/doc/man3/EC_KEY_new.pod
@@ -2,10 +2,10 @@
 
 =head1 NAME
 
-EC_KEY_get_method, EC_KEY_set_method,
+EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex,
 EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags,
-EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref,
-EC_KEY_get0_engine,
+EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy,
+EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine,
 EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key,
 EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key,
 EC_KEY_get_conv_form,
@@ -19,10 +19,12 @@ EC_KEY objects
 
  #include <openssl/ec.h>
 
+ EC_KEY *EC_KEY_new_ex(OPENSSL_CTX *ctx);
  EC_KEY *EC_KEY_new(void);
  int EC_KEY_get_flags(const EC_KEY *key);
  void EC_KEY_set_flags(EC_KEY *key, int flags);
  void EC_KEY_clear_flags(EC_KEY *key, int flags);
+ EC_KEY *EC_KEY_new_by_curve_name_ex(OPENSSL_CTX *ctx, int nid);
  EC_KEY *EC_KEY_new_by_curve_name(int nid);
  void EC_KEY_free(EC_KEY *key);
  EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
@@ -57,15 +59,31 @@ EC_KEY objects
 =head1 DESCRIPTION
 
 An EC_KEY represents a public key and, optionally, the associated private
-key. A new EC_KEY with no associated curve can be constructed by calling
-EC_KEY_new(). The reference count for the newly created EC_KEY is initially
-set to 1. A curve can be associated with the EC_KEY by calling
+key.
+A new EC_KEY with no associated curve can be constructed by calling
+EC_KEY_new_ex() and specifying the associated library context in B<ctx>
+(see L<OPENSSL_CTX(3)>).
+The B<ctx> parameter may be NULL in which case the default library context is
+used.
+The reference count for the newly created EC_KEY is initially
+set to 1.
+A curve can be associated with the EC_KEY by calling
 EC_KEY_set_group().
 
+EC_KEY_new() is the same as EC_KEY_new_ex() except that the default library
+context is always used.
+
 Alternatively a new EC_KEY can be constructed by calling
-EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See
-L<EC_GROUP_new(3)> for a description of curve names. This function simply
-wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name().
+EC_KEY_new_by_curve_name_ex() and supplying the nid of the associated curve and
+the library context to be used B<ctx> (see L<OPENSSL_CTX(3)>).
+The B<ctx> parameter may be NULL in which case the default library context is
+used.
+See L<EC_GROUP_new(3)> for a description of curve names.
+This function simply wraps calls to EC_KEY_new_ex() and
+EC_GROUP_new_by_curve_name_ex().
+
+EC_KEY_new_by_curve_name() is the same as EC_KEY_new_by_curve_name_ex() except
+that the default library context is always used.
 
 Calling EC_KEY_free() decrements the reference count for the EC_KEY object,
 and if it has dropped to zero then frees the memory associated with it.  If
@@ -144,8 +162,8 @@ EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer.
 
 =head1 RETURN VALUES
 
-EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to
-the newly created EC_KEY object, or NULL on error.
+EC_KEY_new_ex(), EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup()
+return a pointer to the newly created EC_KEY object, or NULL on error.
 
 EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an
 integer.
@@ -174,7 +192,8 @@ L<crypto(7)>, L<EC_GROUP_new(3)>,
 L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
 L<EC_POINT_add(3)>,
 L<EC_GFp_simple_method(3)>,
-L<d2i_ECPKParameters(3)>
+L<d2i_ECPKParameters(3)>,
+L<OPENSSL_CTX(3)>
 
 =head1 COPYRIGHT