blob: 259cf44b35ac9bdaa5fe5465761a103de08dfb31 [file] [log] [blame]
Jarno Lamsa18987a42019-04-24 15:40:43 +03001/* ecc_dh.h - TinyCrypt interface to EC-DSA implementation */
2
3/*
Simon Butcher92c3d1f2019-09-09 17:25:08 +01004 * Copyright (c) 2019, Arm Limited (or its affiliates), All Rights Reserved.
5 * SPDX-License-Identifier: BSD-3-Clause
6 */
7
8/*
Jarno Lamsa18987a42019-04-24 15:40:43 +03009 * Copyright (c) 2014, Kenneth MacKay
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * * Redistributions of source code must retain the above copyright notice, this
16 * list of conditions and the following disclaimer.
17 *
18 * * Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 */
34
35/*
36 * Copyright (C) 2017 by Intel Corporation, All Rights Reserved.
37 *
38 * Redistribution and use in source and binary forms, with or without
39 * modification, are permitted provided that the following conditions are met:
40 *
41 * - Redistributions of source code must retain the above copyright notice,
42 * this list of conditions and the following disclaimer.
43 *
44 * - Redistributions in binary form must reproduce the above copyright
45 * notice, this list of conditions and the following disclaimer in the
46 * documentation and/or other materials provided with the distribution.
47 *
48 * - Neither the name of Intel Corporation nor the names of its contributors
49 * may be used to endorse or promote products derived from this software
50 * without specific prior written permission.
51 *
52 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
53 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
54 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
55 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
56 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
57 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
58 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
59 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
60 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
61 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
62 * POSSIBILITY OF SUCH DAMAGE.
63 */
64
65/**
66 * @file
67 * @brief -- Interface to EC-DSA implementation.
68 *
69 * Overview: This software is an implementation of EC-DSA. This implementation
70 * uses curve NIST p-256.
71 *
72 * Security: The curve NIST p-256 provides approximately 128 bits of security.
73 *
74 * Usage: - To sign: Compute a hash of the data you wish to sign (SHA-2 is
75 * recommended) and pass it in to ecdsa_sign function along with your
76 * private key and a random number. You must use a new non-predictable
77 * random number to generate each new signature.
78 * - To verify a signature: Compute the hash of the signed data using
79 * the same hash as the signer and pass it to this function along with
80 * the signer's public key and the signature values (r and s).
81 */
82
Manuel Pégourié-Gonnardafdc1b52019-05-09 11:24:11 +020083#if defined(MBEDTLS_USE_TINYCRYPT)
Jarno Lamsa18987a42019-04-24 15:40:43 +030084#ifndef __TC_ECC_DSA_H__
85#define __TC_ECC_DSA_H__
86
87#include <tinycrypt/ecc.h>
88
89#ifdef __cplusplus
90extern "C" {
91#endif
92
93/**
94 * @brief Generate an ECDSA signature for a given hash value.
Manuel Pégourié-Gonnard9d6a5352019-11-25 13:06:05 +010095 * @return UECC_SUCCESS or UECC_FAILURE or UECC_FAULT_DETECTED
Jarno Lamsa18987a42019-04-24 15:40:43 +030096 *
97 * @param p_private_key IN -- Your private key.
98 * @param p_message_hash IN -- The hash of the message to sign.
99 * @param p_hash_size IN -- The size of p_message_hash in bytes.
100 * @param p_signature OUT -- Will be filled in with the signature value. Must be
101 * at least 2 * curve size long (for secp256r1, signature must be 64 bytes long).
102 *
103 * @warning A cryptographically-secure PRNG function must be set (using
104 * uECC_set_rng()) before calling uECC_sign().
105 * @note Usage: Compute a hash of the data you wish to sign (SHA-2 is
106 * recommended) and pass it in to this function along with your private key.
107 * @note side-channel countermeasure: algorithm strengthened against timing
108 * attack.
109 */
110int uECC_sign(const uint8_t *p_private_key, const uint8_t *p_message_hash,
Manuel Pégourié-Gonnard1a533712019-11-21 12:00:43 +0100111 unsigned p_hash_size, uint8_t *p_signature);
Jarno Lamsa18987a42019-04-24 15:40:43 +0300112
113#ifdef ENABLE_TESTS
114/*
115 * THIS FUNCTION SHOULD BE CALLED FOR TEST PURPOSES ONLY.
116 * Refer to uECC_sign() function for real applications.
117 */
118int uECC_sign_with_k(const uint8_t *private_key, const uint8_t *message_hash,
Manuel Pégourié-Gonnard1a533712019-11-21 12:00:43 +0100119 unsigned int hash_size, uECC_word_t *k, uint8_t *signature)
Jarno Lamsa18987a42019-04-24 15:40:43 +0300120#endif
121
122/**
123 * @brief Verify an ECDSA signature.
Manuel Pégourié-Gonnard10d8e8e2019-11-06 10:30:26 +0100124 * @return returns UECC_SUCCESS if the signature is valid
125 * returns UECC_FAILURE if the signature is invalid.
Jarno Lamsa18987a42019-04-24 15:40:43 +0300126 *
127 * @param p_public_key IN -- The signer's public key.
128 * @param p_message_hash IN -- The hash of the signed data.
129 * @param p_hash_size IN -- The size of p_message_hash in bytes.
130 * @param p_signature IN -- The signature values.
131 *
132 * @note Usage: Compute the hash of the signed data using the same hash as the
133 * signer and pass it to this function along with the signer's public key and
134 * the signature values (hash_size and signature).
135 */
136int uECC_verify(const uint8_t *p_public_key, const uint8_t *p_message_hash,
Manuel Pégourié-Gonnard1a533712019-11-21 12:00:43 +0100137 unsigned int p_hash_size, const uint8_t *p_signature);
Jarno Lamsa18987a42019-04-24 15:40:43 +0300138
139#ifdef __cplusplus
140}
141#endif
142
143#endif /* __TC_ECC_DSA_H__ */
Manuel Pégourié-Gonnardafdc1b52019-05-09 11:24:11 +0200144#endif /* MBEDTLS_USE_TINYCRYPT */