dhm.h

00001 /**
00002  * \file dhm.h
00003  *
00004  * \brief Diffie-Hellman-Merkle key exchange
00005  *
00006  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00007  *  SPDX-License-Identifier: Apache-2.0
00008  *
00009  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  *  not use this file except in compliance with the License.
00011  *  You may obtain a copy of the License at
00012  *
00013  *  http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  *  Unless required by applicable law or agreed to in writing, software
00016  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  *  See the License for the specific language governing permissions and
00019  *  limitations under the License.
00020  *
00021  *  This file is part of mbed TLS (https://tls.mbed.org)
00022  */
00023 #ifndef MBEDTLS_DHM_H
00024 #define MBEDTLS_DHM_H
00025 
00026 #include "bignum.h"
00027 
00028 /*
00029  * DHM Error codes
00030  */
00031 #define MBEDTLS_ERR_DHM_BAD_INPUT_DATA                    -0x3080  /**< Bad input parameters to function. */
00032 #define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED                -0x3100  /**< Reading of the DHM parameters failed. */
00033 #define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED                -0x3180  /**< Making of the DHM parameters failed. */
00034 #define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED                -0x3200  /**< Reading of the public values failed. */
00035 #define MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED                -0x3280  /**< Making of the public value failed. */
00036 #define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED                -0x3300  /**< Calculation of the DHM secret failed. */
00037 #define MBEDTLS_ERR_DHM_INVALID_FORMAT                    -0x3380  /**< The ASN.1 data is not formatted correctly. */
00038 #define MBEDTLS_ERR_DHM_ALLOC_FAILED                      -0x3400  /**< Allocation of memory failed. */
00039 #define MBEDTLS_ERR_DHM_FILE_IO_ERROR                     -0x3480  /**< Read/write of file failed. */
00040 
00041 /**
00042  * RFC 3526 defines a number of standardized Diffie-Hellman groups
00043  * for IKE.
00044  * RFC 5114 defines a number of standardized Diffie-Hellman groups
00045  * that can be used.
00046  *
00047  * Some are included here for convenience.
00048  *
00049  * Included are:
00050  *  RFC 3526 3.    2048-bit MODP Group
00051  *  RFC 3526 4.    3072-bit MODP Group
00052  *  RFC 3526 5.    4096-bit MODP Group
00053  *  RFC 5114 2.2.  2048-bit MODP Group with 224-bit Prime Order Subgroup
00054  */
00055 #define MBEDTLS_DHM_RFC3526_MODP_2048_P               \
00056     "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
00057     "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
00058     "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
00059     "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
00060     "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
00061     "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
00062     "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
00063     "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
00064     "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
00065     "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
00066     "15728E5A8AACAA68FFFFFFFFFFFFFFFF"
00067 
00068 #define MBEDTLS_DHM_RFC3526_MODP_2048_G          "02"
00069 
00070 #define MBEDTLS_DHM_RFC3526_MODP_3072_P               \
00071     "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
00072     "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
00073     "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
00074     "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
00075     "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
00076     "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
00077     "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
00078     "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
00079     "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
00080     "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
00081     "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
00082     "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
00083     "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
00084     "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
00085     "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
00086     "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF"
00087 
00088 #define MBEDTLS_DHM_RFC3526_MODP_3072_G          "02"
00089 
00090 #define MBEDTLS_DHM_RFC3526_MODP_4096_P                \
00091     "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
00092     "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
00093     "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
00094     "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
00095     "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
00096     "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
00097     "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
00098     "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
00099     "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
00100     "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
00101     "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
00102     "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
00103     "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
00104     "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
00105     "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
00106     "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7" \
00107     "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA" \
00108     "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6" \
00109     "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED" \
00110     "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9" \
00111     "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \
00112     "FFFFFFFFFFFFFFFF"
00113 
00114 #define MBEDTLS_DHM_RFC3526_MODP_4096_G          "02"
00115 
00116 #define MBEDTLS_DHM_RFC5114_MODP_2048_P               \
00117     "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
00118     "B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \
00119     "EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \
00120     "9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \
00121     "C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \
00122     "B3BF8A317091883681286130BC8985DB1602E714415D9330" \
00123     "278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \
00124     "CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \
00125     "BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \
00126     "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
00127     "CF9DE5384E71B81C0AC4DFFE0C10E64F"
00128 
00129 #define MBEDTLS_DHM_RFC5114_MODP_2048_G              \
00130     "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF"\
00131     "74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA"\
00132     "AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7"\
00133     "C17669101999024AF4D027275AC1348BB8A762D0521BC98A"\
00134     "E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE"\
00135     "F180EB34118E98D119529A45D6F834566E3025E316A330EF"\
00136     "BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB"\
00137     "10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381"\
00138     "B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269"\
00139     "EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179"\
00140     "81BC087F2A7065B384B890D3191F2BFA"
00141 
00142 #ifdef __cplusplus
00143 extern "C" {
00144 #endif
00145 
00146 /**
00147  * \brief          DHM context structure
00148  */
00149 typedef struct
00150 {
00151     size_t len ; /*!<  size(P) in chars  */
00152     mbedtls_mpi P ;      /*!<  prime modulus     */
00153     mbedtls_mpi G ;      /*!<  generator         */
00154     mbedtls_mpi X ;      /*!<  secret value      */
00155     mbedtls_mpi GX ;     /*!<  self = G^X mod P  */
00156     mbedtls_mpi GY ;     /*!<  peer = G^Y mod P  */
00157     mbedtls_mpi K ;      /*!<  key = GY^X mod P  */
00158     mbedtls_mpi RP ;     /*!<  cached R^2 mod P  */
00159     mbedtls_mpi Vi ;     /*!<  blinding value    */
00160     mbedtls_mpi Vf ;     /*!<  un-blinding value */
00161     mbedtls_mpi pX ;     /*!<  previous X        */
00162 }
00163 mbedtls_dhm_context;
00164 
00165 /**
00166  * \brief          Initialize DHM context
00167  *
00168  * \param ctx      DHM context to be initialized
00169  */
00170 void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
00171 
00172 /**
00173  * \brief          Parse the ServerKeyExchange parameters
00174  *
00175  * \param ctx      DHM context
00176  * \param p        &(start of input buffer)
00177  * \param end      end of buffer
00178  *
00179  * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
00180  */
00181 int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
00182                      unsigned char **p,
00183                      const unsigned char *end );
00184 
00185 /**
00186  * \brief          Setup and write the ServerKeyExchange parameters
00187  *
00188  * \param ctx      DHM context
00189  * \param x_size   private value size in bytes
00190  * \param output   destination buffer
00191  * \param olen     number of chars written
00192  * \param f_rng    RNG function
00193  * \param p_rng    RNG parameter
00194  *
00195  * \note           This function assumes that ctx->P and ctx->G
00196  *                 have already been properly set (for example
00197  *                 using mbedtls_mpi_read_string or mbedtls_mpi_read_binary).
00198  *
00199  * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
00200  */
00201 int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
00202                      unsigned char *output, size_t *olen,
00203                      int (*f_rng)(void *, unsigned char *, size_t),
00204                      void *p_rng );
00205 
00206 /**
00207  * \brief          Import the peer's public value G^Y
00208  *
00209  * \param ctx      DHM context
00210  * \param input    input buffer
00211  * \param ilen     size of buffer
00212  *
00213  * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
00214  */
00215 int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
00216                      const unsigned char *input, size_t ilen );
00217 
00218 /**
00219  * \brief          Create own private value X and export G^X
00220  *
00221  * \param ctx      DHM context
00222  * \param x_size   private value size in bytes
00223  * \param output   destination buffer
00224  * \param olen     must be at least equal to the size of P, ctx->len
00225  * \param f_rng    RNG function
00226  * \param p_rng    RNG parameter
00227  *
00228  * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
00229  */
00230 int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
00231                      unsigned char *output, size_t olen,
00232                      int (*f_rng)(void *, unsigned char *, size_t),
00233                      void *p_rng );
00234 
00235 /**
00236  * \brief          Derive and export the shared secret (G^Y)^X mod P
00237  *
00238  * \param ctx      DHM context
00239  * \param output   destination buffer
00240  * \param output_size   size of the destination buffer
00241  * \param olen     on exit, holds the actual number of bytes written
00242  * \param f_rng    RNG function, for blinding purposes
00243  * \param p_rng    RNG parameter
00244  *
00245  * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
00246  *
00247  * \note           If non-NULL, f_rng is used to blind the input as
00248  *                 countermeasure against timing attacks. Blinding is
00249  *                 automatically used if and only if our secret value X is
00250  *                 re-used and costs nothing otherwise, so it is recommended
00251  *                 to always pass a non-NULL f_rng argument.
00252  */
00253 int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
00254                      unsigned char *output, size_t output_size, size_t *olen,
00255                      int (*f_rng)(void *, unsigned char *, size_t),
00256                      void *p_rng );
00257 
00258 /**
00259  * \brief          Free and clear the components of a DHM key
00260  *
00261  * \param ctx      DHM context to free and clear
00262  */
00263 void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
00264 
00265 #if defined(MBEDTLS_ASN1_PARSE_C)
00266 /** \ingroup x509_module */
00267 /**
00268  * \brief          Parse DHM parameters in PEM or DER format
00269  *
00270  * \param dhm      DHM context to be initialized
00271  * \param dhmin    input buffer
00272  * \param dhminlen size of the buffer
00273  *                 (including the terminating null byte for PEM data)
00274  *
00275  * \return         0 if successful, or a specific DHM or PEM error code
00276  */
00277 int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
00278                    size_t dhminlen );
00279 
00280 #if defined(MBEDTLS_FS_IO)
00281 /** \ingroup x509_module */
00282 /**
00283  * \brief          Load and parse DHM parameters
00284  *
00285  * \param dhm      DHM context to be initialized
00286  * \param path     filename to read the DHM Parameters from
00287  *
00288  * \return         0 if successful, or a specific DHM or PEM error code
00289  */
00290 int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
00291 #endif /* MBEDTLS_FS_IO */
00292 #endif /* MBEDTLS_ASN1_PARSE_C */
00293 
00294 /**
00295  * \brief          Checkup routine
00296  *
00297  * \return         0 if successful, or 1 if the test failed
00298  */
00299 int mbedtls_dhm_self_test( int verbose );
00300 
00301 #ifdef __cplusplus
00302 }
00303 #endif
00304 
00305 #endif /* dhm.h */