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