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