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