lib/silcclient/README

   1
   2                       SILC Client Library Manual
   3
   4                              Version 0.7
   5
   6 1.0 Introduction
   7
   8 SILC Client library is a full featured SILC Client protocolimplementation.
   9 The library has been designed to be complete SILC client without actual
  10 user interface.  The library provides the API for the appliation which
  11 it can use to implement generally whatever user interface it wants.  The
  12 SILC Client Library recides in the lib/silcclient/ directory.  It uses
  13 common and core compomnent of SILC protocol from the lib/silccore, SKE
  14 from lib/silcske and general utility routines from lib/silcutil.
  15
  16 The `silcapi.h' file defines the function prototypes that application
  17 must implement in order to be able to create the user interface with the
  18 library.  The idea is that the application can implement whatever user
  19 interface routines in the functions and display the data whatever way
  20 it wants.  The library is entirely transparent to the user interface and
  21 it does not include any user interface specific issues such as window
  22 handling or item handling on the screen etc.  These does not interest
  23 the library.  The `silcapi.h' also defines the client libary interface
  24 the application can call.  The interface includes for example functions
  25 for sending channel and private messages, client and channel retrieval
  26 and other utility functions.
  27
  28
  29 1.1 Creating Client
  30
  31 The client is context or entity based, so several client entitites can
  32 be created in the application if needed.  However, it should be noted
  33 that they are completely independent from each other and can be seen
  34 as different applications.  Usually only one client entity is needed
  35 per application.
  36
  37 The client object is SilcClient which is usually allocated in following
  38 manner:
  39
  40         SilcClient client = silc_client_alloc(&ops, context, version);
  41
  42 `ops' is the static structure of client operations that library will call.
  43 `context' can be some application specific context that will be saved into
  44 the SilcClient object.  It is up to the caller to free this context.
  45 SilcClient is always passed to the application thus the application
  46 specific context can be retrieved from the SilcClient object.  See
  47 `client.h' file for detailed definition of SilcClient object.
  48
  49 `ops' can be defined for example as follows:
  50
  51 SilcClientOperations ops = {
  52   silc_say,
  53   silc_channel_message,
  54   silc_private_message,
  55   silc_notify,
  56   silc_command,
  57   silc_command_reply,
  58   silc_connect,
  59   silc_disconnect,
  60   silc_get_auth_method,
  61   silc_verify_public_key,
  62   silc_ask_passphrase,
  63   silc_failure,
  64   silc_key_agreement,
  65 };
  66
  67 Please see the `client_ops_example.h' header file in lib/silcclient/
  68 directory for predefined structure and stub functions for your
  69 convenince.  It is provided for programmers so that they can copy
  70 it and use it directly in their application.
  71
  72
  73 1.2 Initializing the Client
  74
  75 The client must be initialized before running.  However, there are also
  76 some other tasks that must be done before initializing the client.
  77 The following pointers must be set by the application  before calling
  78 the initializing function:
  79
  80         client->username
  81         client->hostname
  82         client->realname
  83         client->pkcs
  84         client->public_key
  85         client->private_key
  86
  87 You may also set client->nickname if you want.  If it is set then the
  88 library will change the nickname to that one after the client is connected
  89 to the server.  If not set, then server will initially give the nickname
  90 which is same as the username.
  91
  92 After setting the pointers one must call:
  93
  94         silc_client_init(client);
  95
  96 which then initializes the client library for the `client'.  If the
  97 pointers mentioned above are not initialized the silc_client_init will
  98 fail.  The application should check the return value of the silc_client_init
  99 function.
 100
 101
 102 1.3 Running the Client
 103
 104 The client is run by calling silc_client_run.  The function will call
 105 the scheduler from utility library that will be run until the program is
 106 ended.  When silc_client_run returns the application is ended.  Thus,
 107 to run the client, call:
 108
 109         silc_client_run(client);
 110
 111 Usually application may do some other initializations before calling
 112 this function.  For example before calling this function application
 113 should initialize the user interface.
 114
 115
 116 1.4 Creating Connection to Server
 117
 118 Connection to remote SILC server is done by calling:
 119
 120         silc_client_connect_to_server(client, port, hostname, context);
 121
 122 The function will create the connection asynchronously to the server, ie.
 123 the function will return before the actual connection is created.  After
 124 the connection is created the client->ops->connect operation is called.
 125
 126 Generally speaking the connections are associated with windows' on the
 127 screen.  IRC is usually implemented this way, however it is not the
 128 necessary way to associate the client's connections.  SilcClientConnection
 129 object is provided by the library (and is always passed to the application)
 130 that can be used in the application to associate the connection from the
 131 library.  Application specific context can be saved to the
 132 SilcClientConnection object which then can be retrieved in the application,
 133 thus perhaps associate the connection with what ever object in
 134 application (window or something else).
 135
 136
 137 1.4.1 Using Own Connecting
 138
 139 Application might not want to use silc_client_connect_to_server function
 140 if it wants to perform its own connecting for some reason.  In this case
 141 application must call function silc_client_start_key_exchange after it
 142 has created the connection by itself.  This function starts the key
 143 exhange protocol between the client and server and the library takes care
 144 of everything after that.
 145
 146 After connection has been created application must call:
 147
 148         SilcClientConnection conn;
 149
 150         /* Add new connection to client */
 151         conn = silc_client_add_connection(client, hostname, port, context);
 152
 153         /* Start key exchange and let the library handle everything
 154            after this point on. */
 155         silc_client_start_key_exchange(client, conn, sock);
 156
 157 NOTE: These calls are performed only and only if application did not call
 158 silc_client_connect_to_server function, but performed the connecting
 159 process manually.
 160
 161
 162 1.5 Example Client
 163
 164 This section includes an example SILC client implementation in pseudo-like
 165 C code.  It creates and initializes the client and sets up an imaginary
 166 user interface.  The user will use the user interface then to create
 167 the connections.  The SilcClientOperations are expected to be implemented.
 168
 169 #include "silcincludes.h"
 170 #include "silcapi.h"
 171
 172 int main()
 173 {
 174         SilcClientOperations ops = {
 175           silc_say,
 176           silc_channel_message,
 177           silc_private_message,
 178           silc_notify,
 179           silc_command,
 180           silc_command_reply,
 181           silc_connect,
 182           silc_disconnect,
 183           silc_get_auth_method,
 184           silc_verify_public_key,
 185           silc_ask_passphrase,
 186           silc_failure,
 187           silc_key_agreement,
 188         };
 189
 190         SilcClient client;
 191
 192         /* Allocate SILC client. The `silc_version_string' is defined
 193            in includes/version.h file. */
 194         client = silc_client_alloc(&ops, NULL, silc_version_string);
 195
 196         /* Register default ciphers, pkcs, hash funtions and hmacs. */
 197         silc_cipher_register_default();
 198         silc_pkcs_register_default();
 199         silc_hash_register_default();
 200         silc_hmac_register_default();
 201
 202         /* Set the mandatory pointers, read public and private key from
 203            files (or somewhere) and return pointers and PKCS context. */
 204         client->username = silc_get_username();
 205         client->hostname = silc_net_localhost();
 206         client->realname = silc_get_real_name();
 207         client->pkcs = get_public_and_private_key(&client->public_key,
 208                                                   &client->private_key);
 209
 210         /* If the keys does not exist, create a key pair since we must
 211            provide key pair to the library. */
 212         if (!client->pkcs)
 213           generate_key_new_key_pair(client);
 214
 215         /* Iinitialize client */
 216         if (!silc_client_init(client))
 217           fatal_error("Could not initialize client");
 218
 219         /* Initialize user interface. The user interface can be generally
 220            initialized at any phase, including before actually allocating
 221            and initializing the client, if wished. */
 222         InitUserInterface();
 223         DoCoolThings();
 224
 225         /* Start the client. This will start the scheduler. At this phase
 226            the user might have the user interface in front of him already.
 227            He will use the user interface to create the connection to the
 228            server for example. When this function returns the program is
 229           ended. */
 230         silc_client_run(client);
 231
 232         /* Client is ended */
 233         return 0;
 234 }