1 <!doctype linuxdoc system>
5 # SILC Library Reference Manual SGML source code
7 # Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
9 # Copyright (C) 2000 Pekka Riikonen
11 # This program is free software; you can redistribute it and/or modify
12 # it under the terms of the GNU General Public License as published by
13 # the Free Software Foundation; either version 2 of the License, or
14 # (at your option) any later version.
16 # This program is distributed in the hope that it will be useful,
17 # but WITHOUT ANY WARRANTY; without even the implied warranty of
18 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 # GNU General Public License for more details.
26 <!-- Title information -->
28 <title>SILC Library Reference Manual
29 <author>Pekka Riikonen <tt>priikone@poseidon.pspt.fi</tt>
30 <date>Last updated: $Id$
32 This document describes the SILC Library functions and programming
33 application interfaces. The SILC Library is pretty much generic purpose
34 library in many ways. It includes routines for basic things like buffer
35 management, network connection management, scheduling and task management.
36 However, it includes a lot routines that are related only to SILC. This
37 document does not describe the implementation of the SILC client and SILC
38 server. They and their API's will be described in separate documents.
41 <!-- Table of contents -->
44 <!-- Begin the document -->
49 This document describes the SILC Library functions and programming
50 application interfaces. The SILC Library is pretty much generic purpose
51 library in many ways. It includes routines for basic things like buffer
52 management, network connection management, scheduling and task management.
53 However, it includes a lot routines that are related only to SILC. This
54 document does not describe the implementation of the SILC client and SILC
55 server. They and their API's will be described in separate documents.
57 <sect><tt>lib/</tt> directory
60 This section describes the libraries implemented in the SILC Library
61 as a whole. The SILC package and the SILC library includes other libraries
62 that are out of scope of this document. Those libraries are mentioned
63 separately and reference to the corresponding library manual is given.
65 <sect1><tt>silccore</tt>
68 This directory includes the core library of the SILC. It includes all the
69 basic and common routines used by SILC client and server applications.
70 This includes buffer management, file management, network connection
71 mangement, task management and scheduling.
73 <sect1><tt>silccrypt</tt>
76 This directory includes the crypto library. It includes implementations
77 of various cryptographic algrotihms, hash functions and public key
78 cryptosystems. It also includes cryptographically strong random number
79 generator. Most of the implementations of the algorithms are copied
80 from other crypto libraries.
82 <sect1><tt>silcmath</tt>
85 This directory includes math library. It includes GNU MP library and
86 some other routines. The math library is tightly related to the crypto
87 library and specificly public key cryptosystems.
89 <sect2><tt>silcmath/gmp-3.0.1</tt>
92 This directory includes the GNU MP library. The description of this
93 library is out of scope of this document. See
94 <url url="http://www.swox.com/gmp/"> for more detailed information.
96 <sect1><tt>silcsim</tt>
99 This directory includes the SILC Module (SIM) library. SIM's are dynamically
100 loadable shared objects.
102 <sect1><tt>silcske</tt>
105 This directory includes implementation of the SILC Key Exchange (SKE)
106 protocol. SKE protocol is used to perform key exchange between two
107 connecting entities such as client and server. The SKE protocol
108 specification is described in the Internet Draft
109 <tt>draft-riikonen-silc-ke-auth-00.txt</tt> document available from
110 <url url="http://www.ietf.org">.
112 <sect>Basic programming with SILC library
120 SILC Core library includes all the basic and common routines used by
121 SILC client and server applications. This includes buffer management,
122 file management, network connection mangement, task management and scheduling.
123 It also includes core components related to the actual SILC protocol
124 implementation such as ID routines, ID cache system and SILC packet management.
127 This section lists all the public header files of the core library thus
128 all the public application programming interfaces of the core library.
130 <sect1>lib/silccore/id.h
133 These are important ID types used in SILC. SILC server creates these
134 but SILC client has to handle these as well since these are used in
135 packet sending and reception. However, client never creates these
136 but it receives the correct ID's from server. Clients, servers and
137 channels are identified by the these ID's. Note that these are currently
138 IPv4 specific, although adding IPv6 support is not a bad task and SILC
139 protocol already supports IPv6.
144 <tt>#include "id.h"</tt>
149 <verb>typedef unsigned char SilcIdType;</verb>
151 Type definition for all ID types.
156 #define SILC_ID_SERVER_LEN
157 #define SILC_ID_CLIENT_LEN
158 #define SILC_ID_CHANNEL_LEN
167 #define SILC_ID_SERVER
168 #define SILC_ID_CLIENT
169 #define SILC_ID_CHANNEL
172 All types of the ID's.
178 struct in_addr ip; /* 32 bit IP */
179 unsigned short port; /* 16 bit port */
180 unsigned short rnd; /* 16 bit random number */
184 Defines the Server ID structure. This is used to distinguish a server in
191 struct in_addr ip; /* 32 bit IP */
192 unsigned char rnd; /* 8 bit random number */
193 unsigned char hash[CLIENTID_HASH_LEN]; /* 88 bit MD5 hash */
197 Defines the Client ID structure. This is used to distinguish a client in
204 struct in_addr ip; /* 32 bit IP */
205 unsigned short port; /* 16 bit port */
206 unsigned short rnd; /* 16 bit random number */
210 Defines the Channel ID structure. This is used to distinguish a channel in
214 <sect2>Public Interface
218 unsigned char *silc_id_id2str(void *id, SilcIdType type);
221 Converts ID to unsigned char string. First argument is a pointer of the
222 ID to be converted, second argument is the of the ID. Returns the converted
228 void *silc_id_str2id(unsigned char *id, SilcIdType type);
231 Converts string to ID. First argument is the string ID seconf is the type
232 of the ID. Returns the converted ID.
237 unsigned int silc_id_get_len(SilcIdType type);
240 Returns length of a type of an ID.
244 <sect1>lib/silccore/idcache.h
245 <sect1>lib/silccore/silcbuffer.h
246 <sect1>lib/silccore/silcbuffmt.h
247 <sect1>lib/silccore/silcbufutil.h
248 <sect1>lib/silccore/silcchannel.h
249 <sect1>lib/silccore/silccommand.h
250 <sect1>lib/silccore/silcconfig.h
251 <sect1>lib/silccore/silclog.h
252 <sect1>lib/silccore/silcmemory.h
253 <sect1>lib/silccore/silcnet.h
254 <sect1>lib/silccore/silcpacket.h
255 <sect1>lib/silccore/silcprotocol.h
256 <sect1>lib/silccore/silcschedule.h
257 <sect1>lib/silccore/silcsockconn.h
258 <sect1>lib/silccore/silctask.h
259 <sect1>lib/silccore/silcutil.h
271 All right, so you're typing along, and you want to show some example code,
272 or example I/O with a program, whatever. Use the <tt/code/ or <tt/verb/
273 ``environments'' for this, wrapped in a <tt/tscreen/ environment, as so:
275 This is an example verb environment.
279 This is an example code environment.
281 The <tt/tscreen/ environment just sets the font to small type and
282 indents it nicely. It's not required for using <tt/verb/ or <tt/code/,
283 but I suggest that you do.
285 The <em/Linuxdoc-SGML User's Guide/ explains what special characters you
286 can and can't use in the <tt/verb/ and <tt/code/ environments.
288 <sect1><heading><label id="test-ref">Cross references</>
291 What about cross-references? This section has been marked with the
292 <tt>label</> command; using <tt>ref</> will provide a cross reference,
293 as in ``See Section <ref id="test-ref">'' for more.
295 Right now cross-references don't work in the <tt/groff/ translation for
296 plain ASCII. They do work when generating LaTeX or HTML output.
301 You want fonts, we got fonts. Of course these won't show up in the
302 plain ASCII text, but they all map into the various output formats:
303 <bf/boldface/, <em/emphasis/, <sf/sans serif/, <sl/slanted/,
304 <tt/typewriter/, and <it/italics/.
309 Lists are easy as well. Just use the <tt/itemize/ element with the
310 <tt/item/ commands, seen here:
312 <item> This is a list.
313 <item> Nothing exciting about that.
315 <item> Multiple levels are supported as well.
316 <item> Again, that's no surprise.
319 <item> Enumerated lists using <tt>enum</> also work.
320 <item> Description environments using <tt>descrip</> along
321 with <tt>tag</> are also available, as seen here.
324 <tag/First item./ Here's one item.
325 <tag/Second item./ Here's another.
326 <tag/Third item./ Can we go for three?
328 <item> A final item to top it all off.
331 This is just about everything that you need to get started with
332 writing SGML docs using the <tt/linuxdoc-sgml/ DTD. Please let me know
333 if you think something should be changed or added to this document.