diff options
Diffstat (limited to 'src/include/gnunet_pseudonym_lib.h')
-rw-r--r-- | src/include/gnunet_pseudonym_lib.h | 271 |
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 | */ | ||
46 | struct 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 | */ | ||
58 | struct GNUNET_PseudonymHandle; | ||
59 | |||
60 | |||
61 | /** | ||
62 | * Signature made with a pseudonym (includes the full public key) | ||
63 | */ | ||
64 | struct 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 | */ | ||
82 | struct 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 | */ | ||
102 | struct GNUNET_PseudonymHandle * | ||
103 | GNUNET_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 | */ | ||
112 | struct GNUNET_PseudonymHandle * | ||
113 | GNUNET_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 | */ | ||
124 | struct GNUNET_PseudonymHandle * | ||
125 | GNUNET_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 | */ | ||
134 | void | ||
135 | GNUNET_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 | */ | ||
150 | void | ||
151 | GNUNET_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 | */ | ||
168 | void | ||
169 | GNUNET_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 | */ | ||
184 | int | ||
185 | GNUNET_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 | */ | ||
196 | void | ||
197 | GNUNET_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 | */ |
53 | typedef int (*GNUNET_PSEUDONYM_Iterator) (void *cls, | 213 | typedef 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 | */ |
68 | int | 229 | int |
69 | GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg, | 230 | GNUNET_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 | */ |
81 | void | 245 | int |
82 | GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg, | 246 | GNUNET_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 | */ |
95 | int | 259 | int |
96 | GNUNET_PSEUDONYM_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg, | 260 | GNUNET_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 | */ | ||
268 | struct 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 | */ |
103 | int | 280 | struct GNUNET_PSEUDONYM_DiscoveryHandle * |
104 | GNUNET_PSEUDONYM_discovery_callback_register (const struct | 281 | GNUNET_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 | */ |
112 | int | 291 | void |
113 | GNUNET_PSEUDONYM_discovery_callback_unregister (GNUNET_PSEUDONYM_Iterator | 292 | GNUNET_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 | */ |
128 | char * | 306 | char * |
129 | GNUNET_PSEUDONYM_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg, | 307 | GNUNET_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 | */ |
153 | int | 333 | int |
154 | GNUNET_PSEUDONYM_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg, | 334 | GNUNET_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 | */ |
167 | int | 350 | int |
168 | GNUNET_PSEUDONYM_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg, | 351 | GNUNET_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 | */ |
183 | int | 368 | int |
184 | GNUNET_PSEUDONYM_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg, | 369 | GNUNET_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 */ |