2 This file is part of GNUnet.
3 Copyright (C) 2017 GNUnet e.V.
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.
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.
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/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @author Martin Schanzenbach
25 * Identity attribute definitions
27 * @defgroup reclaim-attribute reclaim attributes
30 #ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H
31 #define GNUNET_RECLAIM_ATTRIBUTE_LIB_H
35 #if 0 /* keep Emacsens' auto-indent happy */
40 #include "gnunet_util_lib.h"
46 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_NONE 0
51 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_STRING 1
54 * No value attestation.
56 #define GNUNET_RECLAIM_ATTESTATION_TYPE_NONE 10
59 * A JSON Web Token attestation.
61 #define GNUNET_RECLAIM_ATTESTATION_TYPE_JWT 11
64 * We want an ID to be a 256-bit symmetric key
66 #define GNUNET_RECLAIM_ID_LENGTH (256 / 8)
69 * A reclaim identifier
70 * FIXME maybe put this in a different namespace
72 struct GNUNET_RECLAIM_Identifier
74 char id[GNUNET_RECLAIM_ID_LENGTH];
77 static const struct GNUNET_RECLAIM_Identifier GNUNET_RECLAIM_ID_ZERO;
79 #define GNUNET_RECLAIM_id_is_equal(a,b) ((0 == \
82 sizeof (GNUNET_RECLAIM_ID_ZERO))) \
84 GNUNET_YES : GNUNET_NO)
87 #define GNUNET_RECLAIM_id_is_zero(a) GNUNET_RECLAIM_id_is_equal (a, \
89 GNUNET_RECLAIM_ID_ZERO)
91 #define GNUNET_RECLAIM_id_generate(id) \
92 (GNUNET_CRYPTO_random_block (GNUNET_CRYPTO_QUALITY_STRONG, \
94 sizeof (GNUNET_RECLAIM_ID_ZERO)))
99 struct GNUNET_RECLAIM_Attribute
104 struct GNUNET_RECLAIM_Identifier id;
107 * Referenced ID of Attestation (may be 0 if self-attested)
109 struct GNUNET_RECLAIM_Identifier attestation;
122 * The name of the attribute. Note "name" must never be individually
128 * Number of bytes in @e data.
133 * Binary value stored as attribute value. Note: "data" must never
134 * be individually 'malloc'ed, but instead always points into some
135 * existing data area.
143 struct GNUNET_RECLAIM_Attestation
148 struct GNUNET_RECLAIM_Identifier id;
151 * Type/Format of Claim
161 * The name of the attribute. Note "name" must never be individually
167 * Number of bytes in @e data.
172 * Binary value stored as attribute value. Note: "data" must never
173 * be individually 'malloc'ed, but instead always points into some
174 * existing data area.
181 * A list of GNUNET_RECLAIM_Attribute structures.
183 struct GNUNET_RECLAIM_AttributeList
188 struct GNUNET_RECLAIM_AttributeListEntry *list_head;
193 struct GNUNET_RECLAIM_AttributeListEntry *list_tail;
197 struct GNUNET_RECLAIM_AttributeListEntry
202 struct GNUNET_RECLAIM_AttributeListEntry *prev;
207 struct GNUNET_RECLAIM_AttributeListEntry *next;
210 * The attribute claim
212 struct GNUNET_RECLAIM_Attribute *attribute;
217 * A list of GNUNET_RECLAIM_Attestation structures.
219 struct GNUNET_RECLAIM_AttestationList
224 struct GNUNET_RECLAIM_AttestationListEntry *list_head;
229 struct GNUNET_RECLAIM_AttestationListEntry *list_tail;
233 struct GNUNET_RECLAIM_AttestationListEntry
238 struct GNUNET_RECLAIM_AttestationListEntry *prev;
243 struct GNUNET_RECLAIM_AttestationListEntry *next;
248 struct GNUNET_RECLAIM_Attestation *attestation;
254 * Create a new attribute claim.
256 * @param attr_name the attribute name
257 * @param attestation ID of the attestation (may be NULL)
258 * @param type the attribute type
259 * @param data the attribute value. Must be the mapped name if attestation not NULL
260 * @param data_size the attribute value size
261 * @return the new attribute
263 struct GNUNET_RECLAIM_Attribute *
264 GNUNET_RECLAIM_attribute_new (const char *attr_name,
265 const struct GNUNET_RECLAIM_Identifier *attestation,
272 * Get required size for serialization buffer
274 * @param attrs the attribute list to serialize
275 * @return the required buffer size
278 GNUNET_RECLAIM_attribute_list_serialize_get_size (
279 const struct GNUNET_RECLAIM_AttributeList *attrs);
285 * @param attrs list to destroy
288 GNUNET_RECLAIM_attribute_list_destroy (
289 struct GNUNET_RECLAIM_AttributeList *attrs);
293 * Add a new attribute to a claim list
295 * @param attrs the attribute list to add to
296 * @param attr_name the name of the new attribute claim
297 * @param attestation attestation ID (may be NULL)
298 * @param type the type of the claim
299 * @param data claim payload
300 * @param data_size claim payload size
303 GNUNET_RECLAIM_attribute_list_add (
304 struct GNUNET_RECLAIM_AttributeList *attrs,
305 const char *attr_name,
306 const struct GNUNET_RECLAIM_Identifier *attestation,
313 * Serialize an attribute list
315 * @param attrs the attribute list to serialize
316 * @param result the serialized attribute
317 * @return length of serialized data
320 GNUNET_RECLAIM_attribute_list_serialize (
321 const struct GNUNET_RECLAIM_AttributeList *attrs,
326 * Deserialize an attribute list
328 * @param data the serialized attribute list
329 * @param data_size the length of the serialized data
330 * @return a GNUNET_IDENTITY_PROVIDER_AttributeList, must be free'd by caller
332 struct GNUNET_RECLAIM_AttributeList *
333 GNUNET_RECLAIM_attribute_list_deserialize (const char *data, size_t data_size);
336 * Get required size for serialization buffer
338 * @param attr the attribute to serialize
339 * @return the required buffer size
342 GNUNET_RECLAIM_attribute_serialize_get_size (
343 const struct GNUNET_RECLAIM_Attribute *attr);
347 * Serialize an attribute
349 * @param attr the attribute to serialize
350 * @param result the serialized attribute
351 * @return length of serialized data
354 GNUNET_RECLAIM_attribute_serialize (const struct GNUNET_RECLAIM_Attribute *attr,
359 * Deserialize an attribute
361 * @param data the serialized attribute
362 * @param data_size the length of the serialized data
364 * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
366 struct GNUNET_RECLAIM_Attribute *
367 GNUNET_RECLAIM_attribute_deserialize (const char *data, size_t data_size);
371 * Make a (deep) copy of a claim list
372 * @param attrs claim list to copy
373 * @return copied claim list
375 struct GNUNET_RECLAIM_AttributeList *
376 GNUNET_RECLAIM_attribute_list_dup (
377 const struct GNUNET_RECLAIM_AttributeList *attrs);
381 * Convert a type name to the corresponding number
383 * @param typename name to convert
384 * @return corresponding number, UINT32_MAX on error
387 GNUNET_RECLAIM_attribute_typename_to_number (const char *typename);
390 * Convert human-readable version of a 'claim' of an attribute to the binary
393 * @param type type of the claim
394 * @param s human-readable string
395 * @param data set to value in binary encoding (will be allocated)
396 * @param data_size set to number of bytes in @a data
397 * @return #GNUNET_OK on success
400 GNUNET_RECLAIM_attribute_string_to_value (uint32_t type,
407 * Convert the 'claim' of an attribute to a string
409 * @param type the type of attribute
410 * @param data claim in binary encoding
411 * @param data_size number of bytes in @a data
412 * @return NULL on error, otherwise human-readable representation of the claim
415 GNUNET_RECLAIM_attribute_value_to_string (uint32_t type,
420 * Convert a type number to the corresponding type string
422 * @param type number of a type
423 * @return corresponding typestring, NULL on error
426 GNUNET_RECLAIM_attribute_number_to_typename (uint32_t type);
430 * Get required size for serialization buffer
432 * @param attrs the attribute list to serialize
433 * @return the required buffer size
436 GNUNET_RECLAIM_attestation_list_serialize_get_size (
437 const struct GNUNET_RECLAIM_AttestationList *attestations);
443 * @param attrs list to destroy
446 GNUNET_RECLAIM_attestation_list_destroy (
447 struct GNUNET_RECLAIM_AttestationList *attestations);
451 * Add a new attribute to a claim list
453 * @param attr_name the name of the new attribute claim
454 * @param type the type of the claim
455 * @param data claim payload
456 * @param data_size claim payload size
459 GNUNET_RECLAIM_attestation_list_add (
460 struct GNUNET_RECLAIM_AttestationList *attrs,
461 const char *att_name,
468 * Serialize an attribute list
470 * @param attrs the attribute list to serialize
471 * @param result the serialized attribute
472 * @return length of serialized data
475 GNUNET_RECLAIM_attestation_list_serialize (
476 const struct GNUNET_RECLAIM_AttestationList *attrs,
481 * Deserialize an attribute list
483 * @param data the serialized attribute list
484 * @param data_size the length of the serialized data
485 * @return a GNUNET_IDENTITY_PROVIDER_AttributeList, must be free'd by caller
487 struct GNUNET_RECLAIM_AttestationList *
488 GNUNET_RECLAIM_attestation_list_deserialize (const char *data,
494 * @param attestation the attestation to serialize
495 * @return the required buffer size
498 GNUNET_RECLAIM_attestation_serialize_get_size (
499 const struct GNUNET_RECLAIM_Attestation *attestation);
503 * Serialize an attestation
505 * @param attestation the attestation to serialize
506 * @param result the serialized attestation
507 * @return length of serialized data
510 GNUNET_RECLAIM_attestation_serialize (
511 const struct GNUNET_RECLAIM_Attestation *attestation,
516 * Deserialize an attestation
518 * @param data the serialized attestation
519 * @param data_size the length of the serialized data
521 * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
523 struct GNUNET_RECLAIM_Attestation *
524 GNUNET_RECLAIM_attestation_deserialize (const char *data, size_t data_size);
528 * Create a new attestation.
530 * @param name the attestation name
531 * @param type the attestation type
532 * @param data the attestation value
533 * @param data_size the attestation value size
534 * @return the new attestation
536 struct GNUNET_RECLAIM_Attestation *
537 GNUNET_RECLAIM_attestation_new (const char *name,
543 * Convert the 'claim' of an attestation to a string
545 * @param type the type of attestation
546 * @param data claim in binary encoding
547 * @param data_size number of bytes in @a data
548 * @return NULL on error, otherwise human-readable representation of the claim
551 GNUNET_RECLAIM_attestation_value_to_string (uint32_t type,
556 * Convert human-readable version of a 'claim' of an attestation to the binary
559 * @param type type of the claim
560 * @param s human-readable string
561 * @param data set to value in binary encoding (will be allocated)
562 * @param data_size set to number of bytes in @a data
563 * @return #GNUNET_OK on success
566 GNUNET_RECLAIM_attestation_string_to_value (uint32_t type,
572 * Convert an attestation type number to the corresponding attestation type string
574 * @param type number of a type
575 * @return corresponding typestring, NULL on error
578 GNUNET_RECLAIM_attestation_number_to_typename (uint32_t type);
581 * Convert an attestation type name to the corresponding number
583 * @param typename name to convert
584 * @return corresponding number, UINT32_MAX on error
587 GNUNET_RECLAIM_attestation_typename_to_number (const char *typename);
590 #if 0 /* keep Emacsens' auto-indent happy */
598 /* ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H */
601 /** @} */ /* end of group reclaim-attribute */
603 /* end of gnunet_reclaim_attribute_lib.h */