gnunet_hello_uri_lib.h (10444B)
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 * @param pid peer the builder is for 71 * @return new builder 72 */ 73 struct GNUNET_HELLO_Builder * 74 GNUNET_HELLO_builder_new (const struct GNUNET_PeerIdentity *pid); 75 76 77 /** 78 * Allocate builder from parser. 79 * 80 * @param parser the parser 81 * @return new builder 82 */ 83 struct GNUNET_HELLO_Builder * 84 GNUNET_HELLO_builder_from_parser (const struct GNUNET_HELLO_Parser *parser); 85 86 /** 87 * Get the PeerIdentity for this builder. 88 */ 89 const struct GNUNET_PeerIdentity * 90 GNUNET_HELLO_parser_get_id (const struct GNUNET_HELLO_Parser *parser); 91 92 93 /** 94 * Release resources of a @a builder. 95 * 96 * @param[in] builder to free 97 */ 98 void 99 GNUNET_HELLO_builder_free (struct GNUNET_HELLO_Builder *builder); 100 101 /** 102 * Release resources of a @a builder. 103 * 104 * @param[in] builder to free 105 */ 106 void 107 GNUNET_HELLO_parser_free (struct GNUNET_HELLO_Parser *parser); 108 109 110 /** 111 * Parse @a msg. 112 * 113 * @param msg message to parse 114 * @return builder, NULL on failure 115 */ 116 struct GNUNET_HELLO_Parser * 117 GNUNET_HELLO_parser_from_msg (const struct GNUNET_MessageHeader *msg); 118 119 120 /** 121 * Parse @a block. 122 * 123 * @param block DHT block to parse 124 * @param block_size number of bytes in @a block 125 * @return builder, NULL on failure 126 */ 127 struct GNUNET_HELLO_Parser * 128 GNUNET_HELLO_parser_from_block (const void *block, 129 size_t block_size); 130 131 132 /** 133 * Parse GNUnet HELLO @a url. 134 * 135 * @param url URL to parse 136 * @return builder, NULL on failure 137 */ 138 struct GNUNET_HELLO_Parser * 139 GNUNET_HELLO_parser_from_url (const char *url); 140 141 142 /** 143 * Get the expiration time for this HELLO. 144 * 145 * @param msg The hello msg. 146 * @return The expiration time. 147 */ 148 struct GNUNET_TIME_Absolute 149 GNUNET_HELLO_get_expiration_time_from_msg (const struct 150 GNUNET_MessageHeader *msg); 151 152 153 /** 154 * Generate envelope with GNUnet HELLO message (including 155 * peer ID) from a @a builder 156 * 157 * @param builder builder to serialize 158 * @param priv private key to use to sign the result 159 * @return HELLO message matching @a builder 160 */ 161 struct GNUNET_MQ_Envelope * 162 GNUNET_HELLO_builder_to_env (const struct GNUNET_HELLO_Builder *builder, 163 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 164 struct GNUNET_TIME_Relative expiration_time); 165 166 167 /** 168 * Generate envelope with GNUnet HELLO message (including 169 * peer ID) from a @a parser 170 * 171 * @param builder builder to serialize 172 * @return HELLO message matching @a parser 173 */ 174 struct GNUNET_MQ_Envelope * 175 GNUNET_HELLO_parser_to_env (const struct GNUNET_HELLO_Parser *parser); 176 177 /** 178 * Generate DHT HELLO message (without peer ID) from a @a builder 179 * 180 * @param builder builder to serialize 181 * @param priv private key to use to sign the result 182 * @return HELLO message matching @a builder 183 */ 184 struct GNUNET_MessageHeader * 185 GNUNET_HELLO_builder_to_dht_hello_msg ( 186 const struct GNUNET_HELLO_Builder *builder, 187 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 188 struct GNUNET_TIME_Relative expiration_time); 189 190 /** 191 * Generate GNUnet HELLO URI from a @a parser 192 * 193 * @param parser HELLO parser to serialize 194 * @return hello URI 195 */ 196 char * 197 GNUNET_HELLO_parser_to_url (const struct GNUNET_HELLO_Parser *parser); 198 199 /** 200 * Generate GNUnet HELLO URI from a @a builder 201 * 202 * @param builder builder to serialize 203 * @param priv private key to use to sign the result 204 * @return hello URI 205 */ 206 char * 207 GNUNET_HELLO_builder_to_url (const struct GNUNET_HELLO_Builder *builder, 208 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv); 209 210 /** 211 * Generate GNUnet HELLO URI from a @a builder 212 * 213 * @param builder builder to serialize 214 * @param priv private key to use to sign the result 215 * @param expiration_time the expiration time to use. 216 * @return hello URI 217 */ 218 char * 219 GNUNET_HELLO_builder_to_url2 (const struct GNUNET_HELLO_Builder *builder, 220 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 221 struct GNUNET_TIME_Relative expiration_time); 222 223 /** 224 * Generate DHT block from a @a builder 225 * 226 * @param builder the builder to serialize 227 * @param priv private key to use to sign the result 228 * @param[out] block where to write the block, NULL to only calculate @a block_size 229 * @param[in,out] block_size input is number of bytes available in @a block, 230 * output is number of bytes needed in @a block 231 * @return #GNUNET_OK on success, #GNUNET_NO if @a block_size was too small 232 * or if @a block was NULL 233 */ 234 enum GNUNET_GenericReturnValue 235 GNUNET_HELLO_builder_to_block (const struct GNUNET_HELLO_Builder *builder, 236 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 237 void *block, 238 size_t *block_size, 239 struct GNUNET_TIME_Relative expiration_time); 240 241 242 /** 243 * Generate DHT block from a @a parser 244 * 245 * @param builder the builder to serialize 246 * @param[out] block where to write the block, NULL to only calculate @a block_size 247 * @param[in,out] block_size input is number of bytes available in @a block, 248 * output is number of bytes needed in @a block 249 * @return #GNUNET_OK on success, #GNUNET_NO if @a block_size was too small 250 * or if @a block was NULL 251 */ 252 enum GNUNET_GenericReturnValue 253 GNUNET_HELLO_parser_to_block(const struct GNUNET_HELLO_Parser *parser, 254 void *block, size_t *block_size); 255 256 /** 257 * Add individual @a address to the @a builder 258 * 259 * @param[in,out] builder to update 260 * @param address address URI to add 261 * @return #GNUNET_OK on success, #GNUNET_NO if @a address was already 262 * in @a builder 263 */ 264 enum GNUNET_GenericReturnValue 265 GNUNET_HELLO_builder_add_address (struct GNUNET_HELLO_Builder *builder, 266 const char *address); 267 268 269 /** 270 * Remove individual @a address from the @a builder 271 * 272 * @param[in,out] builder to update 273 * @param address address URI to remove 274 * @return #GNUNET_OK on success, #GNUNET_NO if @a address was not 275 * in @a builder 276 */ 277 enum GNUNET_GenericReturnValue 278 GNUNET_HELLO_builder_del_address (struct GNUNET_HELLO_Builder *builder, 279 const char *address); 280 281 282 /** 283 * Callback function used to extract URIs from a builder. 284 * 285 * @param cls closure 286 * @param uri one of the URIs 287 */ 288 typedef void 289 (*GNUNET_HELLO_UriCallback) (void *cls, 290 const struct GNUNET_PeerIdentity *pid, 291 const char *uri); 292 293 294 /** 295 * Iterate over URIs in a parser. 296 * 297 * @param builder builder to iterate over 298 * @param uc callback invoked for each URI, can be NULL 299 * @param uc_cls closure for @a addrgen 300 * @return pid of the peer the @a builder is for, can be NULL 301 */ 302 const struct GNUNET_PeerIdentity * 303 GNUNET_HELLO_parser_iterate (const struct GNUNET_HELLO_Parser *parser, 304 GNUNET_HELLO_UriCallback uc, 305 void *uc_cls); 306 307 308 /** 309 * Convert a DHT @a hello message to a HELLO @a block. 310 * 311 * @param hello the HELLO message 312 * @param pid peer that created the @a hello 313 * @param[out] block set to the HELLO block 314 * @param[out] block_size set to number of bytes in @a block 315 * @param[out] block_expiration set to expiration time of @a block 316 * @return #GNUNET_OK on success, 317 * #GNUNET_NO if the @a hello is expired (@a block is set!) 318 * #GNUNET_SYSERR if @a hello is invalid (@a block will be set to NULL) 319 */ 320 enum GNUNET_GenericReturnValue 321 GNUNET_HELLO_dht_msg_to_block (const struct GNUNET_MessageHeader *hello, 322 const struct GNUNET_PeerIdentity *pid, 323 void **block, 324 size_t *block_size, 325 struct GNUNET_TIME_Absolute *block_expiration); 326 327 328 /** 329 * Given an address as a string, extract the prefix that identifies 330 * the communicator offering transmissions to that address. 331 * 332 * @param address a peer's address 333 * @return NULL if the address is mal-formed, otherwise the prefix 334 */ 335 char * 336 GNUNET_HELLO_address_to_prefix (const char *address); 337 338 /** 339 * Build address record by signing raw information with private key. 340 * 341 * @param address text address to sign 342 * @param nt network type of @a address 343 * @param mono_time when was @a address valid 344 * @param private_key signing key to use 345 * @param[out] result where to write address record (allocated) 346 * @param[out] result_size set to size of @a result 347 */ 348 void 349 GNUNET_HELLO_sign_address ( 350 const char *address, 351 enum GNUNET_NetworkType nt, 352 struct GNUNET_TIME_Absolute mono_time, 353 const struct GNUNET_CRYPTO_EddsaPrivateKey *private_key, 354 void **result, 355 size_t *result_size); 356 357 #if 0 /* keep Emacsens' auto-indent happy */ 358 { 359 #endif 360 #ifdef __cplusplus 361 } 362 #endif 363 364 /* ifndef GNUNET_HELLO_URI_LIB_H */ 365 #endif 366 367 /** @} */ /* end of group */ 368 369 /** @} */ /* end of group addition */ 370 371 /* end of gnunet_hello_uri_lib.h */