src/third_party/boringssl/src/include/openssl/ec.h

   1 /* Originally written by Bodo Moeller for the OpenSSL project.
   2  * ====================================================================
   3  * Copyright (c) 1998-2005 The OpenSSL Project.  All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in
  14  *    the documentation and/or other materials provided with the
  15  *    distribution.
  16  *
  17  * 3. All advertising materials mentioning features or use of this
  18  *    software must display the following acknowledgment:
  19  *    "This product includes software developed by the OpenSSL Project
  20  *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  21  *
  22  * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  23  *    endorse or promote products derived from this software without
  24  *    prior written permission. For written permission, please contact
  25  *    openssl-core@openssl.org.
  26  *
  27  * 5. Products derived from this software may not be called "OpenSSL"
  28  *    nor may "OpenSSL" appear in their names without prior written
  29  *    permission of the OpenSSL Project.
  30  *
  31  * 6. Redistributions of any form whatsoever must retain the following
  32  *    acknowledgment:
  33  *    "This product includes software developed by the OpenSSL Project
  34  *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  35  *
  36  * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  37  * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  38  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  39  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  42  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  43  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  44  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  45  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  46  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  47  * OF THE POSSIBILITY OF SUCH DAMAGE.
  48  * ====================================================================
  49  *
  50  * This product includes cryptographic software written by Eric Young
  51  * (eay@cryptsoft.com).  This product includes software written by Tim
  52  * Hudson (tjh@cryptsoft.com).
  53  *
  54  */
  55 /* ====================================================================
  56  * Copyright 2002 Sun Microsystems, Inc. ALL RIGHTS RESERVED.
  57  *
  58  * Portions of the attached software ("Contribution") are developed by
  59  * SUN MICROSYSTEMS, INC., and are contributed to the OpenSSL project.
  60  *
  61  * The Contribution is licensed pursuant to the OpenSSL open source
  62  * license provided above.
  63  *
  64  * The elliptic curve binary polynomial software is originally written by
  65  * Sheueling Chang Shantz and Douglas Stebila of Sun Microsystems
  66  * Laboratories. */
  67
  68 #ifndef OPENSSL_HEADER_EC_H
  69 #define OPENSSL_HEADER_EC_H
  70
  71 #include <openssl/base.h>
  72
  73 #if defined(__cplusplus)
  74 extern "C" {
  75 #endif
  76
  77
  78 typedef struct ec_group_st EC_GROUP;
  79 typedef struct ec_point_st EC_POINT;
  80
  81 /** Enum for the point conversion form as defined in X9.62 (ECDSA)
  82  *  for the encoding of a elliptic curve point (x,y) */
  83 typedef enum {
  84         /** the point is encoded as z||x, where the octet z specifies
  85          *  which solution of the quadratic equation y is  */
  86         POINT_CONVERSION_COMPRESSED = 2,
  87         /** the point is encoded as z||x||y, where z is the octet 0x02  */
  88         POINT_CONVERSION_UNCOMPRESSED = 4,
  89         /** the point is encoded as z||x||y, where the octet z specifies
  90          *  which solution of the quadratic equation y is  */
  91         POINT_CONVERSION_HYBRID = 6
  92 } point_conversion_form_t;
  93
  94
  95 /* Elliptic curve groups. */
  96
  97 /* EC_GROUP_new_by_curve_name returns a fresh EC_GROUP object for the elliptic
  98  * curve specified by |nid|, or NULL on error.
  99  *
 100  * The supported NIDs are:
 101  *   NID_secp224r1,
 102  *   NID_X9_62_prime256v1,
 103  *   NID_secp384r1,
 104  *   NID_secp521r1 */
 105 OPENSSL_EXPORT EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
 106
 107 /* EC_GROUP_free frees |group| and the data that it points to. */
 108 OPENSSL_EXPORT void EC_GROUP_free(EC_GROUP *group);
 109
 110 /* EC_GROUP_copy sets |*dest| equal to |*src|. It returns one on success and
 111  * zero otherwise. */
 112 OPENSSL_EXPORT int EC_GROUP_copy(EC_GROUP *dest, const EC_GROUP *src);
 113
 114 /* EC_GROUP_dup returns a fresh |EC_GROUP| which is equal to |a| or NULL on
 115  * error. */
 116 OPENSSL_EXPORT EC_GROUP *EC_GROUP_dup(const EC_GROUP *a);
 117
 118 /* EC_GROUP_cmp returns one if |a| and |b| are the same group and zero
 119  * otherwise. */
 120 OPENSSL_EXPORT int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b);
 121
 122 /* EC_GROUP_get0_generator returns a pointer to the internal |EC_POINT| object
 123  * in |group| that specifies the generator for the group. */
 124 OPENSSL_EXPORT const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
 125
 126 /* EC_GROUP_get_order sets |*order| to the order of |group| using |ctx|, if
 127  * it's not NULL. It returns one on success and zero otherwise. */
 128 OPENSSL_EXPORT int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order,
 129                                       BN_CTX *ctx);
 130
 131 /* EC_GROUP_get_cofactor sets |*cofactor| to the cofactor of |group| using
 132  * |ctx|, if it's not NULL. It returns one on success and zero otherwise. */
 133 OPENSSL_EXPORT int EC_GROUP_get_cofactor(const EC_GROUP *group,
 134                                          BIGNUM *cofactor, BN_CTX *ctx);
 135
 136 /* EC_GROUP_get_curve_GFp gets various parameters about a group. It sets
 137  * |*out_p| to the order of the coordinate field and |*out_a| and |*out_b| to
 138  * the parameters of the curve when expressed as y² = x³ + ax + b. Any of the
 139  * output parameters can be NULL. It returns one on success and zero on
 140  * error. */
 141 OPENSSL_EXPORT int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *out_p,
 142                                           BIGNUM *out_a, BIGNUM *out_b,
 143                                           BN_CTX *ctx);
 144
 145 /* EC_GROUP_get_curve_name returns a NID that identifies |group|. */
 146 OPENSSL_EXPORT int EC_GROUP_get_curve_name(const EC_GROUP *group);
 147
 148 /* EC_GROUP_get_degree returns the number of bits needed to represent an
 149  * element of the field underlying |group|. */
 150 OPENSSL_EXPORT int EC_GROUP_get_degree(const EC_GROUP *group);
 151
 152 /* EC_GROUP_set_point_conversion_form sets the form that serialised points will
 153  * take as one of the |POINT_CONVERSION_*| values. */
 154 OPENSSL_EXPORT void EC_GROUP_set_point_conversion_form(
 155     EC_GROUP *group, point_conversion_form_t form);
 156
 157 /* EC_GROUP_precompute_mult precomputes multiplies of the generator in order to
 158  * speed up operations that involve calculating generator multiples. It returns
 159  * one on sucess and zero otherwise. If |ctx| is not NULL, it may be used. */
 160 OPENSSL_EXPORT int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
 161
 162 /* EC_GROUP_have_precompute_mult returns one if |group| contains precomputed
 163  * generator multiples. */
 164 OPENSSL_EXPORT int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
 165
 166
 167 /* Points on elliptic curves. */
 168
 169 /* EC_POINT_new returns a fresh |EC_POINT| object in the given group, or NULL
 170  * on error. */
 171 OPENSSL_EXPORT EC_POINT *EC_POINT_new(const EC_GROUP *group);
 172
 173 /* EC_POINT_free frees |point| and the data that it points to. */
 174 OPENSSL_EXPORT void EC_POINT_free(EC_POINT *point);
 175
 176 /* EC_POINT_clear_free clears the data that |point| points to, frees it and
 177  * then frees |point| itself. */
 178 OPENSSL_EXPORT void EC_POINT_clear_free(EC_POINT *point);
 179
 180 /* EC_POINT_copy sets |*dest| equal to |*src|. It returns one on success and
 181  * zero otherwise. */
 182 OPENSSL_EXPORT int EC_POINT_copy(EC_POINT *dest, const EC_POINT *src);
 183
 184 /* EC_POINT_dup returns a fresh |EC_POINT| that contains the same values as
 185  * |src|, or NULL on error. */
 186 OPENSSL_EXPORT EC_POINT *EC_POINT_dup(const EC_POINT *src,
 187                                       const EC_GROUP *group);
 188
 189 /* EC_POINT_set_to_infinity sets |point| to be the "point at infinity" for the
 190  * given group. */
 191 OPENSSL_EXPORT int EC_POINT_set_to_infinity(const EC_GROUP *group,
 192                                             EC_POINT *point);
 193
 194 /* EC_POINT_is_at_infinity returns one iff |point| is the point at infinity and
 195  * zero otherwise. */
 196 OPENSSL_EXPORT int EC_POINT_is_at_infinity(const EC_GROUP *group,
 197                                            const EC_POINT *point);
 198
 199 /* EC_POINT_is_on_curve returns one if |point| is an element of |group| and
 200  * zero otheriwse. If |ctx| is non-NULL, it may be used. */
 201 OPENSSL_EXPORT int EC_POINT_is_on_curve(const EC_GROUP *group,
 202                                         const EC_POINT *point, BN_CTX *ctx);
 203
 204 /* EC_POINT_cmp returns zero if |a| is equal to |b|, greater than zero is
 205  * non-equal and -1 on error. If |ctx| is not NULL, it may be used. */
 206 OPENSSL_EXPORT int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a,
 207                                 const EC_POINT *b, BN_CTX *ctx);
 208
 209 /* EC_POINT_make_affine converts |point| to affine form, internally. It returns
 210  * one on success and zero otherwise. If |ctx| is not NULL, it may be used. */
 211 OPENSSL_EXPORT int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point,
 212                                         BN_CTX *ctx);
 213
 214 /* EC_POINTs_make_affine converts |num| points from |points| to affine form,
 215  * internally. It returns one on success and zero otherwise. If |ctx| is not
 216  * NULL, it may be used. */
 217 OPENSSL_EXPORT int EC_POINTs_make_affine(const EC_GROUP *group, size_t num,
 218                                          EC_POINT *points[], BN_CTX *ctx);
 219
 220
 221 /* Point conversion. */
 222
 223 /* EC_POINT_get_affine_coordinates_GFp sets |x| and |y| to the affine value of
 224  * |point| using |ctx|, if it's not NULL. It returns one on success and zero
 225  * otherwise. */
 226 OPENSSL_EXPORT int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
 227                                                        const EC_POINT *point,
 228                                                        BIGNUM *x, BIGNUM *y,
 229                                                        BN_CTX *ctx);
 230
 231 /* EC_POINT_set_affine_coordinates sets the value of |p| to be (|x|, |y|). The
 232  * |ctx| argument may be used if not NULL. */
 233 OPENSSL_EXPORT int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group,
 234                                                        EC_POINT *point,
 235                                                        const BIGNUM *x,
 236                                                        const BIGNUM *y,
 237                                                        BN_CTX *ctx);
 238
 239 /* EC_POINT_point2oct serialises |point| into the X9.62 form given by |form|
 240  * into, at most, |len| bytes at |buf|. It returns the number of bytes written
 241  * or zero on error if |buf| is non-NULL, else the number of bytes needed. The
 242  * |ctx| argument may be used if not NULL. */
 243 OPENSSL_EXPORT size_t EC_POINT_point2oct(const EC_GROUP *group,
 244                                          const EC_POINT *point,
 245                                          point_conversion_form_t form,
 246                                          uint8_t *buf, size_t len, BN_CTX *ctx);
 247
 248 /* EC_POINT_oct2point sets |point| from |len| bytes of X9.62 format
 249  * serialisation in |buf|. It returns one on success and zero otherwise. The
 250  * |ctx| argument may be used if not NULL. */
 251 OPENSSL_EXPORT int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *point,
 252                                       const uint8_t *buf, size_t len,
 253                                       BN_CTX *ctx);
 254
 255 /* EC_POINT_set_compressed_coordinates_GFp sets |point| to equal the point with
 256  * the given |x| coordinate and the y coordinate specified by |y_bit| (see
 257  * X9.62). It returns one on success and zero otherwise. */
 258 OPENSSL_EXPORT int EC_POINT_set_compressed_coordinates_GFp(
 259     const EC_GROUP *group, EC_POINT *point, const BIGNUM *x, int y_bit,
 260     BN_CTX *ctx);
 261
 262
 263 /* Group operations. */
 264
 265 /* EC_POINT_add sets |r| equal to |a| plus |b|. It returns one on success and
 266  * zero otherwise. If |ctx| is not NULL, it may be used. */
 267 OPENSSL_EXPORT int EC_POINT_add(const EC_GROUP *group, EC_POINT *r,
 268                                 const EC_POINT *a, const EC_POINT *b,
 269                                 BN_CTX *ctx);
 270
 271 /* EC_POINT_dbl sets |r| equal to |a| plus |a|. It returns one on success and
 272  * zero otherwise. If |ctx| is not NULL, it may be used. */
 273 OPENSSL_EXPORT int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r,
 274                                 const EC_POINT *a, BN_CTX *ctx);
 275
 276 /* EC_POINT_dbl sets |a| equal to minus |a|. It returns one on success and zero
 277  * otherwise. If |ctx| is not NULL, it may be used. */
 278 OPENSSL_EXPORT int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a,
 279                                    BN_CTX *ctx);
 280
 281 /* EC_POINT_mul sets r = generator*n + q*m. It returns one on success and zero
 282  * otherwise. If |ctx| is not NULL, it may be used. */
 283 OPENSSL_EXPORT int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r,
 284                                 const BIGNUM *n, const EC_POINT *q,
 285                                 const BIGNUM *m, BN_CTX *ctx);
 286
 287 /* EC_POINTs_mul sets r = generator*n + sum(p[i]*m[i]). It returns one on
 288  * success and zero otherwise. If |ctx| is not NULL, it may be used. */
 289 OPENSSL_EXPORT int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r,
 290                                  const BIGNUM *n, size_t num,
 291                                  const EC_POINT *p[], const BIGNUM *m[],
 292                                  BN_CTX *ctx);
 293
 294
 295 /* Old code expects to get EC_KEY from ec.h. */
 296 #if !defined(OPENSSL_HEADER_EC_KEY_H)
 297 #include <openssl/ec_key.h>
 298 #endif
 299
 300
 301 #if defined(__cplusplus)
 302 }  /* extern C */
 303 #endif
 304
 305 #define EC_F_ec_pre_comp_new 100
 306 #define EC_F_ec_GFp_mont_field_decode 101
 307 #define EC_F_ec_group_new_from_data 102
 308 #define EC_F_ec_GFp_simple_point_get_affine_coordinates 103
 309 #define EC_F_ec_GFp_simple_make_affine 104
 310 #define EC_F_EC_KEY_new_method 105
 311 #define EC_F_ec_GFp_mont_field_encode 106
 312 #define EC_F_EC_GROUP_new_by_curve_name 107
 313 #define EC_F_ec_group_new 108
 314 #define EC_F_ec_asn1_group2pkparameters 109
 315 #define EC_F_EC_POINT_set_compressed_coordinates_GFp 110
 316 #define EC_F_ec_GFp_mont_field_sqr 111
 317 #define EC_F_EC_POINT_make_affine 112
 318 #define EC_F_i2d_ECParameters 113
 319 #define EC_F_ec_wNAF_mul 114
 320 #define EC_F_EC_GROUP_copy 115
 321 #define EC_F_EC_POINT_cmp 116
 322 #define EC_F_ec_GFp_mont_field_mul 117
 323 #define EC_F_EC_POINT_dup 118
 324 #define EC_F_EC_POINT_invert 119
 325 #define EC_F_ec_GFp_simple_point_set_affine_coordinates 120
 326 #define EC_F_ec_GFp_simple_points_make_affine 121
 327 #define EC_F_i2o_ECPublicKey 122
 328 #define EC_F_EC_KEY_check_key 123
 329 #define EC_F_ec_wNAF_precompute_mult 124
 330 #define EC_F_EC_POINT_oct2point 125
 331 #define EC_F_EC_POINT_is_at_infinity 126
 332 #define EC_F_EC_POINT_get_affine_coordinates_GFp 127
 333 #define EC_F_ec_point_set_Jprojective_coordinates_GFp 128
 334 #define EC_F_o2i_ECPublicKey 129
 335 #define EC_F_ec_GFp_mont_field_set_to_one 130
 336 #define EC_F_ec_group_new_curve_GFp 131
 337 #define EC_F_EC_POINT_dbl 132
 338 #define EC_F_ec_asn1_pkparameters2group 133
 339 #define EC_F_i2d_ECPKParameters 134
 340 #define EC_F_EC_KEY_copy 135
 341 #define EC_F_EC_POINT_new 136
 342 #define EC_F_EC_POINT_point2oct 137
 343 #define EC_F_EC_POINT_copy 138
 344 #define EC_F_EC_POINT_is_on_curve 139
 345 #define EC_F_ec_GFp_simple_group_set_curve 140
 346 #define EC_F_i2d_ECPrivateKey 141
 347 #define EC_F_d2i_ECParameters 142
 348 #define EC_F_ec_GFp_mont_group_set_curve 143
 349 #define EC_F_EC_POINT_set_to_infinity 144
 350 #define EC_F_EC_POINTs_make_affine 145
 351 #define EC_F_compute_wNAF 146
 352 #define EC_F_ec_GFp_simple_point2oct 147
 353 #define EC_F_EC_GROUP_get_degree 148
 354 #define EC_F_ec_GFp_simple_group_check_discriminant 149
 355 #define EC_F_d2i_ECPKParameters 150
 356 #define EC_F_d2i_ECPrivateKey 151
 357 #define EC_F_ec_GFp_simple_oct2point 152
 358 #define EC_F_EC_POINT_set_affine_coordinates_GFp 153
 359 #define EC_F_EC_KEY_set_public_key_affine_coordinates 154
 360 #define EC_F_EC_KEY_generate_key 155
 361 #define EC_F_ec_GFp_simple_set_compressed_coordinates 156
 362 #define EC_F_EC_POINT_add 157
 363 #define EC_F_EC_GROUP_get_curve_GFp 158
 364 #define EC_R_PKPARAMETERS2GROUP_FAILURE 100
 365 #define EC_R_NON_NAMED_CURVE 101
 366 #define EC_R_COORDINATES_OUT_OF_RANGE 102
 367 #define EC_R_POINT_AT_INFINITY 103
 368 #define EC_R_NOT_INITIALIZED 104
 369 #define EC_R_MISSING_PRIVATE_KEY 105
 370 #define EC_R_GROUP2PKPARAMETERS_FAILURE 106
 371 #define EC_R_INVALID_ENCODING 107
 372 #define EC_R_BUFFER_TOO_SMALL 108
 373 #define EC_R_D2I_ECPKPARAMETERS_FAILURE 109
 374 #define EC_R_INVALID_FORM 110
 375 #define EC_R_INVALID_PRIVATE_KEY 111
 376 #define EC_R_INVALID_COMPRESSED_POINT 112
 377 #define EC_R_MISSING_PARAMETERS 113
 378 #define EC_R_INVALID_FIELD 114
 379 #define EC_R_INVALID_COMPRESSION_BIT 115
 380 #define EC_R_GF2M_NOT_SUPPORTED 116
 381 #define EC_R_POINT_IS_NOT_ON_CURVE 117
 382 #define EC_R_UNKNOWN_ORDER 118
 383 #define EC_R_UNKNOWN_GROUP 119
 384 #define EC_R_WRONG_ORDER 120
 385 #define EC_R_UNDEFINED_GENERATOR 121
 386 #define EC_R_INCOMPATIBLE_OBJECTS 122
 387 #define EC_R_I2D_ECPKPARAMETERS_FAILURE 123
 388 #define EC_R_EC_GROUP_NEW_BY_NAME_FAILURE 124
 389 #define EC_R_INVALID_GROUP_ORDER 125
 390 #define EC_R_SLOT_FULL 126
 391
 392 #endif  /* OPENSSL_HEADER_EC_H */