diff options
Diffstat (limited to 'src/include/gnunet_pseudonym_lib.h')
-rw-r--r-- | src/include/gnunet_pseudonym_lib.h | 418 |
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 | ||
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 | * 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 | */ | ||
67 | struct 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 | */ | ||
77 | struct 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 | */ | ||
100 | struct 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 | */ | ||
120 | struct GNUNET_PseudonymHandle * | ||
121 | GNUNET_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 | */ | ||
130 | struct GNUNET_PseudonymHandle * | ||
131 | GNUNET_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 | */ | ||
142 | struct GNUNET_PseudonymHandle * | ||
143 | GNUNET_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 | */ | ||
152 | void | ||
153 | GNUNET_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 | */ | ||
169 | int | ||
170 | GNUNET_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 | */ | ||
188 | int | ||
189 | GNUNET_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 | */ | ||
204 | int | ||
205 | GNUNET_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 | */ | ||
216 | void | ||
217 | GNUNET_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 | */ | ||
233 | typedef 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 | */ | ||
249 | int | ||
250 | GNUNET_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 | */ | ||
265 | int | ||
266 | GNUNET_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 | */ | ||
279 | int | ||
280 | GNUNET_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 | */ | ||
288 | struct 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 | */ | ||
300 | struct GNUNET_PSEUDONYM_DiscoveryHandle * | ||
301 | GNUNET_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 | */ | ||
311 | void | ||
312 | GNUNET_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 | */ | ||
326 | char * | ||
327 | GNUNET_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 | */ | ||
353 | int | ||
354 | GNUNET_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 | */ | ||
370 | int | ||
371 | GNUNET_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 | */ | ||
388 | int | ||
389 | GNUNET_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 | */ | ||
403 | int | ||
404 | GNUNET_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 */ | ||