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  * Number of bits for secretsharing keys.
  47  * Must be smaller than the Pallier key size used internally
  48  * by the secretsharing service.
  49  */
  50 #define GNUNET_SECRETSHARING_KEY_BITS 1024
  51
  52
  53 /**
  54  * Session that will eventually establish a shared secred between
  55  * the involved peers and allow encryption and cooperative decryption.
  56  */
  57 struct GNUNET_SECRETSHARING_Session;
  58
  59 /**
  60  * Share of a secret shared with a group of peers.
  61  * Contains both the share and information about the peers that have
  62  * the other parts of the share.
  63  */
  64 struct GNUNET_SECRETSHARING_Share;
  65
  66
  67 /**
  68  * Handle to cancel a cooperative decryption operation.
  69  */
  70 struct GNUNET_SECRETSHARING_DecryptionHandle;
  71
  72
  73 /**
  74  * Public key of a group sharing a secret.
  75  */
  76 struct GNUNET_SECRETSHARING_PublicKey
  77 {
  78   uint32_t bits[GNUNET_SECRETSHARING_KEY_BITS / 8 / sizeof (uint32_t)];
  79 };
  80
  81
  82 /**
  83  * Encrypted field element.
  84  */
  85 struct GNUNET_SECRETSHARING_Ciphertext
  86 {
  87   uint32_t bits[2 * GNUNET_SECRETSHARING_KEY_BITS / 8 / sizeof (uint32_t)];
  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 than '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  * If the secret sharing failed, num_ready_peers is 0 and my_share and public_key is NULL.
 112  *
 113  * @param cls closure
 114  * @param my_share the share of this peer
 115  * @param public_key public key of the session
 116  * @param num_ready_peers number of peers in @a ready_peers
 117  * @param ready_peers peers that successfuly participated in establishing
 118  *                    the shared secret
 119  */
 120 typedef void (*GNUNET_SECRETSHARING_SecretReadyCallback) (void *cls,
 121                                                           const struct GNUNET_SECRETSHARING_Share *my_share,
 122                                                           const struct GNUNET_SECRETSHARING_PublicKey public_key,
 123                                                           unsigned int num_ready_peers,
 124                                                           const struct GNUNET_PeerIdentity *ready_peers);
 125
 126
 127 /**
 128  * Called when a decryption has succeeded.
 129  *
 130  * @param cls closure
 131  * @param data decrypted value
 132  * @param data_size number of bytes in @a data
 133  */
 134 typedef void (*GNUNET_SECRETSHARING_DecryptCallback) (void *cls,
 135                                                       const void *data,
 136                                                       size_t data_size);
 137
 138
 139 /**
 140  * Create a session that will eventually establish a shared secret
 141  * with the other peers.
 142  *
 143  * @param cfg configuration to use
 144  * @param num_peers number of peers in 'peers'
 145  * @param peers array of peers that we will share secrets with, can optionally contain the local peer
 146  * @param session_id unique session id
 147  * @param deadline point in time where the session must be established; taken as hint
 148  *                 by underlying consensus sessions
 149  * @param threshold minimum number of peers that must cooperate to decrypt a value
 150  * @param cb called when the secret has been established
 151  * @param cls closure for cb
 152  */
 153 struct GNUNET_SECRETSHARING_Session *
 154 GNUNET_SECRETSHARING_create_session (const struct GNUNET_CONFIGURATION_Handle *cfg,
 155                                      unsigned int num_peers,
 156                                      const struct GNUNET_PeerIdentity *peers,
 157                                      const struct GNUNET_HashCode *session_id,
 158                                      struct GNUNET_TIME_Absolute deadline,
 159                                      unsigned int threshold,
 160                                      GNUNET_SECRETSHARING_SecretReadyCallback *cb,
 161                                      void *cls);
 162
 163
 164 /**
 165  * Destroy a secret share.
 166  *
 167  * @param share secret share to destroy
 168  */
 169 void
 170 GNUNET_SECRETSHARING_share_destroy (const struct GNUNET_SECRETSHARING_Share *share);
 171
 172
 173 /**
 174  * Destroy a secret sharing session.
 175  *
 176  * @param session session to destroy
 177  */
 178 void
 179 GNUNET_SECRETSHARING_destroy_session (struct GNUNET_SECRETSHARING_Session *session);
 180
 181
 182 /**
 183  * Encrypt a value.  This operation is executed locally, no communication is
 184  * necessary.
 185  *
 186  * This is a helper function, encryption can be done soley with a session's public key
 187  * and the crypto system parameters.
 188  *
 189  * @param public_key public key to use for decryption
 190  * @param message message to encrypt
 191  * @param message_size number of bytes in @a message
 192  * @param result_ciphertext pointer to store the resulting ciphertext
 193  * @return #GNUNET_YES on succes, #GNUNET_SYSERR if the message is invalid (invalid range)
 194  */
 195 int
 196 GNUNET_SECRETSHARING_encrypt (struct GNUNET_SECRETSHARING_PublicKey *public_key,
 197                               const void *message,
 198                               size_t message_size,
 199                               struct GNUNET_SECRETSHARING_Ciphertext *result_ciphertext);
 200
 201
 202 /**
 203  * Publish the given ciphertext for decryption.  Once a sufficient (>=k) number of peers has
 204  * published the same value, it will be decrypted.
 205  *
 206  * When the operation is canceled, the decrypt_cb is not called anymore, but the calling
 207  * peer may already have irrevocably contributed his share for the decryption of the value.
 208  *
 209  * @param share our secret share to use for decryption
 210  * @param ciphertext ciphertext to publish in order to decrypt it (if enough peers agree)
 211  * @param decrypt_cb callback called once the decryption succeeded
 212  * @param decrypt_cb_cls closure for @a decrypt_cb
 213  * @return handle to cancel the operation
 214  */
 215 struct GNUNET_SECRETSHARING_DecryptionHandle *
 216 GNUNET_SECRETSHARING_decrypt (struct GNUNET_SECRETSHARING_Share *share,
 217                               struct GNUNET_SECRETSHARING_Ciphertext *ciphertext,
 218                               GNUNET_SECRETSHARING_DecryptCallback decrypt_cb,
 219                               void *decrypt_cb_cls);
 220
 221
 222 /**
 223  * Cancel a decryption.
 224  *
 225  * The decrypt_cb is not called anymore, but the calling
 226  * peer may already have irrevocably contributed his share for the decryption of the value.
 227  *
 228  * @param decryption_handle decryption to cancel
 229  */
 230 void
 231 GNUNET_SECRETSHARING_decrypt_cancel (struct GNUNET_SECRETSHARING_DecryptionHandle *decryption_handle);
 232
 233
 234 /**
 235  * Read a share from its binary representation.
 236  *
 237  * @param data binary representation of the share
 238  * @param len length of @a data
 239  * @return the share, or NULL on error
 240  */
 241 struct GNUNET_SECRETSHARING_Share *
 242 GNUNET_SECRETSHARING_share_read (void *data, size_t len);
 243
 244
 245 /**
 246  * Convert a share to its binary representation.  Use
 247  * #GNUNET_SECRETSHARING_share_size to get the necessary size for the binary
 248  * representation.
 249  *
 250  * @param share share to write
 251  * @param buf buffer to write to
 252  * @param buflen number of writable bytes in @a buffer
 253  * @param[out] writelen pointer to store number of bytes written,
 254  *             ignored if NULL
 255  * @return GNUNET_YES on success, GNUNET_NO on failure
 256  */
 257 int
 258 GNUNET_SECRETSHARING_share_write (struct GNUNET_SECRETSHARING_Share *share,
 259                                   void *buf, size_t buflen, size_t *writelen);
 260
 261
 262 /**
 263  * Get the number of bytes necessary to represent the given share.
 264  *
 265  * @param share share
 266  * @return number of bytes necessary to represent @a share
 267  */
 268 size_t
 269 GNUNET_SECRETSHARING_share_size (struct GNUNET_SECRETSHARING_Share *share);
 270
 271
 272
 273 #if 0                           /* keep Emacsens' auto-indent happy */
 274 {
 275 #endif
 276 #ifdef __cplusplus
 277 }
 278 #endif
 279
 280 #endif