gnunet_hello_uri_lib.h (8544B)
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 (or parsing) HELLO URIs. 51 */ 52 struct GNUNET_HELLO_Builder; 53 54 55 /** 56 * For how long are HELLO signatures valid? 57 */ 58 #define GNUNET_HELLO_ADDRESS_EXPIRATION GNUNET_TIME_relative_multiply ( \ 59 GNUNET_TIME_UNIT_DAYS, 2) 60 61 62 /** 63 * Allocate builder. 64 * 65 * @param pid peer the builder is for 66 * @return new builder 67 */ 68 struct GNUNET_HELLO_Builder * 69 GNUNET_HELLO_builder_new (const struct GNUNET_PeerIdentity *pid); 70 71 72 /** 73 * Get the PeerIdentity for this builder. 74 */ 75 const struct GNUNET_PeerIdentity * 76 GNUNET_HELLO_builder_get_id (const struct GNUNET_HELLO_Builder *builder); 77 78 79 /** 80 * Release resources of a @a builder. 81 * 82 * @param[in] builder to free 83 */ 84 void 85 GNUNET_HELLO_builder_free (struct GNUNET_HELLO_Builder *builder); 86 87 88 /** 89 * Parse @a msg into builder. 90 * 91 * @param msg message to parse 92 * @return builder, NULL on failure 93 */ 94 struct GNUNET_HELLO_Builder * 95 GNUNET_HELLO_builder_from_msg (const struct GNUNET_MessageHeader *msg); 96 97 98 /** 99 * Parse @a block into builder. 100 * 101 * @param block DHT block to parse 102 * @param block_size number of bytes in @a block 103 * @return builder, NULL on failure 104 */ 105 struct GNUNET_HELLO_Builder * 106 GNUNET_HELLO_builder_from_block (const void *block, 107 size_t block_size); 108 109 110 /** 111 * Parse GNUnet HELLO @a url into builder. 112 * 113 * @param url URL to parse 114 * @return builder, NULL on failure 115 */ 116 struct GNUNET_HELLO_Builder * 117 GNUNET_HELLO_builder_from_url (const char *url); 118 119 120 /** 121 * Get the expiration time for this HELLO. 122 * 123 * @param msg The hello msg. 124 * @return The expiration time. 125 */ 126 struct GNUNET_TIME_Absolute 127 GNUNET_HELLO_builder_get_expiration_time (const struct 128 GNUNET_MessageHeader *msg); 129 130 131 /** 132 * Generate envelope with GNUnet HELLO message (including 133 * peer ID) from a @a builder 134 * 135 * @param builder builder to serialize 136 * @param priv private key to use to sign the result 137 * @return HELLO message matching @a builder 138 */ 139 struct GNUNET_MQ_Envelope * 140 GNUNET_HELLO_builder_to_env (const struct GNUNET_HELLO_Builder *builder, 141 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 142 struct GNUNET_TIME_Relative expiration_time); 143 144 145 /** 146 * Generate DHT HELLO message (without peer ID) from a @a builder 147 * 148 * @param builder builder to serialize 149 * @param priv private key to use to sign the result 150 * @return HELLO message matching @a builder 151 */ 152 struct GNUNET_MessageHeader * 153 GNUNET_HELLO_builder_to_dht_hello_msg ( 154 const struct GNUNET_HELLO_Builder *builder, 155 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 156 struct GNUNET_TIME_Relative expiration_time); 157 158 159 /** 160 * Generate GNUnet HELLO URI from a @a builder 161 * 162 * @param builder builder to serialize 163 * @param priv private key to use to sign the result 164 * @return hello URI 165 */ 166 char * 167 GNUNET_HELLO_builder_to_url (const struct GNUNET_HELLO_Builder *builder, 168 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv); 169 170 /** 171 * Generate DHT block from a @a builder 172 * 173 * @param builder the builder to serialize 174 * @param priv private key to use to sign the result 175 * @param[out] block where to write the block, NULL to only calculate @a block_size 176 * @param[in,out] block_size input is number of bytes available in @a block, 177 * output is number of bytes needed in @a block 178 * @return #GNUNET_OK on success, #GNUNET_NO if @a block_size was too small 179 * or if @a block was NULL 180 */ 181 enum GNUNET_GenericReturnValue 182 GNUNET_HELLO_builder_to_block (const struct GNUNET_HELLO_Builder *builder, 183 const struct GNUNET_CRYPTO_EddsaPrivateKey *priv, 184 void *block, 185 size_t *block_size, 186 struct GNUNET_TIME_Relative expiration_time); 187 188 189 /** 190 * Add individual @a address to the @a builder 191 * 192 * @param[in,out] builder to update 193 * @param address address URI to add 194 * @return #GNUNET_OK on success, #GNUNET_NO if @a address was already 195 * in @a builder 196 */ 197 enum GNUNET_GenericReturnValue 198 GNUNET_HELLO_builder_add_address (struct GNUNET_HELLO_Builder *builder, 199 const char *address); 200 201 202 /** 203 * Remove individual @a address from the @a builder 204 * 205 * @param[in,out] builder to update 206 * @param address address URI to remove 207 * @return #GNUNET_OK on success, #GNUNET_NO if @a address was not 208 * in @a builder 209 */ 210 enum GNUNET_GenericReturnValue 211 GNUNET_HELLO_builder_del_address (struct GNUNET_HELLO_Builder *builder, 212 const char *address); 213 214 215 /** 216 * Callback function used to extract URIs from a builder. 217 * 218 * @param cls closure 219 * @param uri one of the URIs 220 */ 221 typedef void 222 (*GNUNET_HELLO_UriCallback) (void *cls, 223 const struct GNUNET_PeerIdentity* pid, 224 const char *uri); 225 226 227 /** 228 * Iterate over URIs in a builder. 229 * 230 * @param builder builder to iterate over 231 * @param uc callback invoked for each URI, can be NULL 232 * @param uc_cls closure for @a addrgen 233 * @return pid of the peer the @a builder is for, can be NULL 234 */ 235 const struct GNUNET_PeerIdentity * 236 GNUNET_HELLO_builder_iterate (const struct GNUNET_HELLO_Builder *builder, 237 GNUNET_HELLO_UriCallback uc, 238 void *uc_cls); 239 240 241 /** 242 * Convert a DHT @a hello message to a HELLO @a block. 243 * 244 * @param hello the HELLO message 245 * @param pid peer that created the @a hello 246 * @param[out] block set to the HELLO block 247 * @param[out] block_size set to number of bytes in @a block 248 * @param[out] block_expiration set to expiration time of @a block 249 * @return #GNUNET_OK on success, 250 * #GNUNET_NO if the @a hello is expired (@a block is set!) 251 * #GNUNET_SYSERR if @a hello is invalid (@a block will be set to NULL) 252 */ 253 enum GNUNET_GenericReturnValue 254 GNUNET_HELLO_dht_msg_to_block (const struct GNUNET_MessageHeader *hello, 255 const struct GNUNET_PeerIdentity *pid, 256 void **block, 257 size_t *block_size, 258 struct GNUNET_TIME_Absolute *block_expiration); 259 260 261 /** 262 * Given an address as a string, extract the prefix that identifies 263 * the communicator offering transmissions to that address. 264 * 265 * @param address a peer's address 266 * @return NULL if the address is mal-formed, otherwise the prefix 267 */ 268 char * 269 GNUNET_HELLO_address_to_prefix (const char *address); 270 271 /** 272 * Build address record by signing raw information with private key. 273 * 274 * @param address text address to sign 275 * @param nt network type of @a address 276 * @param mono_time when was @a address valid 277 * @param private_key signing key to use 278 * @param[out] result where to write address record (allocated) 279 * @param[out] result_size set to size of @a result 280 */ 281 void 282 GNUNET_HELLO_sign_address ( 283 const char *address, 284 enum GNUNET_NetworkType nt, 285 struct GNUNET_TIME_Absolute mono_time, 286 const struct GNUNET_CRYPTO_EddsaPrivateKey *private_key, 287 void **result, 288 size_t *result_size); 289 290 #if 0 /* keep Emacsens' auto-indent happy */ 291 { 292 #endif 293 #ifdef __cplusplus 294 } 295 #endif 296 297 /* ifndef GNUNET_HELLO_URI_LIB_H */ 298 #endif 299 300 /** @} */ /* end of group */ 301 302 /** @} */ /* end of group addition */ 303 304 /* end of gnunet_hello_uri_lib.h */