diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-02-23 12:56:17 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-02-23 12:56:17 +0000 |
commit | 27ee63d892f4cd54c785cd9b6082b4863b631284 (patch) | |
tree | 676d25c89d26d289bc923c761cbfdeef12e7f716 /src/include/gnunet_namestore_service.h | |
parent | 3d8f372adbd1f765b2c4e0fadb4d7152e9301588 (diff) | |
download | gnunet-27ee63d892f4cd54c785cd9b6082b4863b631284.tar.gz gnunet-27ee63d892f4cd54c785cd9b6082b4863b631284.zip |
-updated namestore API
Diffstat (limited to 'src/include/gnunet_namestore_service.h')
-rw-r--r-- | src/include/gnunet_namestore_service.h | 251 |
1 files changed, 115 insertions, 136 deletions
diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h index 894397543..51079fec8 100644 --- a/src/include/gnunet_namestore_service.h +++ b/src/include/gnunet_namestore_service.h | |||
@@ -127,44 +127,52 @@ enum GNUNET_NAMESTORE_RecordFlags | |||
127 | 127 | ||
128 | 128 | ||
129 | /** | 129 | /** |
130 | * Get the hash of a record | 130 | * A GNS record. |
131 | * | ||
132 | * @param zone hash of the public key of the zone | ||
133 | * @param name name that is being mapped (at most 255 characters long) | ||
134 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
135 | * @param expiration expiration time for the content | ||
136 | * @param flags flags for the content | ||
137 | * @param data_size number of bytes in data | ||
138 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
139 | * GNS specification for GNS extensions) | ||
140 | * @param record_hash hash of the record (set) | ||
141 | */ | 131 | */ |
142 | void | 132 | struct GNUNET_NAMESTORE_RecordData |
143 | GNUNET_NAMESTORE_record_hash (struct GNUNET_NAMESTORE_Handle *h, | 133 | { |
144 | const GNUNET_HashCode *zone, | 134 | |
145 | const char *name, | 135 | /** |
146 | uint32_t record_type, | 136 | * Binary value stored in the DNS record. |
147 | struct GNUNET_TIME_Absolute expiration, | 137 | */ |
148 | enum GNUNET_NAMESTORE_RecordFlags flags, | 138 | const void *data; |
149 | size_t data_size, | 139 | |
150 | const void *data, | 140 | /** |
151 | GNUNET_HashCode *record_hash); | 141 | * Expiration time for the DNS record. |
142 | */ | ||
143 | struct GNUNET_TIME_Absolute expiration; | ||
144 | |||
145 | /** | ||
146 | * Number of bytes in 'data'. | ||
147 | */ | ||
148 | size_t data_size; | ||
149 | |||
150 | /** | ||
151 | * Type of the GNS/DNS record. | ||
152 | */ | ||
153 | uint32_t record_type; | ||
154 | |||
155 | /** | ||
156 | * Flags for the record. | ||
157 | */ | ||
158 | enum GNUNET_NAMESTORE_RecordFlags flags; | ||
159 | }; | ||
152 | 160 | ||
153 | 161 | ||
154 | /** | 162 | /** |
155 | * Store an item in the namestore. If the item is already present, | 163 | * Store an item in the namestore. If the item is already present, |
156 | * the expiration time is updated to the max of the existing time and | 164 | * the expiration time is updated to the max of the existing time and |
157 | * the new time. | 165 | * the new time. This API is used when we cache signatures from other |
166 | * authorities. | ||
158 | * | 167 | * |
159 | * @param h handle to the namestore | 168 | * @param h handle to the namestore |
160 | * @param zone hash of the public key of the zone | 169 | * @param zone hash of the public key of the zone |
161 | * @param name name that is being mapped (at most 255 characters long) | 170 | * @param name name that is being mapped (at most 255 characters long) |
162 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | 171 | * @param expire when does the corresponding block in the DHT expire (until |
163 | * @param expiration expiration time for the content | 172 | * when should we never do a DHT lookup for the same name again)? |
164 | * @param flags flags for the content | 173 | * @param rd_count number of entries in 'rd' array |
165 | * @param data_size number of bytes in data | 174 | * @param rd array of records with data to store |
166 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | 175 | * @param signature signature for all the records in the zone under the given name |
167 | * GNS specification for GNS extensions) | ||
168 | * @param cont continuation to call when done | 176 | * @param cont continuation to call when done |
169 | * @param cont_cls closure for cont | 177 | * @param cont_cls closure for cont |
170 | * @return handle to abort the request | 178 | * @return handle to abort the request |
@@ -173,33 +181,53 @@ struct GNUNET_NAMESTORE_QueueEntry * | |||
173 | GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h, | 181 | GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h, |
174 | const GNUNET_HashCode *zone, | 182 | const GNUNET_HashCode *zone, |
175 | const char *name, | 183 | const char *name, |
176 | uint32_t record_type, | 184 | struct GNUNET_TIME_Absolute expire, |
177 | struct GNUNET_TIME_Absolute expiration, | 185 | unsigned int rd_count, |
178 | enum GNUNET_NAMESTORE_RecordFlags flags, | 186 | const struct GNUNET_NAMESTORE_RecordData *rd, |
179 | size_t data_size, | 187 | const struct GNUNET_CRYPTO_RsaSignature *signature, |
180 | const void *data, | ||
181 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | 188 | GNUNET_NAMESTORE_ContinuationWithStatus cont, |
182 | void *cont_cls); | 189 | void *cont_cls); |
183 | 190 | ||
191 | |||
192 | /** | ||
193 | * Check if a signature is valid. This API is used by the GNS Block | ||
194 | * to validate signatures received from the network. | ||
195 | * | ||
196 | * @param public_key public key of the zone | ||
197 | * @param name name that is being mapped (at most 255 characters long) | ||
198 | * @param rd_count number of entries in 'rd' array | ||
199 | * @param rd array of records with data to store | ||
200 | * @param signature signature for all the records in the zone under the given name | ||
201 | * @return GNUNET_OK if the signature is valid | ||
202 | */ | ||
203 | int | ||
204 | GNUNET_NAMESTORE_verify_signature (const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key, | ||
205 | const char *name, | ||
206 | unsigned int rd_count, | ||
207 | const struct GNUNET_NAMESTORE_RecordData *rd, | ||
208 | const struct GNUNET_CRYPTO_RsaSignature *signature); | ||
209 | |||
210 | |||
184 | /** | 211 | /** |
185 | * Store a signature for 'name' in the namestore. | 212 | * Store an item in the namestore. If the item is already present, |
186 | * Used by non-authorities to store signatures for cached name records. | 213 | * the expiration time is updated to the max of the existing time and |
214 | * the new time. This API is used by the authority of a zone. | ||
187 | * | 215 | * |
188 | * @param h handle to the namestore | 216 | * @param h handle to the namestore |
189 | * @param zone hash of the public key of the zone | 217 | * @param pkey private key of the zone |
190 | * @param name name that is being mapped (at most 255 characters long) | 218 | * @param name name that is being mapped (at most 255 characters long) |
191 | * @param sig the signature | 219 | * @param rd record data to store |
192 | * @param cont continuation to call when done | 220 | * @param cont continuation to call when done |
193 | * @param cont_cls closure for cont | 221 | * @param cont_cls closure for cont |
194 | * @return handle to abort the request | 222 | * @return handle to abort the request |
195 | */ | 223 | */ |
196 | struct GNUNET_NAMESTORE_QueueEntry * | 224 | struct GNUNET_NAMESTORE_QueueEntry * |
197 | GNUNET_NAMESTORE_signature_put (struct GNUNET_NAMESTORE_Handle *h, | 225 | GNUNET_NAMESTORE_record_create (struct GNUNET_NAMESTORE_Handle *h, |
198 | const GNUNET_HashCode *zone, | 226 | const struct GNUNET_CRYPTO_RsaPrivateKey *pkey, |
199 | const char *name, | 227 | const char *name, |
200 | struct GNUNET_CRYPTO_RsaSignature sig, | 228 | const struct GNUNET_NAMESTORE_RecordData *rd, |
201 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | 229 | GNUNET_NAMESTORE_ContinuationWithStatus cont, |
202 | void *cont_cls); | 230 | void *cont_cls); |
203 | 231 | ||
204 | 232 | ||
205 | /** | 233 | /** |
@@ -207,24 +235,21 @@ GNUNET_NAMESTORE_signature_put (struct GNUNET_NAMESTORE_Handle *h, | |||
207 | * "cont"inuation will be called with status "GNUNET_OK" if content | 235 | * "cont"inuation will be called with status "GNUNET_OK" if content |
208 | * was removed, "GNUNET_NO" if no matching entry was found and | 236 | * was removed, "GNUNET_NO" if no matching entry was found and |
209 | * "GNUNET_SYSERR" on all other types of errors. | 237 | * "GNUNET_SYSERR" on all other types of errors. |
238 | * This API is used by the authority of a zone. | ||
210 | * | 239 | * |
211 | * @param h handle to the namestore | 240 | * @param h handle to the namestore |
212 | * @param zone hash of the public key of the zone | 241 | * @param pkey private key of the zone |
213 | * @param name name that is being mapped (at most 255 characters long) | 242 | * @param name name that is being mapped (at most 255 characters long) |
214 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | 243 | * @param rd record data |
215 | * @param size number of bytes in data | ||
216 | * @param data content stored | ||
217 | * @param cont continuation to call when done | 244 | * @param cont continuation to call when done |
218 | * @param cont_cls closure for cont | 245 | * @param cont_cls closure for cont |
219 | * @return handle to abort the request | 246 | * @return handle to abort the request |
220 | */ | 247 | */ |
221 | struct GNUNET_NAMESTORE_QueueEntry * | 248 | struct GNUNET_NAMESTORE_QueueEntry * |
222 | GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h, | 249 | GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h, |
223 | const GNUNET_HashCode *zone, | 250 | const struct GNUNET_CRYPTO_RsaPrivateKey *pkey, |
224 | const char *name, | 251 | const char *name, |
225 | uint32_t record_type, | 252 | const struct GNUNET_NAMESTORE_RecordData *rd, |
226 | size_t size, | ||
227 | const void *data, | ||
228 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | 253 | GNUNET_NAMESTORE_ContinuationWithStatus cont, |
229 | void *cont_cls); | 254 | void *cont_cls); |
230 | 255 | ||
@@ -233,47 +258,34 @@ GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h, | |||
233 | * Process a record that was stored in the namestore. | 258 | * Process a record that was stored in the namestore. |
234 | * | 259 | * |
235 | * @param cls closure | 260 | * @param cls closure |
236 | * @param zone hash of the public key of the zone | 261 | * @param zone_key public key of the zone |
262 | * @param expire when does the corresponding block in the DHT expire (until | ||
263 | * when should we never do a DHT lookup for the same name again)? | ||
237 | * @param name name that is being mapped (at most 255 characters long) | 264 | * @param name name that is being mapped (at most 255 characters long) |
238 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | 265 | * @param rd_count number of entries in 'rd' array |
239 | * @param expiration expiration time for the content | 266 | * @param rd array of records with data to store |
240 | * @param flags flags for the content | 267 | * @param signature signature of the record block, NULL if signature is unavailable (i.e. |
241 | * @param size number of bytes in data | 268 | * because the user queried for a particular record type only) |
242 | * @param data content stored | ||
243 | */ | 269 | */ |
244 | typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls, | 270 | typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls, |
245 | const GNUNET_HashCode *zone, | 271 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, |
246 | const char *name, | 272 | struct GNUNET_TIME_Absolute expire, |
247 | uint32_t record_type, | 273 | const char *name, |
248 | struct GNUNET_TIME_Absolute expiration, | 274 | unsigned int rd_count, |
249 | enum GNUNET_NAMESTORE_RecordFlags flags, | 275 | const struct GNUNET_NAMESTORE_RecordData *rd, |
250 | size_t size, const void *data); | 276 | const struct GNUNET_CRYPTO_RsaSignature *signature); |
251 | |||
252 | /** | ||
253 | * Process a signature for a given name | ||
254 | * | ||
255 | * @param cls closure | ||
256 | * @param zone hash of the public key of the zone | ||
257 | * @param name name of the records that were signed | ||
258 | * @param sig the signature | ||
259 | */ | ||
260 | typedef void (*GNUNET_NAMESTORE_SignatureProcessor) (void *cls, | ||
261 | const GNUNET_HashCode *zone, | ||
262 | const char *name, | ||
263 | struct GNUNET_CRYPTO_RsaSignature sig); | ||
264 | |||
265 | 277 | ||
266 | 278 | ||
267 | /** | 279 | /** |
268 | * Get a result for a particular key from the namestore. The processor | 280 | * Get a result for a particular key from the namestore. The processor |
269 | * will only be called once. | 281 | * will only be called once. |
270 | * | 282 | * |
271 | * @param h handle to the namestore | 283 | * @param h handle to the namestore |
272 | * @param zone zone to look up a record from | 284 | * @param zone zone to look up a record from |
273 | * @param name name to look up | 285 | * @param name name to look up |
274 | * @param record_type desired record type | 286 | * @param record_type desired record type, 0 for all |
275 | * @param proc function to call on each matching value; | 287 | * @param proc function to call on the matching records, or with |
276 | * will be called once with a NULL value at the end | 288 | * NULL (rd_count == 0) if there are no matching records |
277 | * @param proc_cls closure for proc | 289 | * @param proc_cls closure for proc |
278 | * @return a handle that can be used to | 290 | * @return a handle that can be used to |
279 | * cancel | 291 | * cancel |
@@ -287,74 +299,41 @@ GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h, | |||
287 | 299 | ||
288 | 300 | ||
289 | /** | 301 | /** |
290 | * Obtain latest/current signature of a zone's name. The processor | 302 | * Starts a new zone iteration (used to periodically PUT all of our |
291 | * will only be called once. | 303 | * records into our DHT). This MUST lock the GNUNET_NAMESTORE_Handle |
292 | * | 304 | * for any other calls than GNUNET_NAMESTORE_zone_iterator_next and |
293 | * @param h handle to the namestore | 305 | * GNUNET_NAMESTORE_zone_iteration_stop. "proc" will be called once |
294 | * @param zone zone to look up a signature from | 306 | * immediately, and then again after |
295 | * @param the common name of the records the signature is for | 307 | * "GNUNET_NAMESTORE_zone_iterator_next" is invoked. |
296 | * @param proc function to call on each matching value; | ||
297 | * will be called once with a NULL value at the end | ||
298 | * @param proc_cls closure for proc | ||
299 | * @return a handle that can be used to | ||
300 | * cancel | ||
301 | */ | ||
302 | struct GNUNET_NAMESTORE_QueueEntry * | ||
303 | GNUNET_NAMESTORE_lookup_signature (struct GNUNET_NAMESTORE_Handle *h, | ||
304 | const GNUNET_HashCode *zone, | ||
305 | const char* name, | ||
306 | GNUNET_NAMESTORE_SignatureProcessor proc, void *proc_cls); | ||
307 | |||
308 | |||
309 | /** | ||
310 | * Get all records of a zone. | ||
311 | * | ||
312 | * @param h handle to the namestore | ||
313 | * @param zone zone to access | ||
314 | * @param proc function to call on a random value; it | ||
315 | * will be called repeatedly with a value (if available) | ||
316 | * and always once at the end with a zone and name of NULL. | ||
317 | * @param proc_cls closure for proc | ||
318 | * @return a handle that can be used to | ||
319 | * cancel | ||
320 | */ | ||
321 | struct GNUNET_NAMESTORE_QueueEntry * | ||
322 | GNUNET_NAMESTORE_zone_transfer (struct GNUNET_NAMESTORE_Handle *h, | ||
323 | const GNUNET_HashCode *zone, | ||
324 | GNUNET_NAMESTORE_RecordProcessor proc, | ||
325 | void *proc_cls); | ||
326 | |||
327 | |||
328 | /** | ||
329 | * Starts a new zone iteration. This MUST lock the GNUNET_NAMESTORE_Handle | ||
330 | * for any other calls than | ||
331 | * GNUNET_NAMESTORE_zone_iterator_next | ||
332 | * and | ||
333 | * GNUNET_NAMESTORE_zone_iteration_stop | ||
334 | * | 308 | * |
335 | * @param h handle to the namestore | 309 | * @param h handle to the namestore |
336 | * @param zone zone to access | 310 | * @param zone zone to access, NULL for all zones |
337 | * @param proc function to call on a random value; it | 311 | * @param must_have_flags flags that must be set for the record to be returned |
312 | * @param must_not_have_flags flags that must NOT be set for the record to be returned | ||
313 | * @param proc function to call on each name from the zone; it | ||
338 | * will be called repeatedly with a value (if available) | 314 | * will be called repeatedly with a value (if available) |
339 | * and always once at the end with a zone and name of NULL. | 315 | * and always once at the end with a name of NULL. |
340 | * @param proc_cls closure for proc | 316 | * @param proc_cls closure for proc |
341 | * @return an iterator handle to use for iteration | 317 | * @return an iterator handle to use for iteration |
342 | */ | 318 | */ |
343 | struct GNUNET_NAMESTORE_ZoneIterator * | 319 | struct GNUNET_NAMESTORE_ZoneIterator * |
344 | GNUNET_NAMESTORE_zone_iteration_start(struct GNUNET_NAMESTORE_Handle *h, | 320 | GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h, |
345 | const GNUNET_HashCode *zone, | 321 | const GNUNET_HashCode *zone, |
346 | GNUNET_NAMESTORE_RecordProcessor proc, | 322 | enum GNUNET_NAMESTORE_RecordFlags must_have_flags, |
347 | void *proc_cls); | 323 | enum GNUNET_NAMESTORE_RecordFlags must_not_have_flags, |
324 | GNUNET_NAMESTORE_RecordProcessor proc, | ||
325 | void *proc_cls); | ||
326 | |||
348 | 327 | ||
349 | /** | 328 | /** |
350 | * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start | 329 | * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start |
351 | * for the next record. | 330 | * for the next record. |
352 | * | 331 | * |
353 | * @param it the iterator | 332 | * @param it the iterator |
354 | * @return 0 if no more records are available to iterate | ||
355 | */ | 333 | */ |
356 | int | 334 | void |
357 | GNUNET_NAMESTORE_zone_iterator_next(struct GNUNET_NAMESTORE_ZoneIterator *it); | 335 | GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it); |
336 | |||
358 | 337 | ||
359 | /** | 338 | /** |
360 | * Stops iteration and releases the namestore handle for further calls. | 339 | * Stops iteration and releases the namestore handle for further calls. |
@@ -362,7 +341,7 @@ GNUNET_NAMESTORE_zone_iterator_next(struct GNUNET_NAMESTORE_ZoneIterator *it); | |||
362 | * @param it the iterator | 341 | * @param it the iterator |
363 | */ | 342 | */ |
364 | void | 343 | void |
365 | GNUNET_NAMESTORE_zone_iteration_stop(struct GNUNET_NAMESTORE_ZoneIterator *it); | 344 | GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it); |
366 | 345 | ||
367 | 346 | ||
368 | /** | 347 | /** |