Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 1 | /* ==================================================================== |
| 2 | * Copyright (c) 1998-2005 The OpenSSL Project. All rights reserved. |
| 3 | * |
| 4 | * Redistribution and use in source and binary forms, with or without |
| 5 | * modification, are permitted provided that the following conditions |
| 6 | * are met: |
| 7 | * |
| 8 | * 1. Redistributions of source code must retain the above copyright |
| 9 | * notice, this list of conditions and the following disclaimer. |
| 10 | * |
| 11 | * 2. Redistributions in binary form must reproduce the above copyright |
| 12 | * notice, this list of conditions and the following disclaimer in |
| 13 | * the documentation and/or other materials provided with the |
| 14 | * distribution. |
| 15 | * |
| 16 | * 3. All advertising materials mentioning features or use of this |
| 17 | * software must display the following acknowledgment: |
| 18 | * "This product includes software developed by the OpenSSL Project |
| 19 | * for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)" |
| 20 | * |
| 21 | * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to |
| 22 | * endorse or promote products derived from this software without |
| 23 | * prior written permission. For written permission, please contact |
| 24 | * openssl-core@OpenSSL.org. |
| 25 | * |
| 26 | * 5. Products derived from this software may not be called "OpenSSL" |
| 27 | * nor may "OpenSSL" appear in their names without prior written |
| 28 | * permission of the OpenSSL Project. |
| 29 | * |
| 30 | * 6. Redistributions of any form whatsoever must retain the following |
| 31 | * acknowledgment: |
| 32 | * "This product includes software developed by the OpenSSL Project |
| 33 | * for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)" |
| 34 | * |
| 35 | * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY |
| 36 | * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 37 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| 38 | * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR |
| 39 | * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 40 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| 41 | * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| 42 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 43 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
| 44 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 45 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
| 46 | * OF THE POSSIBILITY OF SUCH DAMAGE. |
| 47 | * ==================================================================== |
| 48 | * |
| 49 | * This product includes cryptographic software written by Eric Young |
| 50 | * (eay@cryptsoft.com). This product includes software written by Tim |
| 51 | * Hudson (tjh@cryptsoft.com). */ |
| 52 | |
| 53 | #ifndef OPENSSL_HEADER_ECDSA_H |
| 54 | #define OPENSSL_HEADER_ECDSA_H |
| 55 | |
| 56 | #include <openssl/base.h> |
| 57 | |
| 58 | #include <openssl/ec_key.h> |
| 59 | |
| 60 | #if defined(__cplusplus) |
| 61 | extern "C" { |
| 62 | #endif |
| 63 | |
| 64 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 65 | // ECDSA contains functions for signing and verifying with the Digital Signature |
| 66 | // Algorithm over elliptic curves. |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 67 | |
| 68 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 69 | // Signing and verifying. |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 70 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 71 | // ECDSA_sign signs |digest_len| bytes from |digest| with |key| and writes the |
| 72 | // resulting signature to |sig|, which must have |ECDSA_size(key)| bytes of |
| 73 | // space. On successful exit, |*sig_len| is set to the actual number of bytes |
| 74 | // written. The |type| argument should be zero. It returns one on success and |
| 75 | // zero otherwise. |
David Benjamin | 940475d | 2021-05-13 18:45:52 -0400 | [diff] [blame] | 76 | // |
| 77 | // WARNING: |digest| must be the output of some hash function on the data to be |
| 78 | // signed. Passing unhashed inputs will not result in a secure signature scheme. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 79 | OPENSSL_EXPORT int ECDSA_sign(int type, const uint8_t *digest, |
| 80 | size_t digest_len, uint8_t *sig, |
Matthew Braithwaite | c4796c9 | 2017-02-16 16:49:54 -0800 | [diff] [blame] | 81 | unsigned int *sig_len, const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 82 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 83 | // ECDSA_verify verifies that |sig_len| bytes from |sig| constitute a valid |
| 84 | // signature by |key| of |digest|. (The |type| argument should be zero.) It |
| 85 | // returns one on success or zero if the signature is invalid or an error |
| 86 | // occurred. |
David Benjamin | 940475d | 2021-05-13 18:45:52 -0400 | [diff] [blame] | 87 | // |
| 88 | // WARNING: |digest| must be the output of some hash function on the data to be |
| 89 | // verified. Passing unhashed inputs will not result in a secure signature |
| 90 | // scheme. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 91 | OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest, |
| 92 | size_t digest_len, const uint8_t *sig, |
Matthew Braithwaite | c4796c9 | 2017-02-16 16:49:54 -0800 | [diff] [blame] | 93 | size_t sig_len, const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 94 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 95 | // ECDSA_size returns the maximum size of an ECDSA signature using |key|. It |
Joshua Liebow-Feeser | 9781699 | 2018-08-13 16:02:05 -0700 | [diff] [blame] | 96 | // returns zero if |key| is NULL or if it doesn't have a group set. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 97 | OPENSSL_EXPORT size_t ECDSA_size(const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 98 | |
| 99 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 100 | // Low-level signing and verification. |
| 101 | // |
| 102 | // Low-level functions handle signatures as |ECDSA_SIG| structures which allow |
| 103 | // the two values in an ECDSA signature to be handled separately. |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 104 | |
| 105 | struct ecdsa_sig_st { |
| 106 | BIGNUM *r; |
| 107 | BIGNUM *s; |
| 108 | }; |
| 109 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 110 | // ECDSA_SIG_new returns a fresh |ECDSA_SIG| structure or NULL on error. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 111 | OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_new(void); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 112 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 113 | // ECDSA_SIG_free frees |sig| its member |BIGNUM|s. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 114 | OPENSSL_EXPORT void ECDSA_SIG_free(ECDSA_SIG *sig); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 115 | |
Shelley Vohr | 6432bb4 | 2020-02-13 11:26:31 -0800 | [diff] [blame] | 116 | // ECDSA_SIG_get0_r returns the r component of |sig|. |
| 117 | OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig); |
| 118 | |
| 119 | // ECDSA_SIG_get0_s returns the s component of |sig|. |
| 120 | OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig); |
| 121 | |
David Benjamin | 8dc226c | 2017-11-21 20:33:36 -0500 | [diff] [blame] | 122 | // ECDSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two |
| 123 | // components of |sig|. |
| 124 | OPENSSL_EXPORT void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **out_r, |
| 125 | const BIGNUM **out_s); |
| 126 | |
| 127 | // ECDSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may |
| 128 | // be NULL. On success, it takes ownership of each argument and returns one. |
| 129 | // Otherwise, it returns zero. |
| 130 | OPENSSL_EXPORT int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); |
| 131 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 132 | // ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns |
| 133 | // the resulting signature structure, or NULL on error. |
David Benjamin | 940475d | 2021-05-13 18:45:52 -0400 | [diff] [blame] | 134 | // |
| 135 | // WARNING: |digest| must be the output of some hash function on the data to be |
| 136 | // signed. Passing unhashed inputs will not result in a secure signature scheme. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 137 | OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest, |
Matthew Braithwaite | c4796c9 | 2017-02-16 16:49:54 -0800 | [diff] [blame] | 138 | size_t digest_len, const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 139 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 140 | // ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key| |
| 141 | // of |digest|. It returns one on success or zero if the signature is invalid |
| 142 | // or on error. |
David Benjamin | 940475d | 2021-05-13 18:45:52 -0400 | [diff] [blame] | 143 | // |
| 144 | // WARNING: |digest| must be the output of some hash function on the data to be |
| 145 | // verified. Passing unhashed inputs will not result in a secure signature |
| 146 | // scheme. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 147 | OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len, |
Matthew Braithwaite | c4796c9 | 2017-02-16 16:49:54 -0800 | [diff] [blame] | 148 | const ECDSA_SIG *sig, const EC_KEY *key); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 149 | |
| 150 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 151 | // ASN.1 functions. |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 152 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 153 | // ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from |cbs| and |
| 154 | // advances |cbs|. It returns a newly-allocated |ECDSA_SIG| or NULL on error. |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 155 | OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_parse(CBS *cbs); |
| 156 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 157 | // ECDSA_SIG_from_bytes parses |in| as a DER-encoded ECDSA-Sig-Value structure. |
| 158 | // It returns a newly-allocated |ECDSA_SIG| structure or NULL on error. |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 159 | OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_from_bytes(const uint8_t *in, |
| 160 | size_t in_len); |
| 161 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 162 | // ECDSA_SIG_marshal marshals |sig| as a DER-encoded ECDSA-Sig-Value and appends |
| 163 | // the result to |cbb|. It returns one on success and zero on error. |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 164 | OPENSSL_EXPORT int ECDSA_SIG_marshal(CBB *cbb, const ECDSA_SIG *sig); |
| 165 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 166 | // ECDSA_SIG_to_bytes marshals |sig| as a DER-encoded ECDSA-Sig-Value and, on |
| 167 | // success, sets |*out_bytes| to a newly allocated buffer containing the result |
| 168 | // and returns one. Otherwise, it returns zero. The result should be freed with |
| 169 | // |OPENSSL_free|. |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 170 | OPENSSL_EXPORT int ECDSA_SIG_to_bytes(uint8_t **out_bytes, size_t *out_len, |
| 171 | const ECDSA_SIG *sig); |
| 172 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 173 | // ECDSA_SIG_max_len returns the maximum length of a DER-encoded ECDSA-Sig-Value |
| 174 | // structure for a group whose order is represented in |order_len| bytes, or |
| 175 | // zero on overflow. |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 176 | OPENSSL_EXPORT size_t ECDSA_SIG_max_len(size_t order_len); |
| 177 | |
| 178 | |
David Benjamin | 409ea28 | 2021-01-31 18:04:07 -0500 | [diff] [blame] | 179 | // Testing-only functions. |
| 180 | |
| 181 | // ECDSA_sign_with_nonce_and_leak_private_key_for_testing behaves like |
| 182 | // |ECDSA_do_sign| but uses |nonce| for the ECDSA nonce 'k', instead of a random |
| 183 | // value. |nonce| is interpreted as a big-endian integer. It must be reduced |
| 184 | // modulo the group order and padded with zeros up to |BN_num_bytes(order)| |
| 185 | // bytes. |
| 186 | // |
| 187 | // WARNING: This function is only exported for testing purposes, when using test |
| 188 | // vectors or fuzzing strategies. It must not be used outside tests and may leak |
| 189 | // any private keys it is used with. |
| 190 | OPENSSL_EXPORT ECDSA_SIG * |
| 191 | ECDSA_sign_with_nonce_and_leak_private_key_for_testing(const uint8_t *digest, |
| 192 | size_t digest_len, |
| 193 | const EC_KEY *eckey, |
| 194 | const uint8_t *nonce, |
| 195 | size_t nonce_len); |
| 196 | |
| 197 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 198 | // Deprecated functions. |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 199 | |
David Benjamin | cfafcd4 | 2021-10-14 17:22:23 -0400 | [diff] [blame] | 200 | // d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from |len| |
| 201 | // bytes at |*inp|, as described in |d2i_SAMPLE|. |
| 202 | // |
| 203 | // Use |ECDSA_SIG_parse| instead. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 204 | OPENSSL_EXPORT ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **out, const uint8_t **inp, |
| 205 | long len); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 206 | |
David Benjamin | cfafcd4 | 2021-10-14 17:22:23 -0400 | [diff] [blame] | 207 | // i2d_ECDSA_SIG marshals |sig| as a DER-encoded ECDSA-Sig-Value, as described |
| 208 | // in |i2d_SAMPLE|. |
| 209 | // |
| 210 | // Use |ECDSA_SIG_marshal| instead. |
Adam Langley | eb7d2ed | 2014-07-30 16:02:14 -0700 | [diff] [blame] | 211 | OPENSSL_EXPORT int i2d_ECDSA_SIG(const ECDSA_SIG *sig, uint8_t **outp); |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 212 | |
| 213 | |
| 214 | #if defined(__cplusplus) |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 215 | } // extern C |
Matt Braithwaite | d17d74d | 2016-08-17 20:10:28 -0700 | [diff] [blame] | 216 | |
| 217 | extern "C++" { |
| 218 | |
Joshua Liebow-Feeser | 8c7c635 | 2018-08-26 18:53:36 -0700 | [diff] [blame] | 219 | BSSL_NAMESPACE_BEGIN |
Matt Braithwaite | d17d74d | 2016-08-17 20:10:28 -0700 | [diff] [blame] | 220 | |
Matt Braithwaite | d17d74d | 2016-08-17 20:10:28 -0700 | [diff] [blame] | 221 | BORINGSSL_MAKE_DELETER(ECDSA_SIG, ECDSA_SIG_free) |
| 222 | |
Joshua Liebow-Feeser | 8c7c635 | 2018-08-26 18:53:36 -0700 | [diff] [blame] | 223 | BSSL_NAMESPACE_END |
Matt Braithwaite | d17d74d | 2016-08-17 20:10:28 -0700 | [diff] [blame] | 224 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 225 | } // extern C++ |
Matt Braithwaite | d17d74d | 2016-08-17 20:10:28 -0700 | [diff] [blame] | 226 | |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 227 | #endif |
| 228 | |
David Benjamin | 689be0f | 2015-02-11 15:55:26 -0500 | [diff] [blame] | 229 | #define ECDSA_R_BAD_SIGNATURE 100 |
| 230 | #define ECDSA_R_MISSING_PARAMETERS 101 |
| 231 | #define ECDSA_R_NEED_NEW_SETUP_VALUES 102 |
| 232 | #define ECDSA_R_NOT_IMPLEMENTED 103 |
| 233 | #define ECDSA_R_RANDOM_NUMBER_GENERATION_FAILED 104 |
David Benjamin | 87897a8 | 2015-06-11 23:30:53 -0400 | [diff] [blame] | 234 | #define ECDSA_R_ENCODE_ERROR 105 |
David Benjamin | 474ddf8 | 2023-02-11 10:13:32 -0500 | [diff] [blame] | 235 | #define ECDSA_R_TOO_MANY_ITERATIONS 106 |
Adam Langley | 95c29f3 | 2014-06-20 12:00:00 -0700 | [diff] [blame] | 236 | |
David Benjamin | 4512b79 | 2017-08-18 19:21:50 -0400 | [diff] [blame] | 237 | #endif // OPENSSL_HEADER_ECDSA_H |