X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fman3%2FEC_GROUP_copy.pod;h=b62eaa959c723984eb2d24b817b1aa45dd54da6e;hb=37f03b9881a4ffa52b0059ae444be3c416cf2a5f;hp=ee20f9526adc6328188f126f0bed06aaf210a88f;hpb=e9b77246879071308130cda42336338ddb63cbb4;p=openssl.git diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod index ee20f9526a..b62eaa959c 100644 --- a/doc/man3/EC_GROUP_copy.pod +++ b/doc/man3/EC_GROUP_copy.pod @@ -9,9 +9,10 @@ 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_get_pentanomial_basis, EC_GROUP_get0_field - Functions for manipulating EC_GROUP objects =head1 SYNOPSIS @@ -32,6 +33,7 @@ EC_GROUP_get_pentanomial_basis int EC_GROUP_order_bits(const EC_GROUP *group); int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group); + const BIGNUM *EC_GROUP_get0_field(const EC_GROUP *group); void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); int EC_GROUP_get_curve_name(const EC_GROUP *group); @@ -49,6 +51,7 @@ EC_GROUP_get_pentanomial_basis 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); @@ -89,7 +92,7 @@ named curve form is used and the parameters must have a corresponding named curve NID set. If asn1_flags is B the parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. -Note: B was first added to OpenSSL 1.1.0, for +Note: B was added in OpenSSL 1.1.0, for previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL 1.1.0 the default form was to use explicit parameters (meaning that applications would have to explicitly set the named curve form) in OpenSSL @@ -127,7 +130,7 @@ in that a parameter obtained in this way is highly unlikely to be susceptible to If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the -builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using +built-in curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use this seed value, although it will be preserved in any ASN1 based communications. @@ -142,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. +The function 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 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 (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 is 1 it will only look for NIST approved curves, otherwise it searches all built-in curves. + EC_GROUP_cmp compares B and 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 @@ -174,9 +185,13 @@ 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_get_order_bits() returns the number of bits in 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. +EC_GROUP_get0_field() returns an internal pointer to the group field. For curves over GF(p), this is the modulus; for curves +over GF(2^m), this is the irreducible polynomial defining the field. EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. @@ -195,11 +210,15 @@ L, L, L, L, L, L, L +=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. +Copyright 2013-2019 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at L.