aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_pseudonym_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_pseudonym_lib.h')
-rw-r--r--src/include/gnunet_pseudonym_lib.h271
1 files changed, 229 insertions, 42 deletions
diff --git a/src/include/gnunet_pseudonym_lib.h b/src/include/gnunet_pseudonym_lib.h
index 6ec51b678..11b5cd9e4 100644
--- a/src/include/gnunet_pseudonym_lib.h
+++ b/src/include/gnunet_pseudonym_lib.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 Christian Grothoff (and other contributing authors) 3 (C) 2001--2013 Christian Grothoff (and other contributing authors)
4 4
5 GNUnet is free software; you can redistribute it and/or modify 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 6 it under the terms of the GNU General Public License as published
@@ -39,6 +39,166 @@ extern "C"
39#include "gnunet_configuration_lib.h" 39#include "gnunet_configuration_lib.h"
40#include "gnunet_container_lib.h" 40#include "gnunet_container_lib.h"
41 41
42
43/**
44 * Identifier for a GNUnet pseudonym (the public key).
45 */
46struct GNUNET_PseudonymIdentifier
47{
48 /**
49 * The public key of the pseudonym.
50 */
51 char public_key[42];
52};
53
54
55/**
56 * Handle for a pseudonym (private key).
57 */
58struct GNUNET_PseudonymHandle;
59
60
61/**
62 * Signature made with a pseudonym (includes the full public key)
63 */
64struct GNUNET_PseudonymSignature
65{
66
67 /**
68 * Who created the signature? (public key of the signer)
69 */
70 struct GNUNET_PseudonymIdentifier signer;
71
72 /**
73 * Binary signature data, padded with zeros if needed.
74 */
75 char signature[42];
76};
77
78
79/**
80 * Purpose for signature made with a pseudonym.
81 */
82struct GNUNET_PseudonymSignaturePurpose
83{
84 /**
85 * How many bytes are being signed (including this header)?
86 */
87 uint32_t size;
88
89 /**
90 * What is the context/purpose of the signature?
91 */
92 uint32_t purpose;
93};
94
95
96/**
97 * Create a pseudonym.
98 *
99 * @param filename name of the file to use for storage, NULL for in-memory only
100 * @return handle to the private key of the pseudonym
101 */
102struct GNUNET_PseudonymHandle *
103GNUNET_PSEUDONYM_create (const char *filename);
104
105
106/**
107 * Create a pseudonym, from a file that must already exist.
108 *
109 * @param filename name of the file to use for storage, NULL for in-memory only
110 * @return handle to the private key of the pseudonym
111 */
112struct GNUNET_PseudonymHandle *
113GNUNET_PSEUDONYM_create_from_existing_file (const char *filename);
114
115
116/**
117 * Get the handle for the 'anonymous' pseudonym shared by all users.
118 * That pseudonym uses a fixed 'secret' for the private key; this
119 * construction is useful to make anonymous and pseudonymous APIs
120 * (and packets) indistinguishable on the network. See #2564.
121 *
122 * @return handle to the (non-secret) private key of the 'anonymous' pseudonym
123 */
124struct GNUNET_PseudonymHandle *
125GNUNET_PSEUDONYM_get_anonymous_pseudonym_handle (void);
126
127
128/**
129 * Destroy a pseudonym handle. Does NOT remove the private key from
130 * the disk.
131 *
132 * @param ph pseudonym handle to destroy
133 */
134void
135GNUNET_PSEUDONYM_destroy (struct GNUNET_PseudonymHandle *ph);
136
137
138/**
139 * Cryptographically sign some data with the pseudonym.
140 *
141 * @param ph private key used for signing (corresponds to 'x' in #2564)
142 * @param purpose data to sign
143 * @param seed hash of the plaintext of the data that we are signing,
144 * used for deterministic PRNG for anonymous signing;
145 * corresponds to 'k' in section 2.7 of #2564
146 * @param signing_key modifier to apply to the private key for signing;
147 * corresponds to 'h' in section 2.3 of #2564.
148 * @param signature where to store the signature
149 */
150void
151GNUNET_PSEUDONYM_sign (struct GNUNET_PseudonymHandle *ph,
152 const struct GNUNET_PseudonymSignaturePurpose *purpose,
153 const struct GNUNET_HashCode *seed,
154 const struct GNUNET_HashCode *signing_key,
155 struct GNUNET_PseudonymSignature *signature);
156
157
158/**
159 * Given a pseudonym and a signing key, derive the corresponding public
160 * key that would be used to verify the resulting signature.
161 *
162 * @param pseudonym the public key (g^x)
163 * @param signing_key input to derive 'h' (see section 2.4 of #2564)
164 * @param verification_key resulting public key to verify the signature
165 * created from the 'ph' of 'pseudonym' and the 'signing_key';
166 * the value stored here can then be given to GNUNET_PSEUDONYM_verify.
167 */
168void
169GNUNET_PSEUDONYM_derive_verification_key (struct GNUNET_PseudonymIdentifier *pseudonym,
170 const struct GNUNET_HashCode *signing_key,
171 struct GNUNET_PseudonymIdentifier *verification_key);
172
173
174/**
175 * Verify a signature made with a pseudonym.
176 *
177 * @param purpose data that was signed
178 * @param signature signature to verify
179 * @param verification_key public key to use for checking the signature;
180 * corresponds to 'g^(x+h)' in section 2.4 of #2564.
181 * @return GNUNET_OK on success (signature valid, 'pseudonym' set),
182 * GNUNET_SYSERR if the signature is invalid
183 */
184int
185GNUNET_PSEUDONYM_verify (const struct GNUNET_PseudonymSignaturePurpose *purpose,
186 const struct GNUNET_PseudonymSignature *signature,
187 const struct GNUNET_PseudonymIdentifier *verification_key);
188
189
190/**
191 * Get the identifier (public key) of a pseudonym.
192 *
193 * @param ph pseudonym handle with the private key
194 * @param pseudonym pseudonym identifier (set based on 'ph')
195 */
196void
197GNUNET_PSEUDONYM_get_identifier (struct GNUNET_PseudonymHandle *ph,
198 struct GNUNET_PseudonymIdentifier *pseudonym);
199
200
201
42/** 202/**
43 * Iterator over all known pseudonyms. 203 * Iterator over all known pseudonyms.
44 * 204 *
@@ -51,23 +211,26 @@ extern "C"
51 * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort 211 * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
52 */ 212 */
53typedef int (*GNUNET_PSEUDONYM_Iterator) (void *cls, 213typedef int (*GNUNET_PSEUDONYM_Iterator) (void *cls,
54 const struct GNUNET_HashCode * pseudonym, 214 const struct GNUNET_PseudonymIdentifier *pseudonym,
55 const char *name, 215 const char *name,
56 const char *unique_name, 216 const char *unique_name,
57 const struct GNUNET_CONTAINER_MetaData 217 const struct GNUNET_CONTAINER_MetaData *md,
58 * md, int rating); 218 int32_t rating);
219
59 220
60/** 221/**
61 * Change the ranking of a pseudonym. 222 * Change the rank of a pseudonym.
62 * 223 *
63 * @param cfg overall configuration 224 * @param cfg overall configuration
64 * @param nsid id of the pseudonym 225 * @param pseudonym identity of the pseudonym
65 * @param delta by how much should the rating be changed? 226 * @param delta by how much should the rating be changed?
66 * @return new rating of the namespace 227 * @return new rating of the pseudonym
67 */ 228 */
68int 229int
69GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg, 230GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg,
70 const struct GNUNET_HashCode * nsid, int delta); 231 const struct GNUNET_PseudonymIdentifier *pseudonym,
232 int32_t delta);
233
71 234
72/** 235/**
73 * Add a pseudonym to the set of known pseudonyms. 236 * Add a pseudonym to the set of known pseudonyms.
@@ -77,10 +240,11 @@ GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg,
77 * @param cfg overall configuration 240 * @param cfg overall configuration
78 * @param id the pseudonym identifier 241 * @param id the pseudonym identifier
79 * @param meta metadata for the pseudonym 242 * @param meta metadata for the pseudonym
243 * @return GNUNET_OK on success, GNUNET_SYSERR on failure
80 */ 244 */
81void 245int
82GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg, 246GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg,
83 const struct GNUNET_HashCode * id, 247 const struct GNUNET_PseudonymIdentifier *pseudonym,
84 const struct GNUNET_CONTAINER_MetaData *meta); 248 const struct GNUNET_CONTAINER_MetaData *meta);
85 249
86 250
@@ -89,37 +253,51 @@ GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg,
89 * 253 *
90 * @param cfg overall configuration 254 * @param cfg overall configuration
91 * @param iterator function to call for each pseudonym 255 * @param iterator function to call for each pseudonym
92 * @param closure closure for iterator 256 * @param iterator_cls closure for iterator
93 * @return number of pseudonyms found 257 * @return number of pseudonyms found
94 */ 258 */
95int 259int
96GNUNET_PSEUDONYM_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg, 260GNUNET_PSEUDONYM_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg,
97 GNUNET_PSEUDONYM_Iterator iterator, void *closure); 261 GNUNET_PSEUDONYM_Iterator iterator,
262 void *iterator_cls);
263
264
265/**
266 * Handle for a discovery callback registration.
267 */
268struct GNUNET_PSEUDONYM_DiscoveryHandle;
269
98 270
99/** 271/**
100 * Register callback to be invoked whenever we discover 272 * Register callback to be invoked whenever we discover
101 * a new pseudonym. 273 * a new pseudonym.
274 *
275 * @param cfg our configuration
276 * @param iterator function to invoke on discovery
277 * @param iterator_cls closure for iterator
278 * @return registration handle
102 */ 279 */
103int 280struct GNUNET_PSEUDONYM_DiscoveryHandle *
104GNUNET_PSEUDONYM_discovery_callback_register (const struct 281GNUNET_PSEUDONYM_discovery_callback_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
105 GNUNET_CONFIGURATION_Handle *cfg, 282 GNUNET_PSEUDONYM_Iterator iterator,
106 GNUNET_PSEUDONYM_Iterator 283 void *iterator_cls);
107 iterator, void *closure); 284
108 285
109/** 286/**
110 * Unregister namespace discovery callback. 287 * Unregister pseudonym discovery callback.
288 *
289 * @param dh registration to unregister
111 */ 290 */
112int 291void
113GNUNET_PSEUDONYM_discovery_callback_unregister (GNUNET_PSEUDONYM_Iterator 292GNUNET_PSEUDONYM_discovery_callback_unregister (struct GNUNET_PSEUDONYM_DiscoveryHandle *dh);
114 iterator, void *closure); 293
115 294
116/** 295/**
117 * Return unique variant of the namespace name. 296 * Return unique variant of the pseudonym name. Use after
118 * Use after GNUNET_PSEUDONYM_id_to_name() to make sure 297 * GNUNET_PSEUDONYM_id_to_name() to make sure that name is unique.
119 * that name is unique.
120 * 298 *
121 * @param cfg configuration 299 * @param cfg configuration
122 * @param nsid cryptographic ID of the namespace 300 * @param pseudonym cryptographic ID of the pseudonym
123 * @param name name to uniquify 301 * @param name name to uniquify
124 * @param suffix if not NULL, filled with the suffix value 302 * @param suffix if not NULL, filled with the suffix value
125 * @return NULL on failure (should never happen), name on success. 303 * @return NULL on failure (should never happen), name on success.
@@ -127,18 +305,20 @@ GNUNET_PSEUDONYM_discovery_callback_unregister (GNUNET_PSEUDONYM_Iterator
127 */ 305 */
128char * 306char *
129GNUNET_PSEUDONYM_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg, 307GNUNET_PSEUDONYM_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg,
130 const struct GNUNET_HashCode * nsid, const char *name, unsigned int *suffix); 308 const struct GNUNET_PseudonymIdentifier *pseudonym,
309 const char *name,
310 unsigned int *suffix);
311
131 312
132/** 313/**
133 * Get namespace name, metadata and rank 314 * Get pseudonym name, metadata and rank. This is a wrapper around
134 * This is a wrapper around internal read_info() call, and ensures that 315 * internal read_info() call, and ensures that returned data is not
135 * returned data is not invalid (not NULL). 316 * invalid (not NULL). Writing back information returned by this
136 * Writing back information returned by this function will give 317 * function will give a name "no-name" to pseudonyms that have no
137 * a name "no-name" to pseudonyms that have no name. This side-effect is 318 * name. This side-effect is unavoidable, but hardly harmful.
138 * unavoidable, but hardly harmful.
139 * 319 *
140 * @param cfg configuration 320 * @param cfg configuration
141 * @param nsid cryptographic ID of the namespace 321 * @param pseudonym cryptographic ID of the pseudonym
142 * @param ret_meta a location to store metadata pointer. NULL, if metadata 322 * @param ret_meta a location to store metadata pointer. NULL, if metadata
143 * is not needed. Destroy with GNUNET_CONTAINER_meta_data_destroy(). 323 * is not needed. Destroy with GNUNET_CONTAINER_meta_data_destroy().
144 * @param ret_rank a location to store rank. NULL, if rank not needed. 324 * @param ret_rank a location to store rank. NULL, if rank not needed.
@@ -152,27 +332,32 @@ GNUNET_PSEUDONYM_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg,
152 */ 332 */
153int 333int
154GNUNET_PSEUDONYM_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg, 334GNUNET_PSEUDONYM_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
155 const struct GNUNET_HashCode * nsid, struct GNUNET_CONTAINER_MetaData **ret_meta, 335 const struct GNUNET_PseudonymIdentifier *pseudonym,
156 int32_t *ret_rank, char **ret_name, int *name_is_a_dup); 336 struct GNUNET_CONTAINER_MetaData **ret_meta,
337 int32_t *ret_rank,
338 char **ret_name,
339 int *name_is_a_dup);
157 340
158 341
159/** 342/**
160 * Get the namespace ID belonging to the given namespace name. 343 * Get the pseudonym ID belonging to the given pseudonym name.
161 * 344 *
162 * @param cfg configuration to use 345 * @param cfg configuration to use
163 * @param ns_uname unique (!) human-readable name for the namespace 346 * @param ps_uname unique (!) human-readable name for the pseudonym
164 * @param nsid set to namespace ID based on 'ns_uname' 347 * @param pseudonym set to pseudonym ID based on 'ns_uname'
165 * @return GNUNET_OK on success, GNUNET_SYSERR on failure 348 * @return GNUNET_OK on success, GNUNET_SYSERR on failure
166 */ 349 */
167int 350int
168GNUNET_PSEUDONYM_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg, 351GNUNET_PSEUDONYM_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg,
169 const char *ns_uname, struct GNUNET_HashCode * nsid); 352 const char *ps_uname,
353 struct GNUNET_PseudonymIdentifier *pseudonym);
354
170 355
171/** 356/**
172 * Set the pseudonym metadata, rank and name. 357 * Set the pseudonym metadata, rank and name.
173 * 358 *
174 * @param cfg overall configuration 359 * @param cfg overall configuration
175 * @param nsid id of the pseudonym 360 * @param pseudonym id of the pseudonym
176 * @param name name to set. Must be the non-unique version of it. 361 * @param name name to set. Must be the non-unique version of it.
177 * May be NULL, in which case it erases pseudonym's name! 362 * May be NULL, in which case it erases pseudonym's name!
178 * @param md metadata to set 363 * @param md metadata to set
@@ -182,8 +367,10 @@ GNUNET_PSEUDONYM_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg,
182 */ 367 */
183int 368int
184GNUNET_PSEUDONYM_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg, 369GNUNET_PSEUDONYM_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
185 const struct GNUNET_HashCode * nsid, const char *name, 370 const struct GNUNET_PseudonymIdentifier *pseudonym,
186 const struct GNUNET_CONTAINER_MetaData *md, int rank); 371 const char *name,
372 const struct GNUNET_CONTAINER_MetaData *md,
373 int32_t rank);
187 374
188 375
189#if 0 /* keep Emacsens' auto-indent happy */ 376#if 0 /* keep Emacsens' auto-indent happy */