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
   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  * API to the Credential service
  26  *
  27  * @defgroup credential  Credential service
  28  * Credentials
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_CREDENTIAL_SERVICE_H
  33 #define GNUNET_CREDENTIAL_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_CREDENTIAL_Handle;
  52
  53 /**
  54  * Handle to control a lookup operation.
  55  */
  56 struct GNUNET_CREDENTIAL_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_CREDENTIAL_CredentialFlags {
  62
  63   //Subject had credentials before, but have been revoked now
  64   GNUNET_CREDENTIAL_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_CREDENTIAL_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_CREDENTIAL_FLAG_ISSUER=2
  71
  72 };
  73
  74 GNUNET_NETWORK_STRUCT_BEGIN
  75 /**
  76  * The attribute delegation record
  77  */
  78 struct GNUNET_CREDENTIAL_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_CREDENTIAL_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_CREDENTIAL_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_CREDENTIAL_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 credential
 172  */
 173 struct GNUNET_CREDENTIAL_Credential {
 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 attribute
 197    */
 198   uint32_t issuer_attribute_len;
 199
 200   /**
 201    * The attribute
 202    */
 203   const char *issuer_attribute;
 204
 205 };
 206
 207
 208
 209 /**
 210  * Initialize the connection with the Credential service.
 211  *
 212  * @param cfg configuration to use
 213  * @return handle to the Credential service, or NULL on error
 214  */
 215 struct GNUNET_CREDENTIAL_Handle *
 216 GNUNET_CREDENTIAL_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 217
 218
 219 /**
 220  * Shutdown connection with the Credentail service.
 221  *
 222  * @param handle connection to shut down
 223  */
 224 void
 225 GNUNET_CREDENTIAL_disconnect (struct GNUNET_CREDENTIAL_Handle *handle);
 226
 227
 228 /**
 229  * Iterator called on obtained result for an attribute verification.
 230  *
 231  * @param cls closure
 232  * @param d_count the number of delegations processed
 233  * @param delegation_chain the delegations processed
 234  * @param c_count the number of credentials found
 235  * @param credential the credentials
 236  */
 237 typedef void (*GNUNET_CREDENTIAL_CredentialResultProcessor) (void *cls,
 238                                                          unsigned int d_count,
 239                                                          struct GNUNET_CREDENTIAL_Delegation *delegation_chain,
 240                                                          unsigned int c_count,
 241                                                          struct GNUNET_CREDENTIAL_Credential *credential);
 242
 243 /**
 244  * Iterator called on obtained result for an attribute delegation.
 245  *
 246  * @param cls closure
 247  * @param success GNUNET_YES if successful
 248  * @param result the record data that can be handed to the subject
 249  */
 250 typedef void (*GNUNET_CREDENTIAL_DelegateResultProcessor) (void *cls,
 251                                                            uint32_t success);
 252
 253 /**
 254  * Iterator called on obtained result for an attribute delegation removal.
 255  *
 256  * @param cls closure
 257  * @param success GNUNET_YES if successful
 258  * @param result the record data that can be handed to the subject
 259  */
 260 typedef void (*GNUNET_CREDENTIAL_RemoveDelegateResultProcessor) (void *cls,
 261                                                                  uint32_t success);
 262
 263
 264 /**
 265  * Performs attribute verification.
 266  * Checks if there is a delegation chain from
 267  * attribute ``issuer_attribute'' issued by the issuer
 268  * with public key ``issuer_key'' maps to the attribute
 269  * ``subject_attribute'' claimed by the subject with key
 270  * ``subject_key''
 271  *
 272  * @param handle handle to the Credential service
 273  * @param issuer_key the issuer public key
 274  * @param issuer_attribute the issuer attribute
 275  * @param subject_key the subject public key
 276  * @param credential_count number of credentials
 277  * @param credentials the subject credentials
 278  * @param proc function to call on result
 279  * @param proc_cls closure for processor
 280  * @return handle to the queued request
 281  */
 282 struct GNUNET_CREDENTIAL_Request*
 283 GNUNET_CREDENTIAL_verify (struct GNUNET_CREDENTIAL_Handle *handle,
 284                           const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
 285                           const char *issuer_attribute,
 286                           const struct GNUNET_CRYPTO_EcdsaPublicKey *subject_key,
 287                           uint32_t credential_count,
 288                           const struct GNUNET_CREDENTIAL_Credential *credentials,
 289                           GNUNET_CREDENTIAL_CredentialResultProcessor proc,
 290                           void *proc_cls);
 291
 292 struct GNUNET_CREDENTIAL_Request*
 293 GNUNET_CREDENTIAL_collect (struct GNUNET_CREDENTIAL_Handle *handle,
 294                            const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
 295                            const char *issuer_attribute,
 296                            const struct GNUNET_CRYPTO_EcdsaPrivateKey *subject_key,
 297                            GNUNET_CREDENTIAL_CredentialResultProcessor proc,
 298                            void *proc_cls);
 299
 300 /**
 301  * Delegate an attribute
 302  *
 303  * @param handle handle to the Credential service
 304  * @param issuer the ego that should be used to delegate the attribute
 305  * @param attribute the name of the attribute to delegate
 306  * @param subject the subject of the delegation
 307  * @param delegated_attribute the name of the attribute that is delegated to
 308  * @param proc the result callback
 309  * @param proc_cls the result closure context
 310  * @return handle to the queued request
 311  */
 312 struct GNUNET_CREDENTIAL_Request *
 313 GNUNET_CREDENTIAL_add_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
 314                                   struct GNUNET_IDENTITY_Ego *issuer,
 315                                   const char *attribute,
 316                                   struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
 317                                   const char *delegated_attribute,
 318                                   GNUNET_CREDENTIAL_DelegateResultProcessor proc,
 319                                   void *proc_cls);
 320
 321 /**
 322  * Remove a delegation
 323  *
 324  * @param handle handle to the Credential service
 325  * @param issuer the ego that was used to delegate the attribute
 326  * @param attribute the name of the attribute that is delegated
 327  * @param proc the callback
 328  * @param proc_cls callback closure
 329  * @return handle to the queued request
 330  */
 331 struct GNUNET_CREDENTIAL_Request *
 332 GNUNET_CREDENTIAL_remove_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
 333                                      struct GNUNET_IDENTITY_Ego *issuer,
 334                                      const char *attribute,
 335                                      GNUNET_CREDENTIAL_RemoveDelegateResultProcessor proc,
 336                                      void *proc_cls);
 337
 338
 339
 340 /**
 341  * Issue an attribute to a subject
 342  *
 343  * @param issuer the ego that should be used to issue the attribute
 344  * @param subject the subject of the attribute
 345  * @param attribute the name of the attribute
 346  * @param expiration the TTL of the credential
 347  * @return handle to the queued request
 348  */
 349 struct GNUNET_CREDENTIAL_Credential*
 350 GNUNET_CREDENTIAL_credential_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *issuer,
 351                                     struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
 352                                     const char *attribute,
 353                                     struct GNUNET_TIME_Absolute *expiration);
 354
 355
 356
 357 /**
 358  * Cancel pending lookup request
 359  *
 360  * @param lr the lookup request to cancel
 361  */
 362 void
 363 GNUNET_CREDENTIAL_request_cancel (struct GNUNET_CREDENTIAL_Request *lr);
 364
 365
 366 #if 0                           /* keep Emacsens' auto-indent happy */
 367 {
 368 #endif
 369 #ifdef __cplusplus
 370 }
 371 #endif
 372
 373 #endif
 374
 375 /** @} */  /* end of group */