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  * Share of a secret shared with a group of peers.
  53  */
  54 struct GNUNET_SECRETSHARING_Share;
  55
  56
  57 /**
  58  * Handle to cancel a cooperative decryption operation.
  59  */
  60 struct GNUNET_SECRETSHARING_DecryptionHandle;
  61
  62
  63 /**
  64  * Public key of a group sharing a secret.
  65  */
  66 struct GNUNET_SECRETSHARING_PublicKey
  67 {
  68   /**
  69    * Value of the private key.
  70    */
  71   gcry_mpi_t value;
  72 };
  73
  74
  75 /**
  76  * Encrypted field element.
  77  */
  78 struct GNUNET_SECRETSHARING_Ciphertext
  79 {
  80   /**
  81    * First component.
  82    */
  83   gcry_mpi_t c1;
  84   /**
  85    * Second component.
  86    */
  87   gcry_mpi_t c2;
  88 };
  89
  90
  91 /**
  92  * Plain, unencrypted message that can be encrypted with
  93  * a group public key.
  94  */
  95 struct GNUNET_SECRETSHARING_Message
  96 {
  97   /**
  98    * Value of the message.
  99    */
 100   gcry_mpi_t value;
 101 };
 102
 103
 104 /**
 105  * Called once the secret has been established with all peers, or the deadline is due.
 106  *
 107  * Note that the number of peers can be smaller that 'k' (this threshold parameter), which
 108  * makes the threshold crypto system useless.  However, in this case one can still determine which peers
 109  * were able to participate in the secret sharing successfully.
 110  *
 111  * @param cls closure
 112  * @param my_share the share of this peer
 113  * @param public_key public key of the session
 114  * @param num_ready_peers number of peers in ready_peers
 115  * @param ready_peers peers that successfuly participated in establishing
 116  *                    the shared secret
 117  */
 118 typedef void (*GNUNET_SECRETSHARING_SecretReadyCallback) (void *cls,
 119                                                           const struct GNUNET_SECRETSHARING_Share *my_share,
 120                                                           const struct GNUNET_SECRETSHARING_PublicKey public_key,
 121                                                           unsigned int num_ready_peers,
 122                                                           const struct GNUNET_PeerIdentity *ready_peers);
 123
 124
 125 /**
 126  * Called when a decryption has succeeded.
 127  *
 128  * @param cls closure
 129  * @param result decrypted value, must be free'd by the callback eventually
 130  */
 131 typedef void (*GNUNET_SECRETSHARING_DecryptCallback) (void *cls,
 132                                                       struct GNUNET_SECRETSHARING_Message *result);
 133
 134
 135 /**
 136  * Create a session that will eventually establish a shared secret
 137  * with the other peers.
 138  *
 139  * @param cfg configuration to use
 140  * @param num_peers number of peers in 'peers'
 141  * @param peers array of peers that we will share secrets with, can optionally contain the local peer
 142  * @param session_id unique session id
 143  * @param deadline point in time where the session must be established; taken as hint
 144  *                 by underlying consensus sessions
 145  * @param threshold minimum number of peers that must cooperate to decrypt a value
 146  * @param cb called when the secret has been established
 147  * @param cls closure for cb
 148  */
 149 struct GNUNET_SECRETSHARING_Session *
 150 GNUNET_SECRETSHARING_create_session (const struct GNUNET_CONFIGURATION_Handle *cfg,
 151                                      unsigned int num_peers,
 152                                      const struct GNUNET_PeerIdentity *peers,
 153                                      const struct GNUNET_HashCode *session_id,
 154                                      struct GNUNET_TIME_Absolute deadline,
 155                                      unsigned int threshold,
 156                                      GNUNET_SECRETSHARING_SecretReadyCallback *cb,
 157                                      void *cls);
 158
 159
 160 /**
 161  * Load a session from an existing share.
 162  *
 163  * @param cfg configuration to use for connecting to the secretsharing service
 164  * @param share share to load the session from
 165  */
 166 struct GNUNET_SECRETSHARING_Session *
 167 GNUNET_SECRETSHARING_load_session (const struct GNUNET_CONFIGURATION_Handle *cfg,
 168                                    const struct GNUNET_SECRETSHARING_Share *share);
 169
 170 /**
 171  * Convert a secret share to a string.
 172  *
 173  * @param share share to serialize
 174  * @return the serialized secret share, to be freed by the caller
 175  */
 176 char *
 177 GNUNET_SECRETSHARING_share_to_string (const struct GNUNET_SECRETSHARING_Share *share);
 178
 179
 180 /**
 181  * Convert a secret share to a string.
 182  *
 183  * @param str string to deserialize
 184  * @return the serialized secret share, to be freed by the caller
 185  */
 186 const struct GNUNET_SECRETSHARING_Share *
 187 GNUNET_SECRETSHARING_share_from_string (const char *str);
 188
 189
 190 /**
 191  * Destroy a secret share.
 192  *
 193  * @param share secret share to destroy
 194  */
 195 void
 196 GNUNET_SECRETSHARING_share_destroy (const struct GNUNET_SECRETSHARING_Share *share);
 197
 198
 199 /**
 200  * Destroy a secret sharing session.
 201  *
 202  * @param session session to destroy
 203  */
 204 void
 205 GNUNET_SECRETSHARING_destroy_session (struct GNUNET_SECRETSHARING_Session *session);
 206
 207
 208 /**
 209  * Encrypt a value.  This operation is executed locally, no communication is
 210  * necessary.
 211  *
 212  * This is a helper function, encryption can be done soley with a session's public key
 213  * and the crypto system parameters.
 214  *
 215  * @param session session to take the key for encryption from,
 216  *                the session's ready callback must have been already called
 217  * @param message message to encrypt
 218  * @param result_ciphertext pointer to store the resulting ciphertext
 219  * @return GNUNET_YES on succes, GNUNET_SYSERR if the message is invalid (invalid range)
 220  */
 221 int
 222 GNUNET_SECRETSHARING_encrypt (const struct GNUNET_SECRETSHARING_Session *session,
 223                               const struct GNUNET_SECRETSHARING_Message *message,
 224                               struct GNUNET_SECRETSHARING_Ciphertext *result_ciphertext);
 225
 226
 227 /**
 228  * Publish the given ciphertext for decryption.  Once a sufficient (>=k) number of peers has
 229  * published the same value, it will be decrypted.
 230  *
 231  * When the operation is canceled, the decrypt_cb is not called anymore, but the calling
 232  * peer may already have irrevocably contributed his share for the decryption of the value.
 233  *
 234  * @param session session to use for the decryption
 235  * @param ciphertext ciphertext to publish in order to decrypt it (if enough peers agree)
 236  * @param decrypt_cb callback called once the decryption succeeded
 237  * @param cls closure for decrypt_cb
 238  * @return handle to cancel the operation
 239  */
 240 struct GNUNET_SECRETSHARING_DecryptionHandle *
 241 GNUNET_SECRETSHARING_publish_decrypt (struct GNUNET_SECRETSHARING_Session *session,
 242                                       struct GNUNET_SECRETSHARING_Ciphertext *ciphertext,
 243                                       GNUNET_SECRETSHARING_DecryptCallback decrypt_cb,
 244                                       void *cls);
 245
 246
 247 /**
 248  * Cancel a decryption.
 249  *
 250  * The decrypt_cb is not called anymore, but the calling
 251  * peer may already have irrevocably contributed his share for the decryption of the value.
 252  *
 253  * @param decryption_handle decryption to cancel
 254  */
 255 void
 256 GNUNET_SECRETSHARING_cancel_decrypt (struct GNUNET_SECRETSHARING_DecryptionHandle *decryption_handle);
 257
 258
 259
 260
 261 #if 0                           /* keep Emacsens' auto-indent happy */
 262 {
 263 #endif
 264 #ifdef __cplusplus
 265 }
 266 #endif
 267
 268 #endif