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 occurred */
  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 occurred 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 occurred. 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   uint32 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 occurred
 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 occurred.
 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, uint16 port,
 163                          SilcProtocolAuthMeth *auth_meth,
 164                          unsigned char **auth_data,
 165                          uint32 *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                            uint32 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 occurred, 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    If the `sock' is NULL then the conn->sock will be used.  If `sock' is
 290    provided it will be checked whether the sock and `conn->sock' are the
 291    same (they can be different, ie. a socket can use `conn' as its
 292    connection but `conn->sock' might be actually a different connection
 293    than the `sock'). */
 294 void silc_client_close_connection(SilcClient client,
 295                                   SilcSocketConnection sock,
 296                                   SilcClientConnection conn);
 297
 298
 299 /* Message sending functions (client_channel.c and client_prvmsg.c) */
 300
 301 /* Sends packet to the `channel'. Packet to channel is always encrypted
 302    differently from "normal" packets. SILC header of the packet is
 303    encrypted with the next receiver's key and the rest of the packet is
 304    encrypted with the channel specific key. Padding and HMAC is computed
 305    with the next receiver's key. The `data' is the channel message. If
 306    the `force_send' is TRUE then the packet is sent immediately.
 307
 308    If `key' is provided then that private key is used to encrypt the
 309    channel message.  If it is not provided, private keys has not been
 310    set at all, the normal channel key is used automatically.  If private
 311    keys are set then the first key (the key that was added first as
 312    private key) is used. */
 313 void silc_client_send_channel_message(SilcClient client,
 314                                       SilcClientConnection conn,
 315                                       SilcChannelEntry channel,
 316                                       SilcChannelPrivateKey key,
 317                                       SilcMessageFlags flags,
 318                                       unsigned char *data,
 319                                       uint32 data_len,
 320                                       int force_send);
 321
 322 /* Sends private message to remote client. If private message key has
 323    not been set with this client then the message will be encrypted using
 324    normal session keys. Private messages are special packets in SILC
 325    network hence we need this own function for them. This is similar
 326    to silc_client_packet_send_to_channel except that we send private
 327    message. The `data' is the private message. If the `force_send' is
 328    TRUE the packet is sent immediately. */
 329 void silc_client_send_private_message(SilcClient client,
 330                                       SilcClientConnection conn,
 331                                       SilcClientEntry client_entry,
 332                                       SilcMessageFlags flags,
 333                                       unsigned char *data,
 334                                       uint32 data_len,
 335                                       int force_send);
 336
 337
 338 /* Client and Channel entry retrieval (idlist.c) */
 339
 340 /* Callback function given to the silc_client_get_client function. The
 341    found entries are allocated into the `clients' array. The array must
 342    not be freed by the caller, the library will free it later. If the
 343    `clients' is NULL, no such clients exist in the SILC Network. */
 344 typedef void (*SilcGetClientCallback)(SilcClient client,
 345                                       SilcClientConnection conn,
 346                                       SilcClientEntry *clients,
 347                                       uint32 clients_count,
 348                                       void *context);
 349
 350 /* Finds client entry or entries by the `nickname' and `server'. The
 351    completion callback will be called when the client entries has been found.
 352
 353    Note: this function is always asynchronous and resolves the client
 354    information from the server. Thus, if you already know the client
 355    information then use the silc_client_get_client_by_id function to
 356    get the client entry since this function may be very slow and should
 357    be used only to initially get the client entries. */
 358 void silc_client_get_clients(SilcClient client,
 359                              SilcClientConnection conn,
 360                              char *nickname,
 361                              char *server,
 362                              SilcGetClientCallback completion,
 363                              void *context);
 364
 365 /* Same as above function but does not resolve anything from the server.
 366    This checks local cache and returns all clients from the cache. */
 367 SilcClientEntry *silc_client_get_clients_local(SilcClient client,
 368                                                SilcClientConnection conn,
 369                                                char *nickname,
 370                                                char *server,
 371                                                uint32 *clients_count);
 372
 373 /* Gets client entries by the list of client ID's `client_id_list'. This
 374    always resolves those client ID's it does not know yet from the server
 375    so this function might take a while. The `client_id_list' is a list
 376    of ID Payloads added one after other.  JOIN command reply and USERS
 377    command reply for example returns this sort of list. The `completion'
 378    will be called after the entries are available. */
 379 void silc_client_get_clients_by_list(SilcClient client,
 380                                      SilcClientConnection conn,
 381                                      uint32 list_count,
 382                                      SilcBuffer client_id_list,
 383                                      SilcGetClientCallback completion,
 384                                      void *context);
 385
 386 /* Find entry for client by the client's ID. Returns the entry or NULL
 387    if the entry was not found. */
 388 SilcClientEntry silc_client_get_client_by_id(SilcClient client,
 389                                              SilcClientConnection conn,
 390                                              SilcClientID *client_id);
 391
 392 /* Same as above but will always resolve the information from the server.
 393    Use this only if you know that you don't have the entry and the only
 394    thing you know about the client is its ID. */
 395 void silc_client_get_client_by_id_resolve(SilcClient client,
 396                                           SilcClientConnection conn,
 397                                           SilcClientID *client_id,
 398                                           SilcGetClientCallback completion,
 399                                           void *context);
 400
 401 /* Finds entry for channel by the channel name. Returns the entry or NULL
 402    if the entry was not found. It is found only if the client is joined
 403    to the channel. */
 404 SilcChannelEntry silc_client_get_channel(SilcClient client,
 405                                          SilcClientConnection conn,
 406                                          char *channel);
 407
 408
 409 /* Command management (command.c) */
 410
 411 /* Allocate Command Context. The context is defined in `command.h' file.
 412    The context is used by the library commands and applications should use
 413    it as well. However, application may choose to use some own context
 414    for its local commands. All library commands, however, must use this
 415    context. */
 416 SilcClientCommandContext silc_client_command_alloc();
 417
 418 /* Free command context and its internals */
 419 void silc_client_command_free(SilcClientCommandContext ctx);
 420
 421 /* Duplicate Command Context by adding reference counter. The context won't
 422    be free'd untill it hits zero. */
 423 SilcClientCommandContext silc_client_command_dup(SilcClientCommandContext ctx);
 424
 425 /* Finds and returns a pointer to the command list. Return NULL if the
 426    command is not found. See the `command.[ch]' for the command list. */
 427 SilcClientCommand *silc_client_command_find(const char *name);
 428
 429 /* Generic function to send any command. The arguments must be sent already
 430    encoded into correct form and in correct order. */
 431 void silc_client_send_command(SilcClient client, SilcClientConnection conn,
 432                               SilcCommand command, uint16 ident,
 433                               uint32 argc, ...);
 434
 435 /* Pending Command callback destructor. This is called after calling the
 436    pending callback or if error occurs while processing the pending command.
 437    If error occurs then the callback won't be called at all, and only this
 438    destructor is called. The `context' is the context given for the function
 439    silc_client_command_pending. */
 440 typedef void (*SilcClientPendingDestructor)(void *context);
 441
 442 /* Add new pending command to be executed when reply to a command has been
 443    received.  The `reply_cmd' is the command that will call the `callback'
 444    with `context' when reply has been received.  If `ident is non-zero
 445    the `callback' will be executed when received reply with command
 446    identifier `ident'. */
 447 void silc_client_command_pending(SilcClientConnection conn,
 448                                  SilcCommand reply_cmd,
 449                                  uint16 ident,
 450                                  SilcClientPendingDestructor destructor,
 451                                  SilcCommandCb callback,
 452                                  void *context);
 453
 454
 455 /* Private Message key management (client_prvmsg.c) */
 456
 457 /* Adds private message key to the client library. The key will be used to
 458    encrypt all private message between the client and the remote client
 459    indicated by the `client_entry'. If the `key' is NULL and the boolean
 460    value `generate_key' is TRUE the library will generate random key.
 461    The `key' maybe for example pre-shared-key, passphrase or similar.
 462    The `cipher' MAY be provided but SHOULD be NULL to assure that the
 463    requirements of the SILC protocol are met. The API, however, allows
 464    to allocate any cipher.
 465
 466    It is not necessary to set key for normal private message usage. If the
 467    key is not set then the private messages are encrypted using normal
 468    session keys. Setting the private key, however, increases the security.
 469
 470    Returns FALSE if the key is already set for the `client_entry', TRUE
 471    otherwise. */
 472 int silc_client_add_private_message_key(SilcClient client,
 473                                         SilcClientConnection conn,
 474                                         SilcClientEntry client_entry,
 475                                         char *cipher,
 476                                         unsigned char *key,
 477                                         uint32 key_len,
 478                                         int generate_key);
 479
 480 /* Same as above but takes the key material from the SKE key material
 481    structure. This structure is received if the application uses the
 482    silc_client_send_key_agreement to negotiate the key material. The
 483    `cipher' SHOULD be provided as it is negotiated also in the SKE
 484    protocol. */
 485 int silc_client_add_private_message_key_ske(SilcClient client,
 486                                             SilcClientConnection conn,
 487                                             SilcClientEntry client_entry,
 488                                             char *cipher,
 489                                             SilcSKEKeyMaterial *key);
 490
 491 /* Sends private message key payload to the remote client indicated by
 492    the `client_entry'. If the `force_send' is TRUE the packet is sent
 493    immediately. Returns FALSE if error occurs, TRUE otherwise. The
 494    application should call this function after setting the key to the
 495    client.
 496
 497    Note that the key sent using this function is sent to the remote client
 498    through the SILC network. The packet is protected using normal session
 499    keys. */
 500 int silc_client_send_private_message_key(SilcClient client,
 501                                          SilcClientConnection conn,
 502                                          SilcClientEntry client_entry,
 503                                          int force_send);
 504
 505 /* Removes the private message from the library. The key won't be used
 506    after this to protect the private messages with the remote `client_entry'
 507    client. Returns FALSE on error, TRUE otherwise. */
 508 int silc_client_del_private_message_key(SilcClient client,
 509                                         SilcClientConnection conn,
 510                                         SilcClientEntry client_entry);
 511
 512 /* Returns array of set private message keys associated to the connection
 513    `conn'. Returns allocated SilcPrivateMessageKeys array and the array
 514    count to the `key_count' argument. The array must be freed by the caller
 515    by calling the silc_client_free_private_message_keys function. Note:
 516    the keys returned in the array is in raw format. It might not be desired
 517    to show the keys as is. The application might choose not to show the keys
 518    at all or to show the fingerprints of the keys. */
 519 SilcPrivateMessageKeys
 520 silc_client_list_private_message_keys(SilcClient client,
 521                                       SilcClientConnection conn,
 522                                       uint32 *key_count);
 523
 524 /* Frees the SilcPrivateMessageKeys array returned by the function
 525    silc_client_list_private_message_keys. */
 526 void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
 527                                            uint32 key_count);
 528
 529
 530 /* Channel private key management (client_channel.c,
 531    SilcChannelPrivateKey is defined in idlist.h) */
 532
 533 /* Adds private key for channel. This may be set only if the channel's mode
 534    mask includes the SILC_CHANNEL_MODE_PRIVKEY. This returns FALSE if the
 535    mode is not set. When channel has private key then the messages are
 536    encrypted using that key. All clients on the channel must also know the
 537    key in order to decrypt the messages. However, it is possible to have
 538    several private keys per one channel. In this case only some of the
 539    clients on the channel may know the one key and only some the other key.
 540
 541    The private key for channel is optional. If it is not set then the
 542    channel messages are encrypted using the channel key generated by the
 543    server. However, setting the private key (or keys) for the channel
 544    significantly adds security. If more than one key is set the library
 545    will automatically try all keys at the message decryption phase. Note:
 546    setting many keys slows down the decryption phase as all keys has to
 547    be tried in order to find the correct decryption key. However, setting
 548    a few keys does not have big impact to the decryption performace.
 549
 550    NOTE: that this is entirely local setting. The key set using this function
 551    is not sent to the network at any phase.
 552
 553    NOTE: If the key material was originated by the SKE protocol (using
 554    silc_client_send_key_agreement) then the `key' MUST be the
 555    key->send_enc_key as this is dictated by the SILC protocol. However,
 556    currently it is not expected that the SKE key material would be used
 557    as channel private key. However, this API allows it. */
 558 int silc_client_add_channel_private_key(SilcClient client,
 559                                         SilcClientConnection conn,
 560                                         SilcChannelEntry channel,
 561                                         char *cipher,
 562                                         char *hmac,
 563                                         unsigned char *key,
 564                                         uint32 key_len);
 565
 566 /* Removes all private keys from the `channel'. The old channel key is used
 567    after calling this to protect the channel messages. Returns FALSE on
 568    on error, TRUE otherwise. */
 569 int silc_client_del_channel_private_keys(SilcClient client,
 570                                          SilcClientConnection conn,
 571                                          SilcChannelEntry channel);
 572
 573 /* Removes and frees private key `key' from the channel `channel'. The `key'
 574    is retrieved by calling the function silc_client_list_channel_private_keys.
 575    The key is not used after this. If the key was last private key then the
 576    old channel key is used hereafter to protect the channel messages. This
 577    returns FALSE on error, TRUE otherwise. */
 578 int silc_client_del_channel_private_key(SilcClient client,
 579                                         SilcClientConnection conn,
 580                                         SilcChannelEntry channel,
 581                                         SilcChannelPrivateKey key);
 582
 583 /* Returns array (pointers) of private keys associated to the `channel'.
 584    The caller must free the array by calling the function
 585    silc_client_free_channel_private_keys. The pointers in the array may be
 586    used to delete the specific key by giving the pointer as argument to the
 587    function silc_client_del_channel_private_key. */
 588 SilcChannelPrivateKey *
 589 silc_client_list_channel_private_keys(SilcClient client,
 590                                       SilcClientConnection conn,
 591                                       SilcChannelEntry channel,
 592                                       uint32 *key_count);
 593
 594 /* Frees the SilcChannelPrivateKey array. */
 595 void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys,
 596                                            uint32 key_count);
 597
 598
 599 /* Key Agreement routines (client_keyagr.c) */
 600
 601 /* Sends key agreement request to the remote client indicated by the
 602    `client_entry'. If the caller provides the `hostname' and the `port'
 603    arguments then the library will bind the client to that hostname and
 604    that port for the key agreement protocol. It also sends the `hostname'
 605    and the `port' in the key agreement packet to the remote client. This
 606    would indicate that the remote client may initiate the key agreement
 607    protocol to the `hostname' on the `port'.  If port is zero then the
 608    bound port is undefined (the operating system defines it).
 609
 610    If the `hostname' and `port' is not provided then empty key agreement
 611    packet is sent to the remote client. The remote client may reply with
 612    the same packet including its hostname and port. If the library receives
 613    the reply from the remote client the `key_agreement' client operation
 614    callback will be called to verify whether the user wants to perform the
 615    key agreement or not.
 616
 617    NOTE: If the application provided the `hostname' and the `port' and the
 618    remote side initiates the key agreement protocol it is not verified
 619    from the user anymore whether the protocol should be executed or not.
 620    By setting the `hostname' and `port' the user gives permission to
 621    perform the protocol (we are responder in this case).
 622
 623    NOTE: If the remote side decides not to initiate the key agreement
 624    or decides not to reply with the key agreement packet then we cannot
 625    perform the key agreement at all. If the key agreement protocol is
 626    performed the `completion' callback with the `context' will be called.
 627    If remote side decides to ignore the request the `completion' will be
 628    called after the specified timeout, `timeout_secs'.
 629
 630    NOTE: There can be only one active key agreement for one client entry.
 631    Before setting new one, the old one must be finished (it is finished
 632    after calling the completion callback) or the function
 633    silc_client_abort_key_agreement must be called. */
 634 void silc_client_send_key_agreement(SilcClient client,
 635                                     SilcClientConnection conn,
 636                                     SilcClientEntry client_entry,
 637                                     char *hostname,
 638                                     int port,
 639                                     uint32 timeout_secs,
 640                                     SilcKeyAgreementCallback completion,
 641                                     void *context);
 642
 643 /* Performs the actual key agreement protocol. Application may use this
 644    to initiate the key agreement protocol. This can be called for example
 645    after the application has received the `key_agreement' client operation,
 646    and did not return TRUE from it.
 647
 648    The `hostname' is the remote hostname (or IP address) and the `port'
 649    is the remote port. The `completion' callback with the `context' will
 650    be called after the key agreement protocol.
 651
 652    NOTE: If the application returns TRUE in the `key_agreement' client
 653    operation the library will automatically start the key agreement. In this
 654    case the application must not call this function. However, application
 655    may choose to just ignore the `key_agreement' client operation (and
 656    merely just print information about it on the screen) and call this
 657    function when the user whishes to do so (by, for example, giving some
 658    specific command). Thus, the API provides both, automatic and manual
 659    initiation of the key agreement. Calling this function is the manual
 660    initiation and returning TRUE in the `key_agreement' client operation
 661    is the automatic initiation. */
 662 void silc_client_perform_key_agreement(SilcClient client,
 663                                        SilcClientConnection conn,
 664                                        SilcClientEntry client_entry,
 665                                        char *hostname,
 666                                        int port,
 667                                        SilcKeyAgreementCallback completion,
 668                                        void *context);
 669
 670 /* Same as above but application has created already the connection to
 671    the remote host. The `sock' is the socket to the remote connection.
 672    Application can use this function if it does not want the client library
 673    to create the connection. */
 674 void silc_client_perform_key_agreement_fd(SilcClient client,
 675                                           SilcClientConnection conn,
 676                                           SilcClientEntry client_entry,
 677                                           int sock,
 678                                           char *hostname,
 679                                           SilcKeyAgreementCallback completion,
 680                                           void *context);
 681
 682 /* This function can be called to unbind the hostname and the port for
 683    the key agreement protocol. However, this function has effect only
 684    before the key agreement protocol has been performed. After it has
 685    been performed the library will automatically unbind the port. The
 686    `client_entry' is the client to which we sent the key agreement
 687    request. */
 688 void silc_client_abort_key_agreement(SilcClient client,
 689                                      SilcClientConnection conn,
 690                                      SilcClientEntry client_entry);
 691
 692 #endif