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