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 record
  77  */
  78 struct GNUNET_CREDENTIAL_AttributeRecordData {
  79
  80   /**
  81    * Public key of the subject this credential was issued to
  82    */
  83   struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
  84
  85   /**
  86    * Public key of the issuer
  87    */
  88   struct GNUNET_CRYPTO_EcdsaPublicKey issuer_key;
  89
  90   /**
  91    * Flags for this credential
  92    */
  93   uint32_t credential_flags GNUNET_PACKED;
  94
  95   /**
  96    * Expiration time of this credential
  97    */
  98   uint64_t expiration GNUNET_PACKED;
  99
 100   /**
 101    * The signature for this credential by the issuer
 102    */
 103   struct GNUNET_CRYPTO_EcdsaSignature sig;
 104
 105   /**
 106    * Followed by the attribute string
 107    */
 108 };
 109
 110
 111 /**
 112  * The attribute delegation record
 113 */
 114 struct GNUNET_CREDENTIAL_AttributeDelegationRecordData {
 115
 116   /**
 117    * Public key of the subject this attribute was delegated to
 118    */
 119   struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
 120
 121   /**
 122    * Followed by the attribute that was delegated to as string
 123    */
 124 };
 125
 126
 127
 128 GNUNET_NETWORK_STRUCT_END
 129
 130
 131
 132 /**
 133  * Initialize the connection with the Credential service.
 134  *
 135  * @param cfg configuration to use
 136  * @return handle to the Credential service, or NULL on error
 137  */
 138 struct GNUNET_CREDENTIAL_Handle *
 139 GNUNET_CREDENTIAL_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 140
 141
 142 /**
 143  * Shutdown connection with the Credentail service.
 144  *
 145  * @param handle connection to shut down
 146  */
 147 void
 148 GNUNET_CREDENTIAL_disconnect (struct GNUNET_CREDENTIAL_Handle *handle);
 149
 150
 151 /**
 152  * Iterator called on obtained result for an attribute verification.
 153  *
 154  * @param cls closure
 155  * @param issuer the issuer of the attribute NULL if verification failed
 156  * @param result the result of the verification
 157  * @param rd the records in reply
 158  */
 159 typedef void (*GNUNET_CREDENTIAL_VerifyResultProcessor) (void *cls,
 160                                                   struct GNUNET_CRYPTO_EcdsaPublicKey *issuer,
 161               uint32_t result);
 162
 163 /**
 164  * Iterator called on obtained result for an attribute issuance.
 165  *
 166  * @param cls closure
 167  * @param result the record data that can be handed to the subject
 168  */
 169 typedef void (*GNUNET_CREDENTIAL_IssueResultProcessor) (void *cls,
 170                                                   struct GNUNET_CREDENTIAL_AttributeRecordData *data);
 171
 172 /**
 173  * Iterator called on obtained result for an attribute delegation.
 174  *
 175  * @param cls closure
 176  * @param success GNUNET_YES if successful
 177  * @param result the record data that can be handed to the subject
 178  */
 179 typedef void (*GNUNET_CREDENTIAL_DelegateResultProcessor) (void *cls,
 180                                                   uint32_t success);
 181
 182 /**
 183  * Iterator called on obtained result for an attribute delegation removal.
 184  *
 185  * @param cls closure
 186  * @param success GNUNET_YES if successful
 187  * @param result the record data that can be handed to the subject
 188  */
 189 typedef void (*GNUNET_CREDENTIAL_RemoveDelegateResultProcessor) (void *cls,
 190                                                   uint32_t success);
 191
 192
 193
 194
 195 /**
 196  * Performs attribute verification.
 197  * Checks if there is a delegation chain from
 198  * attribute ``issuer_attribute'' issued by the issuer
 199  * with public key ``issuer_key'' maps to the attribute
 200  * ``subject_attribute'' claimed by the subject with key
 201  * ``subject_key''
 202  *
 203  * @param handle handle to the Credential service
 204  * @param issuer_key the issuer public key
 205  * @param issuer_attribute the issuer attribute
 206  * @param subject_key the subject public key
 207  * @param subject_attribute the attribute claimed by the subject
 208  * @param proc function to call on result
 209  * @param proc_cls closure for processor
 210  * @return handle to the queued request
 211  */
 212 struct GNUNET_CREDENTIAL_Request*
 213 GNUNET_CREDENTIAL_verify (struct GNUNET_CREDENTIAL_Handle *handle,
 214                           const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
 215                           const char *issuer_attribute,
 216                           const struct GNUNET_CRYPTO_EcdsaPublicKey *subject_key,
 217                           const char *subject_attribute,
 218                           GNUNET_CREDENTIAL_VerifyResultProcessor proc,
 219                           void *proc_cls);
 220
 221 /**
 222  * Delegate an attribute
 223  *
 224  * @param handle handle to the Credential service
 225  * @param issuer the ego that should be used to delegate the attribute
 226  * @param attribute the name of the attribute to delegate
 227  * @param subject the subject of the delegation
 228  * @param delegated_attribute the name of the attribute that is delegated to
 229  * @return handle to the queued request
 230  */
 231 struct GNUNET_CREDENTIAL_Request *
 232 GNUNET_CREDENTIAL_add_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
 233                                   struct GNUNET_IDENTITY_Ego *issuer,
 234                                   const char *attribute,
 235                                   struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
 236                                   const char *delegated_attribute,
 237                                   GNUNET_CREDENTIAL_DelegateResultProcessor proc,
 238                                   void *proc_cls);
 239
 240 /**
 241  * Remove a delegation
 242  *
 243  * @param handle handle to the Credential service
 244  * @param issuer the ego that was used to delegate the attribute
 245  * @param attribute the name of the attribute that is delegated
 246  * @return handle to the queued request
 247  */
 248 struct GNUNET_CREDENTIAL_Request *
 249 GNUNET_CREDENTIAL_remove_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
 250                                   struct GNUNET_IDENTITY_Ego *issuer,
 251                                   const char *attribute,
 252                                   GNUNET_CREDENTIAL_RemoveDelegateResultProcessor proc,
 253                                   void *proc_cls);
 254
 255
 256
 257 /**
 258  * Issue an attribute to a subject
 259  *
 260  * @param handle handle to the Credential service
 261  * @param issuer the ego that should be used to issue the attribute
 262  * @param subject the subject of the attribute
 263  * @param attribute the name of the attribute
 264  * @return handle to the queued request
 265  */
 266 struct GNUNET_CREDENTIAL_Request *
 267 GNUNET_CREDENTIAL_issue (struct GNUNET_CREDENTIAL_Handle *handle,
 268                          struct GNUNET_IDENTITY_Ego *issuer,
 269                          struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
 270                          const char *attribute,
 271                          GNUNET_CREDENTIAL_IssueResultProcessor proc,
 272                          void *proc_cls);
 273
 274
 275 /**
 276  * Remove a credential
 277  *
 278  * @param handle handle to the Credential service
 279  * @param issuer the identity that issued the credential
 280  * @param subject the subject of the credential
 281  * @param credential the name of the credential
 282  * @return handle to the queued request
 283  */
 284 /**
 285   struct GNUNET_CREDENTIAL_IssueRequest *
 286   GNUNET_CREDENTIAL_remove (struct GNUNET_CREDENTIAL_Handle *handle,
 287   struct GNUNET_IDENTITY_Ego *issuer,
 288   struct GNUNET_IDENTITY_Ego *subject,
 289   const char *credential,
 290   GNUNET_CREDENTIAL_IssueResultProcessor proc,
 291   void *proc_cls);
 292   */
 293
 294
 295 /**
 296  * Cancel pending lookup request
 297  *
 298  * @param lr the lookup request to cancel
 299  */
 300 void
 301 GNUNET_CREDENTIAL_verify_cancel (struct GNUNET_CREDENTIAL_Request *vr);
 302
 303
 304 #if 0                           /* keep Emacsens' auto-indent happy */
 305 {
 306 #endif
 307 #ifdef __cplusplus
 308 }
 309 #endif
 310
 311 #endif
 312
 313 /** @} */  /* end of group */