lib/silcclient/silcapi.h

   1 /*
   2
   3   silcapi.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   6
   7   Copyright (C) 2000 - 2001 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 #ifndef SILCAPI_H
  22 #define SILCAPI_H
  23
  24 #include "clientlibincludes.h"
  25
  26 /*
  27    This file defines the SILC Client Library API for the application.  The
  28    client operations are defined first.  These are callback functions that
  29    the application MUST implement since the library may call the functions
  30    at any time.  At the end of file is the API for the application that
  31    it can use from the library.  This is the only file that the application
  32    may include from the SIlC Client Library.
  33
  34    Please, refer to the README file in this directory for the directions
  35    of how to use the SILC Client Library.
  36 */
  37
  38 /* General definitions */
  39
  40 /* Key agreement status types indicating the status of the protocol. */
  41 typedef enum {
  42   SILC_KEY_AGREEMENT_OK,               /* Everything is Ok */
  43   SILC_KEY_AGREEMENT_ERROR,            /* Unknown error occured */
  44   SILC_KEY_AGREEMENT_FAILURE,          /* The protocol failed */
  45   SILC_KEY_AGREEMENT_TIMEOUT,          /* The protocol timeout */
  46 } SilcKeyAgreementStatus;
  47
  48 /* Key agreement callback that is called after the key agreement protocol
  49    has been performed. This is called also if error occured during the
  50    key agreement protocol. The `key' is the allocated key material and
  51    the caller is responsible of freeing it. The `key' is NULL if error
  52    has occured. The application can freely use the `key' to whatever
  53    purpose it needs. See lib/silcske/silcske.h for the definition of
  54    the SilcSKEKeyMaterial structure. */
  55 typedef void (*SilcKeyAgreementCallback)(SilcClient client,
  56                                          SilcClientConnection conn,
  57                                          SilcClientEntry client_entry,
  58                                          SilcKeyAgreementStatus status,
  59                                          SilcSKEKeyMaterial *key,
  60                                          void *context);
  61
  62 /* Structure to hold the list of private message keys. The array of this
  63    structure is returned by the silc_client_list_private_message_keys
  64    function. */
  65 typedef struct {
  66   SilcClientEntry client_entry;       /* The remote client entry */
  67   char *cipher;                       /* The cipher name */
  68   unsigned char *key;                 /* The original key, If the appliation
  69                                          provided it. This is NULL if the
  70                                          library generated the key or if
  71                                          the SKE key material was used. */
  72   unsigned int key_len;               /* The key length */
  73 } *SilcPrivateMessageKeys;
  74
  75 /******************************************************************************
  76
  77                            SILC Client Operations
  78
  79   These functions must be implemented by the application calling the SILC
  80   client library. The client library can call these functions at any time.
  81
  82   To use this structure: define a static SilcClientOperations variable,
  83   fill it and pass its pointer to silc_client_alloc function.
  84
  85 ******************************************************************************/
  86
  87 /* SILC Client Operations. These must be implemented by the application. */
  88 typedef struct {
  89   /* Message sent to the application by library. `conn' associates the
  90      message to a specific connection.  `conn', however, may be NULL. */
  91   void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...);
  92
  93   /* Message for a channel. The `sender' is the sender of the message
  94      The `channel' is the channel. */
  95   void (*channel_message)(SilcClient client, SilcClientConnection conn,
  96                           SilcClientEntry sender, SilcChannelEntry channel,
  97                           char *msg);
  98
  99   /* Private message to the client. The `sender' is the sender of the
 100      message. */
 101   void (*private_message)(SilcClient client, SilcClientConnection conn,
 102                           SilcClientEntry sender, char *msg);
 103
 104   /* Notify message to the client. The notify arguments are sent in the
 105      same order as servers sends them. The arguments are same as received
 106      from the server except for ID's.  If ID is received application receives
 107      the corresponding entry to the ID. For example, if Client ID is received
 108      application receives SilcClientEntry.  Also, if the notify type is
 109      for channel the channel entry is sent to application (even if server
 110      does not send it because client library gets the channel entry from
 111      the Channel ID in the packet's header). */
 112   void (*notify)(SilcClient client, SilcClientConnection conn,
 113                  SilcNotifyType type, ...);
 114
 115   /* Command handler. This function is called always in the command function.
 116      If error occurs it will be called as well. `conn' is the associated
 117      client connection. `cmd_context' is the command context that was
 118      originally sent to the command. `success' is FALSE if error occured
 119      during command. `command' is the command being processed. It must be
 120      noted that this is not reply from server. This is merely called just
 121      after application has called the command. Just to tell application
 122      that the command really was processed. */
 123   void (*command)(SilcClient client, SilcClientConnection conn,
 124                   SilcClientCommandContext cmd_context, int success,
 125                   SilcCommand command);
 126
 127   /* Command reply handler. This function is called always in the command reply
 128      function. If error occurs it will be called as well. Normal scenario
 129      is that it will be called after the received command data has been parsed
 130      and processed. The function is used to pass the received command data to
 131      the application.
 132
 133      `conn' is the associated client connection. `cmd_payload' is the command
 134      payload data received from server and it can be ignored. It is provided
 135      if the application would like to re-parse the received command data,
 136      however, it must be noted that the data is parsed already by the library
 137      thus the payload can be ignored. `success' is FALSE if error occured.
 138      In this case arguments are not sent to the application. The `status' is
 139      the command reply status server returned. The `command' is the command
 140      reply being processed. The function has variable argument list and each
 141      command defines the number and type of arguments it passes to the
 142      application (on error they are not sent). */
 143   void (*command_reply)(SilcClient client, SilcClientConnection conn,
 144                         SilcCommandPayload cmd_payload, int success,
 145                         SilcCommand command, SilcCommandStatus status, ...);
 146
 147   /* Called to indicate that connection was either successfully established
 148      or connecting failed.  This is also the first time application receives
 149      the SilcClientConnection objecet which it should save somewhere. */
 150   void (*connect)(SilcClient client, SilcClientConnection conn, int success);
 151
 152   /* Called to indicate that connection was disconnected to the server. */
 153   void (*disconnect)(SilcClient client, SilcClientConnection conn);
 154
 155   /* Find authentication method and authentication data by hostname and
 156      port. The hostname may be IP address as well. The found authentication
 157      method and authentication data is returned to `auth_meth', `auth_data'
 158      and `auth_data_len'. The function returns TRUE if authentication method
 159      is found and FALSE if not. `conn' may be NULL. */
 160   int (*get_auth_method)(SilcClient client, SilcClientConnection conn,
 161                          char *hostname, unsigned short port,
 162                          SilcProtocolAuthMeth *auth_meth,
 163                          unsigned char **auth_data,
 164                          unsigned int *auth_data_len);
 165
 166   /* Verifies received public key. The `conn_type' indicates which entity
 167      (server, client etc.) has sent the public key. If user decides to trust
 168      the key may be saved as trusted public key for later use. If user does
 169      not trust the key this returns FALSE. If everything is Ok this returns
 170      TRUE. */
 171   int (*verify_public_key)(SilcClient client, SilcClientConnection conn,
 172                            SilcSocketType conn_type, unsigned char *pk,
 173                            unsigned int pk_len, SilcSKEPKType pk_type);
 174
 175   /* Ask (interact, that is) a passphrase from user. Returns the passphrase
 176      or NULL on error. */
 177   unsigned char *(*ask_passphrase)(SilcClient client,
 178                                    SilcClientConnection conn);
 179
 180   /* Notifies application that failure packet was received.  This is called
 181      if there is some protocol active in the client.  The `protocol' is the
 182      protocol context.  The `failure' is opaque pointer to the failure
 183      indication.  Note, that the `failure' is protocol dependant and
 184      application must explicitly cast it to correct type.  Usually `failure'
 185      is 32 bit failure type (see protocol specs for all protocol failure
 186      types). */
 187   void (*failure)(SilcClient client, SilcClientConnection conn,
 188                   SilcProtocol protocol, void *failure);
 189
 190   /* Asks whether the user would like to perform the key agreement protocol.
 191      This is called after we have received an key agreement packet or an
 192      reply to our key agreement packet. This returns TRUE if the user wants
 193      the library to perform the key agreement protocol and FALSE if it is not
 194      desired (application may start it later by calling the function
 195      silc_client_perform_key_agreement). If TRUE is returned also the
 196      `completion' and `context' arguments must be set by the application. */
 197   int (*key_agreement)(SilcClient client, SilcClientConnection conn,
 198                        SilcClientEntry client_entry, char *hostname,
 199                        int port,
 200                        SilcKeyAgreementCallback *completion,
 201                        void **context);
 202 } SilcClientOperations;
 203
 204
 205
 206 /******************************************************************************
 207
 208                            SILC Client Library API
 209
 210   This is the API that is published by the SILC Client Library for the
 211   applications.  These functions are implemented in the SILC Client Library.
 212   Application may freely call these functions from the library.
 213
 214 ******************************************************************************/
 215
 216 /* Initialization functions (client.c) */
 217
 218 /* Allocates new client object. This has to be done before client may
 219    work. After calling this one must call silc_client_init to initialize
 220    the client. The `application' is application specific user data pointer
 221    and caller must free it. */
 222 SilcClient silc_client_alloc(SilcClientOperations *ops, void *application);
 223
 224 /* Frees client object and its internals. */
 225 void silc_client_free(SilcClient client);
 226
 227 /* Initializes the client. This makes all the necessary steps to make
 228    the client ready to be run. One must call silc_client_run to run the
 229    client. Returns FALSE if error occured, TRUE otherwise. */
 230 int silc_client_init(SilcClient client);
 231
 232 /* Runs the client. This starts the scheduler from the utility library.
 233    When this functions returns the execution of the appliation is over. */
 234 void silc_client_run(SilcClient client);
 235
 236 /* Stops the client. This is called to stop the client and thus to stop
 237    the program. */
 238 void silc_client_stop(SilcClient client);
 239
 240
 241 /* Connecting functions (client.c) */
 242
 243 /* Connects to remote server. This is the main routine used to connect
 244    to SILC server. Returns -1 on error and the created socket otherwise.
 245    The `context' is user context that is saved into the SilcClientConnection
 246    that is created after the connection is created. Note that application
 247    may handle the connecting process outside the library. If this is the
 248    case then this function is not used at all. When the connecting is
 249    done the `connect' client operation is called. */
 250 int silc_client_connect_to_server(SilcClient client, int port,
 251                                   char *host, void *context);
 252
 253 /* Allocates and adds new connection to the client. This adds the allocated
 254    connection to the connection table and returns a pointer to it. A client
 255    can have multiple connections to multiple servers. Every connection must
 256    be added to the client using this function. User data `context' may
 257    be sent as argument. This function is normally used only if the
 258    application performed the connecting outside the library. The library
 259    however may use this internally. */
 260 SilcClientConnection silc_client_add_connection(SilcClient client,
 261                                                 char *hostname,
 262                                                 int port,
 263                                                 void *context);
 264
 265 /* Removes connection from client. Frees all memory. */
 266 void silc_client_del_connection(SilcClient client, SilcClientConnection conn);
 267
 268 /* Adds listener socket to the listener sockets table. This function is
 269    used to add socket objects that are listeners to the client.  This should
 270    not be used to add other connection objects. */
 271 void silc_client_add_socket(SilcClient client, SilcSocketConnection sock);
 272
 273 /* Deletes listener socket from the listener sockets table. */
 274 void silc_client_del_socket(SilcClient client, SilcSocketConnection sock);
 275
 276 /* Start SILC Key Exchange (SKE) protocol to negotiate shared secret
 277    key material between client and server.  This function can be called
 278    directly if application is performing its own connecting and does not
 279    use the connecting provided by this library. This function is normally
 280    used only if the application performed the connecting outside the library.
 281    The library however may use this internally. */
 282 int silc_client_start_key_exchange(SilcClient client,
 283                                    SilcClientConnection conn,
 284                                    int fd);
 285
 286 /* Closes connection to remote end. Free's all allocated data except
 287    for some information such as nickname etc. that are valid at all time. */
 288 void silc_client_close_connection(SilcClient client,
 289                                   SilcClientConnection conn);
 290
 291
 292 /* Message sending functions (client_channel.c and client_prvmsg.c) */
 293
 294 /* Sends packet to the `channel'. Packet to channel is always encrypted
 295    differently from "normal" packets. SILC header of the packet is
 296    encrypted with the next receiver's key and the rest of the packet is
 297    encrypted with the channel specific key. Padding and HMAC is computed
 298    with the next receiver's key. The `data' is the channel message. If
 299    the `force_send' is TRUE then the packet is sent immediately.
 300
 301    If `key' is provided then that private key is used to encrypt the
 302    channel message.  If it is not provided, private keys has not been
 303    set at all, the normal channel key is used automatically.  If private
 304    keys are set then the first key (the key that was added first as
 305    private key) is used. */
 306 void silc_client_send_channel_message(SilcClient client,
 307                                       SilcClientConnection conn,
 308                                       SilcChannelEntry channel,
 309                                       SilcChannelPrivateKey key,
 310                                       unsigned char *data,
 311                                       unsigned int data_len,
 312                                       int force_send);
 313
 314 /* Sends private message to remote client. If private message key has
 315    not been set with this client then the message will be encrypted using
 316    normal session keys. Private messages are special packets in SILC
 317    network hence we need this own function for them. This is similiar
 318    to silc_client_packet_send_to_channel except that we send private
 319    message. The `data' is the private message. If the `force_send' is
 320    TRUE the packet is sent immediately. */
 321 void silc_client_send_private_message(SilcClient client,
 322                                       SilcClientConnection conn,
 323                                       SilcClientEntry client_entry,
 324                                       unsigned char *data,
 325                                       unsigned int data_len,
 326                                       int force_send);
 327
 328
 329 /* Client and Channel entry retrieval (idlist.c) */
 330
 331 /* Callback function given to the silc_client_get_client function. The
 332    found entries are allocated into the `clients' array. The array must
 333    not be freed by the caller, the library will free it later. If the
 334    `clients' is NULL, no such clients exist in the SILC Network. */
 335 typedef void (*SilcGetClientCallback)(SilcClient client,
 336                                       SilcClientConnection conn,
 337                                       SilcClientEntry *clients,
 338                                       unsigned int clients_count,
 339                                       void *context);
 340
 341 /* Finds client entry or entries by the `nickname' and `server'. The
 342    completion callback will be called when the client entries has been found.
 343
 344    Note: this function is always asynchronous and resolves the client
 345    information from the server. Thus, if you already know the client
 346    information then use the silc_client_get_client_by_id function to
 347    get the client entry since this function may be very slow and should
 348    be used only to initially get the client entries. */
 349 void silc_client_get_clients(SilcClient client,
 350                              SilcClientConnection conn,
 351                              char *nickname,
 352                              char *server,
 353                              SilcGetClientCallback completion,
 354                              void *context);
 355
 356 /* Same as above function but does not resolve anything from the server.
 357    This checks local cache and returns all clients from the cache. */
 358 SilcClientEntry *silc_client_get_clients_local(SilcClient client,
 359                                                SilcClientConnection conn,
 360                                                char *nickname,
 361                                                char *server,
 362                                                unsigned int *clients_count);
 363
 364 /* Gets client entries by the list of client ID's `client_id_list'. This
 365    always resolves those client ID's it does not know yet from the server
 366    so this function might take a while. The `client_id_list' is a list
 367    of ID Payloads added one after other.  JOIN command reply and USERS
 368    command reply for example returns this sort of list. The `completion'
 369    will be called after the entries are available. */
 370 void silc_client_get_clients_by_list(SilcClient client,
 371                                      SilcClientConnection conn,
 372                                      unsigned int list_count,
 373                                      SilcBuffer client_id_list,
 374                                      SilcGetClientCallback completion,
 375                                      void *context);
 376
 377 /* Find entry for client by the client's ID. Returns the entry or NULL
 378    if the entry was not found. */
 379 SilcClientEntry silc_client_get_client_by_id(SilcClient client,
 380                                              SilcClientConnection conn,
 381                                              SilcClientID *client_id);
 382
 383 /* Same as above but will always resolve the information from the server.
 384    Use this only if you know that you don't have the entry and the only
 385    thing you know about the client is its ID. */
 386 void silc_client_get_client_by_id_resolve(SilcClient client,
 387                                           SilcClientConnection conn,
 388                                           SilcClientID *client_id,
 389                                           SilcGetClientCallback completion,
 390                                           void *context);
 391
 392 /* Finds entry for channel by the channel name. Returns the entry or NULL
 393    if the entry was not found. It is found only if the client is joined
 394    to the channel. */
 395 SilcChannelEntry silc_client_get_channel(SilcClient client,
 396                                          SilcClientConnection conn,
 397                                          char *channel);
 398
 399
 400 /* Command management (command.c) */
 401
 402 /* Allocate Command Context. The context is defined in `command.h' file.
 403    The context is used by the library commands and applications should use
 404    it as well. However, application may choose to use some own context
 405    for its local commands. All library commands, however, must use this
 406    context. */
 407 SilcClientCommandContext silc_client_command_alloc();
 408
 409 /* Free command context and its internals */
 410 void silc_client_command_free(SilcClientCommandContext ctx);
 411
 412 /* Duplicate Command Context by adding reference counter. The context won't
 413    be free'd untill it hits zero. */
 414 SilcClientCommandContext silc_client_command_dup(SilcClientCommandContext ctx);
 415
 416 /* Finds and returns a pointer to the command list. Return NULL if the
 417    command is not found. See the `command.[ch]' for the command list. */
 418 SilcClientCommand *silc_client_command_find(const char *name);
 419
 420 /* Generic function to send any command. The arguments must be sent already
 421    encoded into correct form and in correct order. */
 422 void silc_client_send_command(SilcClient client, SilcClientConnection conn,
 423                               SilcCommand command, unsigned short ident,
 424                               unsigned int argc, ...);
 425
 426 /* Pending Command callback destructor. This is called after calling the
 427    pending callback or if error occurs while processing the pending command.
 428    If error occurs then the callback won't be called at all, and only this
 429    destructor is called. The `context' is the context given for the function
 430    silc_client_command_pending. */
 431 typedef void (*SilcClientPendingDestructor)(void *context);
 432
 433 /* Add new pending command to be executed when reply to a command has been
 434    received.  The `reply_cmd' is the command that will call the `callback'
 435    with `context' when reply has been received.  If `ident is non-zero
 436    the `callback' will be executed when received reply with command
 437    identifier `ident'. */
 438 void silc_client_command_pending(SilcClientConnection conn,
 439                                  SilcCommand reply_cmd,
 440                                  unsigned short ident,
 441                                  SilcClientPendingDestructor destructor,
 442                                  SilcCommandCb callback,
 443                                  void *context);
 444
 445
 446 /* Private Message key management (client_prvmsg.c) */
 447
 448 /* Adds private message key to the client library. The key will be used to
 449    encrypt all private message between the client and the remote client
 450    indicated by the `client_entry'. If the `key' is NULL and the boolean
 451    value `generate_key' is TRUE the library will generate random key.
 452    The `key' maybe for example pre-shared-key, passphrase or similar.
 453    The `cipher' MAY be provided but SHOULD be NULL to assure that the
 454    requirements of the SILC protocol are met. The API, however, allows
 455    to allocate any cipher.
 456
 457    It is not necessary to set key for normal private message usage. If the
 458    key is not set then the private messages are encrypted using normal
 459    session keys. Setting the private key, however, increases the security.
 460
 461    Returns FALSE if the key is already set for the `client_entry', TRUE
 462    otherwise. */
 463 int silc_client_add_private_message_key(SilcClient client,
 464                                         SilcClientConnection conn,
 465                                         SilcClientEntry client_entry,
 466                                         char *cipher,
 467                                         unsigned char *key,
 468                                         unsigned int key_len,
 469                                         int generate_key);
 470
 471 /* Same as above but takes the key material from the SKE key material
 472    structure. This structure is received if the application uses the
 473    silc_client_send_key_agreement to negotiate the key material. The
 474    `cipher' SHOULD be provided as it is negotiated also in the SKE
 475    protocol. */
 476 int silc_client_add_private_message_key_ske(SilcClient client,
 477                                             SilcClientConnection conn,
 478                                             SilcClientEntry client_entry,
 479                                             char *cipher,
 480                                             SilcSKEKeyMaterial *key);
 481
 482 /* Sends private message key payload to the remote client indicated by
 483    the `client_entry'. If the `force_send' is TRUE the packet is sent
 484    immediately. Returns FALSE if error occurs, TRUE otherwise. The
 485    application should call this function after setting the key to the
 486    client.
 487
 488    Note that the key sent using this function is sent to the remote client
 489    through the SILC network. The packet is protected using normal session
 490    keys. */
 491 int silc_client_send_private_message_key(SilcClient client,
 492                                          SilcClientConnection conn,
 493                                          SilcClientEntry client_entry,
 494                                          int force_send);
 495
 496 /* Removes the private message from the library. The key won't be used
 497    after this to protect the private messages with the remote `client_entry'
 498    client. Returns FALSE on error, TRUE otherwise. */
 499 int silc_client_del_private_message_key(SilcClient client,
 500                                         SilcClientConnection conn,
 501                                         SilcClientEntry client_entry);
 502
 503 /* Returns array of set private message keys associated to the connection
 504    `conn'. Returns allocated SilcPrivateMessageKeys array and the array
 505    count to the `key_count' argument. The array must be freed by the caller
 506    by calling the silc_client_free_private_message_keys function. Note:
 507    the keys returned in the array is in raw format. It might not be desired
 508    to show the keys as is. The application might choose not to show the keys
 509    at all or to show the fingerprints of the keys. */
 510 SilcPrivateMessageKeys
 511 silc_client_list_private_message_keys(SilcClient client,
 512                                       SilcClientConnection conn,
 513                                       unsigned int *key_count);
 514
 515 /* Frees the SilcPrivateMessageKeys array returned by the function
 516    silc_client_list_private_message_keys. */
 517 void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
 518                                            unsigned int key_count);
 519
 520
 521 /* Channel private key management (client_channel.c,
 522    SilcChannelPrivateKey is defined in idlist.h) */
 523
 524 /* Adds private key for channel. This may be set only if the channel's mode
 525    mask includes the SILC_CHANNEL_MODE_PRIVKEY. This returns FALSE if the
 526    mode is not set. When channel has private key then the messages are
 527    encrypted using that key. All clients on the channel must also know the
 528    key in order to decrypt the messages. However, it is possible to have
 529    several private keys per one channel. In this case only some of the
 530    clients on the channel may know the one key and only some the other key.
 531
 532    The private key for channel is optional. If it is not set then the
 533    channel messages are encrypted using the channel key generated by the
 534    server. However, setting the private key (or keys) for the channel
 535    significantly adds security. If more than one key is set the library
 536    will automatically try all keys at the message decryption phase. Note:
 537    setting many keys slows down the decryption phase as all keys has to
 538    be tried in order to find the correct decryption key. However, setting
 539    a few keys does not have big impact to the decryption performace.
 540
 541    NOTE: that this is entirely local setting. The key set using this function
 542    is not sent to the network at any phase.
 543
 544    NOTE: If the key material was originated by the SKE protocol (using
 545    silc_client_send_key_agreement) then the `key' MUST be the
 546    key->send_enc_key as this is dictated by the SILC protocol. However,
 547    currently it is not expected that the SKE key material would be used
 548    as channel private key. However, this API allows it. */
 549 int silc_client_add_channel_private_key(SilcClient client,
 550                                         SilcClientConnection conn,
 551                                         SilcChannelEntry channel,
 552                                         char *cipher,
 553                                         char *hmac,
 554                                         unsigned char *key,
 555                                         unsigned int key_len);
 556
 557 /* Removes all private keys from the `channel'. The old channel key is used
 558    after calling this to protect the channel messages. Returns FALSE on
 559    on error, TRUE otherwise. */
 560 int silc_client_del_channel_private_keys(SilcClient client,
 561                                          SilcClientConnection conn,
 562                                          SilcChannelEntry channel);
 563
 564 /* Removes and frees private key `key' from the channel `channel'. The `key'
 565    is retrieved by calling the function silc_client_list_channel_private_keys.
 566    The key is not used after this. If the key was last private key then the
 567    old channel key is used hereafter to protect the channel messages. This
 568    returns FALSE on error, TRUE otherwise. */
 569 int silc_client_del_channel_private_key(SilcClient client,
 570                                         SilcClientConnection conn,
 571                                         SilcChannelEntry channel,
 572                                         SilcChannelPrivateKey key);
 573
 574 /* Returns array (pointers) of private keys associated to the `channel'.
 575    The caller must free the array by calling the function
 576    silc_client_free_channel_private_keys. The pointers in the array may be
 577    used to delete the specific key by giving the pointer as argument to the
 578    function silc_client_del_channel_private_key. */
 579 SilcChannelPrivateKey *
 580 silc_client_list_channel_private_keys(SilcClient client,
 581                                       SilcClientConnection conn,
 582                                       SilcChannelEntry channel,
 583                                       unsigned int *key_count);
 584
 585 /* Frees the SilcChannelPrivateKey array. */
 586 void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys,
 587                                            unsigned int key_count);
 588
 589
 590 /* Key Agreement routines (client_keyagr.c) */
 591
 592 /* Sends key agreement request to the remote client indicated by the
 593    `client_entry'. If the caller provides the `hostname' and the `port'
 594    arguments then the library will bind the client to that hostname and
 595    that port for the key agreement protocol. It also sends the `hostname'
 596    and the `port' in the key agreement packet to the remote client. This
 597    would indicate that the remote client may initiate the key agreement
 598    protocol to the `hostname' on the `port'.  If port is zero then the
 599    bound port is undefined (the operating system defines it).
 600
 601    If the `hostname' and `port' is not provided then empty key agreement
 602    packet is sent to the remote client. The remote client may reply with
 603    the same packet including its hostname and port. If the library receives
 604    the reply from the remote client the `key_agreement' client operation
 605    callback will be called to verify whether the user wants to perform the
 606    key agreement or not.
 607
 608    NOTE: If the application provided the `hostname' and the `port' and the
 609    remote side initiates the key agreement protocol it is not verified
 610    from the user anymore whether the protocol should be executed or not.
 611    By setting the `hostname' and `port' the user gives permission to
 612    perform the protocol (we are responder in this case).
 613
 614    NOTE: If the remote side decides not to initiate the key agreement
 615    or decides not to reply with the key agreement packet then we cannot
 616    perform the key agreement at all. If the key agreement protocol is
 617    performed the `completion' callback with the `context' will be called.
 618    If remote side decides to ignore the request the `completion' will be
 619    called after the specified timeout, `timeout_secs'.
 620
 621    NOTE: There can be only one active key agreement for one client entry.
 622    Before setting new one, the old one must be finished (it is finished
 623    after calling the completion callback) or the function
 624    silc_client_abort_key_agreement must be called. */
 625 void silc_client_send_key_agreement(SilcClient client,
 626                                     SilcClientConnection conn,
 627                                     SilcClientEntry client_entry,
 628                                     char *hostname,
 629                                     int port,
 630                                     unsigned long timeout_secs,
 631                                     SilcKeyAgreementCallback completion,
 632                                     void *context);
 633
 634 /* Performs the actual key agreement protocol. Application may use this
 635    to initiate the key agreement protocol. This can be called for example
 636    after the application has received the `key_agreement' client operation,
 637    and did not return TRUE from it.
 638
 639    The `hostname' is the remote hostname (or IP address) and the `port'
 640    is the remote port. The `completion' callback with the `context' will
 641    be called after the key agreement protocol.
 642
 643    NOTE: If the application returns TRUE in the `key_agreement' client
 644    operation the library will automatically start the key agreement. In this
 645    case the application must not call this function. However, application
 646    may choose to just ignore the `key_agreement' client operation (and
 647    merely just print information about it on the screen) and call this
 648    function when the user whishes to do so (by, for example, giving some
 649    specific command). Thus, the API provides both, automatic and manual
 650    initiation of the key agreement. Calling this function is the manual
 651    initiation and returning TRUE in the `key_agreement' client operation
 652    is the automatic initiation. */
 653 void silc_client_perform_key_agreement(SilcClient client,
 654                                        SilcClientConnection conn,
 655                                        SilcClientEntry client_entry,
 656                                        char *hostname,
 657                                        int port,
 658                                        SilcKeyAgreementCallback completion,
 659                                        void *context);
 660
 661 /* Same as above but application has created already the connection to
 662    the remote host. The `sock' is the socket to the remote connection.
 663    Application can use this function if it does not want the client library
 664    to create the connection. */
 665 void silc_client_perform_key_agreement_fd(SilcClient client,
 666                                           SilcClientConnection conn,
 667                                           SilcClientEntry client_entry,
 668                                           int sock,
 669                                           char *hostname,
 670                                           SilcKeyAgreementCallback completion,
 671                                           void *context);
 672
 673 /* This function can be called to unbind the hostname and the port for
 674    the key agreement protocol. However, this function has effect only
 675    before the key agreement protocol has been performed. After it has
 676    been performed the library will automatically unbind the port. The
 677    `client_entry' is the client to which we sent the key agreement
 678    request. */
 679 void silc_client_abort_key_agreement(SilcClient client,
 680                                      SilcClientConnection conn,
 681                                      SilcClientEntry client_entry);
 682
 683 #endif