Source/charon/transforms/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 draft 3.3.2 and RFC 3526.
  37  */
  38 enum diffie_hellman_group_t {
  39         MODP_UNDEFINED = 1024,
  40         MODP_768_BIT = 1,
  41         MODP_1024_BIT = 2,
  42         MODP_1536_BIT = 5,
  43         MODP_2048_BIT = 14,
  44         MODP_3072_BIT = 15,
  45         MODP_4096_BIT = 16,
  46         MODP_6144_BIT = 17,
  47         MODP_8192_BIT = 18
  48 };
  49
  50 /**
  51  * string mappings for diffie_hellman_group_t
  52  */
  53 extern mapping_t diffie_hellman_group_m[];
  54
  55
  56 typedef struct diffie_hellman_t diffie_hellman_t;
  57
  58 /**
  59  * @brief Implementation of the widely used Diffie-Hellman algorithm.
  60  *
  61  * @ingroup transforms
  62  */
  63 struct diffie_hellman_t {
  64
  65         /**
  66          * @brief Returns the shared secret of this diffie hellman exchange.
  67          *
  68          * @warning Space for returned secret is allocated and must be
  69          * freed by the caller.
  70          *
  71          * @param this                  calling diffie_hellman_t object
  72          * @param[out] secret   shared secret will be written into this chunk
  73          * @return
  74          *                                              - SUCCESS, or
  75          *                                              - FAILED if not both DH values are set
  76          *                                              - OUT_OF_RES if out of ressources
  77          */
  78         status_t (*get_shared_secret) (diffie_hellman_t *this, chunk_t *secret);
  79
  80         /**
  81          * @brief Sets the public value of partner.
  82          *
  83          * @warning chunk gets copied
  84          *
  85          * @param this                  calling diffie_hellman_t object
  86          * @param public_value  public value of partner
  87          * @return
  88          *                                              - SUCCESS, or
  89          *                                              - OUT_OF_RES if out of ressources
  90          */
  91         status_t (*set_other_public_value) (diffie_hellman_t *this, chunk_t public_value);
  92
  93         /**
  94          * @brief Gets the public value of partner.
  95          *
  96          * @warning chunk gets copied
  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, or
 102          *                                                      - OUT_OF_RES if out of ressources
 103          *                                                      - FAILED if other public value not set
 104          */
 105         status_t (*get_other_public_value) (diffie_hellman_t *this, chunk_t *public_value);
 106
 107         /**
 108          * @brief Gets the public value of caller
 109          *
 110          * @warning chunk gets copied
 111          *
 112          * @param this                          calling diffie_hellman_t object
 113          * @param[out] public_value public value of caller is stored at this location
 114          * @return
 115          *                                                      - SUCCESS, or
 116          *                                                      - OUT_OF_RES if out of ressources
 117          */
 118         status_t (*get_my_public_value) (diffie_hellman_t *this, chunk_t *public_value);
 119
 120         /**
 121          * @brief Destroys an diffie_hellman_t object.
 122          *
 123          * @param this                          diffie_hellman_t object to destroy
 124          * @return
 125          *                                                      - SUCCESS in any case
 126          */
 127         status_t (*destroy) (diffie_hellman_t *this);
 128 };
 129
 130 /**
 131  * @brief Creates a new diffie_hellman_t object.
 132  *
 133  * The first diffie hellman public value gets automatically created.
 134  *
 135  * @param dh_group_number       Diffie Hellman group number to use
 136  * @return
 137  *                                                      - diffie_hellman_t if successfully
 138  *                                                      - NULL if out of ressources or dh_group not supported
 139  *
 140  * @ingroup transforms
 141  */
 142 diffie_hellman_t *diffie_hellman_create(diffie_hellman_group_t dh_group_number);
 143
 144 #endif /*DIFFIE_HELLMAN_H_*/