1 /*
2  * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 /*!
8  @addtogroup eddsa
9  @{
10  */
11 
12 /*!
13  @file
14 
15  @brief This file contains the CryptoCell EDDSA Edwards curve APIs.
16 
17  This API supports EDDSA Edwards for generating, signing and verifying keys.
18  This is implemented based on <em>Ed25519: High-speed high-security
19  signatures</em>.
20  */
21 
22 #ifndef _MBEDTLS_ECDSA_EDWARDS_H
23 #define _MBEDTLS_ECDSA_EDWARDS_H
24 
25 
26 #include "cc_pal_types.h"
27 #include "cc_error.h"
28 
29 #ifdef __cplusplus
30 extern "C"
31 {
32 #endif
33 
34 
35 /*************************** Defines *****************************************/
36 
37 /*************************** Typedefs  ***************************************/
38 
39 /*************************** Enums *******************************************/
40 
41 /*************************** Structs  ****************************************/
42 
43 /*************************** context Structs  ********************************/
44 
45 /*!
46  @brief This function generates an EDDSA keypair on the Edwards 25519 curve.
47 
48  @return    \c 0 on success.
49  @return    An \c MBEDTLS_ERR_ECP_XXX code on failure.
50  */
51 int mbedtls_ecdsa_genkey_edwards(
52         /*! The EDDSA context to store the keypair in. */
53         mbedtls_ecdsa_context *ctx,
54         /*! The elliptic curve to use. Currently only 25519 curve is
55         supported. */
56         mbedtls_ecp_group_id gid,
57         /*! The RNG function. */
58         int (*f_rng)(void *, unsigned char *, size_t),
59         /*! The RNG context. */
60         void *p_rng
61         );
62 
63 /*!
64    @brief           This function computes the EDDSA signature of a
65                     previously-hashed message.
66 
67    @note            If the bitlength of the message hash is larger than the
68                     bitlength of the group order, then the hash is truncated
69                     as defined in <em>Standards for Efficient Cryptography Group
70                     (SECG): SEC1 Elliptic Curve Cryptography</em>, section
71                     4.1.3, step 5.
72 
73    @return          \c 0 on success.
74    @return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
75                     on failure.
76  */
77 int mbedtls_ecdsa_sign_edwards(
78             /*! The ECP group. */
79             mbedtls_ecp_group *grp,
80             /*! The first output integer. */
81             mbedtls_mpi *r,
82             /*! The second output integer. */
83             mbedtls_mpi *s,
84             /*! The private signing key. */
85             const mbedtls_mpi *d,
86             /*! The message hash. */
87             const unsigned char *buf,
88             /*! The length of \p buf. */
89             size_t blen
90             );
91 
92 
93 /*!
94    @brief           This function verifies the EDDSA signature of a
95                     previously-hashed message.
96 
97    @note            If the bitlength of the message hash is larger than the
98                     bitlength of the group order, then the hash is truncated as
99                     defined in <em>Standards for Efficient Cryptography Group
100                     (SECG): SEC1 Elliptic Curve Cryptography</em>, section
101                     4.1.4, step 3.
102 
103    @return          \c 0 on success.
104    @return          \c MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
105    @return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
106                     error code on failure for any other reason.
107   */
108 int mbedtls_ecdsa_verify_edwards(
109             /*! The ECP group. */
110             mbedtls_ecp_group *grp,
111             /*!The message hash . */
112             const unsigned char *buf,
113             /*! The length of \p buf. */
114             size_t blen,
115             /*! The public key to use for verification. */
116             const mbedtls_ecp_point *Q,
117             /*! The first integer of the signature. */
118             const mbedtls_mpi *r,
119             /*! The second integer of the signature. */
120             const mbedtls_mpi *s
121             );
122 
123 /**
124    @brief           This function imports an EC Edwards public key.
125 
126    @return          \c 0 on success.
127    @return          \c MBEDTLS_ERR_ECP_BAD_INPUT_DATA
128                     or \c MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE on failure.
129  */
130 int mbedtls_ecdsa_public_key_read_edwards(
131             /*! [out] The public key to import. */
132             mbedtls_ecp_point *Q,
133             /*! [in] The buffer to read the public key from. */
134             unsigned char *buf,
135             /*! [in] The length of the buffer in bytes. */
136             size_t blen
137             );
138 
139 /**
140    @brief           This function exports an EC Edwards public key.
141 
142    @return          \c 0 on success.
143    @return          \c MBEDTLS_ERR_ECP_BAD_INPUT_DATA
144                     or \c MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
145  */
146 int mbedtls_ecdsa_public_key_write_edwards(
147             /*! [in] The public key to export. */
148             const mbedtls_ecp_point *Q,
149             /*! [out] The length of the data written in bytes. */
150             size_t *olen,
151             /*! [out] The buffer to write the public key to. */
152             unsigned char *buf,
153             /*! [in] The length of the buffer in bytes. */
154             size_t blen
155             );
156 
157 
158  #ifdef __cplusplus
159 }
160 #endif
161 
162 /*!
163  @}
164  */
165 #endif /* _MBEDTLS_ECDSA_EDWARDS_H */
166 
167