2 This file is part of GNUnet
3 Copyright (C) 2012-2014 GNUnet e.V.
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.
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.
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/>.
20 * @author Martin Schanzenbach
23 * API to the Credential service
25 * @defgroup credential Credential service
30 #ifndef GNUNET_CREDENTIAL_SERVICE_H
31 #define GNUNET_CREDENTIAL_SERVICE_H
33 #include "gnunet_util_lib.h"
34 #include "gnunet_gns_service.h"
35 #include "gnunet_identity_service.h"
40 #if 0 /* keep Emacsens' auto-indent happy */
47 * Connection to the Credential service.
49 struct GNUNET_CREDENTIAL_Handle;
52 * Handle to control a lookup operation.
54 struct GNUNET_CREDENTIAL_Request;
57 * Enum used for checking whether the issuer has the authority to issue credentials or is just a subject
59 enum GNUNET_CREDENTIAL_CredentialFlags {
61 //Subject had credentials before, but have been revoked now
62 GNUNET_CREDENTIAL_FLAG_REVOKED=0,
64 //Subject flag indicates that the subject is a holder of this credential and may present it as such
65 GNUNET_CREDENTIAL_FLAG_SUBJECT=1,
67 //Issuer flag is used to signify that the subject is allowed to issue this credential and delegate issuance
68 GNUNET_CREDENTIAL_FLAG_ISSUER=2
72 GNUNET_NETWORK_STRUCT_BEGIN
74 * The attribute delegation record
76 struct GNUNET_CREDENTIAL_DelegationRecord {
79 * Number of delegation sets in this record
84 * Length of delegation sets
88 * Followed by set_count DelegationSetRecords
94 * The attribute delegation record
96 struct GNUNET_CREDENTIAL_DelegationRecordSet {
99 * Public key of the subject this attribute was delegated to
101 struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
104 * Length of attribute, may be 0
106 uint32_t subject_attribute_len;
110 GNUNET_NETWORK_STRUCT_END
113 * The attribute delegation record
115 struct GNUNET_CREDENTIAL_DelegationSet {
118 * Public key of the subject this attribute was delegated to
120 struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
122 uint32_t subject_attribute_len;
125 * The subject attribute
127 const char *subject_attribute;
134 struct GNUNET_CREDENTIAL_Delegation {
137 * The issuer of the delegation
139 struct GNUNET_CRYPTO_EcdsaPublicKey issuer_key;
142 * Public key of the subject this attribute was delegated to
144 struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
147 * Length of the attribute
149 uint32_t issuer_attribute_len;
154 const char *issuer_attribute;
157 * Length of the attribute
159 uint32_t subject_attribute_len;
164 const char *subject_attribute;
171 struct GNUNET_CREDENTIAL_Credential {
174 * The issuer of the credential
176 struct GNUNET_CRYPTO_EcdsaPublicKey issuer_key;
179 * Public key of the subject this credential was issued to
181 struct GNUNET_CRYPTO_EcdsaPublicKey subject_key;
184 * Signature of this credential
186 struct GNUNET_CRYPTO_EcdsaSignature signature;
189 * Expiration of this credential
191 struct GNUNET_TIME_Absolute expiration;
194 * Length of the attribute
196 uint32_t issuer_attribute_len;
201 const char *issuer_attribute;
208 * Initialize the connection with the Credential service.
210 * @param cfg configuration to use
211 * @return handle to the Credential service, or NULL on error
213 struct GNUNET_CREDENTIAL_Handle *
214 GNUNET_CREDENTIAL_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
218 * Shutdown connection with the Credentail service.
220 * @param handle connection to shut down
223 GNUNET_CREDENTIAL_disconnect (struct GNUNET_CREDENTIAL_Handle *handle);
227 * Iterator called on obtained result for an attribute verification.
230 * @param d_count the number of delegations processed
231 * @param delegation_chain the delegations processed
232 * @param c_count the number of credentials found
233 * @param credential the credentials
235 typedef void (*GNUNET_CREDENTIAL_CredentialResultProcessor) (void *cls,
236 unsigned int d_count,
237 struct GNUNET_CREDENTIAL_Delegation *delegation_chain,
238 unsigned int c_count,
239 struct GNUNET_CREDENTIAL_Credential *credential);
242 * Iterator called on obtained result for an attribute delegation.
245 * @param success GNUNET_YES if successful
246 * @param result the record data that can be handed to the subject
248 typedef void (*GNUNET_CREDENTIAL_DelegateResultProcessor) (void *cls,
252 * Iterator called on obtained result for an attribute delegation removal.
255 * @param success GNUNET_YES if successful
256 * @param result the record data that can be handed to the subject
258 typedef void (*GNUNET_CREDENTIAL_RemoveDelegateResultProcessor) (void *cls,
263 * Performs attribute verification.
264 * Checks if there is a delegation chain from
265 * attribute ``issuer_attribute'' issued by the issuer
266 * with public key ``issuer_key'' maps to the attribute
267 * ``subject_attribute'' claimed by the subject with key
270 * @param handle handle to the Credential service
271 * @param issuer_key the issuer public key
272 * @param issuer_attribute the issuer attribute
273 * @param subject_key the subject public key
274 * @param credential_count number of credentials
275 * @param credentials the subject credentials
276 * @param proc function to call on result
277 * @param proc_cls closure for processor
278 * @return handle to the queued request
280 struct GNUNET_CREDENTIAL_Request*
281 GNUNET_CREDENTIAL_verify (struct GNUNET_CREDENTIAL_Handle *handle,
282 const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
283 const char *issuer_attribute,
284 const struct GNUNET_CRYPTO_EcdsaPublicKey *subject_key,
285 uint32_t credential_count,
286 const struct GNUNET_CREDENTIAL_Credential *credentials,
287 GNUNET_CREDENTIAL_CredentialResultProcessor proc,
290 struct GNUNET_CREDENTIAL_Request*
291 GNUNET_CREDENTIAL_collect (struct GNUNET_CREDENTIAL_Handle *handle,
292 const struct GNUNET_CRYPTO_EcdsaPublicKey *issuer_key,
293 const char *issuer_attribute,
294 const struct GNUNET_CRYPTO_EcdsaPrivateKey *subject_key,
295 GNUNET_CREDENTIAL_CredentialResultProcessor proc,
299 * Delegate an attribute
301 * @param handle handle to the Credential service
302 * @param issuer the ego that should be used to delegate the attribute
303 * @param attribute the name of the attribute to delegate
304 * @param subject the subject of the delegation
305 * @param delegated_attribute the name of the attribute that is delegated to
306 * @param proc the result callback
307 * @param proc_cls the result closure context
308 * @return handle to the queued request
310 struct GNUNET_CREDENTIAL_Request *
311 GNUNET_CREDENTIAL_add_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
312 struct GNUNET_IDENTITY_Ego *issuer,
313 const char *attribute,
314 struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
315 const char *delegated_attribute,
316 GNUNET_CREDENTIAL_DelegateResultProcessor proc,
320 * Remove a delegation
322 * @param handle handle to the Credential service
323 * @param issuer the ego that was used to delegate the attribute
324 * @param attribute the name of the attribute that is delegated
325 * @param proc the callback
326 * @param proc_cls callback closure
327 * @return handle to the queued request
329 struct GNUNET_CREDENTIAL_Request *
330 GNUNET_CREDENTIAL_remove_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
331 struct GNUNET_IDENTITY_Ego *issuer,
332 const char *attribute,
333 GNUNET_CREDENTIAL_RemoveDelegateResultProcessor proc,
339 * Issue an attribute to a subject
341 * @param issuer the ego that should be used to issue the attribute
342 * @param subject the subject of the attribute
343 * @param attribute the name of the attribute
344 * @param expiration the TTL of the credential
345 * @return handle to the queued request
347 struct GNUNET_CREDENTIAL_Credential*
348 GNUNET_CREDENTIAL_credential_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *issuer,
349 struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
350 const char *attribute,
351 struct GNUNET_TIME_Absolute *expiration);
356 * Cancel pending lookup request
358 * @param lr the lookup request to cancel
361 GNUNET_CREDENTIAL_request_cancel (struct GNUNET_CREDENTIAL_Request *lr);
364 #if 0 /* keep Emacsens' auto-indent happy */
373 /** @} */ /* end of group */