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