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