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