gnunet_hello_uri_lib.h (12585B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2022 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 HELLO URIs 28 * 29 * @defgroup hello_uri Hello_Uri library 30 * Helper library for handling HELLO URIs 31 * 32 * @{ 33 */ 34 35 #ifndef GNUNET_HELLO_URI_LIB_H 36 #define GNUNET_HELLO_URI_LIB_H 37 38 #ifdef __cplusplus 39 extern "C" { 40 #if 0 /* keep Emacsens' auto-indent happy */ 41 } 42 #endif 43 #endif 44 45 46 #include "gnunet_util_lib.h" 47 48 49 /** 50 * Context for building HELLOs. 51 */ 52 struct GNUNET_HELLO_Builder; 53 54 /** 55 * Context for parsing HELLOs. 56 */ 57 struct GNUNET_HELLO_Parser; 58 59 60 /** 61 * For how long are HELLO signatures valid? 62 */ 63 #define GNUNET_HELLO_ADDRESS_EXPIRATION GNUNET_TIME_relative_multiply ( \ 64 GNUNET_TIME_UNIT_DAYS, 2) 65 66 67 /** 68 * Allocate builder. 69 * 70 * @return new builder 71 */ 72 struct GNUNET_HELLO_Builder * 73 GNUNET_HELLO_builder_new (); 74 75 76 /** 77 * Allocate builder from parser. 78 * 79 * @param parser the parser 80 * @param pid the peer identity from the parsed hello 81 * @return new builder 82 */ 83 struct GNUNET_HELLO_Builder * 84 GNUNET_HELLO_builder_from_parser (const struct GNUNET_HELLO_Parser *parser, 85 struct GNUNET_PeerIdentity *pid); 86 87 /** 88 * Get the PeerIdentity for this builder. 89 */ 90 const struct GNUNET_PeerIdentity * 91 GNUNET_HELLO_parser_get_id (const struct GNUNET_HELLO_Parser *parser); 92 93 94 /** 95 * Release resources of a @a builder. 96 * 97 * @param[in] builder to free 98 */ 99 void 100 GNUNET_HELLO_builder_free (struct GNUNET_HELLO_Builder *builder); 101 102 /** 103 * Release resources of a @a builder. 104 * 105 * @param[in] builder to free 106 */ 107 void 108 GNUNET_HELLO_parser_free (struct GNUNET_HELLO_Parser *parser); 109 110 111 /** 112 * Parse @a msg. 113 * 114 * @param msg message to parse 115 * @return builder, NULL on failure 116 */ 117 struct GNUNET_HELLO_Parser * 118 GNUNET_HELLO_parser_from_msg (const struct GNUNET_MessageHeader *msg); 119 120 121 /** 122 * Parse @a block. 123 * 124 * @param block DHT block to parse 125 * @param block_size number of bytes in @a block 126 * @return parser, NULL on failure 127 */ 128 struct GNUNET_HELLO_Parser * 129 GNUNET_HELLO_parser_from_block (const void *block, 130 size_t block_size); 131 132 /** 133 * Parse @a block. Optionally Do not verify signature. 134 * 135 * @param block DHT block to parse 136 * @param block_size number of bytes in @a block 137 * @param noverify not verifying signature if #GNUNET_YES 138 * @return parser, NULL on failure 139 */ 140 struct GNUNET_HELLO_Parser * 141 GNUNET_HELLO_parser_from_block_ (const void *block, 142 size_t block_size, 143 int noverify); 144 145 /** 146 * Parse GNUnet HELLO @a url. 147 * 148 * @param url URL to parse 149 * @return builder, NULL on failure 150 */ 151 struct GNUNET_HELLO_Parser * 152 GNUNET_HELLO_parser_from_url (const char *url); 153 154 155 /** 156 * Get the expiration time for this HELLO. 157 * 158 * @param msg The hello msg. 159 * @return The expiration time. 160 */ 161 struct GNUNET_TIME_Absolute 162 GNUNET_HELLO_get_expiration_time_from_msg (const struct 163 GNUNET_MessageHeader *msg); 164 165 166 /** 167 * Generate envelope with GNUnet HELLO message (including 168 * peer ID) from a @a parser 169 * 170 * @param builder builder to serialize 171 * @return HELLO message matching @a parser 172 */ 173 struct GNUNET_MQ_Envelope * 174 GNUNET_HELLO_parser_to_env (const struct GNUNET_HELLO_Parser *parser); 175 176 177 /** 178 * Generate GNUnet HELLO URI from a @a parser 179 * 180 * @param parser HELLO parser to serialize 181 * @return hello URI 182 */ 183 char * 184 GNUNET_HELLO_parser_to_url (const struct GNUNET_HELLO_Parser *parser); 185 186 187 /** 188 * Generate DHT block from a @a parser 189 * 190 * @param builder the builder to serialize 191 * @param[out] block where to write the block, NULL to only calculate @a block_size 192 * @param[in,out] block_size input is number of bytes available in @a block, 193 * output is number of bytes needed in @a block 194 * @return #GNUNET_OK on success, #GNUNET_NO if @a block_size was too small 195 * or if @a block was NULL 196 */ 197 enum GNUNET_GenericReturnValue 198 GNUNET_HELLO_parser_to_block (const struct GNUNET_HELLO_Parser *parser, 199 void *block, size_t *block_size); 200 201 /** 202 * Add individual @a address to the @a builder 203 * 204 * @param[in,out] builder to update 205 * @param address address URI to add 206 * @return #GNUNET_OK on success, #GNUNET_NO if @a address was already 207 * in @a builder 208 */ 209 enum GNUNET_GenericReturnValue 210 GNUNET_HELLO_builder_add_address (struct GNUNET_HELLO_Builder *builder, 211 const char *address); 212 213 214 /** 215 * Remove individual @a address from the @a builder 216 * 217 * @param[in,out] builder to update 218 * @param address address URI to remove 219 * @return #GNUNET_OK on success, #GNUNET_NO if @a address was not 220 * in @a builder 221 */ 222 enum GNUNET_GenericReturnValue 223 GNUNET_HELLO_builder_del_address (struct GNUNET_HELLO_Builder *builder, 224 const char *address); 225 226 227 /** 228 * Callback function used to extract URIs from a builder. 229 * 230 * @param cls closure 231 * @param uri one of the URIs 232 */ 233 typedef void 234 (*GNUNET_HELLO_UriCallback) (void *cls, 235 const struct GNUNET_PeerIdentity *pid, 236 const char *uri); 237 238 239 /** 240 * Iterate over URIs in a builder. 241 * 242 * @param builder builder to iterate over 243 * @param uc callback invoked for each URI, can be NULL 244 * @param uc_cls closure for @a addrgen 245 * @return pid of the peer the @a builder is for, can be NULL 246 */ 247 void 248 GNUNET_HELLO_builder_iterate (const struct GNUNET_HELLO_Builder *builder, 249 GNUNET_HELLO_UriCallback uc, 250 void *uc_cls); 251 252 /** 253 * Iterate over URIs in a parser. 254 * 255 * @param builder builder to iterate over 256 * @param uc callback invoked for each URI, can be NULL 257 * @param uc_cls closure for @a addrgen 258 * @return pid of the peer the @a builder is for, can be NULL 259 */ 260 const struct GNUNET_PeerIdentity * 261 GNUNET_HELLO_parser_iterate (const struct GNUNET_HELLO_Parser *parser, 262 GNUNET_HELLO_UriCallback uc, 263 void *uc_cls); 264 265 266 /** 267 * Convert a DHT @a hello message to a HELLO @a block. 268 * 269 * @param hello the HELLO message 270 * @param pid peer that created the @a hello 271 * @param[out] block set to the HELLO block 272 * @param[out] block_size set to number of bytes in @a block 273 * @param[out] block_expiration set to expiration time of @a block 274 * @return #GNUNET_OK on success, 275 * #GNUNET_NO if the @a hello is expired (@a block is set!) 276 * #GNUNET_SYSERR if @a hello is invalid (@a block will be set to NULL) 277 */ 278 enum GNUNET_GenericReturnValue 279 GNUNET_HELLO_dht_msg_to_block (const struct GNUNET_MessageHeader *hello, 280 const struct GNUNET_PeerIdentity *pid, 281 void **block, 282 size_t *block_size, 283 struct GNUNET_TIME_Absolute *block_expiration); 284 285 286 /** 287 * Given an address as a string, extract the prefix that identifies 288 * the communicator offering transmissions to that address. 289 * 290 * @param address a peer's address 291 * @return NULL if the address is mal-formed, otherwise the prefix 292 */ 293 char * 294 GNUNET_HELLO_address_to_prefix (const char *address); 295 296 /** 297 * @param builder builder to serialize 298 * @param pid peer identity 299 * @param sig signature of the hello 300 * @param expiration_time expiration time 301 */ 302 enum GNUNET_GenericReturnValue 303 GNUNET_HELLO_build_url (const struct GNUNET_HELLO_Builder *builder, 304 const struct GNUNET_PeerIdentity *pid, 305 const struct GNUNET_CRYPTO_EddsaSignature *sig, 306 struct GNUNET_TIME_Absolute expiration, 307 char **result); 308 309 /** 310 * Generate DHT HELLO message (without peer ID) from a @a builder 311 * 312 * @param builder builder to serialize 313 * @param pid peer identity 314 * @param sig signature of the hello 315 * @param expiration_time expiration time 316 * @return handle to the message 317 */ 318 struct GNUNET_MessageHeader * 319 GNUNET_HELLO_builder_to_dht_hello_msg ( 320 const struct GNUNET_HELLO_Builder *builder, 321 const struct GNUNET_PeerIdentity *pid, 322 const struct GNUNET_CRYPTO_EddsaSignature *sig, 323 struct GNUNET_TIME_Absolute expiration_time); 324 325 /** 326 * Generate DHT HELLO message from a @a parser 327 * 328 * @param parser builder to serialize 329 * @return handle to the message 330 */ 331 struct GNUNET_MessageHeader * 332 GNUNET_HELLO_parser_to_dht_hello_msg ( 333 const struct GNUNET_HELLO_Parser *parser); 334 335 /** 336 * Generate DHT block from a @a builder 337 * 338 * @param builder builder to serialize 339 * @param pid peer identity 340 * @param sig signature of the hello 341 * @param expiration_time expiration time 342 * @param outbuf the buffer to the block 343 */ 344 void 345 GNUNET_HELLO_builder_to_block ( 346 const struct GNUNET_HELLO_Builder *builder, 347 const struct GNUNET_PeerIdentity *pid, 348 const struct GNUNET_CRYPTO_EddsaSignature *sig, 349 struct GNUNET_TIME_Absolute expiration_time, 350 char *outbuf); 351 352 /** 353 * Compute @a hash over addresses in @a builder. 354 * 355 * Note: Duplicate of hash_addresses in src/lib/hello/hello-uri.c 356 * 357 * @param builder the builder to hash addresses of 358 * @param[out] hash where to write the hash 359 */ 360 void 361 GNUNET_HELLO_builder_hash_addresses (const struct GNUNET_HELLO_Builder *builder, 362 struct GNUNET_HashCode *hash); 363 364 /** 365 * Generate envelope with GNUnet HELLO message (including 366 * peer ID) from a @a builder 367 * 368 * @param builder builder to serialize 369 * @param pid peer identity 370 * @param sig signature of the hello 371 * @param expiration_time expiration time 372 * @return HELLO message matching @a builder 373 */ 374 struct GNUNET_MQ_Envelope* 375 GNUNET_HELLO_builder_to_env ( 376 const struct GNUNET_HELLO_Builder *builder, 377 const struct GNUNET_PeerIdentity *pid, 378 const struct GNUNET_CRYPTO_EddsaSignature *sig, 379 struct GNUNET_TIME_Absolute expiration_time); 380 381 /** 382 * Get projected block size for builder 383 * 384 * @param builder builder to serialize 385 * @return block size 386 */ 387 size_t 388 GNUNET_HELLO_get_builder_to_block_size (const struct GNUNET_HELLO_Builder * 389 builder); 390 391 /** 392 * Generate GNUnet HELLO URI from a @a builder 393 * 394 * @param builder builder to serialize 395 * @param pid peer identity 396 * @param sig signature of the hello 397 * @return GNUNET_SYSERR on error 398 */ 399 enum GNUNET_GenericReturnValue 400 GNUNET_HELLO_builder_to_url ( 401 const struct GNUNET_HELLO_Builder *builder, 402 const struct GNUNET_PeerIdentity *pid, 403 const struct GNUNET_CRYPTO_EddsaSignature *sig, 404 char **result); 405 406 407 /** 408 * Generate GNUnet HELLO URI from a @a builder 409 * 410 * @param builder builder to serialize 411 * @param pid peer identity 412 * @param sig signature of the hello 413 * @param validity relative validity target of hello 414 * @return GNUNET_SYSERR on error 415 */ 416 enum GNUNET_GenericReturnValue 417 GNUNET_HELLO_builder_to_url2 ( 418 const struct GNUNET_HELLO_Builder *builder, 419 const struct GNUNET_PeerIdentity *pid, 420 const struct GNUNET_CRYPTO_EddsaSignature *sig, 421 struct GNUNET_TIME_Absolute validity, 422 char **result); 423 424 /** 425 * Compare address lists of two builders. 426 * Assumes that address lists are already sorted. 427 * Will also return GNUNET_YES if address lists 428 * are usorted, but values match! 429 * 430 * @param abuilder the first builder 431 * @param bbuilder the second builder 432 * @return GNUNET_YES if address lists are the same 433 */ 434 enum GNUNET_GenericReturnValue 435 GNUNET_HELLO_builder_address_list_cmp (const struct GNUNET_HELLO_Builder * 436 abuilder, 437 const struct GNUNET_HELLO_Builder * 438 bbuilder); 439 440 #if 0 /* keep Emacsens' auto-indent happy */ 441 { 442 #endif 443 #ifdef __cplusplus 444 } 445 #endif 446 447 /* ifndef GNUNET_HELLO_URI_LIB_H */ 448 #endif 449 450 /** @} */ /* end of group */ 451 452 /** @} */ /* end of group addition */ 453 454 /* end of gnunet_hello_uri_lib.h */