lib/silcclient/silcapi.h

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