diff options
Diffstat (limited to 'src/include/gnunet_hello_lib.h')
-rw-r--r-- | src/include/gnunet_hello_lib.h | 545 |
1 files changed, 0 insertions, 545 deletions
diff --git a/src/include/gnunet_hello_lib.h b/src/include/gnunet_hello_lib.h deleted file mode 100644 index b57f48ac5..000000000 --- a/src/include/gnunet_hello_lib.h +++ /dev/null | |||
@@ -1,545 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2010, 2011 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @addtogroup Backbone | ||
23 | * @{ | ||
24 | * | ||
25 | * @author Christian Grothoff | ||
26 | * @file | ||
27 | * Helper library for handling HELLOs | ||
28 | * | ||
29 | * @defgroup hello Hello library | ||
30 | * Helper library for handling HELLOs | ||
31 | * | ||
32 | * @see [Documentation](https://gnunet.org/gnunets-hostlist-subsystem) | ||
33 | * | ||
34 | * @{ | ||
35 | */ | ||
36 | |||
37 | #ifndef GNUNET_HELLO_LIB_H | ||
38 | #define GNUNET_HELLO_LIB_H | ||
39 | |||
40 | #ifdef __cplusplus | ||
41 | extern "C" { | ||
42 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
43 | } | ||
44 | #endif | ||
45 | #endif | ||
46 | |||
47 | |||
48 | #include "gnunet_util_lib.h" | ||
49 | |||
50 | /** | ||
51 | * Prefix that every HELLO URI must start with. | ||
52 | */ | ||
53 | #define GNUNET_HELLO_URI_PREFIX "gnunet://hello/" | ||
54 | |||
55 | /** | ||
56 | * Prefix that every FRIEND HELLO URI must start with. | ||
57 | */ | ||
58 | #define GNUNET_FRIEND_HELLO_URI_PREFIX "gnunet://friend-hello/" | ||
59 | |||
60 | /** | ||
61 | * Separator used in HELLO URI | ||
62 | */ | ||
63 | #define GNUNET_HELLO_URI_SEP '+' | ||
64 | |||
65 | |||
66 | /** | ||
67 | * Additional local information about an address | ||
68 | * | ||
69 | * These information are only valid for the local peer and are not serialized | ||
70 | * when a #GNUNET_HELLO_Message is created | ||
71 | */ | ||
72 | enum GNUNET_HELLO_AddressInfo | ||
73 | { | ||
74 | /** | ||
75 | * No additional information | ||
76 | */ | ||
77 | GNUNET_HELLO_ADDRESS_INFO_NONE = 0, | ||
78 | |||
79 | /** | ||
80 | * This is an inbound address and cannot be used to initiate an outbound | ||
81 | * connection to another peer | ||
82 | */ | ||
83 | GNUNET_HELLO_ADDRESS_INFO_INBOUND = 1 | ||
84 | }; | ||
85 | |||
86 | |||
87 | /** | ||
88 | * An address for communicating with a peer. We frequently | ||
89 | * need this tuple and the components cannot really be | ||
90 | * separated. This is NOT the format that would be used | ||
91 | * on the wire. | ||
92 | */ | ||
93 | struct GNUNET_HELLO_Address | ||
94 | { | ||
95 | /** | ||
96 | * For which peer is this an address? | ||
97 | */ | ||
98 | struct GNUNET_PeerIdentity peer; | ||
99 | |||
100 | /** | ||
101 | * Name of the transport plugin enabling the communication using | ||
102 | * this address. | ||
103 | */ | ||
104 | const char *transport_name; | ||
105 | |||
106 | /** | ||
107 | * Binary representation of the address (plugin-specific). | ||
108 | */ | ||
109 | const void *address; | ||
110 | |||
111 | /** | ||
112 | * Number of bytes in @e address. | ||
113 | */ | ||
114 | size_t address_length; | ||
115 | |||
116 | /** | ||
117 | * Extended information about address | ||
118 | * | ||
119 | * This field contains additional #GNUNET_HELLO_AddressInfo flags e.g. | ||
120 | * to indicate an address is inbound and cannot be used to initiate an | ||
121 | * outbound connection. | ||
122 | * | ||
123 | * These information are only valid for the local peer and are not serialized | ||
124 | * when a #GNUNET_HELLO_Message is created | ||
125 | */ | ||
126 | enum GNUNET_HELLO_AddressInfo local_info; | ||
127 | }; | ||
128 | |||
129 | |||
130 | /** | ||
131 | * Allocate an address struct. | ||
132 | * | ||
133 | * @param peer the peer | ||
134 | * @param transport_name plugin name | ||
135 | * @param address binary address | ||
136 | * @param address_length number of bytes in @a address | ||
137 | * @param local_info additional local information for the address | ||
138 | * @return the address struct | ||
139 | */ | ||
140 | struct GNUNET_HELLO_Address * | ||
141 | GNUNET_HELLO_address_allocate (const struct GNUNET_PeerIdentity *peer, | ||
142 | const char *transport_name, | ||
143 | const void *address, | ||
144 | size_t address_length, | ||
145 | enum GNUNET_HELLO_AddressInfo local_info); | ||
146 | |||
147 | |||
148 | /** | ||
149 | * Copy an address struct. | ||
150 | * | ||
151 | * @param address address to copy | ||
152 | * @return a copy of the address struct | ||
153 | */ | ||
154 | struct GNUNET_HELLO_Address * | ||
155 | GNUNET_HELLO_address_copy (const struct GNUNET_HELLO_Address *address); | ||
156 | |||
157 | |||
158 | /** | ||
159 | * Compare two addresses. Does NOT compare the peer identity, | ||
160 | * that is assumed already to match! | ||
161 | * | ||
162 | * @param a1 first address | ||
163 | * @param a2 second address | ||
164 | * @return 0 if the addresses are equal, -1 if @a a1< @a a2, 1 if @a a1> @a a2. | ||
165 | */ | ||
166 | int | ||
167 | GNUNET_HELLO_address_cmp (const struct GNUNET_HELLO_Address *a1, | ||
168 | const struct GNUNET_HELLO_Address *a2); | ||
169 | |||
170 | |||
171 | /** | ||
172 | * Get the size of an address struct. | ||
173 | * | ||
174 | * @param address address | ||
175 | * @return the size | ||
176 | */ | ||
177 | size_t | ||
178 | GNUNET_HELLO_address_get_size (const struct GNUNET_HELLO_Address *address); | ||
179 | |||
180 | |||
181 | /** | ||
182 | * Check if an address has a local option set | ||
183 | * | ||
184 | * @param address the address to check | ||
185 | * @param option the respective option to check for | ||
186 | * @return #GNUNET_YES or #GNUNET_NO | ||
187 | */ | ||
188 | int | ||
189 | GNUNET_HELLO_address_check_option (const struct GNUNET_HELLO_Address *address, | ||
190 | enum GNUNET_HELLO_AddressInfo option); | ||
191 | |||
192 | |||
193 | /** | ||
194 | * Free an address. | ||
195 | * | ||
196 | * @param addr address to free | ||
197 | */ | ||
198 | #define GNUNET_HELLO_address_free(addr) GNUNET_free (addr) | ||
199 | |||
200 | |||
201 | GNUNET_NETWORK_STRUCT_BEGIN | ||
202 | |||
203 | /** | ||
204 | * A HELLO message is used to exchange information about | ||
205 | * transports with other peers. This struct is always | ||
206 | * followed by the actual network addresses which have | ||
207 | * the format: | ||
208 | * | ||
209 | * 1) transport-name (0-terminated) | ||
210 | * 2) address-length (uint16_t, network byte order; possibly | ||
211 | * unaligned!) | ||
212 | * 3) address expiration (`struct GNUNET_TIME_AbsoluteNBO`); possibly | ||
213 | * unaligned!) | ||
214 | * 4) address (address-length bytes; possibly unaligned!) | ||
215 | */ | ||
216 | struct GNUNET_HELLO_Message | ||
217 | { | ||
218 | /** | ||
219 | * Type will be #GNUNET_MESSAGE_TYPE_HELLO. | ||
220 | */ | ||
221 | struct GNUNET_MessageHeader header; | ||
222 | |||
223 | /** | ||
224 | * Use in F2F mode: Do not gossip this HELLO message | ||
225 | */ | ||
226 | uint32_t friend_only GNUNET_PACKED; | ||
227 | |||
228 | /** | ||
229 | * The public key of the peer. | ||
230 | */ | ||
231 | struct GNUNET_CRYPTO_EddsaPublicKey publicKey; | ||
232 | }; | ||
233 | GNUNET_NETWORK_STRUCT_END | ||
234 | |||
235 | |||
236 | /** | ||
237 | * Return HELLO type | ||
238 | * | ||
239 | * @param h HELLO Message to test | ||
240 | * @return #GNUNET_YES for friend-only or #GNUNET_NO otherwise | ||
241 | */ | ||
242 | int | ||
243 | GNUNET_HELLO_is_friend_only (const struct GNUNET_HELLO_Message *h); | ||
244 | |||
245 | |||
246 | /** | ||
247 | * Copy the given address information into | ||
248 | * the given buffer using the format of HELLOs. | ||
249 | * | ||
250 | * @param address address to add | ||
251 | * @param expiration expiration for the address | ||
252 | * @param target where to copy the address | ||
253 | * @param max maximum number of bytes to copy to @a target | ||
254 | * @return number of bytes copied, 0 if | ||
255 | * the target buffer was not big enough. | ||
256 | */ | ||
257 | size_t | ||
258 | GNUNET_HELLO_add_address (const struct GNUNET_HELLO_Address *address, | ||
259 | struct GNUNET_TIME_Absolute expiration, | ||
260 | char *target, | ||
261 | size_t max); | ||
262 | |||
263 | |||
264 | /** | ||
265 | * Callback function used to fill a buffer of max bytes with a list of | ||
266 | * addresses in the format used by HELLOs. Should use | ||
267 | * #GNUNET_HELLO_add_address() as a helper function. | ||
268 | * | ||
269 | * @param cls closure | ||
270 | * @param max maximum number of bytes that can be written to @a buf | ||
271 | * @param buf where to write the address information | ||
272 | * @return number of bytes written or 0, #GNUNET_SYSERR to signal the | ||
273 | * end of the iteration. | ||
274 | */ | ||
275 | typedef ssize_t | ||
276 | (*GNUNET_HELLO_GenerateAddressListCallback) (void *cls, | ||
277 | size_t max, | ||
278 | void *buf); | ||
279 | |||
280 | |||
281 | /** | ||
282 | * Construct a HELLO message given the public key, | ||
283 | * expiration time and an iterator that spews the | ||
284 | * transport addresses. | ||
285 | * | ||
286 | * If friend only is set to #GNUNET_YES we create a FRIEND_HELLO which | ||
287 | * will not be gossiped to other peers. | ||
288 | * | ||
289 | * @param public_key public key to include in the HELLO | ||
290 | * @param addrgen callback to invoke to get addresses | ||
291 | * @param addrgen_cls closure for @a addrgen | ||
292 | * @param friend_only should the returned HELLO be only visible to friends? | ||
293 | * @return the hello message | ||
294 | */ | ||
295 | struct GNUNET_HELLO_Message * | ||
296 | GNUNET_HELLO_create (const struct GNUNET_CRYPTO_EddsaPublicKey *public_key, | ||
297 | GNUNET_HELLO_GenerateAddressListCallback addrgen, | ||
298 | void *addrgen_cls, | ||
299 | int friend_only); | ||
300 | |||
301 | |||
302 | /** | ||
303 | * Return the size of the given HELLO message. | ||
304 | * | ||
305 | * @param hello to inspect | ||
306 | * @return the size, 0 if HELLO is invalid | ||
307 | */ | ||
308 | uint16_t | ||
309 | GNUNET_HELLO_size (const struct GNUNET_HELLO_Message *hello); | ||
310 | |||
311 | |||
312 | /** | ||
313 | * Construct a HELLO message by merging the | ||
314 | * addresses in two existing HELLOs (which | ||
315 | * must be for the same peer). | ||
316 | * | ||
317 | * @param h1 first HELLO message | ||
318 | * @param h2 the second HELLO message | ||
319 | * @return the combined hello message | ||
320 | */ | ||
321 | struct GNUNET_HELLO_Message * | ||
322 | GNUNET_HELLO_merge (const struct GNUNET_HELLO_Message *h1, | ||
323 | const struct GNUNET_HELLO_Message *h2); | ||
324 | |||
325 | |||
326 | /** | ||
327 | * Test if two HELLO messages contain the same addresses. | ||
328 | * If they only differ in expiration time, the lowest | ||
329 | * expiration time larger than 'now' where they differ | ||
330 | * is returned. | ||
331 | * | ||
332 | * @param h1 first HELLO message | ||
333 | * @param h2 the second HELLO message | ||
334 | * @param now time to use for deciding which addresses have | ||
335 | * expired and should not be considered at all | ||
336 | * @return absolute time forever if the two HELLOs are | ||
337 | * totally identical; smallest timestamp >= now if | ||
338 | * they only differ in timestamps; | ||
339 | * zero if the some addresses with expirations >= now | ||
340 | * do not match at all | ||
341 | */ | ||
342 | struct GNUNET_TIME_Absolute | ||
343 | GNUNET_HELLO_equals (const struct GNUNET_HELLO_Message *h1, | ||
344 | const struct GNUNET_HELLO_Message *h2, | ||
345 | struct GNUNET_TIME_Absolute now); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Iterator callback to go over all addresses. | ||
350 | * | ||
351 | * @param cls closure | ||
352 | * @param address the address | ||
353 | * @param expiration expiration time | ||
354 | * @return #GNUNET_OK to keep the address, | ||
355 | * #GNUNET_NO to delete it from the HELLO | ||
356 | * #GNUNET_SYSERR to stop iterating (but keep current address) | ||
357 | */ | ||
358 | typedef int (*GNUNET_HELLO_AddressIterator) ( | ||
359 | void *cls, | ||
360 | const struct GNUNET_HELLO_Address *address, | ||
361 | struct GNUNET_TIME_Absolute expiration); | ||
362 | |||
363 | |||
364 | /** | ||
365 | * When does the last address in the given HELLO expire? | ||
366 | * | ||
367 | * @param msg HELLO to inspect | ||
368 | * @return time the last address expires, 0 if there are no addresses in the HELLO | ||
369 | */ | ||
370 | struct GNUNET_TIME_Absolute | ||
371 | GNUNET_HELLO_get_last_expiration (const struct GNUNET_HELLO_Message *msg); | ||
372 | |||
373 | |||
374 | /** | ||
375 | * Iterate over all of the addresses in the HELLO. | ||
376 | * | ||
377 | * @param msg HELLO to iterate over; client does not need to | ||
378 | * have verified that msg is well-formed (beyond starting | ||
379 | * with a GNUNET_MessageHeader of the right type). | ||
380 | * @param return_modified if a modified copy should be returned, | ||
381 | * otherwise NULL will be returned | ||
382 | * @param it iterator to call on each address | ||
383 | * @param it_cls closure for @a it | ||
384 | * @return the modified HELLO or NULL | ||
385 | */ | ||
386 | struct GNUNET_HELLO_Message * | ||
387 | GNUNET_HELLO_iterate_addresses (const struct GNUNET_HELLO_Message *msg, | ||
388 | int return_modified, | ||
389 | GNUNET_HELLO_AddressIterator it, | ||
390 | void *it_cls); | ||
391 | |||
392 | |||
393 | /** | ||
394 | * Iterate over addresses in @a new_hello that are NOT already present | ||
395 | * in @a old_hello. Note that if the address is present in @a old_hello | ||
396 | * but the expiration time in @a new_hello is more recent, the | ||
397 | * iterator is also called. | ||
398 | * | ||
399 | * @param new_hello a HELLO message | ||
400 | * @param old_hello a HELLO message | ||
401 | * @param expiration_limit ignore addresses in old_hello | ||
402 | * that expired before the given time stamp | ||
403 | * @param it iterator to call on each address | ||
404 | * @param it_cls closure for @a it | ||
405 | */ | ||
406 | void | ||
407 | GNUNET_HELLO_iterate_new_addresses ( | ||
408 | const struct GNUNET_HELLO_Message *new_hello, | ||
409 | const struct GNUNET_HELLO_Message *old_hello, | ||
410 | struct GNUNET_TIME_Absolute expiration_limit, | ||
411 | GNUNET_HELLO_AddressIterator it, | ||
412 | void *it_cls); | ||
413 | |||
414 | |||
415 | /** | ||
416 | * Get the peer identity from a HELLO message. | ||
417 | * | ||
418 | * @param hello the hello message | ||
419 | * @param peer where to store the peer's identity | ||
420 | * @return #GNUNET_SYSERR if the HELLO was malformed | ||
421 | */ | ||
422 | int | ||
423 | GNUNET_HELLO_get_id (const struct GNUNET_HELLO_Message *hello, | ||
424 | struct GNUNET_PeerIdentity *peer); | ||
425 | |||
426 | |||
427 | /** | ||
428 | * Get the header from a HELLO message, used so other code | ||
429 | * can correctly send HELLO messages. | ||
430 | * | ||
431 | * @param hello the hello message | ||
432 | * | ||
433 | * @return header or NULL if the HELLO was malformed | ||
434 | */ | ||
435 | struct GNUNET_MessageHeader * | ||
436 | GNUNET_HELLO_get_header (struct GNUNET_HELLO_Message *hello); | ||
437 | |||
438 | |||
439 | /** | ||
440 | * Helper function to load/access transport plugins. | ||
441 | * FIXME: pass closure! | ||
442 | * | ||
443 | * @param name name of the transport plugin to load | ||
444 | * @return NULL if a plugin with name @a name is not known/loadable | ||
445 | */ | ||
446 | typedef struct GNUNET_TRANSPORT_PluginFunctions *( | ||
447 | *GNUNET_HELLO_TransportPluginsFind) (const char *name); | ||
448 | |||
449 | |||
450 | /** | ||
451 | * Compose a hello URI string from a hello message. | ||
452 | * | ||
453 | * @param hello Hello message | ||
454 | * @param plugins_find Function to find transport plugins by name | ||
455 | * @return Hello URI string | ||
456 | */ | ||
457 | char * | ||
458 | GNUNET_HELLO_compose_uri (const struct GNUNET_HELLO_Message *hello, | ||
459 | GNUNET_HELLO_TransportPluginsFind plugins_find); | ||
460 | |||
461 | |||
462 | /** | ||
463 | * Parse a hello URI string to a hello message. | ||
464 | * | ||
465 | * @param uri URI string to parse | ||
466 | * @param pubkey Pointer to struct where public key is parsed | ||
467 | * @param hello Pointer to struct where hello message is parsed | ||
468 | * @param plugins_find Function to find transport plugins by name | ||
469 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if the URI was invalid, #GNUNET_NO on other errors | ||
470 | */ | ||
471 | int | ||
472 | GNUNET_HELLO_parse_uri (const char *uri, | ||
473 | struct GNUNET_CRYPTO_EddsaPublicKey *pubkey, | ||
474 | struct GNUNET_HELLO_Message **hello, | ||
475 | GNUNET_HELLO_TransportPluginsFind plugins_find); | ||
476 | |||
477 | |||
478 | /* NG API */ | ||
479 | #include "gnunet_util_lib.h" | ||
480 | |||
481 | |||
482 | /** | ||
483 | * Build address record by signing raw information with private key. | ||
484 | * | ||
485 | * @param address text address to sign | ||
486 | * @param nt network type of @a address | ||
487 | * @param mono_time when was @a address valid | ||
488 | * @param private_key signing key to use | ||
489 | * @param[out] result where to write address record (allocated) | ||
490 | * @param[out] result_size set to size of @a result | ||
491 | */ | ||
492 | void | ||
493 | GNUNET_HELLO_sign_address ( | ||
494 | const char *address, | ||
495 | enum GNUNET_NetworkType nt, | ||
496 | struct GNUNET_TIME_Absolute mono_time, | ||
497 | const struct GNUNET_CRYPTO_EddsaPrivateKey *private_key, | ||
498 | void **result, | ||
499 | size_t *result_size); | ||
500 | |||
501 | |||
502 | /** | ||
503 | * Check signature and extract address record. | ||
504 | * | ||
505 | * @param raw raw signed address | ||
506 | * @param raw_size size of @a raw | ||
507 | * @param pid public key to use for signature verification | ||
508 | * @param[out] nt set to network type | ||
509 | * @param[out] mono_time when was the address generated | ||
510 | * @return NULL on error, otherwise the address | ||
511 | */ | ||
512 | char * | ||
513 | GNUNET_HELLO_extract_address (const void *raw, | ||
514 | size_t raw_size, | ||
515 | const struct GNUNET_PeerIdentity *pid, | ||
516 | enum GNUNET_NetworkType *nt, | ||
517 | struct GNUNET_TIME_Absolute *mono_time); | ||
518 | |||
519 | |||
520 | /** | ||
521 | * Given an address as a string, extract the prefix that identifies | ||
522 | * the communicator offering transmissions to that address. | ||
523 | * | ||
524 | * @param address a peer's address | ||
525 | * @return NULL if the address is mal-formed, otherwise the prefix | ||
526 | */ | ||
527 | char * | ||
528 | GNUNET_HELLO_address_to_prefix (const char *address); | ||
529 | |||
530 | |||
531 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
532 | { | ||
533 | #endif | ||
534 | #ifdef __cplusplus | ||
535 | } | ||
536 | #endif | ||
537 | |||
538 | /* ifndef GNUNET_HELLO_LIB_H */ | ||
539 | #endif | ||
540 | |||
541 | /** @} */ /* end of group */ | ||
542 | |||
543 | /** @} */ /* end of group addition */ | ||
544 | |||
545 | /* end of gnunet_hello_lib.h */ | ||