1 /*
2
3 silcid.h
4
5 Author: Pekka Riikonen <priikone@silcnet.org>
6
7 Copyright (C) 1997 - 2008 Pekka Riikonen
8
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 */
19
20 /****h* silccore/SILC ID Interface
21 *
22 * DESCRIPTION
23 *
24 * These are important ID types used in SILC. SILC server creates these
25 * but SILC client has to handle these as well since these are used in
26 * packet sending and reception. However, client never creates these
27 * but it receives the correct ID's from server. Clients, servers and
28 * channels are identified by the these ID's.
29 *
30 * The ID's are based on IP addresses. The IP address provides a good
31 * way to distinguish the ID's from other ID's. The ID's supports both
32 * IPv4 and IPv6.
33 *
34 * This file also includes the implementation of the SILC ID Payload
35 * parsing and encoding.
36 *
37 ***/
38
39 #ifndef SILCID_H
40 #define SILCID_H
41
42 /* The ID Lenghts. These are IPv4 based and should be noted if used directly
43 that these cannot be used with IPv6. */
44 #define SILC_ID_SERVER_LEN (64 / 8)
45 #define SILC_ID_CLIENT_LEN (128 / 8)
46 #define SILC_ID_CHANNEL_LEN (64 / 8)
47
48 #define CLIENTID_HASH_LEN (88 / 8) /* Client ID's 88 bit MD5 hash */
49
50 /****d* silccore/SilcIDAPI/SilcIdType
51 *
52 * NAME
53 *
54 * typedef SilcUInt16 SilcIdType;
55 *
56 * DESCRIPTION
57 *
58 * SILC ID type definitions and the ID types.
59 *
60 * SOURCE
61 */
62 typedef SilcUInt16 SilcIdType;
63
64 /* The SILC ID Types */
65 #define SILC_ID_NONE 0
66 #define SILC_ID_SERVER 1
67 #define SILC_ID_CLIENT 2
68 #define SILC_ID_CHANNEL 3
69 /***/
70
71 /****s* silccore/SilcIDAPI/SilcIDIP
72 *
73 * NAME
74 *
75 * typedef struct { ... } SilcIDIP;
76 *
77 * DESCRIPTION
78 *
79 * Generic IP address structure to indicate either IPv4 or IPv6 address.
80 * This structure is used inside all SILC ID's. The true length of the
81 * ID depends of the length of the IP address.
82 *
83 * SOURCE
84 */
85 typedef struct SilcIDIPStruct {
86 unsigned char data[16]; /* IP data (in MSB first order) */
87 SilcUInt8 data_len; /* Length of the data (4 or 16) */
88 } SilcIDIP;
89 /***/
90
91 /****s* silccore/SilcIDAPI/SilcServerID
92 *
93 * NAME
94 *
95 * typedef struct { ... } SilcServerID;
96 *
97 * DESCRIPTION
98 *
99 * 64 or 160 bit SilcServerID structure:
100 *
101 * n bit IP address
102 * 16 bit port
103 * 16 bit random number
104 *
105 * SOURCE
106 */
107 typedef struct SilcServerIDStruct {
108 SilcIDIP ip; /* n bit IP address */
109 SilcUInt16 port; /* 16 bit port */
110 SilcUInt16 rnd; /* 16 bit random number */
111 } SilcServerID;
112 /***/
113
114 /****s* silccore/SilcIDAPI/SilcClientID
115 *
116 * NAME
117 *
118 * typedef struct { ... } SilcClientID;
119 *
120 * DESCRIPTION
121 *
122 * 128 or 224 bit SilcClientID structure:
123 *
124 * n bit ServerID IP address [bits 1-32 or bits 1-128]
125 * 8 bit random number
126 * 88 bit hash value from lowercase nickname
127 *
128 * SOURCE
129 */
130 typedef struct SilcClientIDStruct {
131 SilcIDIP ip; /* n bit IP address */
132 unsigned char rnd; /* 8 bit random number */
133 unsigned char hash[CLIENTID_HASH_LEN]; /* 88 bit MD5 hash */
134 } SilcClientID;
135 /***/
136
137 /****s* silccore/SilcIDAPI/SilcChannelID
138 *
139 * NAME
140 *
141 * typedef struct { ... } SilcChannelID;
142 *
143 * DESCRIPTION
144 *
145 * 64 or 160 bit SilcChannel ID structure:
146 *
147 * n bit Router's ServerID IP address [bits 1-32 or bits 1-128]
148 * 16 bit Router's ServerID port [bits 33-48 or bits 129-144]
149 * 16 bit random number
150 *
151 * SOURCE
152 */
153 typedef struct SilcChannelIDStruct {
154 SilcIDIP ip; /* n bit IP address */
155 SilcUInt16 port; /* 16 bit port */
156 SilcUInt16 rnd; /* 16 bit random number */
157 } SilcChannelID;
158 /***/
159
160 /****s* silccore/SilcIDAPI/SilcID
161 *
162 * NAME
163 *
164 * typedef struct { ... } SilcID;
165 *
166 * DESCRIPTION
167 *
168 * The generic ID structure that can represent SilcClientID, SilcServerID
169 * and SilcChannelID. The silc_id_payload_parse_id returns the ID in the
170 * SilcID structure. Other routines except either SilcClientID,
171 * SilcServerID or SilcChannelID as a void pointer.
172 *
173 * SOURCE
174 */
175 typedef struct SilcIDStruct {
176 union {
177 SilcServerID server_id;
178 SilcChannelID channel_id;
179 SilcClientID client_id;
180 } u;
181 SilcIdType type;
182 } SilcID;
183 /***/
184
185 /* Macros */
186
187 /****d* silccore/SilcIDAPI/SILC_ID_GET_ID
188 *
189 * NAME
190 *
191 * #define SILC_ID_GET_ID ...
192 *
193 * DESCRIPTION
194 *
195 * Returns the ID type specific pointer from the SilcID structure. As
196 * the SilcID is able to house all types of IDs this macro can be used
197 * to get the specific ID from the structure by its type.
198 *
199 * SOURCE
200 */
201 #define SILC_ID_GET_ID(id) \
202 ((id).type == SILC_ID_CLIENT ? (void *)&(id).u.client_id : \
203 (id).type == SILC_ID_SERVER ? (void *)&(id).u.server_id : \
204 (void *)&(id).u.channel_id)
205 /***/
206
207 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE
208 *
209 * NAME
210 *
211 * #define SILC_ID_COMPARE ...
212 *
213 * DESCRIPTION
214 *
215 * Compares two ID's. Returns TRUE if they match and FALSE if they do
216 * not.
217 *
218 * SOURCE
219 */
220 #define SILC_ID_COMPARE(id1, id2, len) (!memcmp(id1, id2, len))
221 /***/
222
223 /****d* silccore/SilcIDAPI/SILC_ID_CLIENT_COMPARE
224 *
225 * NAME
226 *
227 * #define SILC_ID_CLIENT_COMPARE ...
228 *
229 * DESCRIPTION
230 *
231 * Compares Client ID's. Returns TRUE if they match.
232 *
233 * SOURCE
234 */
235 #define SILC_ID_CLIENT_COMPARE(id1, id2) \
236 SILC_ID_COMPARE(id1, id2, sizeof(SilcClientID))
237 /***/
238
239 /****d* silccore/SilcIDAPI/SILC_ID_SERVER_COMPARE
240 *
241 * NAME
242 *
243 * #define SILC_ID_SERVER_COMPARE ...
244 *
245 * DESCRIPTION
246 *
247 * Compares Server ID's. Returns TRUE if they match.
248 *
249 * SOURCE
250 */
251 #define SILC_ID_SERVER_COMPARE(id1, id2) \
252 SILC_ID_COMPARE(id1, id2, sizeof(SilcServerID))
253 /***/
254
255 /****d* silccore/SilcIDAPI/SILC_ID_CHANNEL_COMPARE
256 *
257 * NAME
258 *
259 * #define SILC_ID_CHANNEL_COMPARE ...
260 *
261 * DESCRIPTION
262 *
263 * Compares Channel ID's. Returns TRUE if they match.
264 *
265 * SOURCE
266 */
267 #define SILC_ID_CHANNEL_COMPARE(id1, id2) \
268 SILC_ID_COMPARE(id1, id2, sizeof(SilcChannelID))
269 /***/
270
271 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_TYPE
272 *
273 * NAME
274 *
275 * #define SILC_ID_COMPARE_TYPE ...
276 *
277 * DESCRIPTION
278 *
279 * Compares two ID's by type. Returns TRUE if they match.
280 *
281 * SOURCE
282 */
283 #define SILC_ID_COMPARE_TYPE(id1, id2, type) \
284 (type == SILC_ID_SERVER ? SILC_ID_SERVER_COMPARE(id1, id2) : \
285 type == SILC_ID_CLIENT ? SILC_ID_CLIENT_COMPARE(id1, id2) : \
286 SILC_ID_CHANNEL_COMPARE(id1, id2))
287 /***/
288
289 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_HASH
290 *
291 * NAME
292 *
293 * #define SILC_ID_COMPARE_HASH ...
294 *
295 * DESCRIPTION
296 *
297 * Compares the nickname hash of the Client ID. Returns TRUE if
298 * they match. Since the nickname hash is based on the nickname of
299 * the client this can be used to search the ID by nickname (taking
300 * the hash out of it) or using the hash from the ID.
301 *
302 * SOURCE
303 */
304 #define SILC_ID_COMPARE_HASH(id1, id2) \
305 (!memcmp((id1)->hash, (id2)->hash, CLIENTID_HASH_LEN))
306 /***/
307
308 /****s* silccore/SilcIDAPI/SilcIDPayload
309 *
310 * NAME
311 *
312 * typedef struct SilcIDPayloadStruct *SilcIDPayload;
313 *
314 * DESCRIPTION
315 *
316 * This context is the actual ID Payload and is allocated by
317 * silc_id_payload_parse and given as argument usually to all
318 * silc_id_payload_* functions. It is freed by the function
319 * silc_id_payload_free.
320 *
321 ***/
322 typedef struct SilcIDPayloadStruct *SilcIDPayload;
323
324 /* Prototypes */
325
326 /****f* silccore/SilcIDAPI/silc_id_payload_parse
327 *
328 * SYNOPSIS
329 *
330 * SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
331 * SilcUInt32 payload_len);
332 *
333 * DESCRIPTION
334 *
335 * Parses buffer and return ID payload into payload structure. The
336 * `buffer' is raw payload buffer. The caller must free the returned
337 * payload.
338 *
339 ***/
340 SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
341 SilcUInt32 payload_len);
342
343 /****f* silccore/SilcIDAPI/silc_id_payload_parse_id
344 *
345 * SYNOPSIS
346 *
347 * SilcBool silc_id_payload_parse_id(const unsigned char *data,
348 * SilcUInt32 len, SilcID *ret_id);
349 *
350 * DESCRIPTION
351 *
352 * Return ID directly from the raw ID Payload data buffer. This does
353 * not allocate any memory.
354 *
355 ***/
356 SilcBool silc_id_payload_parse_id(const unsigned char *data, SilcUInt32 len,
357 SilcID *ret_id);
358
359 /****f* silccore/SilcIDAPI/silc_id_payload_encode
360 *
361 * SYNOPSIS
362 *
363 * SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
364 *
365 * DESCRIPTION
366 *
367 * Encodes ID Payload. The `id' is the ID of the type `type' to put
368 * into the payload. Returns the encoded payload buffer.
369 *
370 ***/
371 SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
372
373 /****f* silccore/SilcIDAPI/silc_id_payload_encode_data
374 *
375 * SYNOPSIS
376 *
377 * SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
378 * uin32 id_len, SilcIdType type);
379 *
380 * DESCRIPTION
381 *
382 * Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
383 * of type of `type'. Returns the encoded payload buffer.
384 *
385 ***/
386 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
387 SilcUInt32 id_len, SilcIdType type);
388
389 /****f* silccore/SilcIDAPI/silc_id_payload_free
390 *
391 * SYNOPSIS
392 *
393 * void silc_id_payload_free(SilcIDPayload payload);
394 *
395 * DESCRIPTION
396 *
397 * Frees the ID Payload and all data in it.
398 *
399 ***/
400 void silc_id_payload_free(SilcIDPayload payload);
401
402 /****f* silccore/SilcIDAPI/silc_id_payload_get_type
403 *
404 * SYNOPSIS
405 *
406 * SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
407 *
408 * DESCRIPTION
409 *
410 * Returns the ID type from the ID Payload. The type tells the
411 * type of the ID in the payload.
412 *
413 ***/
414 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
415
416 /****f* silccore/SilcIDAPI/silc_id_payload_get_id
417 *
418 * SYNOPSIS
419 *
420 * SilcBool silc_id_payload_get_id(SilcIDPayload payload, void *ret_id,
421 * SilcUInt32 ret_id_len);
422 *
423 * DESCRIPTION
424 *
425 * Returns the ID in the ID Payload. This does not allocate any memory.
426 *
427 ***/
428 SilcBool silc_id_payload_get_id(SilcIDPayload payload, void *ret_id,
429 SilcUInt32 ret_id_len);
430
431 /****f* silccore/SilcIDAPI/silc_id_payload_get_data
432 *
433 * SYNOPSIS
434 *
435 * unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
436 *
437 * DESCRIPTION
438 *
439 * Returns the raw ID data from the ID Payload. The data is duplicated
440 * and the caller must free it.
441 *
442 ***/
443 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
444
445 /****f* silccore/SilcIDAPI/silc_id_payload_get_len
446 *
447 * SYNOPSIS
448 *
449 * SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
450 *
451 * DESCRIPTION
452 *
453 * Returns the length of the ID in the ID Payload.
454 *
455 ***/
456 SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
457
458 /****f* silccore/SilcIDAPI/silc_id_id2str
459 *
460 * SYNOPSIS
461 *
462 * SilcBool silc_id_id2str(const void *id, SilcIdType type,
463 * unsigned char *ret_id, SilcUInt32 ret_id_size,
464 * SilcUInt32 *ret_id_len);
465 *
466 * DESCRIPTION
467 *
468 * Converts an ID of type `type' to data. This can be used to
469 * convert the ID's to data for inclusion in the packets. This does
470 * not allocate any memory.
471 *
472 ***/
473 SilcBool silc_id_id2str(const void *id, SilcIdType type,
474 unsigned char *ret_id, SilcUInt32 ret_id_size,
475 SilcUInt32 *ret_id_len);
476
477 /****f* silccore/SilcIDAPI/silc_id_str2id
478 *
479 * SYNOPSIS
480 *
481 * SilcBool silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
482 * SilcIdType type, void *ret_id,
483 * SilcUInt32 ret_id_size);
484 *
485 * DESCRIPTION
486 *
487 * Converts ID data string to an ID. This can be used to get the
488 * ID out of data that has been taken for example from packet. This
489 * does not allocate any memory.
490 *
491 ***/
492 SilcBool silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
493 SilcIdType type, void *ret_id, SilcUInt32 ret_id_size);
494
495 /****f* silccore/SilcIDAPI/silc_id_str2id2
496 *
497 * SYNOPSIS
498 *
499 * SilcBool silc_id_str2id2(const unsigned char *id, SilcUInt32 id_len,
500 * SilcIdType type, SilcID *ret_id);
501 *
502 * DESCRIPTION
503 *
504 * Same as silc_id_str2id but returns the ID into SilcID structure in
505 * `ret_id' pointer. This does not allocate any memory.
506 *
507 ***/
508 SilcBool silc_id_str2id2(const unsigned char *id, SilcUInt32 id_len,
509 SilcIdType type, SilcID *ret_id);
510
511 /****f* silccore/SilcIDAPI/silc_id_get_len
512 *
513 * SYNOPSIS
514 *
515 * SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
516 *
517 * DESCRIPTION
518 *
519 * Returns the true length of the ID of the type `type'.
520 *
521 ***/
522 SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
523
524 /****f* silccore/SilcIDAPI/silc_id_dup
525 *
526 * SYNOPSIS
527 *
528 * void *silc_id_dup(const void *id, SilcIdType type);
529 *
530 * DESCRIPTION
531 *
532 * Duplicates the ID of the type `type'. The caller must free the
533 * duplicated ID.
534 *
535 ***/
536 void *silc_id_dup(const void *id, SilcIdType type);
537
538 /****f* silccore/SilcIDAPI/silc_hash_id
539 *
540 * SYNOPSIS
541 *
542 * SilcUInt32 silc_hash_id(void *key, void *user_context);
543 *
544 * DESCRIPTION
545 *
546 * Hash a ID. The `user_context' is the ID type. Can be used with
547 * SilcHashTable.
548 *
549 ***/
550 SilcUInt32 silc_hash_id(void *key, void *user_context);
551
552 /****f* silccore/SilcIDAPI/silc_hash_client_id_hash
553 *
554 * SYNOPSIS
555 *
556 * SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
557 *
558 * DESCRIPTION
559 *
560 * Hash Client ID's hash. Can be used with SilcHashTable.
561 *
562 ***/
563 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
564
565 /****f* silccore/SilcIDAPI/silc_hash_id_compare
566 *
567 * SYNOPSIS
568 *
569 * SilcBool silc_hash_id_compare(void *key1, void *key2,
570 * void *user_context);
571 *
572 * DESCRIPTION
573 *
574 * Compares two ID's. May be used as SilcHashTable comparison function.
575 * The Client ID's compares only the hash of the Client ID not any other
576 * part of the Client ID. Other ID's are fully compared. Can be
577 * used with SilcHashTable.
578 *
579 ***/
580 SilcBool silc_hash_id_compare(void *key1, void *key2, void *user_context);
581
582 /****f* silccore/SilcIDAPI/silc_hash_id_compare_full
583 *
584 * SYNOPSIS
585 *
586 * SilcBool silc_hash_id_compare_full(void *key1, void *key2,
587 * void *user_context)
588 *
589 * DESCRIPTION
590 *
591 * Compares two ID's. May be used as SilcHashTable comparison function.
592 * To compare full ID's instead of only partial, like the
593 * silc_hash_id_compare does, use this function. Can be used with
594 * SilcHashTable.
595 *
596 ***/
597 SilcBool silc_hash_id_compare_full(void *key1, void *key2, void *user_context);
598
599 /****f* silccore/SilcIDAPI/silc_hash_client_id_compare
600 *
601 * SYNOPSIS
602 *
603 * SilcBool silc_hash_client_id_compare(void *key1, void *key2,
604 * void *user_context);
605 *
606 * DESCRIPTION
607 *
608 * Compare two Client ID's entirely and not just the hash from the ID.
609 * Can be used with SilcHashTable.
610 *
611 ***/
612 SilcBool silc_hash_client_id_compare(void *key1, void *key2,
613 void *user_context);
614
615 #endif
616
This page was automatically generated by the LXR engine.
Free-text search provided by Glimpse