diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-04-14 18:45:55 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-04-14 18:45:55 +0000 |
commit | 7d9d8f793ebc261192fe33a87905133e1bf36512 (patch) | |
tree | d9dd0eaa5863a36878cd65190aeff96a41f25ca4 /src/include/gnunet_fs_service.h | |
parent | d03a033c429a993d0d0511600fef0c15ada5d950 (diff) | |
download | gnunet-7d9d8f793ebc261192fe33a87905133e1bf36512.tar.gz gnunet-7d9d8f793ebc261192fe33a87905133e1bf36512.zip |
-move pseudonym code to fs, mark fs as experimental for now
Diffstat (limited to 'src/include/gnunet_fs_service.h')
-rw-r--r-- | src/include/gnunet_fs_service.h | 371 |
1 files changed, 371 insertions, 0 deletions
diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h index 931406e2d..6143f0630 100644 --- a/src/include/gnunet_fs_service.h +++ b/src/include/gnunet_fs_service.h | |||
@@ -79,6 +79,78 @@ extern "C" | |||
79 | */ | 79 | */ |
80 | struct GNUNET_FS_Uri; | 80 | struct GNUNET_FS_Uri; |
81 | 81 | ||
82 | |||
83 | /** | ||
84 | * Identifier for a GNUnet pseudonym (the public key). | ||
85 | * Q-point, Q=dp. | ||
86 | */ | ||
87 | struct GNUNET_PseudonymIdentifier | ||
88 | { | ||
89 | /** | ||
90 | * Q consists of an x- and a y-value, each mod p (256 bits), | ||
91 | * given here in affine coordinates. | ||
92 | */ | ||
93 | unsigned char q_x[256 / 8]; | ||
94 | |||
95 | /** | ||
96 | * Q consists of an x- and a y-value, each mod p (256 bits), | ||
97 | * given here in affine coordinates. | ||
98 | */ | ||
99 | unsigned char q_y[256 / 8]; | ||
100 | |||
101 | }; | ||
102 | |||
103 | |||
104 | /** | ||
105 | * Handle for a pseudonym (private key). | ||
106 | */ | ||
107 | struct GNUNET_PseudonymHandle; | ||
108 | |||
109 | |||
110 | /** | ||
111 | * Signature made with a pseudonym (includes the full public key). | ||
112 | * The ECDSA signature is a pair (r,s) with r = x1 mod n where | ||
113 | * (x1,y1) = kG for "random" k and s = k^{-1}(z + rd) mod n, | ||
114 | * where z is derived from the hash of the message that is being | ||
115 | * signed. | ||
116 | */ | ||
117 | struct GNUNET_PseudonymSignature | ||
118 | { | ||
119 | |||
120 | /** | ||
121 | * Who created the signature? (public key of the signer), 'd' value in NIST P-256. | ||
122 | */ | ||
123 | struct GNUNET_PseudonymIdentifier signer; | ||
124 | |||
125 | /** | ||
126 | * Binary ECDSA signature data, r-value. Value is mod n, and n is 256 bits. | ||
127 | */ | ||
128 | unsigned char sig_r[256 / 8]; | ||
129 | |||
130 | /** | ||
131 | * Binary ECDSA signature data, s-value. Value is mod n, and n is 256 bits. | ||
132 | */ | ||
133 | unsigned char sig_s[256 / 8]; | ||
134 | }; | ||
135 | |||
136 | |||
137 | /** | ||
138 | * Purpose for signature made with a pseudonym. | ||
139 | */ | ||
140 | struct GNUNET_PseudonymSignaturePurpose | ||
141 | { | ||
142 | /** | ||
143 | * How many bytes are being signed (including this header)? | ||
144 | */ | ||
145 | uint32_t size; | ||
146 | |||
147 | /** | ||
148 | * What is the context/purpose of the signature? | ||
149 | */ | ||
150 | uint32_t purpose; | ||
151 | }; | ||
152 | |||
153 | |||
82 | /** | 154 | /** |
83 | * Iterator over keywords | 155 | * Iterator over keywords |
84 | * | 156 | * |
@@ -90,6 +162,303 @@ struct GNUNET_FS_Uri; | |||
90 | typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword, | 162 | typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword, |
91 | int is_mandatory); | 163 | int is_mandatory); |
92 | 164 | ||
165 | |||
166 | |||
167 | |||
168 | /** | ||
169 | * Create a pseudonym. | ||
170 | * | ||
171 | * @param filename name of the file to use for storage, NULL for in-memory only | ||
172 | * @return handle to the private key of the pseudonym | ||
173 | */ | ||
174 | struct GNUNET_PseudonymHandle * | ||
175 | GNUNET_PSEUDONYM_create (const char *filename); | ||
176 | |||
177 | |||
178 | /** | ||
179 | * Create a pseudonym, from a file that must already exist. | ||
180 | * | ||
181 | * @param filename name of the file to use for storage, NULL for in-memory only | ||
182 | * @return handle to the private key of the pseudonym | ||
183 | */ | ||
184 | struct GNUNET_PseudonymHandle * | ||
185 | GNUNET_PSEUDONYM_create_from_existing_file (const char *filename); | ||
186 | |||
187 | |||
188 | /** | ||
189 | * Get the handle for the 'anonymous' pseudonym shared by all users. | ||
190 | * That pseudonym uses a fixed 'secret' for the private key; this | ||
191 | * construction is useful to make anonymous and pseudonymous APIs | ||
192 | * (and packets) indistinguishable on the network. See #2564. | ||
193 | * | ||
194 | * @return handle to the (non-secret) private key of the 'anonymous' pseudonym | ||
195 | */ | ||
196 | struct GNUNET_PseudonymHandle * | ||
197 | GNUNET_PSEUDONYM_get_anonymous_pseudonym_handle (void); | ||
198 | |||
199 | |||
200 | /** | ||
201 | * Destroy a pseudonym handle. Does NOT remove the private key from | ||
202 | * the disk. | ||
203 | * | ||
204 | * @param ph pseudonym handle to destroy | ||
205 | */ | ||
206 | void | ||
207 | GNUNET_PSEUDONYM_destroy (struct GNUNET_PseudonymHandle *ph); | ||
208 | |||
209 | |||
210 | /** | ||
211 | * Cryptographically sign some data with the pseudonym. | ||
212 | * | ||
213 | * @param ph private key used for signing (corresponds to 'x' in #2564) | ||
214 | * @param purpose data to sign | ||
215 | * @param seed hash of the plaintext of the data that we are signing, | ||
216 | * used for deterministic PRNG for anonymous signing; | ||
217 | * corresponds to 'k' in section 2.7 of #2564 | ||
218 | * @param signing_key modifier to apply to the private key for signing; | ||
219 | * corresponds to 'h' in section 2.3 of #2564. | ||
220 | * @param signature where to store the signature | ||
221 | * @return GNUNET_SYSERR on failure | ||
222 | */ | ||
223 | int | ||
224 | GNUNET_PSEUDONYM_sign (struct GNUNET_PseudonymHandle *ph, | ||
225 | const struct GNUNET_PseudonymSignaturePurpose *purpose, | ||
226 | const struct GNUNET_HashCode *seed, | ||
227 | const struct GNUNET_HashCode *signing_key, | ||
228 | struct GNUNET_PseudonymSignature *signature); | ||
229 | |||
230 | |||
231 | /** | ||
232 | * Given a pseudonym and a signing key, derive the corresponding public | ||
233 | * key that would be used to verify the resulting signature. | ||
234 | * | ||
235 | * @param pseudonym the public key (g^x in DSA, dQ in ECDSA) | ||
236 | * @param signing_key input to derive 'h' (see section 2.4 of #2564) | ||
237 | * @param verification_key resulting public key to verify the signature | ||
238 | * created from the 'ph' of 'pseudonym' and the 'signing_key'; | ||
239 | * the value stored here can then be given to GNUNET_PSEUDONYM_verify. | ||
240 | * @return GNUNET_OK on success, GNUNET_SYSERR on error | ||
241 | */ | ||
242 | int | ||
243 | GNUNET_PSEUDONYM_derive_verification_key (struct GNUNET_PseudonymIdentifier *pseudonym, | ||
244 | const struct GNUNET_HashCode *signing_key, | ||
245 | struct GNUNET_PseudonymIdentifier *verification_key); | ||
246 | |||
247 | |||
248 | /** | ||
249 | * Verify a signature made with a pseudonym. | ||
250 | * | ||
251 | * @param purpose data that was signed | ||
252 | * @param signature signature to verify | ||
253 | * @param verification_key public key to use for checking the signature; | ||
254 | * corresponds to 'g^(x+h)' in section 2.4 of #2564. | ||
255 | * @return GNUNET_OK on success (signature valid, 'pseudonym' set), | ||
256 | * GNUNET_SYSERR if the signature is invalid | ||
257 | */ | ||
258 | int | ||
259 | GNUNET_PSEUDONYM_verify (const struct GNUNET_PseudonymSignaturePurpose *purpose, | ||
260 | const struct GNUNET_PseudonymSignature *signature, | ||
261 | const struct GNUNET_PseudonymIdentifier *verification_key); | ||
262 | |||
263 | |||
264 | /** | ||
265 | * Get the identifier (public key) of a pseudonym. | ||
266 | * | ||
267 | * @param ph pseudonym handle with the private key | ||
268 | * @param pseudonym pseudonym identifier (set based on 'ph') | ||
269 | */ | ||
270 | void | ||
271 | GNUNET_PSEUDONYM_get_identifier (struct GNUNET_PseudonymHandle *ph, | ||
272 | struct GNUNET_PseudonymIdentifier *pseudonym); | ||
273 | |||
274 | |||
275 | |||
276 | /** | ||
277 | * Iterator over all known pseudonyms. | ||
278 | * | ||
279 | * @param cls closure | ||
280 | * @param pseudonym hash code of public key of pseudonym | ||
281 | * @param name name of the pseudonym (might be NULL) | ||
282 | * @param unique_name unique name of the pseudonym (might be NULL) | ||
283 | * @param md meta data known about the pseudonym | ||
284 | * @param rating the local rating of the pseudonym | ||
285 | * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort | ||
286 | */ | ||
287 | typedef int (*GNUNET_PSEUDONYM_Iterator) (void *cls, | ||
288 | const struct GNUNET_PseudonymIdentifier *pseudonym, | ||
289 | const char *name, | ||
290 | const char *unique_name, | ||
291 | const struct GNUNET_CONTAINER_MetaData *md, | ||
292 | int32_t rating); | ||
293 | |||
294 | |||
295 | /** | ||
296 | * Change the rank of a pseudonym. | ||
297 | * | ||
298 | * @param cfg overall configuration | ||
299 | * @param pseudonym identity of the pseudonym | ||
300 | * @param delta by how much should the rating be changed? | ||
301 | * @return new rating of the pseudonym | ||
302 | */ | ||
303 | int | ||
304 | GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
305 | const struct GNUNET_PseudonymIdentifier *pseudonym, | ||
306 | int32_t delta); | ||
307 | |||
308 | |||
309 | /** | ||
310 | * Add a pseudonym to the set of known pseudonyms. | ||
311 | * For all pseudonym advertisements that we discover | ||
312 | * FS should automatically call this function. | ||
313 | * | ||
314 | * @param cfg overall configuration | ||
315 | * @param pseudonym the pseudonym identifier | ||
316 | * @param meta metadata for the pseudonym | ||
317 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | ||
318 | */ | ||
319 | int | ||
320 | GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
321 | const struct GNUNET_PseudonymIdentifier *pseudonym, | ||
322 | const struct GNUNET_CONTAINER_MetaData *meta); | ||
323 | |||
324 | |||
325 | /** | ||
326 | * List all known pseudonyms. | ||
327 | * | ||
328 | * @param cfg overall configuration | ||
329 | * @param iterator function to call for each pseudonym | ||
330 | * @param iterator_cls closure for iterator | ||
331 | * @return number of pseudonyms found | ||
332 | */ | ||
333 | int | ||
334 | GNUNET_PSEUDONYM_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
335 | GNUNET_PSEUDONYM_Iterator iterator, | ||
336 | void *iterator_cls); | ||
337 | |||
338 | |||
339 | /** | ||
340 | * Handle for a discovery callback registration. | ||
341 | */ | ||
342 | struct GNUNET_PSEUDONYM_DiscoveryHandle; | ||
343 | |||
344 | |||
345 | /** | ||
346 | * Register callback to be invoked whenever we discover | ||
347 | * a new pseudonym. | ||
348 | * | ||
349 | * @param cfg our configuration | ||
350 | * @param iterator function to invoke on discovery | ||
351 | * @param iterator_cls closure for iterator | ||
352 | * @return registration handle | ||
353 | */ | ||
354 | struct GNUNET_PSEUDONYM_DiscoveryHandle * | ||
355 | GNUNET_PSEUDONYM_discovery_callback_register (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
356 | GNUNET_PSEUDONYM_Iterator iterator, | ||
357 | void *iterator_cls); | ||
358 | |||
359 | |||
360 | /** | ||
361 | * Unregister pseudonym discovery callback. | ||
362 | * | ||
363 | * @param dh registration to unregister | ||
364 | */ | ||
365 | void | ||
366 | GNUNET_PSEUDONYM_discovery_callback_unregister (struct GNUNET_PSEUDONYM_DiscoveryHandle *dh); | ||
367 | |||
368 | |||
369 | /** | ||
370 | * Return unique variant of the pseudonym name. Use after | ||
371 | * GNUNET_PSEUDONYM_id_to_name() to make sure that name is unique. | ||
372 | * | ||
373 | * @param cfg configuration | ||
374 | * @param pseudonym cryptographic ID of the pseudonym | ||
375 | * @param name name to uniquify | ||
376 | * @param suffix if not NULL, filled with the suffix value | ||
377 | * @return NULL on failure (should never happen), name on success. | ||
378 | * Free the name with GNUNET_free(). | ||
379 | */ | ||
380 | char * | ||
381 | GNUNET_PSEUDONYM_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
382 | const struct GNUNET_PseudonymIdentifier *pseudonym, | ||
383 | const char *name, | ||
384 | unsigned int *suffix); | ||
385 | |||
386 | |||
387 | /** | ||
388 | * Get pseudonym name, metadata and rank. This is a wrapper around | ||
389 | * internal read_info() call, and ensures that returned data is not | ||
390 | * invalid (not NULL). Writing back information returned by this | ||
391 | * function will give a name "no-name" to pseudonyms that have no | ||
392 | * name. This side-effect is unavoidable, but hardly harmful. | ||
393 | * | ||
394 | * @param cfg configuration | ||
395 | * @param pseudonym cryptographic ID of the pseudonym | ||
396 | * @param ret_meta a location to store metadata pointer. NULL, if metadata | ||
397 | * is not needed. Destroy with GNUNET_CONTAINER_meta_data_destroy(). | ||
398 | * @param ret_rank a location to store rank. NULL, if rank not needed. | ||
399 | * @param ret_name a location to store human-readable name. Name is not unique. | ||
400 | * NULL, if name is not needed. Free with GNUNET_free(). | ||
401 | * @param name_is_a_dup is set to GNUNET_YES, if ret_name was filled with | ||
402 | * a duplicate of a "no-name" placeholder | ||
403 | * @return GNUNET_OK on success. GNUENT_SYSERR if the data was | ||
404 | * unobtainable (in that case ret_* are filled with placeholders - | ||
405 | * empty metadata container, rank -1 and a "no-name" name). | ||
406 | */ | ||
407 | int | ||
408 | GNUNET_PSEUDONYM_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
409 | const struct GNUNET_PseudonymIdentifier *pseudonym, | ||
410 | struct GNUNET_CONTAINER_MetaData **ret_meta, | ||
411 | int32_t *ret_rank, | ||
412 | char **ret_name, | ||
413 | int *name_is_a_dup); | ||
414 | |||
415 | |||
416 | /** | ||
417 | * Get the pseudonym ID belonging to the given pseudonym name. | ||
418 | * | ||
419 | * @param cfg configuration to use | ||
420 | * @param ns_uname unique (!) human-readable name for the pseudonym | ||
421 | * @param pseudonym set to pseudonym ID based on 'ns_uname' | ||
422 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | ||
423 | */ | ||
424 | int | ||
425 | GNUNET_PSEUDONYM_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
426 | const char *ns_uname, | ||
427 | struct GNUNET_PseudonymIdentifier *pseudonym); | ||
428 | |||
429 | |||
430 | /** | ||
431 | * Set the pseudonym metadata, rank and name. | ||
432 | * | ||
433 | * @param cfg overall configuration | ||
434 | * @param pseudonym id of the pseudonym | ||
435 | * @param name name to set. Must be the non-unique version of it. | ||
436 | * May be NULL, in which case it erases pseudonym's name! | ||
437 | * @param md metadata to set | ||
438 | * May be NULL, in which case it erases pseudonym's metadata! | ||
439 | * @param rank rank to assign | ||
440 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | ||
441 | */ | ||
442 | int | ||
443 | GNUNET_PSEUDONYM_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
444 | const struct GNUNET_PseudonymIdentifier *pseudonym, | ||
445 | const char *name, | ||
446 | const struct GNUNET_CONTAINER_MetaData *md, | ||
447 | int32_t rank); | ||
448 | |||
449 | |||
450 | /** | ||
451 | * Remove pseudonym from the set of known pseudonyms. | ||
452 | * | ||
453 | * @param cfg overall configuration | ||
454 | * @param id the pseudonym identifier | ||
455 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | ||
456 | */ | ||
457 | int | ||
458 | GNUNET_PSEUDONYM_remove (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
459 | const struct GNUNET_PseudonymIdentifier *id); | ||
460 | |||
461 | |||
93 | /** | 462 | /** |
94 | * Get a unique key from a URI. This is for putting URIs | 463 | * Get a unique key from a URI. This is for putting URIs |
95 | * into HashMaps. The key may change between FS implementations. | 464 | * into HashMaps. The key may change between FS implementations. |
@@ -100,6 +469,7 @@ typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword, | |||
100 | void | 469 | void |
101 | GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, struct GNUNET_HashCode * key); | 470 | GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, struct GNUNET_HashCode * key); |
102 | 471 | ||
472 | |||
103 | /** | 473 | /** |
104 | * Convert a URI to a UTF-8 String. | 474 | * Convert a URI to a UTF-8 String. |
105 | * | 475 | * |
@@ -109,6 +479,7 @@ GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, struct GNUNET_HashCode * | |||
109 | char * | 479 | char * |
110 | GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri); | 480 | GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri); |
111 | 481 | ||
482 | |||
112 | /** | 483 | /** |
113 | * Convert keyword URI to a human readable format | 484 | * Convert keyword URI to a human readable format |
114 | * (i.e. the search query that was used in the first place) | 485 | * (i.e. the search query that was used in the first place) |