src/include/gnunet_abd_service.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2012-2014 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  * API to the Credential service
  26  *
  27  * @defgroup abd  Credential service
  28  * Credentials
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_ABD_SERVICE_H
  33 #define GNUNET_ABD_SERVICE_H
  34
  35 #include "gnunet_util_lib.h"
  36 #include "gnunet_gns_service.h"
  37 #include "gnunet_identity_service.h"
  38
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #if 0                           /* keep Emacsens' auto-indent happy */
  43 }
  44 #endif
  45 #endif
  46
  47
  48 /**
  49  * Connection to the Credential service.
  50  */
  51 struct GNUNET_ABD_Handle;
  52
  53 /**
  54  * Handle to control a lookup operation.
  55  */
  56 struct GNUNET_ABD_Request;
  57
  58 /*
  59 * Enum used for checking whether the issuer has the authority to issue credentials or is just a subject
  60 */
  61 enum GNUNET_ABD_CredentialFlags {
  62
  63   //Subject had credentials before, but have been revoked now
  64   GNUNET_ABD_FLAG_REVOKED=0,
  65
  66   //Subject flag indicates that the subject is a holder of this credential and may present it as such
  67   GNUNET_ABD_FLAG_SUBJECT=1,
  68
  69   //Issuer flag is used to signify that the subject is allowed to issue this credential and delegate issuance
  70   GNUNET_ABD_FLAG_ISSUER=2
  71
  72 };
  73
  74 GNUNET_NETWORK_STRUCT_BEGIN
  75 /**
  76  * The attribute delegation record
  77  */
  78 struct GNUNET_ABD_DelegationRecord {
  79
  80   /**
  81    * Number of delegation sets in this record
  82    */
  83   uint32_t set_count;
  84
  85   /**
  86    * Length of delegation sets
  87    */
  88   uint64_t data_size;
  89   /**
  90    * Followed by set_count DelegationSetRecords
  91    *
  92    */
  93 };
  94
  95 /**
  96  * The attribute delegation record
  97  */
  98 struct GNUNET_ABD_DelegationRecordSet {
  99
 100   /**
 101    * Public key of the subject this attribute was delegated to
 102    */
 103   struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
 104
 105   /**
 106    * Length of attribute, may be 0
 107    */
 108   uint32_t subject_attribute_len;
 109 };
 110
 111
 112 GNUNET_NETWORK_STRUCT_END
 113
 114 /**
 115  * The attribute delegation record
 116  */
 117 struct GNUNET_ABD_DelegationSet {
 118
 119   /**
 120    * Public key of the subject this attribute was delegated to
 121    */
 122   struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
 123
 124   uint32_t subject_attribute_len;
 125
 126   /**
 127    * The subject attribute
 128    */
 129   const char *subject_attribute;
 130 };
 131
 132
 133 /**
 134  * A delegation
 135  */
 136 struct GNUNET_ABD_Delegation {
 137
 138   /**
 139    * The issuer of the delegation
 140    */
 141   struct GNUNET_CRYPTO_EcdsaPublicKey issuer_key;
 142
 143   /**
 144    * Public key of the subject this attribute was delegated to
 145    */
 146   struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
 147
 148   /**
 149    * Length of the attribute
 150    */
 151   uint32_t issuer_attribute_len;
 152
 153   /**
 154    * The attribute
 155    */
 156   const char *issuer_attribute;
 157
 158   /**
 159    * Length of the attribute
 160    */
 161   uint32_t subject_attribute_len;
 162
 163   /**
 164    * The attribute
 165    */
 166   const char *subject_attribute;
 167 };
 168
 169
 170 /**
 171  * A delegate
 172  */
 173 struct GNUNET_ABD_Delegate {
 174
 175   /**
 176    * The issuer of the credential
 177    */
 178   struct GNUNET_CRYPTO_EcdsaPublicKey issuer_key;
 179
 180   /**
 181    * Public key of the subject this credential was issued to
 182    */
 183   struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
 184
 185   /**
 186    * Signature of this credential
 187    */
 188   struct GNUNET_CRYPTO_EcdsaSignature signature;
 189
 190   /**
 191    * Expiration of this credential
 192    */
 193   struct GNUNET_TIME_Absolute expiration;
 194
 195   /**
 196    * Length of the issuer attribute
 197    */
 198   uint32_t issuer_attribute_len;
 199
 200   /**
 201    * The issuer attribute
 202    */
 203   const char *issuer_attribute;
 204
 205   /**
 206    * Length of the subject attribute
 207    */
 208   uint32_t subject_attribute_len;
 209
 210   /**
 211    * The subject attribute
 212    */
 213   const char *subject_attribute;
 214
 215 };
 216
 217 /*
 218 * Enum used for checking whether the issuer has the authority to issue credentials or is just a subject
 219 */
 220 enum GNUNET_ABD_AlgoDirectionFlags {
 221
 222   //Subject had credentials before, but have been revoked now
 223   GNUNET_ABD_FLAG_FORWARD=1 << 0,
 224
 225   //Subject flag indicates that the subject is a holder of this credential and may present it as such
 226   GNUNET_ABD_FLAG_BACKWARD=1 << 1
 227
 228 };
 229
 230 /**
 231  * Initialize the connection with the Credential service.
 232  *
 233  * @param cfg configuration to use
 234  * @return handle to the Credential service, or NULL on error
 235  */
 236 struct GNUNET_ABD_Handle *
 237 GNUNET_ABD_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 238
 239
 240 /**
 241  * Shutdown connection with the Credentail service.
 242  *
 243  * @param handle connection to shut down
 244  */
 245 void
 246 GNUNET_ABD_disconnect (struct GNUNET_ABD_Handle *handle);
 247
 248
 249 /**
 250  * Iterator called on obtained result for an attribute verification.
 251  *
 252  * @param cls closure
 253  * @param d_count the number of delegations processed
 254  * @param delegation_chain the delegations processed
 255  * @param c_count the number of delegates found
 256  * @param delegate the delegates
 257  */
 258 typedef void (*GNUNET_ABD_CredentialResultProcessor) (void *cls,
 259                                                          unsigned int d_count,
 260                                                          struct GNUNET_ABD_Delegation *delegation_chain,
 261                                                          unsigned int c_count,
 262                                                          struct GNUNET_ABD_Delegate *delegte);
 263
 264 typedef void (*GNUNET_ABD_IntermediateResultProcessor) (void *cls,
 265                                                          struct GNUNET_ABD_Delegation *delegation,
 266                                                          bool is_bw);
 267
 268 /**
 269  * Iterator called on obtained result for an attribute delegation.
 270  *
 271  * @param cls closure
 272  * @param success GNUNET_YES if successful
 273  * @param result the record data that can be handed to the subject
 274  */
 275 typedef void (*GNUNET_ABD_DelegateResultProcessor) (void *cls,
 276                                                            uint32_t success);
 277
 278 /**
 279  * Iterator called on obtained result for an attribute delegation removal.
 280  *
 281  * @param cls closure
 282  * @param success GNUNET_YES if successful
 283  * @param result the record data that can be handed to the subject
 284  */
 285 typedef void (*GNUNET_ABD_RemoveDelegateResultProcessor) (void *cls,
 286                                                                  uint32_t success);
 287
 288
 289 /**
 290  * Performs attribute verification.
 291  * Checks if there is a delegation chain from
 292  * attribute ``issuer_attribute'' issued by the issuer
 293  * with public key ``issuer_key'' maps to the attribute
 294  * ``subject_attribute'' claimed by the subject with key
 295  * ``subject_key''
 296  *
 297  * @param handle handle to the Credential service
 298  * @param issuer_key the issuer public key
 299  * @param issuer_attribute the issuer attribute
 300  * @param subject_key the subject public key
 301  * @param delegate_count number of delegates
 302  * @param delegates the subject delegates
 303  * @param proc function to call on result
 304  * @param proc_cls closure for processor
 305  * @return handle to the queued request
 306  */
 307 struct GNUNET_ABD_Request*
 308 GNUNET_ABD_verify (struct GNUNET_ABD_Handle *handle,
 309                           const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
 310                           const char *issuer_attribute,
 311                           const struct GNUNET_CRYPTO_EcdsaPublicKey *subject_key,
 312                           uint32_t delegate_count,
 313                           const struct GNUNET_ABD_Delegate *delegates,
 314                           enum GNUNET_ABD_AlgoDirectionFlags direction,
 315                           GNUNET_ABD_CredentialResultProcessor proc,
 316                           void *proc_cls,
 317                           GNUNET_ABD_IntermediateResultProcessor,
 318                           void *proc2_cls);
 319
 320 struct GNUNET_ABD_Request*
 321 GNUNET_ABD_collect (struct GNUNET_ABD_Handle *handle,
 322                            const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
 323                            const char *issuer_attribute,
 324                            const struct GNUNET_CRYPTO_EcdsaPrivateKey *subject_key,
 325                            enum GNUNET_ABD_AlgoDirectionFlags direction,
 326                            GNUNET_ABD_CredentialResultProcessor proc,
 327                            void *proc_cls,
 328                            GNUNET_ABD_IntermediateResultProcessor,
 329                            void *proc2_cls);
 330
 331 /**
 332  * Delegate an attribute
 333  *
 334  * @param handle handle to the Credential service
 335  * @param issuer the ego that should be used to delegate the attribute
 336  * @param attribute the name of the attribute to delegate
 337  * @param subject the subject of the delegation
 338  * @param delegated_attribute the name of the attribute that is delegated to
 339  * @param proc the result callback
 340  * @param proc_cls the result closure context
 341  * @return handle to the queued request
 342  */
 343 struct GNUNET_ABD_Request *
 344 GNUNET_ABD_add_delegation (struct GNUNET_ABD_Handle *handle,
 345                                   struct GNUNET_IDENTITY_Ego *issuer,
 346                                   const char *attribute,
 347                                   struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
 348                                   const char *delegated_attribute,
 349                                   GNUNET_ABD_DelegateResultProcessor proc,
 350                                   void *proc_cls);
 351
 352 /**
 353  * Remove a delegation
 354  *
 355  * @param handle handle to the Credential service
 356  * @param issuer the ego that was used to delegate the attribute
 357  * @param attribute the name of the attribute that is delegated
 358  * @param proc the callback
 359  * @param proc_cls callback closure
 360  * @return handle to the queued request
 361  */
 362 struct GNUNET_ABD_Request *
 363 GNUNET_ABD_remove_delegation (struct GNUNET_ABD_Handle *handle,
 364                                      struct GNUNET_IDENTITY_Ego *issuer,
 365                                      const char *attribute,
 366                                      GNUNET_ABD_RemoveDelegateResultProcessor proc,
 367                                      void *proc_cls);
 368
 369
 370
 371 /**
 372  * Issue an attribute to a subject
 373  *
 374  * @param issuer the ego that should be used to issue the attribute
 375  * @param subject the subject of the attribute
 376  * @param attribute the name of the attribute
 377  * @param expiration the TTL of the credential
 378  * @return handle to the queued request
 379  */
 380 struct GNUNET_ABD_Delegate*
 381 GNUNET_ABD_delegate_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *issuer,
 382                                     struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
 383                                     const char *iss_attr,
 384                                     const char *sub_attr,
 385                                     struct GNUNET_TIME_Absolute *expiration);
 386
 387
 388 /**
 389  * Cancel pending lookup request
 390  *
 391  * @param lr the lookup request to cancel
 392  */
 393 void
 394 GNUNET_ABD_request_cancel (struct GNUNET_ABD_Request *lr);
 395
 396
 397 #if 0                           /* keep Emacsens' auto-indent happy */
 398 {
 399 #endif
 400 #ifdef __cplusplus
 401 }
 402 #endif
 403
 404 #endif
 405
 406 /** @} */  /* end of group */