added code to validate EC named curve parameters

[oweals/openssl.git] / doc / man3 / EC_GROUP_copy.pod

diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod
index 3f7108d0b89d0df4e8e19e4339740647b8dbd8a0..c25c8f04265738dd6409818e1455f592888af917 100644 (file)
--- a/doc/man3/EC_GROUP_copy.pod
+++ b/doc/man3/EC_GROUP_copy.pod
@@ -9,7 +9,8 @@ EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag,
 EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form,
 EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed,
 EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree,
-EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp,
+EC_GROUP_check, EC_GROUP_check_named_curve,
+EC_GROUP_check_discriminant, EC_GROUP_cmp,
 EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis,
 EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
 - Functions for manipulating EC_GROUP objects
@@ -50,6 +51,7 @@ EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
  int EC_GROUP_get_degree(const EC_GROUP *group);
 
  int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
+ int EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only);
 
  int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
 
@@ -143,6 +145,14 @@ The function EC_GROUP_check performs a number of checks on a curve to verify tha
 verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
 the correct order.
 
+EC_GROUP_check_named_curve determines if the group's domain parameters match one of the built in curves supported by the library.
+The curve name is returned as a B<NID> if it matches. If the group's domain parameters have been modified then no match will be found.
+If the curve name of the given group is B<NID_undef> (e.g. it has been created by using explicit parameters with no curve name),
+then this method can be used to lookup the name of the curve that matches the group domain parameters. The built in curves contain
+aliases, so that multiple NID's can map to the same domain parameters. For such curves it is unspecified which of the aliases will be
+returned if the curve name of the given group is NID_undef.
+If B<nist_only> is 1 it will only look for NIST approved curves, otherwise it searches all built in curves.
+
 EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
 
 The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
@@ -175,6 +185,8 @@ EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get
 and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
 specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
 
+EC_GROUP_check_named_curve returns the nid of the matching named curve, otherwise it returns 0 for no match, or -1 on error.
+
 EC_GROUP_get0_order() returns an internal pointer to the group order.
 EC_GROUP_order_bits() returns the number of bits in the group order.
 EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor.
@@ -198,6 +210,10 @@ L<crypto(7)>, L<EC_GROUP_new(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)>
 
+=head1 HISTORY
+
+The EC_GROUP_check_named_curve() function was added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved.