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