5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2006 Pekka Riikonen
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.
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.
20 /****h* silccore/SILC ID Interface
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.
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
34 * This file also includes the implementation of the SILC ID Payload
35 * parsing and encoding.
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)
48 #define CLIENTID_HASH_LEN (88 / 8) /* Client ID's 88 bit MD5 hash */
50 /****d* silccore/SilcIDAPI/SilcIdType
54 * typedef SilcUInt16 SilcIdType;
58 * SILC ID type definitions and the ID types.
62 typedef SilcUInt16 SilcIdType;
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
71 /****s* silccore/SilcIDAPI/SilcIDIP
75 * typedef struct { ... } SilcIDIP;
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.
86 unsigned char data[16]; /* IP data (in MSB first order) */
87 SilcUInt8 data_len; /* Length of the data (4 or 16) */
91 /****s* silccore/SilcIDAPI/SilcServerID
95 * typedef struct { ... } SilcServerID;
99 * 64 or 160 bit SilcServerID structure:
103 * 16 bit random number
108 SilcIDIP ip; /* n bit IP address */
109 SilcUInt16 port; /* 16 bit port */
110 SilcUInt16 rnd; /* 16 bit random number */
114 /****s* silccore/SilcIDAPI/SilcClientID
118 * typedef struct { ... } SilcClientID;
122 * 128 or 224 bit SilcClientID structure:
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
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 */
137 /****s* silccore/SilcIDAPI/SilcChannelID
141 * typedef struct { ... } SilcChannelID;
145 * 64 or 160 bit SilcChannel ID structure:
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
154 SilcIDIP ip; /* n bit IP address */
155 SilcUInt16 port; /* 16 bit port */
156 SilcUInt16 rnd; /* 16 bit random number */
160 /****s* silccore/SilcIDAPI/SilcID
164 * typedef struct { ... } SilcID;
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.
177 SilcServerID server_id;
178 SilcChannelID channel_id;
179 SilcClientID client_id;
187 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE
191 * #define SILC_ID_COMPARE ...
195 * Compares two ID's. Returns TRUE if they match and FALSE if they do
200 #define SILC_ID_COMPARE(id1, id2, len) (!memcmp(id1, id2, len))
203 /****d* silccore/SilcIDAPI/SILC_ID_CLIENT_COMPARE
207 * #define SILC_ID_CLIENT_COMPARE ...
211 * Compares Client ID's. Returns TRUE if they match.
215 #define SILC_ID_CLIENT_COMPARE(id1, id2) \
216 SILC_ID_COMPARE(id1, id2, sizeof(SilcClientID))
219 /****d* silccore/SilcIDAPI/SILC_ID_SERVER_COMPARE
223 * #define SILC_ID_SERVER_COMPARE ...
227 * Compares Server ID's. Returns TRUE if they match.
231 #define SILC_ID_SERVER_COMPARE(id1, id2) \
232 SILC_ID_COMPARE(id1, id2, sizeof(SilcServerID))
235 /****d* silccore/SilcIDAPI/SILC_ID_CHANNEL_COMPARE
239 * #define SILC_ID_CHANNEL_COMPARE ...
243 * Compares Channel ID's. Returns TRUE if they match.
247 #define SILC_ID_CHANNEL_COMPARE(id1, id2) \
248 SILC_ID_COMPARE(id1, id2, sizeof(SilcChannelID))
251 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_TYPE
255 * #define SILC_ID_COMPARE_TYPE ...
259 * Compares two ID's by type. Returns TRUE if they match.
263 #define SILC_ID_COMPARE_TYPE(id1, id2, type) \
264 (type == SILC_ID_SERVER ? SILC_ID_SERVER_COMPARE(id1, id2) : \
265 type == SILC_ID_CLIENT ? SILC_ID_CLIENT_COMPARE(id1, id2) : \
266 SILC_ID_CHANNEL_COMPARE(id1, id2))
269 /****d* silccore/SilcIDAPI/SILC_ID_COMPARE_HASH
273 * #define SILC_ID_COMPARE_HASH ...
277 * Compares the nickname hash of the Client ID. Returns TRUE if
278 * they match. Since the nickname hash is based on the nickname of
279 * the client this can be used to search the ID by nickname (taking
280 * the hash out of it) or using the hash from the ID.
284 #define SILC_ID_COMPARE_HASH(id1, id2) \
285 (!memcmp((id1)->hash, (id2)->hash, CLIENTID_HASH_LEN))
288 /****s* silccore/SilcIDAPI/SilcIDPayload
292 * typedef struct SilcIDPayloadStruct *SilcIDPayload;
296 * This context is the actual ID Payload and is allocated by
297 * silc_id_payload_parse and given as argument usually to all
298 * silc_id_payload_* functions. It is freed by the function
299 * silc_id_payload_free.
302 typedef struct SilcIDPayloadStruct *SilcIDPayload;
306 /****f* silccore/SilcIDAPI/silc_id_payload_parse
310 * SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
311 * SilcUInt32 payload_len);
315 * Parses buffer and return ID payload into payload structure. The
316 * `buffer' is raw payload buffer. The caller must free the returned
320 SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
321 SilcUInt32 payload_len);
323 /****f* silccore/SilcIDAPI/silc_id_payload_parse_id
327 * SilcBool silc_id_payload_parse_id(const unsigned char *data,
328 * SilcUInt32 len, SilcID *ret_id);
332 * Return ID directly from the raw ID Payload data buffer. This does
333 * not allocate any memory.
336 SilcBool silc_id_payload_parse_id(const unsigned char *data, SilcUInt32 len,
339 /****f* silccore/SilcIDAPI/silc_id_payload_encode
343 * SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
347 * Encodes ID Payload. The `id' is the ID of the type `type' to put
348 * into the payload. Returns the encoded payload buffer.
351 SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
353 /****f* silccore/SilcIDAPI/silc_id_payload_encode_data
357 * SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
358 * uin32 id_len, SilcIdType type);
362 * Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
363 * of type of `type'. Returns the encoded payload buffer.
366 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
367 SilcUInt32 id_len, SilcIdType type);
369 /****f* silccore/SilcIDAPI/silc_id_payload_free
373 * void silc_id_payload_free(SilcIDPayload payload);
377 * Frees the ID Payload and all data in it.
380 void silc_id_payload_free(SilcIDPayload payload);
382 /****f* silccore/SilcIDAPI/silc_id_payload_get_type
386 * SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
390 * Returns the ID type from the ID Payload. The type tells the
391 * type of the ID in the payload.
394 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
396 /****f* silccore/SilcIDAPI/silc_id_payload_get_id
400 * SilcBool silc_id_payload_get_id(SilcIDPayload payload, void *ret_id,
401 * SilcUInt32 ret_id_len);
405 * Returns the ID in the ID Payload. This does not allocate any memory.
408 SilcBool silc_id_payload_get_id(SilcIDPayload payload, void *ret_id,
409 SilcUInt32 ret_id_len);
411 /****f* silccore/SilcIDAPI/silc_id_payload_get_data
415 * unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
419 * Returns the raw ID data from the ID Payload. The data is duplicated
420 * and the caller must free it.
423 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
425 /****f* silccore/SilcIDAPI/silc_id_payload_get_len
429 * SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
433 * Returns the length of the ID in the ID Payload.
436 SilcUInt32 silc_id_payload_get_len(SilcIDPayload payload);
438 /****f* silccore/SilcIDAPI/silc_id_id2str
442 * SilcBool silc_id_id2str(const void *id, SilcIdType type,
443 * unsigned char *ret_id, SilcUInt32 ret_id_size,
444 * SilcUInt32 *ret_id_len);
448 * Converts an ID of type `type' to data. This can be used to
449 * convert the ID's to data for inclusion in the packets. This does
450 * not allocate any memory.
453 SilcBool silc_id_id2str(const void *id, SilcIdType type,
454 unsigned char *ret_id, SilcUInt32 ret_id_size,
455 SilcUInt32 *ret_id_len);
457 /****f* silccore/SilcIDAPI/silc_id_str2id
461 * SilcBool silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
462 * SilcIdType type, void *ret_id,
463 * SilcUInt32 ret_id_size);
467 * Converts ID data string to an ID. This can be used to get the
468 * ID out of data that has been taken for example from packet. This
469 * does not allocate any memory.
472 SilcBool silc_id_str2id(const unsigned char *id, SilcUInt32 id_len,
473 SilcIdType type, void *ret_id, SilcUInt32 ret_id_size);
475 /****f* silccore/SilcIDAPI/silc_id_get_len
479 * SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
483 * Returns the true length of the ID of the type `type'.
486 SilcUInt32 silc_id_get_len(const void *id, SilcIdType type);
488 /****f* silccore/SilcIDAPI/silc_id_dup
492 * void *silc_id_dup(const void *id, SilcIdType type);
496 * Duplicates the ID of the type `type'. The caller must free the
500 void *silc_id_dup(const void *id, SilcIdType type);