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 identity-provider  Identity Provider service
  28  * @{
  29  */
  30 #ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H
  31 #define GNUNET_RECLAIM_ATTRIBUTE_LIB_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_util_lib.h"
  42
  43
  44 /**
  45  * No value attribute.
  46  */
  47 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_NONE 0
  48
  49 /**
  50  * String attribute.
  51  */
  52 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_STRING 1
  53
  54
  55
  56 /**
  57  * An attribute.
  58  */
  59 struct GNUNET_RECLAIM_ATTRIBUTE_Claim
  60 {
  61   /**
  62    * ID
  63    */
  64   uint64_t id;
  65
  66   /**
  67    * Type of Claim
  68    */
  69   uint32_t type;
  70
  71   /**
  72    * Version
  73    */
  74   uint32_t version;
  75   /**
  76    * The name of the attribute. Note "name" must never be individually
  77    * free'd
  78    */
  79   const char* name;
  80
  81   /**
  82    * Number of bytes in @e data.
  83    */
  84   size_t data_size;
  85
  86   /**
  87    * Binary value stored as attribute value.  Note: "data" must never
  88    * be individually 'malloc'ed, but instead always points into some
  89    * existing data area.
  90    */
  91   const void *data;
  92
  93 };
  94
  95 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList
  96 {
  97   /**
  98    * List head
  99    */
 100   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_head;
 101
 102   /**
 103    * List tail
 104    */
 105   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_tail;
 106 };
 107
 108 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry
 109 {
 110   /**
 111    * DLL
 112    */
 113   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *prev;
 114
 115   /**
 116    * DLL
 117    */
 118   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *next;
 119
 120   /**
 121    * The attribute claim
 122    */
 123   struct GNUNET_RECLAIM_ATTRIBUTE_Claim *claim;
 124 };
 125
 126 /**
 127  * Create a new attribute claim.
 128  *
 129  * @param attr_name the attribute name
 130  * @param type the attribute type
 131  * @param data the attribute value
 132  * @param data_size the attribute value size
 133  * @return the new attribute
 134  */
 135 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
 136 GNUNET_RECLAIM_ATTRIBUTE_claim_new (const char* attr_name,
 137                                     uint32_t type,
 138                                     const void* data,
 139                                     size_t data_size);
 140
 141
 142 /**
 143  * Get required size for serialization buffer
 144  *
 145  * @param attrs the attribute list to serialize
 146  *
 147  * @return the required buffer size
 148  */
 149 size_t
 150 GNUNET_RECLAIM_ATTRIBUTE_list_serialize_get_size (const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 151
 152 void
 153 GNUNET_RECLAIM_ATTRIBUTE_list_destroy (struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 154
 155 void
 156 GNUNET_RECLAIM_ATTRIBUTE_list_add (struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 157                                    const char* attr_name,
 158                                    uint32_t type,
 159                                    const void* data,
 160                                    size_t data_size);
 161
 162 /**
 163  * Serialize an attribute list
 164  *
 165  * @param attrs the attribute list to serialize
 166  * @param result the serialized attribute
 167  *
 168  * @return length of serialized data
 169  */
 170 size_t
 171 GNUNET_RECLAIM_ATTRIBUTE_list_serialize (const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 172                                          char *result);
 173
 174 /**
 175  * Deserialize an attribute list
 176  *
 177  * @param data the serialized attribute list
 178  * @param data_size the length of the serialized data
 179  *
 180  * @return a GNUNET_IDENTITY_PROVIDER_AttributeList, must be free'd by caller
 181  */
 182 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
 183 GNUNET_RECLAIM_ATTRIBUTE_list_deserialize (const char* data,
 184                                            size_t data_size);
 185
 186
 187 /**
 188  * Get required size for serialization buffer
 189  *
 190  * @param attr the attribute to serialize
 191  *
 192  * @return the required buffer size
 193  */
 194 size_t
 195 GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr);
 196
 197
 198
 199 /**
 200  * Serialize an attribute
 201  *
 202  * @param attr the attribute to serialize
 203  * @param result the serialized attribute
 204  *
 205  * @return length of serialized data
 206  */
 207 size_t
 208 GNUNET_RECLAIM_ATTRIBUTE_serialize (const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
 209                                     char *result);
 210
 211 /**
 212  * Deserialize an attribute
 213  *
 214  * @param data the serialized attribute
 215  * @param data_size the length of the serialized data
 216  *
 217  * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
 218  */
 219 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
 220 GNUNET_RECLAIM_ATTRIBUTE_deserialize (const char* data,
 221                                       size_t data_size);
 222
 223 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList*
 224 GNUNET_RECLAIM_ATTRIBUTE_list_dup (const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 225
 226 /**
 227  * Convert a type name to the corresponding number
 228  *
 229  * @param typename name to convert
 230  * @return corresponding number, UINT32_MAX on error
 231  */
 232 uint32_t
 233 GNUNET_RECLAIM_ATTRIBUTE_typename_to_number (const char *typename);
 234
 235 /**
 236  * Convert human-readable version of a 'claim' of an attribute to the binary
 237  * representation
 238  *
 239  * @param type type of the claim
 240  * @param s human-readable string
 241  * @param data set to value in binary encoding (will be allocated)
 242  * @param data_size set to number of bytes in @a data
 243  * @return #GNUNET_OK on success
 244  */
 245 int
 246 GNUNET_RECLAIM_ATTRIBUTE_string_to_value (uint32_t type,
 247                                           const char *s,
 248                                           void **data,
 249                                           size_t *data_size);
 250
 251 /**
 252  * Convert the 'claim' of an attribute to a string
 253  *
 254  * @param type the type of attribute
 255  * @param data claim in binary encoding
 256  * @param data_size number of bytes in @a data
 257  * @return NULL on error, otherwise human-readable representation of the claim
 258  */
 259 char *
 260 GNUNET_RECLAIM_ATTRIBUTE_value_to_string (uint32_t type,
 261                                           const void* data,
 262                                           size_t data_size);
 263
 264 /**
 265  * Convert a type number to the corresponding type string
 266  *
 267  * @param type number of a type
 268  * @return corresponding typestring, NULL on error
 269  */
 270 const char*
 271 GNUNET_RECLAIM_ATTRIBUTE_number_to_typename (uint32_t type);
 272
 273
 274 #if 0                           /* keep Emacsens' auto-indent happy */
 275 {
 276 #endif
 277 #ifdef __cplusplus
 278 }
 279 #endif
 280
 281
 282 /* ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H */
 283 #endif
 284
 285 /** @} */ /* end of group identity */
 286
 287 /* end of gnunet_reclaim_attribute_lib.h */