=head1 NAME
-EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, 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_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B<EC_GROUP> objects.
+EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor,
+EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator,
+EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor,
+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_get_basis_type, EC_GROUP_get_trinomial_basis,
+EC_GROUP_get_pentanomial_basis
+- Functions for manipulating EC_GROUP objects
=head1 SYNOPSIS
#include <openssl/ec.h>
- #include <openssl/bn.h>
int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
+ const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);
+ 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);
void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
int EC_GROUP_get_curve_name(const EC_GROUP *group);
int EC_GROUP_get_basis_type(const EC_GROUP *);
int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k);
- int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
- unsigned int *k2, unsigned int *k3);
+ int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
+ unsigned int *k2, unsigned int *k3);
=head1 DESCRIPTION
EC_GROUP_method_of obtains the EC_METHOD of B<group>.
-EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These
-paramaters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
+EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These
+parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
-n-1 where n is the B<order>. The B<order> multipied by the B<cofactor> gives the number of points on the curve.
+n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve.
EC_GROUP_get0_generator returns the generator for the identified B<group>.
with the respective order and cofactors for the B<group>.
The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
-(see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
+(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
will return 0.
-The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not.
-If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. 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. If set then
-the curve_name must also be set.
-
-The point_coversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
-point_conversion_form_t is an enum defined as follows:
+The asn1_flag value is used to determine whether the curve encoding uses
+explicit parameters or a named curve using an ASN1 OID: many applications only
+support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the
+named curve form is used and the parameters must have a corresponding
+named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> 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<OPENSSL_EC_EXPLICIT_CURVE> was first added to 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
+1.1.0 and later the named curve form is the default.
+
+The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
+point_conversion_form_t is an enum defined as follows:
typedef enum {
- /** the point is encoded as z||x, where the octet z specifies
- * which solution of the quadratic equation y is */
- POINT_CONVERSION_COMPRESSED = 2,
- /** the point is encoded as z||x||y, where z is the octet 0x02 */
- POINT_CONVERSION_UNCOMPRESSED = 4,
- /** the point is encoded as z||x||y, where the octet z specifies
+ /** the point is encoded as z||x, where the octet z specifies
+ * which solution of the quadratic equation y is */
+ POINT_CONVERSION_COMPRESSED = 2,
+ /** the point is encoded as z||x||y, where z is the octet 0x04 */
+ POINT_CONVERSION_UNCOMPRESSED = 4,
+ /** the point is encoded as z||x||y, where the octet z specifies
* which solution of the quadratic equation y is */
- POINT_CONVERSION_HYBRID = 6
+ POINT_CONVERSION_HYBRID = 6
} point_conversion_form_t;
-
For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by
the octets for x, followed by the octets for y.
For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For
POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of
-the two possible solutions for y has been used, followed by the octets for x.
+the two possible solutions for y has been used, followed by the octets for x.
For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
-function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similary
+function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
B<k2> and B<k3> respectively.
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_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_get0_cofactor() returns an internal pointer to the group cofactor.
+
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.
EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
-0, the the return value will be 1. On error 0 is returned.
+0, the return value will be 1. On error 0 is returned.
EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
=head1 SEE ALSO
-L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
-L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
+L<crypto(3)>, L<ec(3)>, 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 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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<https://www.openssl.org/source/license.html>.
=cut
projects / openssl.git / blobdiff