reactos/include/reactos/libs/mbedtls/ecdh.h

   1 /**
   2  * \file ecdh.h
   3  *
   4  * \brief Elliptic curve Diffie-Hellman
   5  *
   6  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
   7  *  SPDX-License-Identifier: Apache-2.0
   8  *
   9  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  10  *  not use this file except in compliance with the License.
  11  *  You may obtain a copy of the License at
  12  *
  13  *  http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  *  Unless required by applicable law or agreed to in writing, software
  16  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  17  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  *  See the License for the specific language governing permissions and
  19  *  limitations under the License.
  20  *
  21  *  This file is part of mbed TLS (https://tls.mbed.org)
  22  */
  23 #ifndef MBEDTLS_ECDH_H
  24 #define MBEDTLS_ECDH_H
  25
  26 #include "ecp.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * When importing from an EC key, select if it is our key or the peer's key
  34  */
  35 typedef enum
  36 {
  37     MBEDTLS_ECDH_OURS,
  38     MBEDTLS_ECDH_THEIRS,
  39 } mbedtls_ecdh_side;
  40
  41 /**
  42  * \brief           ECDH context structure
  43  */
  44 typedef struct
  45 {
  46     mbedtls_ecp_group grp;      /*!<  elliptic curve used                           */
  47     mbedtls_mpi d;              /*!<  our secret value (private key)                */
  48     mbedtls_ecp_point Q;        /*!<  our public value (public key)                 */
  49     mbedtls_ecp_point Qp;       /*!<  peer's public value (public key)              */
  50     mbedtls_mpi z;              /*!<  shared secret                                 */
  51     int point_format;   /*!<  format for point export in TLS messages       */
  52     mbedtls_ecp_point Vi;       /*!<  blinding value (for later)                    */
  53     mbedtls_ecp_point Vf;       /*!<  un-blinding value (for later)                 */
  54     mbedtls_mpi _d;             /*!<  previous d (for later)                        */
  55 }
  56 mbedtls_ecdh_context;
  57
  58 /**
  59  * \brief           Generate a public key.
  60  *                  Raw function that only does the core computation.
  61  *
  62  * \param grp       ECP group
  63  * \param d         Destination MPI (secret exponent, aka private key)
  64  * \param Q         Destination point (public key)
  65  * \param f_rng     RNG function
  66  * \param p_rng     RNG parameter
  67  *
  68  * \return          0 if successful,
  69  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  70  */
  71 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
  72                      int (*f_rng)(void *, unsigned char *, size_t),
  73                      void *p_rng );
  74
  75 /**
  76  * \brief           Compute shared secret
  77  *                  Raw function that only does the core computation.
  78  *
  79  * \param grp       ECP group
  80  * \param z         Destination MPI (shared secret)
  81  * \param Q         Public key from other party
  82  * \param d         Our secret exponent (private key)
  83  * \param f_rng     RNG function (see notes)
  84  * \param p_rng     RNG parameter
  85  *
  86  * \return          0 if successful,
  87  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  88  *
  89  * \note            If f_rng is not NULL, it is used to implement
  90  *                  countermeasures against potential elaborate timing
  91  *                  attacks, see \c mbedtls_ecp_mul() for details.
  92  */
  93 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
  94                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
  95                          int (*f_rng)(void *, unsigned char *, size_t),
  96                          void *p_rng );
  97
  98 /**
  99  * \brief           Initialize context
 100  *
 101  * \param ctx       Context to initialize
 102  */
 103 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
 104
 105 /**
 106  * \brief           Free context
 107  *
 108  * \param ctx       Context to free
 109  */
 110 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
 111
 112 /**
 113  * \brief           Generate a public key and a TLS ServerKeyExchange payload.
 114  *                  (First function used by a TLS server for ECDHE.)
 115  *
 116  * \param ctx       ECDH context
 117  * \param olen      number of chars written
 118  * \param buf       destination buffer
 119  * \param blen      length of buffer
 120  * \param f_rng     RNG function
 121  * \param p_rng     RNG parameter
 122  *
 123  * \note            This function assumes that ctx->grp has already been
 124  *                  properly set (for example using mbedtls_ecp_group_load).
 125  *
 126  * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
 127  */
 128 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
 129                       unsigned char *buf, size_t blen,
 130                       int (*f_rng)(void *, unsigned char *, size_t),
 131                       void *p_rng );
 132
 133 /**
 134  * \brief           Parse and procress a TLS ServerKeyExhange payload.
 135  *                  (First function used by a TLS client for ECDHE.)
 136  *
 137  * \param ctx       ECDH context
 138  * \param buf       pointer to start of input buffer
 139  * \param end       one past end of buffer
 140  *
 141  * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
 142  */
 143 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
 144                       const unsigned char **buf, const unsigned char *end );
 145
 146 /**
 147  * \brief           Setup an ECDH context from an EC key.
 148  *                  (Used by clients and servers in place of the
 149  *                  ServerKeyEchange for static ECDH: import ECDH parameters
 150  *                  from a certificate's EC key information.)
 151  *
 152  * \param ctx       ECDH constext to set
 153  * \param key       EC key to use
 154  * \param side      Is it our key (1) or the peer's key (0) ?
 155  *
 156  * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
 157  */
 158 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
 159                      mbedtls_ecdh_side side );
 160
 161 /**
 162  * \brief           Generate a public key and a TLS ClientKeyExchange payload.
 163  *                  (Second function used by a TLS client for ECDH(E).)
 164  *
 165  * \param ctx       ECDH context
 166  * \param olen      number of bytes actually written
 167  * \param buf       destination buffer
 168  * \param blen      size of destination buffer
 169  * \param f_rng     RNG function
 170  * \param p_rng     RNG parameter
 171  *
 172  * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
 173  */
 174 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
 175                       unsigned char *buf, size_t blen,
 176                       int (*f_rng)(void *, unsigned char *, size_t),
 177                       void *p_rng );
 178
 179 /**
 180  * \brief           Parse and process a TLS ClientKeyExchange payload.
 181  *                  (Second function used by a TLS server for ECDH(E).)
 182  *
 183  * \param ctx       ECDH context
 184  * \param buf       start of input buffer
 185  * \param blen      length of input buffer
 186  *
 187  * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
 188  */
 189 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
 190                       const unsigned char *buf, size_t blen );
 191
 192 /**
 193  * \brief           Derive and export the shared secret.
 194  *                  (Last function used by both TLS client en servers.)
 195  *
 196  * \param ctx       ECDH context
 197  * \param olen      number of bytes written
 198  * \param buf       destination buffer
 199  * \param blen      buffer length
 200  * \param f_rng     RNG function, see notes for \c mbedtls_ecdh_compute_shared()
 201  * \param p_rng     RNG parameter
 202  *
 203  * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
 204  */
 205 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
 206                       unsigned char *buf, size_t blen,
 207                       int (*f_rng)(void *, unsigned char *, size_t),
 208                       void *p_rng );
 209
 210 #ifdef __cplusplus
 211 }
 212 #endif
 213
 214 #endif /* ecdh.h */