include/tropicssl/dhm.h

   1 /**
   2  * \file dhm.h
   3  *
   4  *  Based on XySSL: Copyright (C) 2006-2008  Christophe Devine
   5  *
   6  *  Copyright (C) 2009  Paul Bakker <polarssl_maintainer at polarssl dot org>
   7  *
   8  *  All rights reserved.
   9  *
  10  *  Redistribution and use in source and binary forms, with or without
  11  *  modification, are permitted provided that the following conditions
  12  *  are met:
  13  *
  14  *    * Redistributions of source code must retain the above copyright
  15  *      notice, this list of conditions and the following disclaimer.
  16  *    * Redistributions in binary form must reproduce the above copyright
  17  *      notice, this list of conditions and the following disclaimer in the
  18  *      documentation and/or other materials provided with the distribution.
  19  *    * Neither the names of PolarSSL or XySSL nor the names of its contributors
  20  *      may be used to endorse or promote products derived from this software
  21  *      without specific prior written permission.
  22  *
  23  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  26  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  *  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35 #ifndef TROPICSSL_DHM_H
  36 #define TROPICSSL_DHM_H
  37
  38 #include "tropicssl/bignum.h"
  39
  40 #define TROPICSSL_ERR_DHM_BAD_INPUT_DATA                    -0x0480
  41 #define TROPICSSL_ERR_DHM_READ_PARAMS_FAILED                -0x0490
  42 #define TROPICSSL_ERR_DHM_MAKE_PARAMS_FAILED                -0x04A0
  43 #define TROPICSSL_ERR_DHM_READ_PUBLIC_FAILED                -0x04B0
  44 #define TROPICSSL_ERR_DHM_MAKE_PUBLIC_FAILED                -0x04C0
  45 #define TROPICSSL_ERR_DHM_CALC_SECRET_FAILED                -0x04D0
  46
  47 typedef struct {
  48         int len;                /*!<  size(P) in chars  */
  49         mpi P;                  /*!<  prime modulus     */
  50         mpi G;                  /*!<  generator         */
  51         mpi X;                  /*!<  secret value      */
  52         mpi GX;                 /*!<  self = G^X mod P  */
  53         mpi GY;                 /*!<  peer = G^Y mod P  */
  54         mpi K;                  /*!<  key = GY^X mod P  */
  55         mpi RP;                 /*!<  cached R^2 mod P  */
  56 } dhm_context;
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62         /**
  63          * \brief          Parse the ServerKeyExchange parameters
  64          *
  65          * \param ctx      DHM context
  66          * \param p        &(start of input buffer)
  67          * \param end      end of buffer
  68          *
  69          * \return         0 if successful, or an TROPICSSL_ERR_DHM_XXX error code
  70          */
  71         int dhm_read_params(dhm_context * ctx,
  72                             unsigned char **p,
  73                             const unsigned char *end);
  74
  75         /**
  76          * \brief          Setup and write the ServerKeyExchange parameters
  77          *
  78          * \param ctx      DHM context
  79          * \param x_size   private value size in bits
  80          * \param output   destination buffer
  81          * \param olen     number of chars written
  82          * \param f_rng    RNG function
  83          * \param p_rng    RNG parameter
  84          *
  85          * \note           This function assumes that ctx->P and ctx->G
  86          *                 have already been properly set (for example
  87          *                 using mpi_read_string or mpi_read_binary).
  88          *
  89          * \return         0 if successful, or an TROPICSSL_ERR_DHM_XXX error code
  90          */
  91         int dhm_make_params(dhm_context * ctx, int s_size,
  92                             unsigned char *output, int *olen,
  93                             int (*f_rng) (void *), void *p_rng);
  94
  95         /**
  96          * \brief          Import the peer's public value G^Y
  97          *
  98          * \param ctx      DHM context
  99          * \param input    input buffer
 100          * \param ilen     size of buffer
 101          *
 102          * \return         0 if successful, or an TROPICSSL_ERR_DHM_XXX error code
 103          */
 104         int dhm_read_public(dhm_context * ctx,
 105                             const unsigned char *input, int ilen);
 106
 107         /**
 108          * \brief          Create own private value X and export G^X
 109          *
 110          * \param ctx      DHM context
 111          * \param x_size   private value size in bits
 112          * \param output   destination buffer
 113          * \param olen     must be equal to ctx->P.len
 114          * \param f_rng    RNG function
 115          * \param p_rng    RNG parameter
 116          *
 117          * \return         0 if successful, or an TROPICSSL_ERR_DHM_XXX error code
 118          */
 119         int dhm_make_public(dhm_context * ctx, int s_size,
 120                             unsigned char *output, int olen,
 121                             int (*f_rng) (void *), void *p_rng);
 122
 123         /**
 124          * \brief          Derive and export the shared secret (G^Y)^X mod P
 125          *
 126          * \param ctx      DHM context
 127          * \param output   destination buffer
 128          * \param olen     number of chars written
 129          *
 130          * \return         0 if successful, or an TROPICSSL_ERR_DHM_XXX error code
 131          */
 132         int dhm_calc_secret(dhm_context * ctx,
 133                             unsigned char *output, int *olen);
 134
 135         /*
 136          * \brief          Free the components of a DHM key
 137          */
 138         void dhm_free(dhm_context * ctx);
 139
 140         /**
 141          * \brief          Checkup routine
 142          *
 143          * \return         0 if successful, or 1 if the test failed
 144          */
 145         int dhm_self_test(int verbose);
 146
 147 #ifdef __cplusplus
 148 }
 149 #endif
 150 #endif