src/include/gnunet_secretsharing_service.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2013 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_secretsharing_service.h
  23  * @brief verified additive secret sharing and cooperative decryption
  24  * @author Florian Dold
  25  */
  26
  27 #ifndef GNUNET_SECRETSHARING_SERVICE_H
  28 #define GNUNET_SECRETSHARING_SERVICE_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 #include "platform.h"
  39 #include "gnunet_common.h"
  40 #include "gnunet_time_lib.h"
  41 #include "gnunet_configuration_lib.h"
  42 #include <gcrypt.h>
  43
  44
  45 /**
  46  * Session that will eventually establish a shared secred between
  47  * the involved peers and allow encryption and cooperative decryption.
  48  */
  49 struct GNUNET_SECRETSHARING_Session;
  50
  51
  52 /**
  53  * Handle to cancel a cooperative decryption operation.
  54  */
  55 struct GNUNET_SECRETSHARING_DecryptionHandle;
  56
  57
  58 /**
  59  * Parameters of the crypto system.
  60  */
  61 struct GNUNET_SECRETSHARING_Parameters
  62 {
  63   /**
  64    * Threshold, that is, minimum number of peers that
  65    * must cooperate to decrypt a value.
  66    */
  67   unsigned int k;
  68   /**
  69    * Prime with p = 2q+1.
  70    */
  71   gcry_mpi_t p;
  72   /**
  73    * Prime.
  74    */
  75   gcry_mpi_t q;
  76   /**
  77    * Generator of G_q.
  78    */
  79   gcry_mpi_t g;
  80 };
  81
  82
  83 /**
  84  * Encrypted field element.
  85  */
  86 struct GNUNET_SECRETSHARING_Ciphertext
  87 {
  88   /**
  89    * First component.
  90    */
  91   gcry_mpi_t c1;
  92   /**
  93    * Second component.
  94    */
  95   gcry_mpi_t c2;
  96 };
  97
  98
  99 /**
 100  * Called once the secret has been established with all peers, or the deadline is due.
 101  *
 102  * Note that the number of peers can be smaller that 'k' (this threshold parameter), which
 103  * makes the threshold crypto system useledd.  However, in this case one can still determine which peers
 104  * were able to participate in the secret sharing successfully.
 105  *
 106  * @param cls closure
 107  * @param public_key public key of the session
 108  * @param num_ready_peers number of peers in @ready_peers
 109  * @parem ready_peers peers that successfuly participated in establishing
 110  *                    the shared secret
 111  */
 112 typedef void (*GNUNET_SECRETSHARING_SecretReadyCallback) (void *cls,
 113                                                           gcry_mpi_t public_key,
 114                                                           unsigned int num_ready_peers,
 115                                                           const struct GNUNET_PeerIdentity *ready_peers);
 116
 117
 118 /**
 119  * Called when a decryption has succeeded.
 120  *
 121  * @param cls closure
 122  * @param result decrypted value
 123  */
 124 typedef void (*GNUNET_SECRETSHARING_DecryptCallback) (void *cls,
 125                                                       gcry_mpi_t result);
 126
 127
 128 /**
 129  * Create a session that will eventually establish a shared secret
 130  * with the other peers.
 131  *
 132  * @param cfg configuration to use
 133  * @param num_peers number of peers in @peers
 134  * @param session_id unique session id
 135  * @param deadline point in time where the session must be established; taken as hint
 136  *                 by underlying consensus sessions
 137  * @param cb called when the secret has been established
 138  * @param cls closure for cb
 139  */
 140 struct GNUNET_SECRETSHARING_Session *
 141 GNUNET_SECRETSHARING_create_session (const struct GNUNET_CONFIGURATION_Handle *cfg,
 142                                      unsigned int num_peers,
 143                                      const struct GNUNET_PeerIdentity *peers,
 144                                      const struct GNUNET_HashCode *session_id,
 145                                      struct GNUNET_TIME_Absolute deadline,
 146                                      struct GNUNET_SECRETSHARING_Parameters *parameters,
 147                                      GNUNET_SECRETSHARING_SecretReadyCallback *cb,
 148                                      void *cls);
 149
 150
 151 /**
 152  * Destroy a secret sharing session.
 153  *
 154  * @param session session to destroy
 155  */
 156 void
 157 GNUNET_SECRETSHARING_destroy_session (struct GNUNET_SECRETSHARING_Session *session);
 158
 159
 160 /**
 161  * Encrypt a value.  This operation is executed locally, no communication is
 162  * necessary.
 163  *
 164  * This is a helper function, encryption can be done soley with a session's public key
 165  * and the crypto system parameters.
 166  *
 167  * @param session session to take the key for encryption from,
 168  *                the session's ready callback must have been already called
 169  * @param message message to encrypt
 170  * @param result_cyphertext pointer to store the resulting ciphertext
 171  * @return GNUNET_YES on succes, GNUNET_SYSERR if the message is invalid (invalid range)
 172  */
 173 int
 174 GNUNET_SECRETSHARING_encrypt (const struct GNUNET_SECRETSHARING_Session *session,
 175                               gcry_mpi_t message,
 176                               struct GNUNET_SECRETSHARING_Ciphertext *result_ciphertext);
 177
 178
 179 /**
 180  * Publish the given ciphertext for decryption.  Once a sufficient (>=k) number of peers has
 181  * published the same value, it will be decrypted.
 182  *
 183  * When the operation is canceled, the decrypt_cb is not called anymore, but the calling
 184  * peer may already have irrevocably contributed his share for the decryption of the value.
 185  *
 186  * @param session session to use for the decryption
 187  * @param ciphertext ciphertext to publish in order to decrypt it (if enough peers agree)
 188  * @param decrypt_cb callback called once the decryption succeeded
 189  * @param cls closure for decrypt_cb
 190  * @return handle to cancel the operation
 191  */
 192 struct GNUNET_SECRETSHARING_DecryptionHandle
 193 GNUNET_SECRETSHARING_publish_decrypt (struct GNUNET_SECRETSHARING_Session *session,
 194                                       struct GNUNET_SECRETSHARING_Ciphertext *ciphertext,
 195                                       GNUNET_SECRETSHARING_DecryptCallback decrypt_cb,
 196                                       void *cls);
 197
 198 /**
 199  * Cancel a decryption.
 200  *
 201  * The decrypt_cb is not called anymore, but the calling
 202  * peer may already have irrevocably contributed his share for the decryption of the value.
 203  *
 204  * @param decryption_handle decryption to cancel
 205  */
 206 void
 207 GNUNET_SECRETSHARING_cancel_decrypt (struct GNUNET_SECRETSHARING_DecryptionHandle *decryption_handle);
 208
 209
 210
 211
 212
 213 #if 0                           /* keep Emacsens' auto-indent happy */
 214 {
 215 #endif
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif