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