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