programs/charon/lib/crypto/diffie_hellman.h

   1 /**
   2  * @file diffie_hellman.h
   3  *
   4  * @brief Interface of diffie_hellman_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef DIFFIE_HELLMAN_H_
  24 #define DIFFIE_HELLMAN_H_
  25
  26 #include <types.h>
  27
  28
  29 typedef enum diffie_hellman_group_t diffie_hellman_group_t;
  30
  31 /**
  32  * @brief Diffie-Hellman group.
  33  *
  34  * The modulus (or group) to use for a Diffie-Hellman calculation.
  35  *
  36  * See IKEv2 RFC 3.3.2 and RFC 3526.
  37  *
  38  * @ingroup transforms
  39  */
  40 enum diffie_hellman_group_t {
  41         MODP_UNDEFINED = 1024,
  42         MODP_768_BIT = 1,
  43         MODP_1024_BIT = 2,
  44         MODP_1536_BIT = 5,
  45         MODP_2048_BIT = 14,
  46         MODP_3072_BIT = 15,
  47         MODP_4096_BIT = 16,
  48         MODP_6144_BIT = 17,
  49         MODP_8192_BIT = 18
  50 };
  51
  52 /**
  53  * String mappings for diffie_hellman_group_t.
  54  */
  55 extern mapping_t diffie_hellman_group_m[];
  56
  57
  58 typedef struct diffie_hellman_t diffie_hellman_t;
  59
  60 /**
  61  * @brief Implementation of the widely used Diffie-Hellman algorithm.
  62  *
  63  * @b Constructors:
  64  *  - diffie_hellman_create()
  65  *
  66  * @ingroup transforms
  67  */
  68 struct diffie_hellman_t {
  69
  70         /**
  71          * @brief Returns the shared secret of this diffie hellman exchange.
  72          *
  73          * @warning Space for returned secret is allocated and must be
  74          * freed by the caller.
  75          *
  76          * @param this                  calling diffie_hellman_t object
  77          * @param[out] secret   shared secret will be written into this chunk
  78          * @return
  79          *                                              - SUCCESS
  80          *                                              - FAILED if not both DH values are set
  81          */
  82         status_t (*get_shared_secret) (diffie_hellman_t *this, chunk_t *secret);
  83
  84         /**
  85          * @brief Sets the public value of partner.
  86          *
  87          * chunk gets cloned and can be destroyed afterwards.
  88          *
  89          * @param this                  calling diffie_hellman_t object
  90          * @param public_value  public value of partner
  91          */
  92         void (*set_other_public_value) (diffie_hellman_t *this, chunk_t public_value);
  93
  94         /**
  95          * @brief Gets the public value of partner.
  96          *
  97          * @warning Space for returned chunk is allocated and must be
  98          * freed by the caller.
  99          *
 100          * @param this                          calling diffie_hellman_t object
 101          * @param[out] public_value public value of partner is stored at this location
 102          * @return
 103          *                                                      - SUCCESS
 104          *                                                      - FAILED if other public value not set
 105          */
 106         status_t (*get_other_public_value) (diffie_hellman_t *this, chunk_t *public_value);
 107
 108         /**
 109          * @brief Gets the public value of caller
 110          *
 111          * @warning Space for returned chunk is allocated and must be
 112          * freed by the caller.
 113          *
 114          * @param this                          calling diffie_hellman_t object
 115          * @param[out]                          public_value public value of caller is stored at this location
 116          */
 117         void (*get_my_public_value) (diffie_hellman_t *this, chunk_t *public_value);
 118
 119         /**
 120          * @brief Get the DH group used.
 121          *
 122          * @param this                          calling diffie_hellman_t object
 123          * @return                                      DH group set in construction
 124          */
 125         diffie_hellman_group_t (*get_dh_group) (diffie_hellman_t *this);
 126
 127         /**
 128          * @brief Destroys an diffie_hellman_t object.
 129          *
 130          * @param this                          diffie_hellman_t object to destroy
 131          */
 132         void (*destroy) (diffie_hellman_t *this);
 133 };
 134
 135 /**
 136  * @brief Creates a new diffie_hellman_t object.
 137  *
 138  * The first diffie hellman public value gets automatically created.
 139  *
 140  * @param dh_group_number       Diffie Hellman group number to use
 141  * @return
 142  *                                                      - diffie_hellman_t object
 143  *                                                      - NULL if dh group not supported
 144  *
 145  * @ingroup transforms
 146  */
 147 diffie_hellman_t *diffie_hellman_create(diffie_hellman_group_t dh_group_number);
 148
 149 #endif /*DIFFIE_HELLMAN_H_*/