SILC Library Reference Manual <author>Pekka Riikonen <tt>priikone@poseidon.pspt.fi</tt> <date>Last updated: $Id$ <abstract> This document describes the SILC Library functions and programming application interfaces. The SILC Library is pretty much generic purpose library in many ways. It includes routines for basic things like buffer management, network connection management, scheduling and task management. However, it includes a lot routines that are related only to SILC. This document does not describe the implementation of the SILC client and SILC server. They and their API's will be described in separate documents. </abstract>  <toc>  <sect>Overview This document describes the SILC Library functions and programming application interfaces. The SILC Library is pretty much generic purpose library in many ways. It includes routines for basic things like buffer management, network connection management, scheduling and task management. However, it includes a lot routines that are related only to SILC. This document does not describe the implementation of the SILC client and SILC server. They and their API's will be described in separate documents. <sect><tt>lib/</tt> directory This section describes the libraries implemented in the SILC Library as a whole. The SILC package and the SILC library includes other libraries that are out of scope of this document. Those libraries are mentioned separately and reference to the corresponding library manual is given. <sect1><tt>silccore</tt> This directory includes the core library of the SILC. It includes all the basic and common routines used by SILC client and server applications. This includes buffer management, file management, network connection mangement, task management and scheduling. <sect1><tt>silccrypt</tt> This directory includes the crypto library. It includes implementations of various cryptographic algrotihms, hash functions and public key cryptosystems. It also includes cryptographically strong random number generator. Most of the implementations of the algorithms are copied from other crypto libraries. <sect1><tt>silcmath</tt> This directory includes math library. It includes GNU MP library and some other routines. The math library is tightly related to the crypto library and specificly public key cryptosystems. <sect2><tt>silcmath/gmp-3.0.1</tt> This directory includes the GNU MP library. The description of this library is out of scope of this document. See <url url="http://www.swox.com/gmp/"> for more detailed information. <sect1><tt>silcsim</tt> This directory includes the SILC Module (SIM) library. SIM's are dynamically loadable shared objects. <sect1><tt>silcske</tt> This directory includes implementation of the SILC Key Exchange (SKE) protocol. SKE protocol is used to perform key exchange between two connecting entities such as client and server. The SKE protocol specification is described in the Internet Draft <tt>draft-riikonen-silc-ke-auth-00.txt</tt> document available from <url url="http://www.ietf.org">. <sect>Basic programming with SILC library <sect>Core Library SILC Core library includes all the basic and common routines used by SILC client and server applications. This includes buffer management, file management, network connection mangement, task management and scheduling. It also includes core components related to the actual SILC protocol implementation such as ID routines, ID cache system and SILC packet management. This section lists all the public header files of the core library thus all the public application programming interfaces of the core library. <sect1>lib/silccore/id.h These are important ID types used in SILC. SILC server creates these but SILC client has to handle these as well since these are used in packet sending and reception. However, client never creates these but it receives the correct ID's from server. Clients, servers and channels are identified by the these ID's. Note that these are currently IPv4 specific, although adding IPv6 support is not a bad task and SILC protocol already supports IPv6. <sect2>Includes <tt>#include "id.h"</tt> <sect2>Definitions <verb>typedef unsigned char SilcIdType;</verb> <descrip><quote> Type definition for all ID types. </quote></descrip> <verb> #define SILC_ID_SERVER_LEN #define SILC_ID_CLIENT_LEN #define SILC_ID_CHANNEL_LEN </verb> <descrip><quote> Length of the ID's. </quote></descrip> <verb> #define SILC_ID_NONE #define SILC_ID_SERVER #define SILC_ID_CLIENT #define SILC_ID_CHANNEL </verb> <descrip><quote> All types of the ID's. </quote></descrip> <verb> typedef struct { struct in_addr ip; /* 32 bit IP */ unsigned short port; /* 16 bit port */ unsigned short rnd; /* 16 bit random number */ } SilcServerID; </verb> <descrip><quote> Defines the Server ID structure. This is used to distinguish a server in SILC network. </quote></descrip> <verb> typedef struct { struct in_addr ip; /* 32 bit IP */ unsigned char rnd; /* 8 bit random number */ unsigned char hash[CLIENTID_HASH_LEN]; /* 88 bit MD5 hash */ } SilcClientID; </verb> <descrip><quote> Defines the Client ID structure. This is used to distinguish a client in SILC network. </quote></descrip> <verb> typedef struct { struct in_addr ip; /* 32 bit IP */ unsigned short port; /* 16 bit port */ unsigned short rnd; /* 16 bit random number */ } SilcChannelID; </verb> <descrip><quote> Defines the Channel ID structure. This is used to distinguish a channel in SILC network. </quote></descrip> <sect2>Public Interface <verb> unsigned char *silc_id_id2str(void *id, SilcIdType type); </verb> <descrip><quote> Converts ID to unsigned char string. First argument is a pointer of the ID to be converted, second argument is the of the ID. Returns the converted ID. </quote></descrip> <verb> void *silc_id_str2id(unsigned char *id, SilcIdType type); </verb> <descrip><quote> Converts string to ID. First argument is the string ID seconf is the type of the ID. Returns the converted ID. </quote></descrip> <verb> unsigned int silc_id_get_len(SilcIdType type); </verb> <descrip><quote> Returns length of a type of an ID. </quote></descrip> <sect1>lib/silccore/idcache.h <sect1>lib/silccore/silcbuffer.h <sect1>lib/silccore/silcbuffmt.h <sect1>lib/silccore/silcbufutil.h <sect1>lib/silccore/silcchannel.h <sect1>lib/silccore/silccommand.h <sect1>lib/silccore/silcconfig.h <sect1>lib/silccore/silclog.h <sect1>lib/silccore/silcmemory.h <sect1>lib/silccore/silcnet.h <sect1>lib/silccore/silcpacket.h <sect1>lib/silccore/silcprotocol.h <sect1>lib/silccore/silcschedule.h <sect1>lib/silccore/silcsockconn.h <sect1>lib/silccore/silctask.h <sect1>lib/silccore/silcutil.h <sect>Crypto Library <sect>Math Library <sect>SIM Library <sect>SKE library All right, so you're typing along, and you want to show some example code, or example I/O with a program, whatever. Use the <tt/code/ or <tt/verb/ ``environments'' for this, wrapped in a <tt/tscreen/ environment, as so: <tscreen><verb> This is an example verb environment. </verb></tscreen> As well as: <tscreen><code> This is an example code environment. </code></tscreen> The <tt/tscreen/ environment just sets the font to small type and indents it nicely. It's not required for using <tt/verb/ or <tt/code/, but I suggest that you do. The <em/Linuxdoc-SGML User's Guide/ explains what special characters you can and can't use in the <tt/verb/ and <tt/code/ environments. <sect1><heading><label id="test-ref">Cross references</> What about cross-references? This section has been marked with the <tt>label</> command; using <tt>ref</> will provide a cross reference, as in ``See Section <ref id="test-ref">'' for more. Right now cross-references don't work in the <tt/groff/ translation for plain ASCII. They do work when generating LaTeX or HTML output. <sect1>Using fonts You want fonts, we got fonts. Of course these won't show up in the plain ASCII text, but they all map into the various output formats: <bf/boldface/, <em/emphasis/, <sf/sans serif/, <sl/slanted/, <tt/typewriter/, and <it/italics/. <sect1>Lists Lists are easy as well. Just use the <tt/itemize/ element with the <tt/item/ commands, seen here: <itemize> <item> This is a list. <item> Nothing exciting about that. <itemize> <item> Multiple levels are supported as well. <item> Again, that's no surprise. </itemize> <enum> <item> Enumerated lists using <tt>enum</> also work. <item> Description environments using <tt>descrip</> along with <tt>tag</> are also available, as seen here. </enum> <descrip> <tag/First item./ Here's one item. <tag/Second item./ Here's another. <tag/Third item./ Can we go for three? </descrip> <item> A final item to top it all off. </itemize> This is just about everything that you need to get started with writing SGML docs using the <tt/linuxdoc-sgml/ DTD. Please let me know if you think something should be changed or added to this document. </article>