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