src/include/gnunet_pseudonym_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001--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 2, 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_pseudonym_lib.h
  23  * @brief functions related to pseudonyms
  24  * @author Christian Grothoff
  25  */
  26
  27 #ifndef GNUNET_PSEUDONYM_LIB_H
  28 #define GNUNET_PSEUDONYM_LIB_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 "gnunet_common.h"
  39 #include "gnunet_configuration_lib.h"
  40 #include "gnunet_container_lib.h"
  41
  42
  43 /**
  44  * Identifier for a GNUnet pseudonym (the public key).
  45  * Q-point, Q=dp.
  46  */
  47 struct GNUNET_PseudonymIdentifier
  48 {
  49   /**
  50    * Q consists of an x- and a y-value, each mod p (256 bits);
  51    * however, (to speed up calculations and/or represent infinity)
  52    * libgcrypt uses projective coordinates, which add an extra
  53    * dimension.  Thus, the MPI value is typically one additional byte
  54    * longer (512 bit + 8 bits).  As we want a size that is a
  55    * multiplicative of 8, we add 8 bytes (not 8 bits), which should
  56    * always suffice to represent Q.
  57    */
  58   unsigned char q[(256 + 256 / 8) + 8];
  59
  60 };
  61
  62
  63 /**
  64  * Handle for a pseudonym (private key).
  65  */
  66 struct GNUNET_PseudonymHandle;
  67
  68
  69 /**
  70  * Signature made with a pseudonym (includes the full public key).
  71  * The ECDSA signature is a pair (r,s) with r = x1 mod n where
  72  * (x1,y1) = kG for "random" k and s = k^{-1}(z + rd) mod n,
  73  * where z is derived from the hash of the message that is being
  74  * signed.
  75  */
  76 struct GNUNET_PseudonymSignature
  77 {
  78
  79   /**
  80    * Who created the signature? (public key of the signer), 'd' value in NIST P-256.
  81    */
  82   struct GNUNET_PseudonymIdentifier signer;
  83
  84   /**
  85    * Binary ECDSA signature data, r-value.  Value is mod n, and n is 256 bits.
  86    */
  87   unsigned char sig_r[256 / 8];
  88
  89   /**
  90    * Binary ECDSA signature data, s-value.  Value is mod n, and n is 256 bits.
  91    */
  92   unsigned char sig_s[256 / 8];
  93 };
  94
  95
  96 /**
  97  * Purpose for signature made with a pseudonym.
  98  */
  99 struct GNUNET_PseudonymSignaturePurpose
 100 {
 101   /**
 102    * How many bytes are being signed (including this header)?
 103    */
 104   uint32_t size;
 105
 106   /**
 107    * What is the context/purpose of the signature?
 108    */
 109   uint32_t purpose;
 110 };
 111
 112
 113 /**
 114  * Create a pseudonym.
 115  *
 116  * @param filename name of the file to use for storage, NULL for in-memory only
 117  * @return handle to the private key of the pseudonym
 118  */
 119 struct GNUNET_PseudonymHandle *
 120 GNUNET_PSEUDONYM_create (const char *filename);
 121
 122
 123 /**
 124  * Create a pseudonym, from a file that must already exist.
 125  *
 126  * @param filename name of the file to use for storage, NULL for in-memory only
 127  * @return handle to the private key of the pseudonym
 128  */
 129 struct GNUNET_PseudonymHandle *
 130 GNUNET_PSEUDONYM_create_from_existing_file (const char *filename);
 131
 132
 133 /**
 134  * Get the handle for the 'anonymous' pseudonym shared by all users.
 135  * That pseudonym uses a fixed 'secret' for the private key; this
 136  * construction is useful to make anonymous and pseudonymous APIs
 137  * (and packets) indistinguishable on the network.  See #2564.
 138  *
 139  * @return handle to the (non-secret) private key of the 'anonymous' pseudonym
 140  */
 141 struct GNUNET_PseudonymHandle *
 142 GNUNET_PSEUDONYM_get_anonymous_pseudonym_handle (void);
 143
 144
 145 /**
 146  * Destroy a pseudonym handle.  Does NOT remove the private key from
 147  * the disk.
 148  *
 149  * @param ph pseudonym handle to destroy
 150  */
 151 void
 152 GNUNET_PSEUDONYM_destroy (struct GNUNET_PseudonymHandle *ph);
 153
 154
 155 /**
 156  * Cryptographically sign some data with the pseudonym.
 157  *
 158  * @param ph private key used for signing (corresponds to 'x' in #2564)
 159  * @param purpose data to sign
 160  * @param seed hash of the plaintext of the data that we are signing,
 161  *             used for deterministic PRNG for anonymous signing;
 162  *             corresponds to 'k' in section 2.7 of #2564
 163  * @param signing_key modifier to apply to the private key for signing;
 164  *                    corresponds to 'h' in section 2.3 of #2564.
 165  * @param signature where to store the signature
 166  * @return GNUNET_SYSERR on failure
 167  */
 168 int
 169 GNUNET_PSEUDONYM_sign (struct GNUNET_PseudonymHandle *ph,
 170                        const struct GNUNET_PseudonymSignaturePurpose *purpose,
 171                        const struct GNUNET_HashCode *seed,
 172                        const struct GNUNET_HashCode *signing_key,
 173                        struct GNUNET_PseudonymSignature *signature);
 174
 175
 176 /**
 177  * Given a pseudonym and a signing key, derive the corresponding public
 178  * key that would be used to verify the resulting signature.
 179  *
 180  * @param pseudonym the public key (g^x in DSA, dQ in ECDSA)
 181  * @param signing_key input to derive 'h' (see section 2.4 of #2564)
 182  * @param verification_key resulting public key to verify the signature
 183  *        created from the 'ph' of 'pseudonym' and the 'signing_key';
 184  *        the value stored here can then be given to GNUNET_PSEUDONYM_verify.
 185  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 186  */
 187 int
 188 GNUNET_PSEUDONYM_derive_verification_key (struct GNUNET_PseudonymIdentifier *pseudonym,
 189                                           const struct GNUNET_HashCode *signing_key,
 190                                           struct GNUNET_PseudonymIdentifier *verification_key);
 191
 192
 193 /**
 194  * Verify a signature made with a pseudonym.
 195  *
 196  * @param purpose data that was signed
 197  * @param signature signature to verify
 198  * @param verification_key public key to use for checking the signature;
 199  *                    corresponds to 'g^(x+h)' in section 2.4 of #2564.
 200  * @return GNUNET_OK on success (signature valid, 'pseudonym' set),
 201  *         GNUNET_SYSERR if the signature is invalid
 202  */
 203 int
 204 GNUNET_PSEUDONYM_verify (const struct GNUNET_PseudonymSignaturePurpose *purpose,
 205                          const struct GNUNET_PseudonymSignature *signature,
 206                          const struct GNUNET_PseudonymIdentifier *verification_key);
 207
 208
 209 /**
 210  * Get the identifier (public key) of a pseudonym.
 211  *
 212  * @param ph pseudonym handle with the private key
 213  * @param pseudonym pseudonym identifier (set based on 'ph')
 214  */
 215 void
 216 GNUNET_PSEUDONYM_get_identifier (struct GNUNET_PseudonymHandle *ph,
 217                                  struct GNUNET_PseudonymIdentifier *pseudonym);
 218
 219
 220
 221 /**
 222  * Iterator over all known pseudonyms.
 223  *
 224  * @param cls closure
 225  * @param pseudonym hash code of public key of pseudonym
 226  * @param name name of the pseudonym (might be NULL)
 227  * @param unique_name unique name of the pseudonym (might be NULL)
 228  * @param md meta data known about the pseudonym
 229  * @param rating the local rating of the pseudonym
 230  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
 231  */
 232 typedef int (*GNUNET_PSEUDONYM_Iterator) (void *cls,
 233                                           const struct GNUNET_PseudonymIdentifier *pseudonym,
 234                                           const char *name,
 235                                           const char *unique_name,
 236                                           const struct GNUNET_CONTAINER_MetaData *md,
 237                                           int32_t rating);
 238
 239
 240 /**
 241  * Change the rank of a pseudonym.
 242  *
 243  * @param cfg overall configuration
 244  * @param pseudonym identity of the pseudonym
 245  * @param delta by how much should the rating be changed?
 246  * @return new rating of the pseudonym
 247  */
 248 int
 249 GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg,
 250                        const struct GNUNET_PseudonymIdentifier *pseudonym,
 251                        int32_t delta);
 252
 253
 254 /**
 255  * Add a pseudonym to the set of known pseudonyms.
 256  * For all pseudonym advertisements that we discover
 257  * FS should automatically call this function.
 258  *
 259  * @param cfg overall configuration
 260  * @param id the pseudonym identifier
 261  * @param meta metadata for the pseudonym
 262  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 263  */
 264 int
 265 GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg,
 266                       const struct GNUNET_PseudonymIdentifier *pseudonym,
 267                       const struct GNUNET_CONTAINER_MetaData *meta);
 268
 269
 270 /**
 271  * List all known pseudonyms.
 272  *
 273  * @param cfg overall configuration
 274  * @param iterator function to call for each pseudonym
 275  * @param iterator_cls closure for iterator
 276  * @return number of pseudonyms found
 277  */
 278 int
 279 GNUNET_PSEUDONYM_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg,
 280                            GNUNET_PSEUDONYM_Iterator iterator,
 281                            void *iterator_cls);
 282
 283
 284 /**
 285  * Handle for a discovery callback registration.
 286  */
 287 struct GNUNET_PSEUDONYM_DiscoveryHandle;
 288
 289
 290 /**
 291  * Register callback to be invoked whenever we discover
 292  * a new pseudonym.
 293  *
 294  * @param cfg our configuration
 295  * @param iterator function to invoke on discovery
 296  * @param iterator_cls closure for iterator
 297  * @return registration handle
 298  */
 299 struct GNUNET_PSEUDONYM_DiscoveryHandle *
 300 GNUNET_PSEUDONYM_discovery_callback_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
 301                                               GNUNET_PSEUDONYM_Iterator iterator,
 302                                               void *iterator_cls);
 303
 304
 305 /**
 306  * Unregister pseudonym discovery callback.
 307  *
 308  * @param dh registration to unregister
 309  */
 310 void
 311 GNUNET_PSEUDONYM_discovery_callback_unregister (struct GNUNET_PSEUDONYM_DiscoveryHandle *dh);
 312
 313
 314 /**
 315  * Return unique variant of the pseudonym name.  Use after
 316  * GNUNET_PSEUDONYM_id_to_name() to make sure that name is unique.
 317  *
 318  * @param cfg configuration
 319  * @param pseudonym cryptographic ID of the pseudonym
 320  * @param name name to uniquify
 321  * @param suffix if not NULL, filled with the suffix value
 322  * @return NULL on failure (should never happen), name on success.
 323  *         Free the name with GNUNET_free().
 324  */
 325 char *
 326 GNUNET_PSEUDONYM_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg,
 327                                 const struct GNUNET_PseudonymIdentifier *pseudonym,
 328                                 const char *name,
 329                                 unsigned int *suffix);
 330
 331
 332 /**
 333  * Get pseudonym name, metadata and rank. This is a wrapper around
 334  * internal read_info() call, and ensures that returned data is not
 335  * invalid (not NULL).  Writing back information returned by this
 336  * function will give a name "no-name" to pseudonyms that have no
 337  * name. This side-effect is unavoidable, but hardly harmful.
 338  *
 339  * @param cfg configuration
 340  * @param pseudonym cryptographic ID of the pseudonym
 341  * @param ret_meta a location to store metadata pointer. NULL, if metadata
 342  *        is not needed. Destroy with GNUNET_CONTAINER_meta_data_destroy().
 343  * @param ret_rank a location to store rank. NULL, if rank not needed.
 344  * @param ret_name a location to store human-readable name. Name is not unique.
 345  *        NULL, if name is not needed. Free with GNUNET_free().
 346  * @param name_is_a_dup is set to GNUNET_YES, if ret_name was filled with
 347  *        a duplicate of a "no-name" placeholder
 348  * @return GNUNET_OK on success. GNUENT_SYSERR if the data was
 349  *         unobtainable (in that case ret_* are filled with placeholders -
 350  *         empty metadata container, rank -1 and a "no-name" name).
 351  */
 352 int
 353 GNUNET_PSEUDONYM_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
 354                            const struct GNUNET_PseudonymIdentifier *pseudonym,
 355                            struct GNUNET_CONTAINER_MetaData **ret_meta,
 356                            int32_t *ret_rank,
 357                            char **ret_name,
 358                            int *name_is_a_dup);
 359
 360
 361 /**
 362  * Get the pseudonym ID belonging to the given pseudonym name.
 363  *
 364  * @param cfg configuration to use
 365  * @param ps_uname unique (!) human-readable name for the pseudonym
 366  * @param pseudonym set to pseudonym ID based on 'ns_uname'
 367  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 368  */
 369 int
 370 GNUNET_PSEUDONYM_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg,
 371                              const char *ps_uname,
 372                              struct GNUNET_PseudonymIdentifier *pseudonym);
 373
 374
 375 /**
 376  * Set the pseudonym metadata, rank and name.
 377  *
 378  * @param cfg overall configuration
 379  * @param pseudonym id of the pseudonym
 380  * @param name name to set. Must be the non-unique version of it.
 381  *        May be NULL, in which case it erases pseudonym's name!
 382  * @param md metadata to set
 383  *        May be NULL, in which case it erases pseudonym's metadata!
 384  * @param rank rank to assign
 385  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 386  */
 387 int
 388 GNUNET_PSEUDONYM_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
 389                            const struct GNUNET_PseudonymIdentifier *pseudonym,
 390                            const char *name,
 391                            const struct GNUNET_CONTAINER_MetaData *md,
 392                            int32_t rank);
 393
 394
 395 /**
 396  * Remove pseudonym from the set of known pseudonyms.
 397  *
 398  * @param cfg overall configuration
 399  * @param id the pseudonym identifier
 400  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 401  */
 402 int
 403 GNUNET_PSEUDONYM_remove (const struct GNUNET_CONFIGURATION_Handle *cfg,
 404     const struct GNUNET_PseudonymIdentifier *id);
 405
 406
 407
 408 #if 0                           /* keep Emacsens' auto-indent happy */
 409 {
 410 #endif
 411 #ifdef __cplusplus
 412 }
 413 #endif
 414
 415 /* ifndef GNUNET_PSEUDONYM_LIB_H */
 416 #endif
 417 /* end of gnunet_pseudonym_lib.h */