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 verifiable 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 @a 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 data decrypted value
 130  * @param data_size number of bytes in @a data
 131  */
 132 typedef void (*GNUNET_SECRETSHARING_DecryptCallback) (void *cls,
 133                                                       const void *data,
 134                                                       size_t data_size);
 135
 136
 137 /**
 138  * Create a session that will eventually establish a shared secret
 139  * with the other peers.
 140  *
 141  * @param cfg configuration to use
 142  * @param num_peers number of peers in 'peers'
 143  * @param peers array of peers that we will share secrets with, can optionally contain the local peer
 144  * @param session_id unique session id
 145  * @param deadline point in time where the session must be established; taken as hint
 146  *                 by underlying consensus sessions
 147  * @param threshold minimum number of peers that must cooperate to decrypt a value
 148  * @param cb called when the secret has been established
 149  * @param cls closure for cb
 150  */
 151 struct GNUNET_SECRETSHARING_Session *
 152 GNUNET_SECRETSHARING_create_session (const struct GNUNET_CONFIGURATION_Handle *cfg,
 153                                      unsigned int num_peers,
 154                                      const struct GNUNET_PeerIdentity *peers,
 155                                      const struct GNUNET_HashCode *session_id,
 156                                      struct GNUNET_TIME_Absolute deadline,
 157                                      unsigned int threshold,
 158                                      GNUNET_SECRETSHARING_SecretReadyCallback *cb,
 159                                      void *cls);
 160
 161
 162 /**
 163  * Load a session from an existing share.
 164  *
 165  * @param cfg configuration to use for connecting to the secretsharing service
 166  * @param share share to load the session from
 167  */
 168 struct GNUNET_SECRETSHARING_Session *
 169 GNUNET_SECRETSHARING_load_session_DEPRECATED (const struct GNUNET_CONFIGURATION_Handle *cfg,
 170                                    const struct GNUNET_SECRETSHARING_Share *share);
 171
 172 /**
 173  * Convert a secret share to a string.
 174  *
 175  * @param share share to serialize
 176  * @return the serialized secret share, to be freed by the caller
 177  */
 178 char *
 179 GNUNET_SECRETSHARING_share_to_BIN (const struct GNUNET_SECRETSHARING_Share *share);
 180
 181
 182 /**
 183  * Convert a secret share to a string.
 184  *
 185  * @param str string to deserialize
 186  * @return the serialized secret share, to be freed by the caller
 187  */
 188 const struct GNUNET_SECRETSHARING_Share *
 189 GNUNET_SECRETSHARING_share_from_BIN (const char *str);
 190
 191
 192 /**
 193  * Destroy a secret share.
 194  *
 195  * @param share secret share to destroy
 196  */
 197 void
 198 GNUNET_SECRETSHARING_share_destroy (const struct GNUNET_SECRETSHARING_Share *share);
 199
 200
 201 /**
 202  * Destroy a secret sharing session.
 203  *
 204  * @param session session to destroy
 205  */
 206 void
 207 GNUNET_SECRETSHARING_destroy_session (struct GNUNET_SECRETSHARING_Session *session);
 208
 209
 210 /**
 211  * Encrypt a value.  This operation is executed locally, no communication is
 212  * necessary.
 213  *
 214  * This is a helper function, encryption can be done soley with a session's public key
 215  * and the crypto system parameters.
 216  *
 217  * @param session session to take the key for encryption from,
 218  *                the session's ready callback must have been already called
 219  * @param message message to encrypt
 220  * @param message_size number of bytes in @a message
 221  * @param result_ciphertext pointer to store the resulting ciphertext
 222  * @return #GNUNET_YES on succes, #GNUNET_SYSERR if the message is invalid (invalid range)
 223  */
 224 int
 225 GNUNET_SECRETSHARING_encrypt (const struct GNUNET_SECRETSHARING_PublicKey *session,
 226                               const void *message,
 227                               size_t message_size,
 228                               struct GNUNET_SECRETSHARING_Ciphertext *result_ciphertext);
 229
 230
 231 /**
 232  * Publish the given ciphertext for decryption.  Once a sufficient (>=k) number of peers has
 233  * published the same value, it will be decrypted.
 234  *
 235  * When the operation is canceled, the decrypt_cb is not called anymore, but the calling
 236  * peer may already have irrevocably contributed his share for the decryption of the value.
 237  *
 238  * @param session session to use for the decryption
 239  * @param ciphertext ciphertext to publish in order to decrypt it (if enough peers agree)
 240  * @param decrypt_cb callback called once the decryption succeeded
 241  * @param decrypt_cb_cls closure for @a decrypt_cb
 242  * @return handle to cancel the operation
 243  */
 244 struct GNUNET_SECRETSHARING_DecryptionHandle *
 245 GNUNET_SECRETSHARING_decrypt (struct GNUNET_SECRETSHARING_Session *session,
 246                               struct GNUNET_SECRETSHARING_Ciphertext *ciphertext,
 247                               GNUNET_SECRETSHARING_DecryptCallback decrypt_cb,
 248                               void *decrypt_cb_cls);
 249
 250
 251 /**
 252  * Cancel a decryption.
 253  *
 254  * The decrypt_cb is not called anymore, but the calling
 255  * peer may already have irrevocably contributed his share for the decryption of the value.
 256  *
 257  * @param decryption_handle decryption to cancel
 258  */
 259 void
 260 GNUNET_SECRETSHARING_decrypt_cancel (struct GNUNET_SECRETSHARING_DecryptionHandle *decryption_handle);
 261
 262
 263
 264
 265 #if 0                           /* keep Emacsens' auto-indent happy */
 266 {
 267 #endif
 268 #ifdef __cplusplus
 269 }
 270 #endif
 271
 272 #endif