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