Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 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) |
| 78 | extern "C" { |
| 79 | #endif |
| 80 | |
| 81 | |
| 82 | /* ec_key.h conatins 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. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 89 | OPENSSL_EXPORT EC_KEY *EC_KEY_new(void); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 90 | |
| 91 | /* EC_KEY_new_method acts the same as |EC_KEY_new|, but takes an explicit |
| 92 | * |ENGINE|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 93 | OPENSSL_EXPORT EC_KEY *EC_KEY_new_method(const ENGINE *engine); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 94 | |
| 95 | /* EC_KEY_new_by_curve_name returns a fresh EC_KEY for group specified by |nid| |
| 96 | * or NULL on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 97 | OPENSSL_EXPORT EC_KEY *EC_KEY_new_by_curve_name(int nid); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 98 | |
| 99 | /* EC_KEY_free frees all the data owned by |key| and |key| itself. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 100 | OPENSSL_EXPORT void EC_KEY_free(EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 101 | |
| 102 | /* EC_KEY_copy sets |dst| equal to |src| and returns |dst| or NULL on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 103 | OPENSSL_EXPORT EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 104 | |
| 105 | /* EC_KEY_dup returns a fresh copy of |src| or NULL on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 106 | OPENSSL_EXPORT EC_KEY *EC_KEY_dup(const EC_KEY *src); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 107 | |
| 108 | /* EC_KEY_up_ref increases the reference count of |key|. It returns one on |
| 109 | * success and zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 110 | OPENSSL_EXPORT int EC_KEY_up_ref(EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 111 | |
David Benjamin | ecc0ce7 | 2014-07-18 18:39:42 -0400 | [diff] [blame] | 112 | /* EC_KEY_is_opaque returns one if |key| is opaque and doesn't expose its key |
| 113 | * material. Otherwise it return zero. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 114 | OPENSSL_EXPORT int EC_KEY_is_opaque(const EC_KEY *key); |
David Benjamin | ecc0ce7 | 2014-07-18 18:39:42 -0400 | [diff] [blame] | 115 | |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 116 | /* EC_KEY_get0_group returns a pointer to the |EC_GROUP| object inside |key|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 117 | OPENSSL_EXPORT const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 118 | |
| 119 | /* EC_KEY_set_group sets the |EC_GROUP| object that |key| will use to |group|. |
| 120 | * It returns one on success and zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 121 | OPENSSL_EXPORT int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 122 | |
| 123 | /* EC_KEY_get0_private_key returns a pointer to the private key inside |key|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 124 | OPENSSL_EXPORT const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 125 | |
| 126 | /* EC_KEY_set_private_key sets the private key of |key| to |priv|. It returns |
| 127 | * one on success and zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 128 | OPENSSL_EXPORT int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 129 | |
| 130 | /* EC_KEY_get0_public_key returns a pointer to the public key point inside |
| 131 | * |key|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 132 | OPENSSL_EXPORT const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 133 | |
| 134 | /* EC_KEY_set_public_key sets the public key of |key| to |pub|, by copying it. |
| 135 | * It returns one on success and zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 136 | OPENSSL_EXPORT int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 137 | |
| 138 | #define EC_PKEY_NO_PARAMETERS 0x001 |
| 139 | #define EC_PKEY_NO_PUBKEY 0x002 |
| 140 | |
| 141 | /* EC_KEY_get_enc_flags returns the encoding flags for |key|, which is a |
| 142 | * bitwise-OR of |EC_PKEY_*| values. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 143 | OPENSSL_EXPORT unsigned EC_KEY_get_enc_flags(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 144 | |
| 145 | /* EC_KEY_set_enc_flags sets the encoding flags for |key|, which is a |
| 146 | * bitwise-OR of |EC_PKEY_*| values. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 147 | OPENSSL_EXPORT void EC_KEY_set_enc_flags(EC_KEY *key, unsigned flags); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 148 | |
| 149 | /* EC_KEY_get_conv_form returns the conversation form that will be used by |
| 150 | * |key|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 151 | OPENSSL_EXPORT point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 152 | |
| 153 | /* EC_KEY_set_conv_form sets the conversion form to be used by |key|. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 154 | OPENSSL_EXPORT void EC_KEY_set_conv_form(EC_KEY *key, |
| 155 | point_conversion_form_t cform); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 156 | |
| 157 | /* EC_KEY_precompute_mult precomputes multiplies of the generator of the |
| 158 | * underlying group in order to speed up operations that calculate generator |
| 159 | * multiples. If |ctx| is not NULL, it may be used. It returns one on success |
| 160 | * and zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 161 | OPENSSL_EXPORT int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 162 | |
| 163 | /* EC_KEY_check_key performs several checks on |key| (possibly including an |
| 164 | * expensive check that the public key is in the primary subgroup). It returns |
| 165 | * one if all checks pass and zero otherwise. If it returns zero then detail |
| 166 | * about the problem can be found on the error stack. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 167 | OPENSSL_EXPORT int EC_KEY_check_key(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 168 | |
| 169 | /* EC_KEY_set_public_key_affine_coordinates sets the public key in |key| to |
| 170 | * (|x|, |y|). It returns one on success and zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 171 | OPENSSL_EXPORT int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, |
| 172 | BIGNUM *x, |
| 173 | BIGNUM *y); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 174 | |
| 175 | |
| 176 | /* Key generation. */ |
| 177 | |
| 178 | /* EC_KEY_generate_key generates a random, private key, calculates the |
| 179 | * corresponding public key and stores both in |key|. It returns one on success |
| 180 | * or zero otherwise. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 181 | OPENSSL_EXPORT int EC_KEY_generate_key(EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 182 | |
| 183 | |
| 184 | /* Serialisation. */ |
| 185 | |
| 186 | /* d2i_ECPrivateKey parses an ASN.1, DER-encoded, private key from |len| bytes |
| 187 | * at |*inp|. If |out_key| is not NULL then, on exit, a pointer to the result |
| 188 | * is in |*out_key|. If |*out_key| is already non-NULL on entry then the result |
| 189 | * is written directly into |*out_key|, otherwise a fresh |EC_KEY| is |
| 190 | * allocated. On successful exit, |*inp| is advanced past the DER structure. It |
| 191 | * returns the result or NULL on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 192 | OPENSSL_EXPORT EC_KEY *d2i_ECPrivateKey(EC_KEY **out_key, const uint8_t **inp, |
| 193 | long len); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 194 | |
| 195 | /* i2d_ECParameters marshals an EC private key from |key| to an ASN.1, DER |
| 196 | * structure. If |outp| is not NULL then the result is written to |*outp| and |
| 197 | * |*outp| is advanced just past the output. It returns the number of bytes in |
| 198 | * the result, whether written or not, or a negative value on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 199 | OPENSSL_EXPORT int i2d_ECPrivateKey(const EC_KEY *key, uint8_t **outp); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 200 | |
| 201 | /* d2i_ECParameters parses an ASN.1, DER-encoded, set of EC parameters from |
| 202 | * |len| bytes at |*inp|. If |out_key| is not NULL then, on exit, a pointer to |
| 203 | * the result is in |*out_key|. If |*out_key| is already non-NULL on entry then |
| 204 | * the result is written directly into |*out_key|, otherwise a fresh |EC_KEY| |
| 205 | * is allocated. On successful exit, |*inp| is advanced past the DER structure. |
| 206 | * It returns the result or NULL on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 207 | OPENSSL_EXPORT EC_KEY *d2i_ECParameters(EC_KEY **out_key, const uint8_t **inp, |
| 208 | long len); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 209 | |
| 210 | /* i2d_ECParameters marshals EC parameters from |key| to an ASN.1, DER |
| 211 | * structure. If |outp| is not NULL then the result is written to |*outp| and |
| 212 | * |*outp| is advanced just past the output. It returns the number of bytes in |
| 213 | * the result, whether written or not, or a negative value on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 214 | OPENSSL_EXPORT int i2d_ECParameters(const EC_KEY *key, uint8_t **outp); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 215 | |
| 216 | /* o2i_ECPublicKey parses an EC point from |len| bytes at |*inp| into |
| 217 | * |*out_key|. Note that this differs from the d2i format in that |*out_key| |
| 218 | * must be non-NULL. On successful exit, |*inp| is advanced past the DER |
| 219 | * structure. It returns |*out_key| or NULL on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 220 | OPENSSL_EXPORT EC_KEY *o2i_ECPublicKey(EC_KEY **out_key, const uint8_t **inp, |
| 221 | long len); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 222 | |
| 223 | /* i2o_ECPublicKey marshals an EC point from |key|. If |outp| is not NULL then |
| 224 | * the result is written to |*outp| and |*outp| is advanced just past the |
| 225 | * output. It returns the number of bytes in the result, whether written or |
| 226 | * not, or a negative value on error. */ |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 227 | OPENSSL_EXPORT int i2o_ECPublicKey(const EC_KEY *key, unsigned char **outp); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 228 | |
| 229 | |
| 230 | /* ex_data functions. |
| 231 | * |
| 232 | * These functions are wrappers. See |ex_data.h| for details. */ |
| 233 | |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 234 | OPENSSL_EXPORT int EC_KEY_get_ex_new_index(long argl, void *argp, |
| 235 | CRYPTO_EX_new *new_func, |
| 236 | CRYPTO_EX_dup *dup_func, |
| 237 | CRYPTO_EX_free *free_func); |
| 238 | OPENSSL_EXPORT int EC_KEY_set_ex_data(EC_KEY *r, int idx, void *arg); |
| 239 | OPENSSL_EXPORT void *EC_KEY_get_ex_data(const EC_KEY *r, int idx); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 240 | |
| 241 | |
| 242 | /* ECDSA method. */ |
| 243 | |
David Benjamin | ecc0ce7 | 2014-07-18 18:39:42 -0400 | [diff] [blame] | 244 | /* ECDSA_FLAG_OPAQUE specifies that this ECDSA_METHOD does not expose its key |
| 245 | * material. This may be set if, for instance, it is wrapping some other crypto |
| 246 | * API, like a platform key store. */ |
| 247 | #define ECDSA_FLAG_OPAQUE 1 |
| 248 | |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 249 | /* ecdsa_method_st is a structure of function pointers for implementing ECDSA. |
| 250 | * See engine.h. */ |
| 251 | struct ecdsa_method_st { |
| 252 | struct openssl_method_common_st common; |
| 253 | |
| 254 | void *app_data; |
| 255 | |
| 256 | int (*init)(EC_KEY *key); |
| 257 | int (*finish)(EC_KEY *key); |
| 258 | |
Adam Langley | 449f16b | 2014-07-15 15:15:09 -0700 | [diff] [blame] | 259 | /* group_order_size returns the number of bytes needed to represent the order |
| 260 | * of the group. This is used to calculate the maximum size of an ECDSA |
| 261 | * signature in |ECDSA_size|. */ |
| 262 | size_t (*group_order_size)(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 263 | |
| 264 | /* sign matches the arguments and behaviour of |ECDSA_sign|. */ |
| 265 | int (*sign)(const uint8_t *digest, size_t digest_len, uint8_t *sig, |
| 266 | unsigned int *sig_len, EC_KEY *eckey); |
| 267 | |
| 268 | /* verify matches the arguments and behaviour of |ECDSA_verify|. */ |
| 269 | int (*verify)(const uint8_t *digest, size_t digest_len, const uint8_t *sig, |
| 270 | size_t sig_len, EC_KEY *eckey); |
David Benjamin | ecc0ce7 | 2014-07-18 18:39:42 -0400 | [diff] [blame] | 271 | |
| 272 | int flags; |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 273 | }; |
| 274 | |
| 275 | |
| 276 | #if defined(__cplusplus) |
| 277 | } /* extern C */ |
| 278 | #endif |
| 279 | |
| 280 | #endif /* OPENSSL_HEADER_EC_KEY_H */ |