src/include/gnunet_reclaim_attribute_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2017 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  * @author Martin Schanzenbach
  23  *
  24  * @file
  25  * Identity attribute definitions
  26  *
  27  * @defgroup reclaim-attribute reclaim attributes
  28  * @{
  29  */
  30 #ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H
  31 #define GNUNET_RECLAIM_ATTRIBUTE_LIB_H
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #if 0 /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_util_lib.h"
  41
  42
  43 /**
  44  * No value attribute.
  45  */
  46 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_NONE 0
  47
  48 /**
  49  * String attribute.
  50  */
  51 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_STRING 1
  52
  53 /**
  54 * No value attestation.
  55 */
  56 #define GNUNET_RECLAIM_ATTESTATION_TYPE_NONE 10
  57
  58 /**
  59 * A JSON Web Token attestation.
  60 */
  61 #define GNUNET_RECLAIM_ATTESTATION_TYPE_JWT 11
  62
  63 /**
  64  * An attribute.
  65  */
  66 struct GNUNET_RECLAIM_ATTRIBUTE_Claim
  67 {
  68   /**
  69    * ID
  70    */
  71   uint64_t id;
  72
  73   /**
  74    * Type of Claim
  75    */
  76   uint32_t type;
  77
  78   /**
  79    * Flags
  80    */
  81   uint32_t flag;
  82   /**
  83    * The name of the attribute. Note "name" must never be individually
  84    * free'd
  85    */
  86   const char *name;
  87
  88   /**
  89    * Number of bytes in @e data.
  90    */
  91   size_t data_size;
  92
  93   /**
  94    * Binary value stored as attribute value.  Note: "data" must never
  95    * be individually 'malloc'ed, but instead always points into some
  96    * existing data area.
  97    */
  98   const void *data;
  99 };
 100
 101 /**
 102  * An attestation.
 103  */
 104 struct GNUNET_RECLAIM_ATTESTATION_Claim
 105 {
 106   /**
 107    * ID
 108    */
 109   uint64_t id;
 110
 111   /**
 112    * Type/Format of Claim
 113    */
 114   uint32_t type;
 115
 116   /**
 117    * Version
 118    */
 119   uint32_t version;
 120
 121   /**
 122    * The name of the attribute. Note "name" must never be individually
 123    * free'd
 124    */
 125   const char *name;
 126
 127   /**
 128    * Number of bytes in @e data.
 129    */
 130   size_t data_size;
 131
 132   /**
 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.
 136    */
 137   const void *data;
 138 };
 139
 140 /**
 141  * A reference to an Attestatiom.
 142  */
 143 struct GNUNET_RECLAIM_ATTESTATION_REFERENCE
 144 {
 145   /**
 146    * ID
 147    */
 148   uint64_t id;
 149
 150   /**
 151    * Referenced ID of Attestation
 152    */
 153   uint64_t id_attest;
 154
 155   /**
 156    * The name of the attribute/attestation reference value. Note "name" must never be individually
 157    * free'd
 158    */
 159   const char *name;
 160
 161   /**
 162    * The name of the attribute/attestation reference value. Note "name" must never be individually
 163    * free'd
 164    */
 165   const char *reference_value;
 166 };
 167
 168 /**
 169  * A list of GNUNET_RECLAIM_ATTRIBUTE_Claim structures.
 170  */
 171 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList
 172 {
 173   /**
 174    * List head
 175    */
 176   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_head;
 177
 178   /**
 179    * List tail
 180    */
 181   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_tail;
 182 };
 183
 184
 185 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry
 186 {
 187   /**
 188    * DLL
 189    */
 190   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *prev;
 191
 192   /**
 193    * DLL
 194    */
 195   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *next;
 196
 197   /**
 198    * The attribute claim
 199    */
 200   struct GNUNET_RECLAIM_ATTRIBUTE_Claim *claim;
 201   /**
 202    * The attestation claim
 203    */
 204   struct GNUNET_RECLAIM_ATTESTATION_Claim *attest;
 205
 206   /**
 207   * The reference
 208   */
 209   struct GNUNET_RECLAIM_ATTESTATION_REFERENCE *reference;
 210 };
 211
 212 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntryType
 213 {
 214   uint32_t type;
 215 };
 216
 217
 218 /**
 219  * Create a new attribute claim.
 220  *
 221  * @param attr_name the attribute name
 222  * @param type the attribute type
 223  * @param data the attribute value
 224  * @param data_size the attribute value size
 225  * @return the new attribute
 226  */
 227 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
 228 GNUNET_RECLAIM_ATTRIBUTE_claim_new (const char *attr_name,
 229                                     uint32_t type,
 230                                     const void *data,
 231                                     size_t data_size);
 232
 233
 234 /**
 235  * Get required size for serialization buffer
 236  *
 237  * @param attrs the attribute list to serialize
 238  * @return the required buffer size
 239  */
 240 size_t
 241 GNUNET_RECLAIM_ATTRIBUTE_list_serialize_get_size (
 242   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 243
 244
 245 /**
 246  * Destroy claim list
 247  *
 248  * @param attrs list to destroy
 249  */
 250 void
 251 GNUNET_RECLAIM_ATTRIBUTE_list_destroy (
 252   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 253
 254
 255 /**
 256  * Add a new attribute to a claim list
 257  *
 258  * @param attr_name the name of the new attribute claim
 259  * @param type the type of the claim
 260  * @param data claim payload
 261  * @param data_size claim payload size
 262  */
 263 void
 264 GNUNET_RECLAIM_ATTRIBUTE_list_add (
 265   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 266   const char *attr_name,
 267   uint32_t type,
 268   const void *data,
 269   size_t data_size);
 270
 271
 272 /**
 273  * Serialize an attribute list
 274  *
 275  * @param attrs the attribute list to serialize
 276  * @param result the serialized attribute
 277  * @return length of serialized data
 278  */
 279 size_t
 280 GNUNET_RECLAIM_ATTRIBUTE_list_serialize (
 281   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 282   char *result);
 283
 284
 285 /**
 286  * Deserialize an attribute list
 287  *
 288  * @param data the serialized attribute list
 289  * @param data_size the length of the serialized data
 290  * @return a GNUNET_IDENTITY_PROVIDER_AttributeList, must be free'd by caller
 291  */
 292 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
 293 GNUNET_RECLAIM_ATTRIBUTE_list_deserialize (const char *data, size_t data_size);
 294
 295 /**
 296  * Count attestations in claim list
 297  *
 298  * @param attrs list
 299  */
 300 int
 301 GNUNET_RECLAIM_ATTRIBUTE_list_count_attest (
 302   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 303
 304 /**
 305  * Get required size for serialization buffer
 306  *
 307  * @param attr the attribute to serialize
 308  * @return the required buffer size
 309  */
 310 size_t
 311 GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (
 312   const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr);
 313
 314
 315 /**
 316  * Serialize an attribute
 317  *
 318  * @param attr the attribute to serialize
 319  * @param result the serialized attribute
 320  * @return length of serialized data
 321  */
 322 size_t
 323 GNUNET_RECLAIM_ATTRIBUTE_serialize (
 324   const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
 325   char *result);
 326
 327
 328 /**
 329  * Deserialize an attribute
 330  *
 331  * @param data the serialized attribute
 332  * @param data_size the length of the serialized data
 333  *
 334  * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
 335  */
 336 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
 337 GNUNET_RECLAIM_ATTRIBUTE_deserialize (const char *data, size_t data_size);
 338
 339
 340 /**
 341  * Make a (deep) copy of a claim list
 342  * @param attrs claim list to copy
 343  * @return copied claim list
 344  */
 345 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
 346 GNUNET_RECLAIM_ATTRIBUTE_list_dup (
 347   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 348
 349
 350 /**
 351  * Convert a type name to the corresponding number
 352  *
 353  * @param typename name to convert
 354  * @return corresponding number, UINT32_MAX on error
 355  */
 356 uint32_t
 357 GNUNET_RECLAIM_ATTRIBUTE_typename_to_number (const char *typename);
 358
 359 /**
 360  * Convert human-readable version of a 'claim' of an attribute to the binary
 361  * representation
 362  *
 363  * @param type type of the claim
 364  * @param s human-readable string
 365  * @param data set to value in binary encoding (will be allocated)
 366  * @param data_size set to number of bytes in @a data
 367  * @return #GNUNET_OK on success
 368  */
 369 int
 370 GNUNET_RECLAIM_ATTRIBUTE_string_to_value (uint32_t type,
 371                                           const char *s,
 372                                           void **data,
 373                                           size_t *data_size);
 374
 375
 376 /**
 377  * Convert the 'claim' of an attribute to a string
 378  *
 379  * @param type the type of attribute
 380  * @param data claim in binary encoding
 381  * @param data_size number of bytes in @a data
 382  * @return NULL on error, otherwise human-readable representation of the claim
 383  */
 384 char *
 385 GNUNET_RECLAIM_ATTRIBUTE_value_to_string (uint32_t type,
 386                                           const void *data,
 387                                           size_t data_size);
 388
 389
 390 /**
 391  * Convert a type number to the corresponding type string
 392  *
 393  * @param type number of a type
 394  * @return corresponding typestring, NULL on error
 395  */
 396 const char *
 397 GNUNET_RECLAIM_ATTRIBUTE_number_to_typename (uint32_t type);
 398
 399 /**
 400    * Get required size for serialization buffer
 401    * FIXME:
 402    * 1. The naming convention is violated here.
 403    * It should GNUNET_RECLAIM_ATTRIBUTE_<lowercase from here>.
 404    * It might make sense to refactor attestations into a separate folder.
 405    * 2. The struct should be called GNUNET_RECLAIM_ATTESTATION_Data or
 406    * GNUNET_RECLAIM_ATTRIBUTE_Attestation depending on location in source.
 407    *
 408    * @param attr the attestation to serialize
 409    * @return the required buffer size
 410    */
 411 size_t
 412 GNUNET_RECLAIM_ATTESTATION_serialize_get_size (
 413   const struct GNUNET_RECLAIM_ATTESTATION_Claim *attr);
 414
 415
 416 /**
 417  * Serialize an attestation
 418  *
 419  * @param attr the attestation to serialize
 420  * @param result the serialized attestation
 421  * @return length of serialized data
 422  */
 423 size_t
 424 GNUNET_RECLAIM_ATTESTATION_serialize (
 425   const struct GNUNET_RECLAIM_ATTESTATION_Claim *attr,
 426   char *result);
 427
 428
 429 /**
 430  * Deserialize an attestation
 431  *
 432  * @param data the serialized attestation
 433  * @param data_size the length of the serialized data
 434  *
 435  * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
 436  */
 437 struct GNUNET_RECLAIM_ATTESTATION_Claim *
 438 GNUNET_RECLAIM_ATTESTATION_deserialize (const char *data, size_t data_size);
 439
 440
 441 /**
 442    * Create a new attestation.
 443    *
 444    * @param attr_name the attestation name
 445    * @param type the attestation type
 446    * @param data the attestation value
 447    * @param data_size the attestation value size
 448    * @return the new attestation
 449    */
 450 struct GNUNET_RECLAIM_ATTESTATION_Claim *
 451 GNUNET_RECLAIM_ATTESTATION_claim_new (const char *attr_name,
 452                                       uint32_t type,
 453                                       const void *data,
 454                                       size_t data_size);
 455
 456 /**
 457  * Convert the 'claim' of an attestation to a string
 458  *
 459  * @param type the type of attestation
 460  * @param data claim in binary encoding
 461  * @param data_size number of bytes in @a data
 462  * @return NULL on error, otherwise human-readable representation of the claim
 463  */
 464 char *
 465 GNUNET_RECLAIM_ATTESTATION_value_to_string (uint32_t type,
 466                                             const void *data,
 467                                             size_t data_size);
 468
 469 /**
 470  * Convert human-readable version of a 'claim' of an attestation to the binary
 471  * representation
 472  *
 473  * @param type type of the claim
 474  * @param s human-readable string
 475  * @param data set to value in binary encoding (will be allocated)
 476  * @param data_size set to number of bytes in @a data
 477  * @return #GNUNET_OK on success
 478  */
 479 int
 480 GNUNET_RECLAIM_ATTESTATION_string_to_value (uint32_t type,
 481                                             const char *s,
 482                                             void **data,
 483                                             size_t *data_size);
 484
 485 /**
 486  * Convert an attestation type number to the corresponding attestation type string
 487  *
 488  * @param type number of a type
 489  * @return corresponding typestring, NULL on error
 490  */
 491 const char *
 492 GNUNET_RECLAIM_ATTESTATION_number_to_typename (uint32_t type);
 493
 494 /**
 495  * Convert an attestation type name to the corresponding number
 496  *
 497  * @param typename name to convert
 498  * @return corresponding number, UINT32_MAX on error
 499  */
 500 uint32_t
 501 GNUNET_RECLAIM_ATTESTATION_typename_to_number (const char *typename);
 502
 503 /**
 504  * Create a new attestation reference.
 505  *
 506  * @param attr_name the referenced claim name
 507  * @param ref_value the claim name in the attestation
 508  * @return the new reference
 509  */
 510 struct GNUNET_RECLAIM_ATTESTATION_REFERENCE *
 511 GNUNET_RECLAIM_ATTESTATION_reference_new (const char *attr_name,
 512                                           const char *ref_value);
 513
 514
 515 /**
 516  * Get required size for serialization buffer
 517  *
 518  * @param attr the reference to serialize
 519  * @return the required buffer size
 520  */
 521 size_t
 522 GNUNET_RECLAIM_ATTESTATION_REF_serialize_get_size (
 523   const struct GNUNET_RECLAIM_ATTESTATION_REFERENCE *attr);
 524
 525 /**
 526  * Serialize a reference
 527  *
 528  * @param attr the reference to serialize
 529  * @param result the serialized reference
 530  * @return length of serialized data
 531  */
 532 size_t
 533 GNUNET_RECLAIM_ATTESTATION_REF_serialize (
 534   const struct GNUNET_RECLAIM_ATTESTATION_REFERENCE *attr,
 535   char *result);
 536
 537 /**
 538  * Deserialize a reference
 539  *
 540  * @param data the serialized reference
 541  * @param data_size the length of the serialized data
 542  *
 543  * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
 544  */
 545 struct GNUNET_RECLAIM_ATTESTATION_REFERENCE *
 546 GNUNET_RECLAIM_ATTESTATION_REF_deserialize (const char *data, size_t data_size);
 547
 548 #if 0 /* keep Emacsens' auto-indent happy */
 549 {
 550 #endif
 551 #ifdef __cplusplus
 552 }
 553 #endif
 554
 555
 556 /* ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H */
 557 #endif
 558
 559 /** @} */ /* end of group reclaim-attribute */
 560
 561 /* end of gnunet_reclaim_attribute_lib.h */