ecdsa.h (10424B)
1 // Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef OPENSSL_HEADER_ECDSA_H 16 #define OPENSSL_HEADER_ECDSA_H 17 18 #include <openssl/base.h> // IWYU pragma: export 19 20 #include <openssl/ec_key.h> 21 22 #if defined(__cplusplus) 23 extern "C" { 24 #endif 25 26 27 // ECDSA contains functions for signing and verifying with the Digital Signature 28 // Algorithm over elliptic curves. 29 30 31 // Signing and verifying. 32 // 33 // ECDSA does not have a single, common signature format across all 34 // applications. These functions implement the more common, ASN.1-based format. 35 // In it, signatures are a DER-encoded ECDSA-Sig-Value structure. Note that this 36 // format is variable-length. Callers must be prepared to receive signatures 37 // that are slightly shorter than the maximum for the ECDSA curve. 38 39 // ECDSA_sign signs |digest_len| bytes from |digest| with |key| and writes the 40 // resulting ASN.1-based signature to |sig|, which must have |ECDSA_size(key)| 41 // bytes of space. On successful exit, |*sig_len| is set to the actual number of 42 // bytes written. The |type| argument should be zero. It returns one on success 43 // and zero otherwise. 44 // 45 // WARNING: |digest| must be the output of some hash function on the data to be 46 // signed. Passing unhashed inputs will not result in a secure signature scheme. 47 OPENSSL_EXPORT int ECDSA_sign(int type, const uint8_t *digest, 48 size_t digest_len, uint8_t *sig, 49 unsigned int *sig_len, const EC_KEY *key); 50 51 // ECDSA_verify verifies that |sig_len| bytes from |sig| constitute a valid 52 // ASN.1-based signature by |key| of |digest|. (The |type| argument should be 53 // zero.) It returns one on success or zero if the signature is invalid or an 54 // error occurred. 55 // 56 // WARNING: |digest| must be the output of some hash function on the data to be 57 // verified. Passing unhashed inputs will not result in a secure signature 58 // scheme. 59 OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest, 60 size_t digest_len, const uint8_t *sig, 61 size_t sig_len, const EC_KEY *key); 62 63 // ECDSA_size returns the maximum size of an ASN.1-based ECDSA signature using 64 // |key|. It returns zero if |key| is NULL or if it doesn't have a group set. 65 OPENSSL_EXPORT size_t ECDSA_size(const EC_KEY *key); 66 67 68 // Low-level signing and verification. 69 // 70 // Low-level functions handle signatures as |ECDSA_SIG| structures which allow 71 // the two values in an ECDSA signature to be handled separately. 72 73 struct ecdsa_sig_st { 74 BIGNUM *r; 75 BIGNUM *s; 76 }; 77 78 // ECDSA_SIG_new returns a fresh |ECDSA_SIG| structure or NULL on error. 79 OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_new(void); 80 81 // ECDSA_SIG_free frees |sig| its member |BIGNUM|s. 82 OPENSSL_EXPORT void ECDSA_SIG_free(ECDSA_SIG *sig); 83 84 // ECDSA_SIG_get0_r returns the r component of |sig|. 85 OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig); 86 87 // ECDSA_SIG_get0_s returns the s component of |sig|. 88 OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig); 89 90 // ECDSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two 91 // components of |sig|. 92 OPENSSL_EXPORT void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **out_r, 93 const BIGNUM **out_s); 94 95 // ECDSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may 96 // be NULL. On success, it takes ownership of each argument and returns one. 97 // Otherwise, it returns zero. 98 OPENSSL_EXPORT int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); 99 100 // ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns 101 // the resulting signature structure, or NULL on error. 102 // 103 // WARNING: |digest| must be the output of some hash function on the data to be 104 // signed. Passing unhashed inputs will not result in a secure signature scheme. 105 OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest, 106 size_t digest_len, const EC_KEY *key); 107 108 // ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key| 109 // of |digest|. It returns one on success or zero if the signature is invalid 110 // or on error. 111 // 112 // WARNING: |digest| must be the output of some hash function on the data to be 113 // verified. Passing unhashed inputs will not result in a secure signature 114 // scheme. 115 OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len, 116 const ECDSA_SIG *sig, const EC_KEY *key); 117 118 119 // ASN.1 functions. 120 121 // ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from |cbs| and 122 // advances |cbs|. It returns a newly-allocated |ECDSA_SIG| or NULL on error. 123 OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_parse(CBS *cbs); 124 125 // ECDSA_SIG_from_bytes parses |in| as a DER-encoded ECDSA-Sig-Value structure. 126 // It returns a newly-allocated |ECDSA_SIG| structure or NULL on error. 127 OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_from_bytes(const uint8_t *in, 128 size_t in_len); 129 130 // ECDSA_SIG_marshal marshals |sig| as a DER-encoded ECDSA-Sig-Value and appends 131 // the result to |cbb|. It returns one on success and zero on error. 132 OPENSSL_EXPORT int ECDSA_SIG_marshal(CBB *cbb, const ECDSA_SIG *sig); 133 134 // ECDSA_SIG_to_bytes marshals |sig| as a DER-encoded ECDSA-Sig-Value and, on 135 // success, sets |*out_bytes| to a newly allocated buffer containing the result 136 // and returns one. Otherwise, it returns zero. The result should be freed with 137 // |OPENSSL_free|. 138 OPENSSL_EXPORT int ECDSA_SIG_to_bytes(uint8_t **out_bytes, size_t *out_len, 139 const ECDSA_SIG *sig); 140 141 // ECDSA_SIG_max_len returns the maximum length of a DER-encoded ECDSA-Sig-Value 142 // structure for a group whose order is represented in |order_len| bytes, or 143 // zero on overflow. 144 OPENSSL_EXPORT size_t ECDSA_SIG_max_len(size_t order_len); 145 146 147 // IEEE P1363 signing and verifying. 148 // 149 // ECDSA does not have a single, common signature format across all 150 // applications. These functions implement the less common, fixed-width format, 151 // defined in IEEE P1363. It is also used in PKCS#11 and DNSSEC. In it, 152 // signatures are a concatenation of r and s components, each zero-padded up to 153 // the width of the group order. This format is fixed-width, so a given ECDSA 154 // curve's signatures will always have the same size. 155 156 // ECDSA_sign_p1363 signs |digest_len| bytes from |digest| with |key| and writes 157 // the resulting P1363-based signature to |sig|, which must have 158 // |ECDSA_size_p1363(key)| bytes of space. On successful exit, |*out_sig_len| is 159 // set to the actual number of bytes written, which will always match 160 // |ECDSA_size_p1363(key)|. It returns one on success and zero otherwise. 161 // 162 // WARNING: |digest| must be the output of some hash function on the data to be 163 // signed. Passing unhashed inputs will not result in a secure signature scheme. 164 OPENSSL_EXPORT int ECDSA_sign_p1363(const uint8_t *digest, size_t digest_len, 165 uint8_t *sig, size_t *out_sig_len, 166 size_t max_sig_len, const EC_KEY *key); 167 168 // ECDSA_verify_p1363 verifies that |sig_len| bytes from |sig| constitute a 169 // valid P1363-based signature by |key| of |digest|. It returns one on success 170 // or zero if the signature is invalid or an error occurred. 171 // 172 // WARNING: |digest| must be the output of some hash function on the data to be 173 // verified. Passing unhashed inputs will not result in a secure signature 174 // scheme. 175 OPENSSL_EXPORT int ECDSA_verify_p1363(const uint8_t *digest, size_t digest_len, 176 const uint8_t *sig, size_t sig_len, 177 const EC_KEY *key); 178 179 // ECDSA_size_p1363 returns the size of a P1363-based ECDSA signature using 180 // |key|. It returns zero if |key| is NULL or if it doesn't have a group set. 181 OPENSSL_EXPORT size_t ECDSA_size_p1363(const EC_KEY *key); 182 183 184 // Testing-only functions. 185 186 // ECDSA_sign_with_nonce_and_leak_private_key_for_testing behaves like 187 // |ECDSA_do_sign| but uses |nonce| for the ECDSA nonce 'k', instead of a random 188 // value. |nonce| is interpreted as a big-endian integer. It must be reduced 189 // modulo the group order and padded with zeros up to |BN_num_bytes(order)| 190 // bytes. 191 // 192 // WARNING: This function is only exported for testing purposes, when using test 193 // vectors or fuzzing strategies. It must not be used outside tests and may leak 194 // any private keys it is used with. 195 OPENSSL_EXPORT ECDSA_SIG * 196 ECDSA_sign_with_nonce_and_leak_private_key_for_testing(const uint8_t *digest, 197 size_t digest_len, 198 const EC_KEY *eckey, 199 const uint8_t *nonce, 200 size_t nonce_len); 201 202 203 // Deprecated functions. 204 205 // d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from |len| 206 // bytes at |*inp|, as described in |d2i_SAMPLE|. 207 // 208 // Use |ECDSA_SIG_parse| instead. 209 OPENSSL_EXPORT ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **out, const uint8_t **inp, 210 long len); 211 212 // i2d_ECDSA_SIG marshals |sig| as a DER-encoded ECDSA-Sig-Value, as described 213 // in |i2d_SAMPLE|. 214 // 215 // Use |ECDSA_SIG_marshal| instead. 216 OPENSSL_EXPORT int i2d_ECDSA_SIG(const ECDSA_SIG *sig, uint8_t **outp); 217 218 219 #if defined(__cplusplus) 220 } // extern C 221 222 extern "C++" { 223 224 BSSL_NAMESPACE_BEGIN 225 226 BORINGSSL_MAKE_DELETER(ECDSA_SIG, ECDSA_SIG_free) 227 228 BSSL_NAMESPACE_END 229 230 } // extern C++ 231 232 #endif 233 234 #define ECDSA_R_BAD_SIGNATURE 100 235 #define ECDSA_R_MISSING_PARAMETERS 101 236 #define ECDSA_R_NEED_NEW_SETUP_VALUES 102 237 #define ECDSA_R_NOT_IMPLEMENTED 103 238 #define ECDSA_R_RANDOM_NUMBER_GENERATION_FAILED 104 239 #define ECDSA_R_ENCODE_ERROR 105 240 #define ECDSA_R_TOO_MANY_ITERATIONS 106 241 242 #endif // OPENSSL_HEADER_ECDSA_H