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_KEY_H 69#define OPENSSL_HEADER_EC_KEY_H 70 71#include <openssl/base.h> 72 73#include <openssl/ec.h> 74#include <openssl/engine.h> 75#include <openssl/ex_data.h> 76 77#if defined(__cplusplus) 78extern "C" { 79#endif 80 81 82// ec_key.h contains functions that handle elliptic-curve points that are 83// public/private keys. 84 85 86// EC key objects. 87 88// EC_KEY_new returns a fresh |EC_KEY| object or NULL on error. 89OPENSSL_EXPORT EC_KEY *EC_KEY_new(void); 90 91// EC_KEY_new_method acts the same as |EC_KEY_new|, but takes an explicit 92// |ENGINE|. 93OPENSSL_EXPORT EC_KEY *EC_KEY_new_method(const ENGINE *engine); 94 95// EC_KEY_new_by_curve_name returns a fresh EC_KEY for group specified by |nid| 96// or NULL on error. 97OPENSSL_EXPORT EC_KEY *EC_KEY_new_by_curve_name(int nid); 98 99// EC_KEY_free frees all the data owned by |key| and |key| itself. 100OPENSSL_EXPORT void EC_KEY_free(EC_KEY *key); 101 102// EC_KEY_copy sets |dst| equal to |src| and returns |dst| or NULL on error. 103OPENSSL_EXPORT EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); 104 105// EC_KEY_dup returns a fresh copy of |src| or NULL on error. 106OPENSSL_EXPORT EC_KEY *EC_KEY_dup(const EC_KEY *src); 107 108// EC_KEY_up_ref increases the reference count of |key| and returns one. 109OPENSSL_EXPORT int EC_KEY_up_ref(EC_KEY *key); 110 111// EC_KEY_is_opaque returns one if |key| is opaque and doesn't expose its key 112// material. Otherwise it return zero. 113OPENSSL_EXPORT int EC_KEY_is_opaque(const EC_KEY *key); 114 115// EC_KEY_get0_group returns a pointer to the |EC_GROUP| object inside |key|. 116OPENSSL_EXPORT const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); 117 118// EC_KEY_set_group sets the |EC_GROUP| object that |key| will use to |group|. 119// It returns one on success and zero otherwise. If |key| already has a group, 120// it is an error to change to a different one. 121OPENSSL_EXPORT int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); 122 123// EC_KEY_get0_private_key returns a pointer to the private key inside |key|. 124OPENSSL_EXPORT const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); 125 126// EC_KEY_set_private_key sets the private key of |key| to |priv|. It returns 127// one on success and zero otherwise. |key| must already have had a group 128// configured (see |EC_KEY_set_group| and |EC_KEY_new_by_curve_name|). 129OPENSSL_EXPORT int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); 130 131// EC_KEY_get0_public_key returns a pointer to the public key point inside 132// |key|. 133OPENSSL_EXPORT const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); 134 135// EC_KEY_set_public_key sets the public key of |key| to |pub|, by copying it. 136// It returns one on success and zero otherwise. |key| must already have had a 137// group configured (see |EC_KEY_set_group| and |EC_KEY_new_by_curve_name|), and 138// |pub| must also belong to that group. 139OPENSSL_EXPORT int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); 140 141#define EC_PKEY_NO_PARAMETERS 0x001 142#define EC_PKEY_NO_PUBKEY 0x002 143 144// EC_KEY_get_enc_flags returns the encoding flags for |key|, which is a 145// bitwise-OR of |EC_PKEY_*| values. 146OPENSSL_EXPORT unsigned EC_KEY_get_enc_flags(const EC_KEY *key); 147 148// EC_KEY_set_enc_flags sets the encoding flags for |key|, which is a 149// bitwise-OR of |EC_PKEY_*| values. 150OPENSSL_EXPORT void EC_KEY_set_enc_flags(EC_KEY *key, unsigned flags); 151 152// EC_KEY_get_conv_form returns the conversation form that will be used by 153// |key|. 154OPENSSL_EXPORT point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); 155 156// EC_KEY_set_conv_form sets the conversion form to be used by |key|. 157OPENSSL_EXPORT void EC_KEY_set_conv_form(EC_KEY *key, 158 point_conversion_form_t cform); 159 160// EC_KEY_check_key performs several checks on |key| (possibly including an 161// expensive check that the public key is in the primary subgroup). It returns 162// one if all checks pass and zero otherwise. If it returns zero then detail 163// about the problem can be found on the error stack. 164OPENSSL_EXPORT int EC_KEY_check_key(const EC_KEY *key); 165 166// EC_KEY_check_fips performs a signing pairwise consistency test (FIPS 140-2 167// 4.9.2). It returns one if it passes and zero otherwise. 168OPENSSL_EXPORT int EC_KEY_check_fips(const EC_KEY *key); 169 170// EC_KEY_set_public_key_affine_coordinates sets the public key in |key| to 171// (|x|, |y|). It returns one on success and zero otherwise. 172OPENSSL_EXPORT int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, 173 BIGNUM *x, 174 BIGNUM *y); 175 176 177// Key generation. 178 179// EC_KEY_generate_key generates a random, private key, calculates the 180// corresponding public key and stores both in |key|. It returns one on success 181// or zero otherwise. 182OPENSSL_EXPORT int EC_KEY_generate_key(EC_KEY *key); 183 184// EC_KEY_generate_key_fips behaves like |EC_KEY_generate_key| but performs 185// additional checks for FIPS compliance. 186OPENSSL_EXPORT int EC_KEY_generate_key_fips(EC_KEY *key); 187 188 189// Serialisation. 190 191// EC_KEY_parse_private_key parses a DER-encoded ECPrivateKey structure (RFC 192// 5915) from |cbs| and advances |cbs|. It returns a newly-allocated |EC_KEY| or 193// NULL on error. If |group| is non-null, the parameters field of the 194// ECPrivateKey may be omitted (but must match |group| if present). Otherwise, 195// the parameters field is required. 196OPENSSL_EXPORT EC_KEY *EC_KEY_parse_private_key(CBS *cbs, 197 const EC_GROUP *group); 198 199// EC_KEY_marshal_private_key marshals |key| as a DER-encoded ECPrivateKey 200// structure (RFC 5915) and appends the result to |cbb|. It returns one on 201// success and zero on failure. |enc_flags| is a combination of |EC_PKEY_*| 202// values and controls whether corresponding fields are omitted. 203OPENSSL_EXPORT int EC_KEY_marshal_private_key(CBB *cbb, const EC_KEY *key, 204 unsigned enc_flags); 205 206// EC_KEY_parse_curve_name parses a DER-encoded OBJECT IDENTIFIER as a curve 207// name from |cbs| and advances |cbs|. It returns a newly-allocated |EC_GROUP| 208// or NULL on error. 209OPENSSL_EXPORT EC_GROUP *EC_KEY_parse_curve_name(CBS *cbs); 210 211// EC_KEY_marshal_curve_name marshals |group| as a DER-encoded OBJECT IDENTIFIER 212// and appends the result to |cbb|. It returns one on success and zero on 213// failure. 214OPENSSL_EXPORT int EC_KEY_marshal_curve_name(CBB *cbb, const EC_GROUP *group); 215 216// EC_KEY_parse_parameters parses a DER-encoded ECParameters structure (RFC 217// 5480) from |cbs| and advances |cbs|. It returns a newly-allocated |EC_GROUP| 218// or NULL on error. It supports the namedCurve and specifiedCurve options, but 219// use of specifiedCurve is deprecated. Use |EC_KEY_parse_curve_name| 220// instead. 221OPENSSL_EXPORT EC_GROUP *EC_KEY_parse_parameters(CBS *cbs); 222 223 224// ex_data functions. 225// 226// These functions are wrappers. See |ex_data.h| for details. 227 228OPENSSL_EXPORT int EC_KEY_get_ex_new_index(long argl, void *argp, 229 CRYPTO_EX_unused *unused, 230 CRYPTO_EX_dup *dup_unused, 231 CRYPTO_EX_free *free_func); 232OPENSSL_EXPORT int EC_KEY_set_ex_data(EC_KEY *r, int idx, void *arg); 233OPENSSL_EXPORT void *EC_KEY_get_ex_data(const EC_KEY *r, int idx); 234 235 236// ECDSA method. 237 238// ECDSA_FLAG_OPAQUE specifies that this ECDSA_METHOD does not expose its key 239// material. This may be set if, for instance, it is wrapping some other crypto 240// API, like a platform key store. 241#define ECDSA_FLAG_OPAQUE 1 242 243// ecdsa_method_st is a structure of function pointers for implementing ECDSA. 244// See engine.h. 245struct ecdsa_method_st { 246 struct openssl_method_common_st common; 247 248 void *app_data; 249 250 int (*init)(EC_KEY *key); 251 int (*finish)(EC_KEY *key); 252 253 // group_order_size returns the number of bytes needed to represent the order 254 // of the group. This is used to calculate the maximum size of an ECDSA 255 // signature in |ECDSA_size|. 256 size_t (*group_order_size)(const EC_KEY *key); 257 258 // sign matches the arguments and behaviour of |ECDSA_sign|. 259 int (*sign)(const uint8_t *digest, size_t digest_len, uint8_t *sig, 260 unsigned int *sig_len, EC_KEY *eckey); 261 262 int flags; 263}; 264 265 266// Deprecated functions. 267 268// EC_KEY_set_asn1_flag does nothing. 269OPENSSL_EXPORT void EC_KEY_set_asn1_flag(EC_KEY *key, int flag); 270 271// d2i_ECPrivateKey parses an ASN.1, DER-encoded, private key from |len| bytes 272// at |*inp|. If |out_key| is not NULL then, on exit, a pointer to the result 273// is in |*out_key|. Note that, even if |*out_key| is already non-NULL on entry, 274// it * will not be written to. Rather, a fresh |EC_KEY| is allocated and the 275// previous * one is freed. On successful exit, |*inp| is advanced past the DER 276// structure. It returns the result or NULL on error. 277// 278// On input, if |*out_key| is non-NULL and has a group configured, the 279// parameters field may be omitted but must match that group if present. 280// 281// Use |EC_KEY_parse_private_key| instead. 282OPENSSL_EXPORT EC_KEY *d2i_ECPrivateKey(EC_KEY **out_key, const uint8_t **inp, 283 long len); 284 285// i2d_ECPrivateKey marshals an EC private key from |key| to an ASN.1, DER 286// structure. If |outp| is not NULL then the result is written to |*outp| and 287// |*outp| is advanced just past the output. It returns the number of bytes in 288// the result, whether written or not, or a negative value on error. 289// 290// Use |EC_KEY_marshal_private_key| instead. 291OPENSSL_EXPORT int i2d_ECPrivateKey(const EC_KEY *key, uint8_t **outp); 292 293// d2i_ECParameters parses an ASN.1, DER-encoded, set of EC parameters from 294// |len| bytes at |*inp|. If |out_key| is not NULL then, on exit, a pointer to 295// the result is in |*out_key|. Note that, even if |*out_key| is already 296// non-NULL on entry, it will not be written to. Rather, a fresh |EC_KEY| is 297// allocated and the previous one is freed. On successful exit, |*inp| is 298// advanced past the DER structure. It returns the result or NULL on error. 299// 300// Use |EC_KEY_parse_parameters| or |EC_KEY_parse_curve_name| instead. 301OPENSSL_EXPORT EC_KEY *d2i_ECParameters(EC_KEY **out_key, const uint8_t **inp, 302 long len); 303 304// i2d_ECParameters marshals EC parameters from |key| to an ASN.1, DER 305// structure. If |outp| is not NULL then the result is written to |*outp| and 306// |*outp| is advanced just past the output. It returns the number of bytes in 307// the result, whether written or not, or a negative value on error. 308// 309// Use |EC_KEY_marshal_curve_name| instead. 310OPENSSL_EXPORT int i2d_ECParameters(const EC_KEY *key, uint8_t **outp); 311 312// o2i_ECPublicKey parses an EC point from |len| bytes at |*inp| into 313// |*out_key|. Note that this differs from the d2i format in that |*out_key| 314// must be non-NULL with a group set. On successful exit, |*inp| is advanced by 315// |len| bytes. It returns |*out_key| or NULL on error. 316// 317// Use |EC_POINT_oct2point| instead. 318OPENSSL_EXPORT EC_KEY *o2i_ECPublicKey(EC_KEY **out_key, const uint8_t **inp, 319 long len); 320 321// i2o_ECPublicKey marshals an EC point from |key|. If |outp| is not NULL then 322// the result is written to |*outp| and |*outp| is advanced just past the 323// output. It returns the number of bytes in the result, whether written or 324// not, or a negative value on error. 325// 326// Use |EC_POINT_point2cbb| instead. 327OPENSSL_EXPORT int i2o_ECPublicKey(const EC_KEY *key, unsigned char **outp); 328 329 330#if defined(__cplusplus) 331} // extern C 332 333extern "C++" { 334 335namespace bssl { 336 337BORINGSSL_MAKE_DELETER(EC_KEY, EC_KEY_free) 338 339} // namespace bssl 340 341} // extern C++ 342 343#endif 344 345#endif // OPENSSL_HEADER_EC_KEY_H 346