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