diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-10-16 20:14:02 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-10-16 20:14:02 +0000 |
commit | 3d670727232e79b7e49a1df7ba9260db4e5798a0 (patch) | |
tree | 093f7b5aec28134dc6c5fe34cd2d8bfb1e1445ad /src/include/gnunet_gnsrecord_lib.h | |
parent | 2de26776993a5e591e487321a5dc1d62b86d9cd4 (diff) | |
download | gnunet-3d670727232e79b7e49a1df7ba9260db4e5798a0.tar.gz gnunet-3d670727232e79b7e49a1df7ba9260db4e5798a0.zip |
-moving namestore_common functions to gnsrecord library
Diffstat (limited to 'src/include/gnunet_gnsrecord_lib.h')
-rw-r--r-- | src/include/gnunet_gnsrecord_lib.h | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/src/include/gnunet_gnsrecord_lib.h b/src/include/gnunet_gnsrecord_lib.h index 2c8d73415..aefdeb4a4 100644 --- a/src/include/gnunet_gnsrecord_lib.h +++ b/src/include/gnunet_gnsrecord_lib.h | |||
@@ -34,6 +34,11 @@ extern "C" | |||
34 | #endif | 34 | #endif |
35 | #endif | 35 | #endif |
36 | 36 | ||
37 | /** | ||
38 | * Maximum size of a value that can be stored in a GNS block. | ||
39 | */ | ||
40 | #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024) | ||
41 | |||
37 | 42 | ||
38 | /** | 43 | /** |
39 | * Record type indicating any record/'*' | 44 | * Record type indicating any record/'*' |
@@ -76,6 +81,144 @@ extern "C" | |||
76 | #define GNUNET_GNSRECORD_TYPE_PHONE 65542 | 81 | #define GNUNET_GNSRECORD_TYPE_PHONE 65542 |
77 | 82 | ||
78 | 83 | ||
84 | /** | ||
85 | * Flags that can be set for a record. | ||
86 | */ | ||
87 | enum GNUNET_NAMESTORE_RecordFlags | ||
88 | { | ||
89 | |||
90 | /** | ||
91 | * No special options. | ||
92 | */ | ||
93 | GNUNET_NAMESTORE_RF_NONE = 0, | ||
94 | |||
95 | /** | ||
96 | * This is a private record of this peer and it should | ||
97 | * thus not be handed out to other peers. | ||
98 | */ | ||
99 | GNUNET_NAMESTORE_RF_PRIVATE = 2, | ||
100 | |||
101 | /** | ||
102 | * This record was added automatically by the system | ||
103 | * and is pending user confimation. | ||
104 | */ | ||
105 | GNUNET_NAMESTORE_RF_PENDING = 4, | ||
106 | |||
107 | /** | ||
108 | * This expiration time of the record is a relative | ||
109 | * time (not an absolute time). | ||
110 | */ | ||
111 | GNUNET_NAMESTORE_RF_RELATIVE_EXPIRATION = 8, | ||
112 | |||
113 | /** | ||
114 | * This record should not be used unless all (other) records with an absolute | ||
115 | * expiration time have expired. | ||
116 | */ | ||
117 | GNUNET_NAMESTORE_RF_SHADOW_RECORD = 16 | ||
118 | |||
119 | /** | ||
120 | * When comparing flags for record equality for removal, | ||
121 | * which flags should must match (in addition to the type, | ||
122 | * name, expiration value and data of the record)? All flags | ||
123 | * that are not listed here will be ignored for this purpose. | ||
124 | * (for example, we don't expect that users will remember to | ||
125 | * pass the '--private' option when removing a record from | ||
126 | * the namestore, hence we don't require this particular option | ||
127 | * to match upon removal). See also | ||
128 | * #GNUNET_NAMESTORE_records_cmp. | ||
129 | */ | ||
130 | #define GNUNET_NAMESTORE_RF_RCMP_FLAGS (GNUNET_NAMESTORE_RF_RELATIVE_EXPIRATION) | ||
131 | }; | ||
132 | |||
133 | |||
134 | /** | ||
135 | * A GNS record. | ||
136 | */ | ||
137 | struct GNUNET_NAMESTORE_RecordData | ||
138 | { | ||
139 | |||
140 | /** | ||
141 | * Binary value stored in the DNS record. Note: "data" must never | ||
142 | * be individually 'malloc'ed, but instead always points into some | ||
143 | * existing data area. | ||
144 | */ | ||
145 | const void *data; | ||
146 | |||
147 | /** | ||
148 | * Expiration time for the DNS record. Can be relative | ||
149 | * or absolute, depending on 'flags'. Measured in the same | ||
150 | * unit as GNUnet time (microseconds). | ||
151 | */ | ||
152 | uint64_t expiration_time; | ||
153 | |||
154 | /** | ||
155 | * Number of bytes in 'data'. | ||
156 | */ | ||
157 | size_t data_size; | ||
158 | |||
159 | /** | ||
160 | * Type of the GNS/DNS record. | ||
161 | */ | ||
162 | uint32_t record_type; | ||
163 | |||
164 | /** | ||
165 | * Flags for the record. | ||
166 | */ | ||
167 | enum GNUNET_NAMESTORE_RecordFlags flags; | ||
168 | }; | ||
169 | |||
170 | |||
171 | |||
172 | GNUNET_NETWORK_STRUCT_BEGIN | ||
173 | |||
174 | |||
175 | /** | ||
176 | * Information we have in an encrypted block with record data (i.e. in the DHT). | ||
177 | */ | ||
178 | struct GNUNET_NAMESTORE_Block | ||
179 | { | ||
180 | |||
181 | /** | ||
182 | * Signature of the block. | ||
183 | */ | ||
184 | struct GNUNET_CRYPTO_EcdsaSignature signature; | ||
185 | |||
186 | /** | ||
187 | * Derived key used for signing; hash of this is the query. | ||
188 | */ | ||
189 | struct GNUNET_CRYPTO_EcdsaPublicKey derived_key; | ||
190 | |||
191 | /** | ||
192 | * Number of bytes signed; also specifies the number of bytes | ||
193 | * of encrypted data that follow. | ||
194 | */ | ||
195 | struct GNUNET_CRYPTO_EccSignaturePurpose purpose; | ||
196 | |||
197 | /** | ||
198 | * Expiration time of the block. | ||
199 | */ | ||
200 | struct GNUNET_TIME_AbsoluteNBO expiration_time; | ||
201 | |||
202 | /* followed by encrypted data */ | ||
203 | }; | ||
204 | |||
205 | GNUNET_NETWORK_STRUCT_END | ||
206 | |||
207 | |||
208 | /** | ||
209 | * Process a records that were decrypted from a block. | ||
210 | * | ||
211 | * @param cls closure | ||
212 | * @param rd_count number of entries in @a rd array | ||
213 | * @param rd array of records with data to store | ||
214 | */ | ||
215 | typedef void (*GNUNET_NAMESTORE_RecordCallback) (void *cls, | ||
216 | unsigned int rd_count, | ||
217 | const struct GNUNET_NAMESTORE_RecordData *rd); | ||
218 | |||
219 | |||
220 | |||
221 | /* ***************** API related to GNSRECORD plugins ************** */ | ||
79 | 222 | ||
80 | /** | 223 | /** |
81 | * Convert the binary value @a data of a record of | 224 | * Convert the binary value @a data of a record of |
@@ -129,6 +272,217 @@ const char * | |||
129 | GNUNET_GNSRECORD_number_to_typename (uint32_t type); | 272 | GNUNET_GNSRECORD_number_to_typename (uint32_t type); |
130 | 273 | ||
131 | 274 | ||
275 | /* convenience APIs for serializing / deserializing GNS records */ | ||
276 | |||
277 | /** | ||
278 | * Calculate how many bytes we will need to serialize the given | ||
279 | * records. | ||
280 | * | ||
281 | * @param rd_count number of records in the @a rd array | ||
282 | * @param rd array of #GNUNET_NAMESTORE_RecordData with @a rd_count elements | ||
283 | * @return the required size to serialize | ||
284 | */ | ||
285 | size_t | ||
286 | GNUNET_NAMESTORE_records_get_size (unsigned int rd_count, | ||
287 | const struct GNUNET_NAMESTORE_RecordData *rd); | ||
288 | |||
289 | |||
290 | /** | ||
291 | * Serialize the given records to the given destination buffer. | ||
292 | * | ||
293 | * @param rd_count number of records in the @a rd array | ||
294 | * @param rd array of #GNUNET_NAMESTORE_RecordData with @a rd_count elements | ||
295 | * @param dest_size size of the destination array @a dst | ||
296 | * @param dest where to write the result | ||
297 | * @return the size of serialized records, -1 if records do not fit | ||
298 | */ | ||
299 | ssize_t | ||
300 | GNUNET_NAMESTORE_records_serialize (unsigned int rd_count, | ||
301 | const struct GNUNET_NAMESTORE_RecordData *rd, | ||
302 | size_t dest_size, | ||
303 | char *dest); | ||
304 | |||
305 | |||
306 | /** | ||
307 | * Deserialize the given records to the given destination. | ||
308 | * | ||
309 | * @param len size of the serialized record data | ||
310 | * @param src the serialized record data | ||
311 | * @param rd_count number of records in the @a dest array | ||
312 | * @param dest where to put the data | ||
313 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | ||
314 | */ | ||
315 | int | ||
316 | GNUNET_NAMESTORE_records_deserialize (size_t len, | ||
317 | const char *src, | ||
318 | unsigned int rd_count, | ||
319 | struct GNUNET_NAMESTORE_RecordData *dest); | ||
320 | |||
321 | |||
322 | /* ******* general APIs relating to blocks, records and labels ******** */ | ||
323 | |||
324 | |||
325 | |||
326 | /** | ||
327 | * Test if a given record is expired. | ||
328 | * | ||
329 | * @param rd record to test | ||
330 | * @return #GNUNET_YES if the record is expired, | ||
331 | * #GNUNET_NO if not | ||
332 | */ | ||
333 | int | ||
334 | GNUNET_NAMESTORE_is_expired (const struct GNUNET_NAMESTORE_RecordData *rd); | ||
335 | |||
336 | |||
337 | /** | ||
338 | * Convert a UTF-8 string to UTF-8 lowercase | ||
339 | * @param src source string | ||
340 | * @return converted result | ||
341 | */ | ||
342 | char * | ||
343 | GNUNET_NAMESTORE_normalize_string (const char *src); | ||
344 | |||
345 | |||
346 | /** | ||
347 | * Convert a zone to a string (for printing debug messages). | ||
348 | * This is one of the very few calls in the entire API that is | ||
349 | * NOT reentrant! | ||
350 | * | ||
351 | * @param z public key of a zone | ||
352 | * @return string form; will be overwritten by next call to #GNUNET_NAMESTORE_z2s. | ||
353 | */ | ||
354 | const char * | ||
355 | GNUNET_NAMESTORE_z2s (const struct GNUNET_CRYPTO_EcdsaPublicKey *z); | ||
356 | |||
357 | |||
358 | /** | ||
359 | * Convert public key to the respective absolute domain name in the | ||
360 | * ".zkey" pTLD. | ||
361 | * This is one of the very few calls in the entire API that is | ||
362 | * NOT reentrant! | ||
363 | * | ||
364 | * @param pkey a public key with a point on the eliptic curve | ||
365 | * @return string "X.zkey" where X is the coordinates of the public | ||
366 | * key in an encoding suitable for DNS labels. | ||
367 | */ | ||
368 | const char * | ||
369 | GNUNET_NAMESTORE_pkey_to_zkey (const struct GNUNET_CRYPTO_EcdsaPublicKey *pkey); | ||
370 | |||
371 | |||
372 | /** | ||
373 | * Convert an absolute domain name in the ".zkey" pTLD to the | ||
374 | * respective public key. | ||
375 | * | ||
376 | * @param zkey string "X.zkey" where X is the public | ||
377 | * key in an encoding suitable for DNS labels. | ||
378 | * @param pkey set to a public key on the eliptic curve | ||
379 | * @return #GNUNET_SYSERR if @a zkey has the wrong syntax | ||
380 | */ | ||
381 | int | ||
382 | GNUNET_NAMESTORE_zkey_to_pkey (const char *zkey, | ||
383 | struct GNUNET_CRYPTO_EcdsaPublicKey *pkey); | ||
384 | |||
385 | |||
386 | /** | ||
387 | * Calculate the DHT query for a given @a label in a given @a zone. | ||
388 | * | ||
389 | * @param zone private key of the zone | ||
390 | * @param label label of the record | ||
391 | * @param query hash to use for the query | ||
392 | */ | ||
393 | void | ||
394 | GNUNET_NAMESTORE_query_from_private_key (const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, | ||
395 | const char *label, | ||
396 | struct GNUNET_HashCode *query); | ||
397 | |||
398 | |||
399 | /** | ||
400 | * Calculate the DHT query for a given @a label in a given @a zone. | ||
401 | * | ||
402 | * @param pub public key of the zone | ||
403 | * @param label label of the record | ||
404 | * @param query hash to use for the query | ||
405 | */ | ||
406 | void | ||
407 | GNUNET_NAMESTORE_query_from_public_key (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub, | ||
408 | const char *label, | ||
409 | struct GNUNET_HashCode *query); | ||
410 | |||
411 | |||
412 | /** | ||
413 | * Sign name and records | ||
414 | * | ||
415 | * @param key the private key | ||
416 | * @param expire block expiration | ||
417 | * @param label the name for the records | ||
418 | * @param rd record data | ||
419 | * @param rd_count number of records in @a rd | ||
420 | */ | ||
421 | struct GNUNET_NAMESTORE_Block * | ||
422 | GNUNET_NAMESTORE_block_create (const struct GNUNET_CRYPTO_EcdsaPrivateKey *key, | ||
423 | struct GNUNET_TIME_Absolute expire, | ||
424 | const char *label, | ||
425 | const struct GNUNET_NAMESTORE_RecordData *rd, | ||
426 | unsigned int rd_count); | ||
427 | |||
428 | |||
429 | /** | ||
430 | * Check if a signature is valid. This API is used by the GNS Block | ||
431 | * to validate signatures received from the network. | ||
432 | * | ||
433 | * @param block block to verify | ||
434 | * @return #GNUNET_OK if the signature is valid | ||
435 | */ | ||
436 | int | ||
437 | GNUNET_NAMESTORE_block_verify (const struct GNUNET_NAMESTORE_Block *block); | ||
438 | |||
439 | |||
440 | /** | ||
441 | * Decrypt block. | ||
442 | * | ||
443 | * @param block block to decrypt | ||
444 | * @param zone_key public key of the zone | ||
445 | * @param label the name for the records | ||
446 | * @param proc function to call with the result | ||
447 | * @param proc_cls closure for @a proc | ||
448 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if the block was | ||
449 | * not well-formed | ||
450 | */ | ||
451 | int | ||
452 | GNUNET_NAMESTORE_block_decrypt (const struct GNUNET_NAMESTORE_Block *block, | ||
453 | const struct GNUNET_CRYPTO_EcdsaPublicKey *zone_key, | ||
454 | const char *label, | ||
455 | GNUNET_NAMESTORE_RecordCallback proc, | ||
456 | void *proc_cls); | ||
457 | |||
458 | |||
459 | /** | ||
460 | * Compares if two records are equal | ||
461 | * | ||
462 | * @param a a record | ||
463 | * @param b another record | ||
464 | * @return #GNUNET_YES if the records are equal, or #GNUNET_NO if not. | ||
465 | */ | ||
466 | int | ||
467 | GNUNET_NAMESTORE_records_cmp (const struct GNUNET_NAMESTORE_RecordData *a, | ||
468 | const struct GNUNET_NAMESTORE_RecordData *b); | ||
469 | |||
470 | |||
471 | /** | ||
472 | * Returns the expiration time of the given block of records. The block | ||
473 | * expiration time is the expiration time of the record with smallest | ||
474 | * expiration time. | ||
475 | * | ||
476 | * @param rd_count number of records given in @a rd | ||
477 | * @param rd array of records | ||
478 | * @return absolute expiration time | ||
479 | */ | ||
480 | struct GNUNET_TIME_Absolute | ||
481 | GNUNET_NAMESTORE_record_get_expiration_time (unsigned int rd_count, | ||
482 | const struct GNUNET_NAMESTORE_RecordData *rd); | ||
483 | |||
484 | |||
485 | |||
132 | #if 0 /* keep Emacsens' auto-indent happy */ | 486 | #if 0 /* keep Emacsens' auto-indent happy */ |
133 | { | 487 | { |
134 | #endif | 488 | #endif |