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