1 /* 2 * Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_ECDSA_H 11 #define OPENSSL_HEADER_ECDSA_H 12 13 #include <openssl/base.h> 14 15 #include <openssl/ec_key.h> 16 17 #if defined(__cplusplus) 18 extern "C" { 19 #endif 20 21 22 // ECDSA contains functions for signing and verifying with the Digital Signature 23 // Algorithm over elliptic curves. 24 25 26 // Signing and verifying. 27 28 // ECDSA_sign signs |digest_len| bytes from |digest| with |key| and writes the 29 // resulting signature to |sig|, which must have |ECDSA_size(key)| bytes of 30 // space. On successful exit, |*sig_len| is set to the actual number of bytes 31 // written. The |type| argument should be zero. It returns one on success and 32 // zero otherwise. 33 // 34 // WARNING: |digest| must be the output of some hash function on the data to be 35 // signed. Passing unhashed inputs will not result in a secure signature scheme. 36 OPENSSL_EXPORT int ECDSA_sign(int type, const uint8_t *digest, 37 size_t digest_len, uint8_t *sig, 38 unsigned int *sig_len, const EC_KEY *key); 39 40 // ECDSA_verify verifies that |sig_len| bytes from |sig| constitute a valid 41 // signature by |key| of |digest|. (The |type| argument should be zero.) It 42 // returns one on success or zero if the signature is invalid or an error 43 // occurred. 44 // 45 // WARNING: |digest| must be the output of some hash function on the data to be 46 // verified. Passing unhashed inputs will not result in a secure signature 47 // scheme. 48 OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest, 49 size_t digest_len, const uint8_t *sig, 50 size_t sig_len, const EC_KEY *key); 51 52 // ECDSA_size returns the maximum size of an ECDSA signature using |key|. It 53 // returns zero if |key| is NULL or if it doesn't have a group set. 54 OPENSSL_EXPORT size_t ECDSA_size(const EC_KEY *key); 55 56 57 // Low-level signing and verification. 58 // 59 // Low-level functions handle signatures as |ECDSA_SIG| structures which allow 60 // the two values in an ECDSA signature to be handled separately. 61 62 struct ecdsa_sig_st { 63 BIGNUM *r; 64 BIGNUM *s; 65 }; 66 67 // ECDSA_SIG_new returns a fresh |ECDSA_SIG| structure or NULL on error. 68 OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_new(void); 69 70 // ECDSA_SIG_free frees |sig| its member |BIGNUM|s. 71 OPENSSL_EXPORT void ECDSA_SIG_free(ECDSA_SIG *sig); 72 73 // ECDSA_SIG_get0_r returns the r component of |sig|. 74 OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig); 75 76 // ECDSA_SIG_get0_s returns the s component of |sig|. 77 OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig); 78 79 // ECDSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two 80 // components of |sig|. 81 OPENSSL_EXPORT void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **out_r, 82 const BIGNUM **out_s); 83 84 // ECDSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may 85 // be NULL. On success, it takes ownership of each argument and returns one. 86 // Otherwise, it returns zero. 87 OPENSSL_EXPORT int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); 88 89 // ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns 90 // the resulting signature structure, or NULL on error. 91 // 92 // WARNING: |digest| must be the output of some hash function on the data to be 93 // signed. Passing unhashed inputs will not result in a secure signature scheme. 94 OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest, 95 size_t digest_len, const EC_KEY *key); 96 97 // ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key| 98 // of |digest|. It returns one on success or zero if the signature is invalid 99 // or on error. 100 // 101 // WARNING: |digest| must be the output of some hash function on the data to be 102 // verified. Passing unhashed inputs will not result in a secure signature 103 // scheme. 104 OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len, 105 const ECDSA_SIG *sig, const EC_KEY *key); 106 107 108 // ASN.1 functions. 109 110 // ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from |cbs| and 111 // advances |cbs|. It returns a newly-allocated |ECDSA_SIG| or NULL on error. 112 OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_parse(CBS *cbs); 113 114 // ECDSA_SIG_from_bytes parses |in| as a DER-encoded ECDSA-Sig-Value structure. 115 // It returns a newly-allocated |ECDSA_SIG| structure or NULL on error. 116 OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_from_bytes(const uint8_t *in, 117 size_t in_len); 118 119 // ECDSA_SIG_marshal marshals |sig| as a DER-encoded ECDSA-Sig-Value and appends 120 // the result to |cbb|. It returns one on success and zero on error. 121 OPENSSL_EXPORT int ECDSA_SIG_marshal(CBB *cbb, const ECDSA_SIG *sig); 122 123 // ECDSA_SIG_to_bytes marshals |sig| as a DER-encoded ECDSA-Sig-Value and, on 124 // success, sets |*out_bytes| to a newly allocated buffer containing the result 125 // and returns one. Otherwise, it returns zero. The result should be freed with 126 // |OPENSSL_free|. 127 OPENSSL_EXPORT int ECDSA_SIG_to_bytes(uint8_t **out_bytes, size_t *out_len, 128 const ECDSA_SIG *sig); 129 130 // ECDSA_SIG_max_len returns the maximum length of a DER-encoded ECDSA-Sig-Value 131 // structure for a group whose order is represented in |order_len| bytes, or 132 // zero on overflow. 133 OPENSSL_EXPORT size_t ECDSA_SIG_max_len(size_t order_len); 134 135 136 // Testing-only functions. 137 138 // ECDSA_sign_with_nonce_and_leak_private_key_for_testing behaves like 139 // |ECDSA_do_sign| but uses |nonce| for the ECDSA nonce 'k', instead of a random 140 // value. |nonce| is interpreted as a big-endian integer. It must be reduced 141 // modulo the group order and padded with zeros up to |BN_num_bytes(order)| 142 // bytes. 143 // 144 // WARNING: This function is only exported for testing purposes, when using test 145 // vectors or fuzzing strategies. It must not be used outside tests and may leak 146 // any private keys it is used with. 147 OPENSSL_EXPORT ECDSA_SIG * 148 ECDSA_sign_with_nonce_and_leak_private_key_for_testing(const uint8_t *digest, 149 size_t digest_len, 150 const EC_KEY *eckey, 151 const uint8_t *nonce, 152 size_t nonce_len); 153 154 155 // Deprecated functions. 156 157 // d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from |len| 158 // bytes at |*inp|, as described in |d2i_SAMPLE|. 159 // 160 // Use |ECDSA_SIG_parse| instead. 161 OPENSSL_EXPORT ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **out, const uint8_t **inp, 162 long len); 163 164 // i2d_ECDSA_SIG marshals |sig| as a DER-encoded ECDSA-Sig-Value, as described 165 // in |i2d_SAMPLE|. 166 // 167 // Use |ECDSA_SIG_marshal| instead. 168 OPENSSL_EXPORT int i2d_ECDSA_SIG(const ECDSA_SIG *sig, uint8_t **outp); 169 170 171 #if defined(__cplusplus) 172 } // extern C 173 174 extern "C++" { 175 176 BSSL_NAMESPACE_BEGIN 177 178 BORINGSSL_MAKE_DELETER(ECDSA_SIG, ECDSA_SIG_free) 179 180 BSSL_NAMESPACE_END 181 182 } // extern C++ 183 184 #endif 185 186 #define ECDSA_R_BAD_SIGNATURE 100 187 #define ECDSA_R_MISSING_PARAMETERS 101 188 #define ECDSA_R_NEED_NEW_SETUP_VALUES 102 189 #define ECDSA_R_NOT_IMPLEMENTED 103 190 #define ECDSA_R_RANDOM_NUMBER_GENERATION_FAILED 104 191 #define ECDSA_R_ENCODE_ERROR 105 192 #define ECDSA_R_TOO_MANY_ITERATIONS 106 193 194 #endif // OPENSSL_HEADER_ECDSA_H 195