Diff: include/mbedtls/ecdsa.h

Revision:

0:cdf462088d13

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/include/mbedtls/ecdsa.h	Thu Jan 05 00:18:44 2017 +0000
@@ -0,0 +1,248 @@
+/**
+ * \file ecdsa.h
+ *
+ * \brief Elliptic curve DSA
+ *
+ *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  This file is part of mbed TLS (https://tls.mbed.org)
+ */
+#ifndef MBEDTLS_ECDSA_H
+#define MBEDTLS_ECDSA_H
+
+#include "ecp.h"
+#include "md.h"
+
+/*
+ * RFC 4492 page 20:
+ *
+ *     Ecdsa-Sig-Value ::= SEQUENCE {
+ *         r       INTEGER,
+ *         s       INTEGER
+ *     }
+ *
+ * Size is at most
+ *    1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
+ *    twice that + 1 (tag) + 2 (len) for the sequence
+ * (assuming ECP_MAX_BYTES is less than 126 for r and s,
+ * and less than 124 (total len <= 255) for the sequence)
+ */
+#if MBEDTLS_ECP_MAX_BYTES > 124
+#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
+#endif
+/** Maximum size of an ECDSA signature in bytes */
+#define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
+
+/**
+ * \brief           ECDSA context structure
+ */
+typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief           Compute ECDSA signature of a previously hashed message
+ *
+ * \note            The deterministic version is usually prefered.
+ *
+ * \param grp       ECP group
+ * \param r         First output integer
+ * \param s         Second output integer
+ * \param d         Private signing key
+ * \param buf       Message hash
+ * \param blen      Length of buf
+ * \param f_rng     RNG function
+ * \param p_rng     RNG parameter
+ *
+ * \return          0 if successful,
+ *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ */
+int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
+                const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
+                int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
+
+#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
+/**
+ * \brief           Compute ECDSA signature of a previously hashed message,
+ *                  deterministic version (RFC 6979).
+ *
+ * \param grp       ECP group
+ * \param r         First output integer
+ * \param s         Second output integer
+ * \param d         Private signing key
+ * \param buf       Message hash
+ * \param blen      Length of buf
+ * \param md_alg    MD algorithm used to hash the message
+ *
+ * \return          0 if successful,
+ *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ */
+int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
+                    const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
+                    mbedtls_md_type_t md_alg );
+#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
+
+/**
+ * \brief           Verify ECDSA signature of a previously hashed message
+ *
+ * \param grp       ECP group
+ * \param buf       Message hash
+ * \param blen      Length of buf
+ * \param Q         Public key to use for verification
+ * \param r         First integer of the signature
+ * \param s         Second integer of the signature
+ *
+ * \return          0 if successful,
+ *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid
+ *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ */
+int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
+                  const unsigned char *buf, size_t blen,
+                  const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
+
+/**
+ * \brief           Compute ECDSA signature and write it to buffer,
+ *                  serialized as defined in RFC 4492 page 20.
+ *                  (Not thread-safe to use same context in multiple threads)
+ *
+ * \note            The deterministice version (RFC 6979) is used if
+ *                  MBEDTLS_ECDSA_DETERMINISTIC is defined.
+ *
+ * \param ctx       ECDSA context
+ * \param md_alg    Algorithm that was used to hash the message
+ * \param hash      Message hash
+ * \param hlen      Length of hash
+ * \param sig       Buffer that will hold the signature
+ * \param slen      Length of the signature written
+ * \param f_rng     RNG function
+ * \param p_rng     RNG parameter
+ *
+ * \note            The "sig" buffer must be at least as large as twice the
+ *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
+ *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
+ *
+ * \return          0 if successful,
+ *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
+ *                  MBEDTLS_ERR_ASN1_XXX error code
+ */
+int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
+                           const unsigned char *hash, size_t hlen,
+                           unsigned char *sig, size_t *slen,
+                           int (*f_rng)(void *, unsigned char *, size_t),
+                           void *p_rng );
+
+#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
+#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED    __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief           Compute ECDSA signature and write it to buffer,
+ *                  serialized as defined in RFC 4492 page 20.
+ *                  Deterministic version, RFC 6979.
+ *                  (Not thread-safe to use same context in multiple threads)
+ *
+ * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
+ *
+ * \param ctx       ECDSA context
+ * \param hash      Message hash
+ * \param hlen      Length of hash
+ * \param sig       Buffer that will hold the signature
+ * \param slen      Length of the signature written
+ * \param md_alg    MD algorithm used to hash the message
+ *
+ * \note            The "sig" buffer must be at least as large as twice the
+ *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
+ *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
+ *
+ * \return          0 if successful,
+ *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
+ *                  MBEDTLS_ERR_ASN1_XXX error code
+ */
+int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
+                               const unsigned char *hash, size_t hlen,
+                               unsigned char *sig, size_t *slen,
+                               mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
+#undef MBEDTLS_DEPRECATED
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
+
+/**
+ * \brief           Read and verify an ECDSA signature
+ *
+ * \param ctx       ECDSA context
+ * \param hash      Message hash
+ * \param hlen      Size of hash
+ * \param sig       Signature to read and verify
+ * \param slen      Size of sig
+ *
+ * \return          0 if successful,
+ *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
+ *                  MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
+ *                  valid but its actual length is less than siglen,
+ *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code
+ */
+int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
+                          const unsigned char *hash, size_t hlen,
+                          const unsigned char *sig, size_t slen );
+
+/**
+ * \brief           Generate an ECDSA keypair on the given curve
+ *
+ * \param ctx       ECDSA context in which the keypair should be stored
+ * \param gid       Group (elliptic curve) to use. One of the various
+ *                  MBEDTLS_ECP_DP_XXX macros depending on configuration.
+ * \param f_rng     RNG function
+ * \param p_rng     RNG parameter
+ *
+ * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ */
+int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
+                  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
+
+/**
+ * \brief           Set an ECDSA context from an EC key pair
+ *
+ * \param ctx       ECDSA context to set
+ * \param key       EC key to use
+ *
+ * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ */
+int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
+
+/**
+ * \brief           Initialize context
+ *
+ * \param ctx       Context to initialize
+ */
+void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
+
+/**
+ * \brief           Free context
+ *
+ * \param ctx       Context to free
+ */
+void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ecdsa.h */