From 8b267c0010e8068e87c21a7413a1a614fd987d90 Mon Sep 17 00:00:00 2001 From: Pekka Riikonen Date: Tue, 27 Feb 2001 13:15:56 +0000 Subject: [PATCH] created and removed. --- lib/silcclient/ops.h | 191 ----------------- lib/silcclient/silcapi.h | 441 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 441 insertions(+), 191 deletions(-) delete mode 100644 lib/silcclient/ops.h create mode 100644 lib/silcclient/silcapi.h diff --git a/lib/silcclient/ops.h b/lib/silcclient/ops.h deleted file mode 100644 index 648a8121..00000000 --- a/lib/silcclient/ops.h +++ /dev/null @@ -1,191 +0,0 @@ -/* - - ops.h - - Author: Pekka Riikonen - - Copyright (C) 2000 Pekka Riikonen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -*/ - -#ifndef OPS_H -#define OPS_H - -/* - * SILC Client Operations - * - * These functions must be implemented by the application calling the - * SILC client library. The client library can call these functions at - * any time. - * - * To use this structure: define a static SilcClientOperations variable, - * fill it and pass its pointer to silc_client_alloc function. - */ -typedef struct { - void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...); - void (*channel_message)(SilcClient client, SilcClientConnection conn, - SilcClientEntry sender, SilcChannelEntry channel, - char *msg); - void (*private_message)(SilcClient client, SilcClientConnection conn, - SilcClientEntry sender, char *msg); - void (*notify)(SilcClient client, SilcClientConnection conn, - SilcNotifyType type, ...); - void (*command)(SilcClient client, SilcClientConnection conn, - SilcClientCommandContext cmd_context, int success, - SilcCommand command); - void (*command_reply)(SilcClient client, SilcClientConnection conn, - SilcCommandPayload cmd_payload, int success, - SilcCommand command, SilcCommandStatus status, ...); - void (*connect)(SilcClient client, SilcClientConnection conn, int success); - void (*disconnect)(SilcClient client, SilcClientConnection conn); - int (*get_auth_method)(SilcClient client, SilcClientConnection conn, - char *hostname, unsigned short port, - SilcProtocolAuthMeth *auth_meth, - unsigned char **auth_data, - unsigned int *auth_data_len); - int (*verify_server_key)(SilcClient client, SilcClientConnection conn, - unsigned char *pk, unsigned int pk_len, - SilcSKEPKType pk_type); - unsigned char *(*ask_passphrase)(SilcClient client, - SilcClientConnection conn); - void (*failure)(SilcClient client, SilcClientConnection conn, - SilcProtocol protocol, void *failure); -} SilcClientOperations; - -/* - Descriptions of above operation functions: - - void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...); - - Message sent to the application by library. `conn' associates the - message to a specific connection. `conn', however, may be NULL. - - - void (*channel_message)(SilcClient client, SilcClientConnection conn, - SilcClientEntry client, SilcChannelEntry channel, - char *msg); - - Message for a channel. The `sender' is the sender of the message - The `channel' is the channel. - - - void (*private_message)(SilcClient client, SilcClientConnection conn, - char *sender, char *msg); - - Private message to the client. The `sender' is the sender of the - message. - - - void (*notify)(SilcClient client, SilcClientConnection conn, ...); - - Notify message to the client. The notify arguments are sent in the - same order as servers sends them. The arguments are same as received - from the server except for ID's. If ID is received application receives - the corresponding entry to the ID. For example, if Client ID is received - application receives SilcClientEntry. Also, if the notify type is - for channel the channel entry is sent to application (even if server - does not send it because client library gets the channel entry from - the Channel ID in the packet's header). - - - void (*command)(SilcClient client, SilcClientConnection conn, - SilcClientCommandContext cmd_context, int success, - SilcCommand command); - - Command handler. This function is called always in the command function. - If error occurs it will be called as well. `conn' is the associated - client connection. `cmd_context' is the command context that was - originally sent to the command. `success' is FALSE if error occured - during command. `command' is the command being processed. It must be - noted that this is not reply from server. This is merely called just - after application has called the command. Just to tell application - that the command really was processed. - - - void (*command_reply)(SilcClient client, SilcClientConnection conn, - SilcCommandPayload cmd_payload, int success, - SilcCommandStatus status, SilcCommand command, ...); - - Command reply handler. This function is called always in the command reply - function. If error occurs it will be called as well. Normal scenario - is that it will be called after the received command data has been parsed - and processed. The function is used to pass the received command data to - the application. - - `conn' is the associated client connection. `cmd_payload' is the command - payload data received from server and it can be ignored. It is provided - if the application would like to re-parse the received command data, - however, it must be noted that the data is parsed already by the library - thus the payload can be ignored. `success' is FALSE if error occured. - In this case arguments are not sent to the application. The `status' is - the command reply status server returned. The `command' is the command - reply being processed. The function has variable argument list and each - command defines the number and type of arguments it passes to the - application (on error they are not sent). - - - void (*connect)(SilcClient client, SilcClientConnection conn, int success); - - Called to indicate that connection was either successfully established - or connecting failed. This is also the first time application receives - the SilcClientConnection objecet which it should save somewhere. - - - void (*disconnect)(SilcClient client, SilcClientConnection conn); - - Called to indicate that connection was disconnected to the server. - - - int (*get_auth_method)(SilcClient client, SilcClientConnection conn, - char *hostname, unsigned short port, - SilcProtocolAuthMeth *auth_meth, - unsigned char **auth_data, - unsigned int *auth_data_len); - - Find authentication method and authentication data by hostname and - port. The hostname may be IP address as well. The found authentication - method and authentication data is returned to `auth_meth', `auth_data' - and `auth_data_len'. The function returns TRUE if authentication method - is found and FALSE if not. `conn' may be NULL. - - - int (*verify_server_key)(SilcClient client, SilcClientConnection conn, - unsigned char *pk, unsigned int pk_len, - SilcSKEPKType pk_type); - - Verifies received public key. The public key has been received from - a server. If user decides to trust the key may be saved as trusted - server key for later use. If user does not trust the key this returns - FALSE. If everything is Ok this returns TRUE. - - - unsigned char *(*ask_passphrase)(SilcClient client, - SilcClientConnection conn); - - Ask (interact, that is) a passphrase from user. Returns the passphrase - or NULL on error. - - - void (*failure)(SilcClient client, SilcClientConnection conn, - SilcProtocol protocol, void *failure); - - Notifies application that failure packet was received. This is called - if there is some protocol active in the client. The `protocol' is the - protocol context. The `failure' is opaque pointer to the failure - indication. Note, that the `failure' is protocol dependant and application - must explicitly cast it to correct type. Usually `failure' is 32 bit - failure type (see protocol specs for all protocol failure types). - -*/ - -#endif diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h new file mode 100644 index 00000000..c67a969f --- /dev/null +++ b/lib/silcclient/silcapi.h @@ -0,0 +1,441 @@ +/* + + silcapi.h + + Author: Pekka Riikonen + + Copyright (C) 2000 - 2001 Pekka Riikonen + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +*/ + +#ifndef SILCAPI_H +#define SILCAPI_H + +#include "clientlibincludes.h" + +/* + This file defines the SILC Client Library API for the application. The + client operations are defined first. These are callback functions that + the application MUST implement since the library may call the functions + at any time. At the end of file is the API for the application that + it can use from the library. This is the only file that the application + may include from the SIlC Client Library. + + Please, refer to the README file in this directory for the directions + of how to use the SILC Client Library. +*/ + +/****************************************************************************** + + SILC Client Operations + + These functions must be implemented by the application calling the SILC + client library. The client library can call these functions at any time. + + To use this structure: define a static SilcClientOperations variable, + fill it and pass its pointer to silc_client_alloc function. + +******************************************************************************/ + +/* SILC Client Operations. These must be implemented by the application. */ +typedef struct { + /* Message sent to the application by library. `conn' associates the + message to a specific connection. `conn', however, may be NULL. */ + void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...); + + /* Message for a channel. The `sender' is the sender of the message + The `channel' is the channel. */ + void (*channel_message)(SilcClient client, SilcClientConnection conn, + SilcClientEntry sender, SilcChannelEntry channel, + char *msg); + + /* Private message to the client. The `sender' is the sender of the + message. */ + void (*private_message)(SilcClient client, SilcClientConnection conn, + SilcClientEntry sender, char *msg); + + + /* Notify message to the client. The notify arguments are sent in the + same order as servers sends them. The arguments are same as received + from the server except for ID's. If ID is received application receives + the corresponding entry to the ID. For example, if Client ID is received + application receives SilcClientEntry. Also, if the notify type is + for channel the channel entry is sent to application (even if server + does not send it because client library gets the channel entry from + the Channel ID in the packet's header). */ + void (*notify)(SilcClient client, SilcClientConnection conn, + SilcNotifyType type, ...); + + + /* Command handler. This function is called always in the command function. + If error occurs it will be called as well. `conn' is the associated + client connection. `cmd_context' is the command context that was + originally sent to the command. `success' is FALSE if error occured + during command. `command' is the command being processed. It must be + noted that this is not reply from server. This is merely called just + after application has called the command. Just to tell application + that the command really was processed. */ + void (*command)(SilcClient client, SilcClientConnection conn, + SilcClientCommandContext cmd_context, int success, + SilcCommand command); + + + /* Command reply handler. This function is called always in the command reply + function. If error occurs it will be called as well. Normal scenario + is that it will be called after the received command data has been parsed + and processed. The function is used to pass the received command data to + the application. + + `conn' is the associated client connection. `cmd_payload' is the command + payload data received from server and it can be ignored. It is provided + if the application would like to re-parse the received command data, + however, it must be noted that the data is parsed already by the library + thus the payload can be ignored. `success' is FALSE if error occured. + In this case arguments are not sent to the application. The `status' is + the command reply status server returned. The `command' is the command + reply being processed. The function has variable argument list and each + command defines the number and type of arguments it passes to the + application (on error they are not sent). */ + void (*command_reply)(SilcClient client, SilcClientConnection conn, + SilcCommandPayload cmd_payload, int success, + SilcCommand command, SilcCommandStatus status, ...); + + /* Called to indicate that connection was either successfully established + or connecting failed. This is also the first time application receives + the SilcClientConnection objecet which it should save somewhere. */ + void (*connect)(SilcClient client, SilcClientConnection conn, int success); + + /* Called to indicate that connection was disconnected to the server. */ + void (*disconnect)(SilcClient client, SilcClientConnection conn); + + /* Find authentication method and authentication data by hostname and + port. The hostname may be IP address as well. The found authentication + method and authentication data is returned to `auth_meth', `auth_data' + and `auth_data_len'. The function returns TRUE if authentication method + is found and FALSE if not. `conn' may be NULL. */ + int (*get_auth_method)(SilcClient client, SilcClientConnection conn, + char *hostname, unsigned short port, + SilcProtocolAuthMeth *auth_meth, + unsigned char **auth_data, + unsigned int *auth_data_len); + + /* Verifies received public key. The public key has been received from + a server. If user decides to trust the key may be saved as trusted + server key for later use. If user does not trust the key this returns + FALSE. If everything is Ok this returns TRUE. */ + int (*verify_server_key)(SilcClient client, SilcClientConnection conn, + unsigned char *pk, unsigned int pk_len, + SilcSKEPKType pk_type); + + /* Ask (interact, that is) a passphrase from user. Returns the passphrase + or NULL on error. */ + unsigned char *(*ask_passphrase)(SilcClient client, + SilcClientConnection conn); + + /* Notifies application that failure packet was received. This is called + if there is some protocol active in the client. The `protocol' is the + protocol context. The `failure' is opaque pointer to the failure + indication. Note, that the `failure' is protocol dependant and + application must explicitly cast it to correct type. Usually `failure' + is 32 bit failure type (see protocol specs for all protocol failure + types). */ + void (*failure)(SilcClient client, SilcClientConnection conn, + SilcProtocol protocol, void *failure); +} SilcClientOperations; + + + +/****************************************************************************** + + SILC Client Library API + + This is the API that is published by the SILC Client Library for the + applications. These functions are implemented in the SILC Client Library. + Application may freely call these functions from the library. + +******************************************************************************/ + +/* Initialization functions */ + +/* Allocates new client object. This has to be done before client may + work. After calling this one must call silc_client_init to initialize + the client. The `application' is application specific user data pointer + and caller must free it. */ +SilcClient silc_client_alloc(SilcClientOperations *ops, void *application); + +/* Frees client object and its internals. */ +void silc_client_free(SilcClient client); + +/* Initializes the client. This makes all the necessary steps to make + the client ready to be run. One must call silc_client_run to run the + client. Returns FALSE if error occured, TRUE otherwise. */ +int silc_client_init(SilcClient client); + +/* Runs the client. This starts the scheduler from the utility library. + When this functions returns the execution of the appliation is over. */ +void silc_client_run(SilcClient client); + +/* Stops the client. This is called to stop the client and thus to stop + the program. */ +void silc_client_stop(SilcClient client); + + +/* Connecting functions */ + +/* Connects to remote server. This is the main routine used to connect + to SILC server. Returns -1 on error and the created socket otherwise. + The `context' is user context that is saved into the SilcClientConnection + that is created after the connection is created. Note that application + may handle the connecting process outside the library. If this is the + case then this function is not used at all. When the connecting is + done the `connect' client operation is called. */ +int silc_client_connect_to_server(SilcClient client, int port, + char *host, void *context); + +/* Allocates and adds new connection to the client. This adds the allocated + connection to the connection table and returns a pointer to it. A client + can have multiple connections to multiple servers. Every connection must + be added to the client using this function. User data `context' may + be sent as argument. This function is normally used only if the + application performed the connecting outside the library. The library + however may use this internally. */ +SilcClientConnection silc_client_add_connection(SilcClient client, + char *hostname, + int port, + void *context); + +/* Removes connection from client. Frees all memory. */ +void silc_client_del_connection(SilcClient client, SilcClientConnection conn); + +/* Start SILC Key Exchange (SKE) protocol to negotiate shared secret + key material between client and server. This function can be called + directly if application is performing its own connecting and does not + use the connecting provided by this library. This function is normally + used only if the application performed the connecting outside the library. + The library however may use this internally. */ +int silc_client_start_key_exchange(SilcClient client, + SilcClientConnection conn, + int fd); + +/* Closes connection to remote end. Free's all allocated data except + for some information such as nickname etc. that are valid at all time. */ +void silc_client_close_connection(SilcClient client, + SilcClientConnection conn); + + +/* Packet sending functions */ + +/* Sends packet to the `channel'. Packet to channel is always encrypted + differently from "normal" packets. SILC header of the packet is + encrypted with the next receiver's key and the rest of the packet is + encrypted with the channel specific key. Padding and HMAC is computed + with the next receiver's key. The `data' is the channel message. If + the `force_send' is TRUE then the packet is sent immediately. */ +void silc_client_send_channel_message(SilcClient client, + SilcClientConnection conn, + SilcChannelEntry channel, + unsigned char *data, + unsigned int data_len, + int force_send); + +/* Sends private message to remote client. If private message key has + not been set with this client then the message will be encrypted using + normal session keys. Private messages are special packets in SILC + network hence we need this own function for them. This is similiar + to silc_client_packet_send_to_channel except that we send private + message. The `data' is the private message. If the `force_send' is + TRUE the packet is sent immediately. */ +void silc_client_send_private_message(SilcClient client, + SilcClientConnection conn, + SilcClientEntry client_entry, + unsigned char *data, + unsigned int data_len, + int force_send); + + +/* Private Message key management */ + +/* Adds private message key to the client library. The key will be used to + encrypt all private message between the client and the remote client + indicated by the `client_entry'. If `key' is NULL and the boolean value + `generate_key' is TRUE then the library will generate random key. + Otherwise the `key' provided by the application will be used. It maybe + random key or pre-shared-key. + + It is not necessary to set key for normal private message usage. If the + key is not set then the private messages are encrypted using normal + session keys. Setting the private key, however, increases the security. + + Note that the key set using this function is sent to the remote client + through the SILC network. The packet is protected using normal session + keys. + + Returns FALSE if the key is already set for the `client_entry', TRUE + otherwise. */ +int silc_client_add_private_message_key(SilcClient client, + SilcClientConnection conn, + SilcClientConnection client_entry, + unsigned char *key, + unsigned int key_len, + int generate_key); + +/* Removes the private message from the library. The key won't be used + after this to protect the private messages with the remote `client_entry' + client. Returns FALSE on error, TRUE otherwise. */ +int silc_client_del_private_message_key(SilcClient client, + SilcClientConnection conn, + SilcClientEntry client_entry); + +/* Structure to hold the list of private message keys. The array of this + structure is returned by the silc_client_list_private_message_keys + function. */ +typedef struct { + SilcClientEntry client_entry; /* The remote client entry */ + unsigned char *key; /* The raw key data */ + unsigned int key_len; /* The key length */ + int generated; /* TRUE if library generated the key */ +} *SilcPrivateMessageKeys; + +/* Returns array of set private message keys associated to the connection + `conn'. Returns allocated SilcPrivateMessageKeys array and the array + count to the `key_count' argument. The array must be freed by the caller + by calling the silc_client_free_private_message_keys function. Note: + the keys returned in the array is in raw format. It might not be desired + to show the keys as is. The application might choose not to show the keys + at all or to show the fingerprints of the keys. */ +SilcPrivateMessageKeys +silc_client_list_private_message_keys(SilcClient client, + SilcClientConnection conn, + unsigned int *key_count); + +/* Frees the SilcPrivateMessageKeys array returned by the function + silc_client_list_private_message_keys. */ +void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys, + unsigned int key_count); + + +/* Channel Message (private) key management */ + +/* Adds private key for channel. This may be set only if the channel's mode + mask includes the SILC_CHANNEL_MODE_PRIVKEY. This returns FALSE if the + mode is not set. When channel has private key then the messages are + encrypted using that key. All clients on the channel must also know the + key in order to decrypt the messages. However, it is possible to have + several private keys per one channel. In this case only some of the + clients on the channel may now the one key and only some the other key. + + The private key for channel is optional. If it is not set then the + channel messages are encrypted using the channel key generated by the + server. However, setting the private key (or keys) for the channel + significantly adds security. If more than one key is set the library + will automatically try all keys at the message decryption phase. Note: + setting many keys slows down the decryption phase as all keys has to + be tried in order to find the correct decryption key. However, setting + a few keys does not have big impact to the decryption performace. + + Note that this is entirely local setting. The key set using this function + is not sent to the network at any phase. */ +int silc_client_add_channel_private_key(SilcClient client, + SilcClientConnection conn, + SilcChannelEntry channel, + unsigned char *key, + unsigned int key_len); + +/* Removes all private keys from the `channel'. The old channel key is used + after calling this to protect the channel messages. Returns FALSE on + on error, TRUE otherwise. */ +int silc_client_del_channel_private_keys(SilcClient client, + SilcClientConnection conn, + SilcChannelEntry channel); + +/* Structure to hold one channel private key. */ +typedef struct { + unsigned char *key; /* The key */ + unsigned int key_len; /* The key length */ +} *SilcChannelPrivateKey; + +/* Removes and frees private key `key' from the channel `channel'. The `key' + is retrieved by calling the function silc_client_list_channel_private_keys. + The key is not used after this. If the key was last private key then the + old channel key is used hereafter to protect the channel messages. This + returns FALSE on error, TRUE otherwise. */ +int silc_client_del_channel_private_key(SilcClient client, + SilcClientConnection conn, + SilcChannelEntry channel, + SilcChannelPrivateKey key); + +/* Returns array (pointers) of private keys associated to the `channel'. + The caller must free the array by calling the function + silc_client_free_channel_private_keys. The pointers in the array may be + used to delete the specific key by giving the pointer as argument to the + function silc_client_del_channel_private_key. */ +SilcChannelPrivateKey * +silc_client_list_channel_private_keys(SilcClient client, + SilcClientConnection conn, + SilcChannelEntry channel, + unsigned int key_count); + +/* Frees the SilcChannelPrivateKey array. */ +void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys, + unsigned int key_count); + + +/* Client and Channel entry retrieval */ + +/* Callback function given to the silc_client_get_client function. The + found entries are allocated into the `clients' array. The array must + not be freed by the caller, the library will free it later. If the + `clients' is NULL, no such clients exist in the SILC Network. */ +typedef void (*SilcGetClientCallback)(SilcClient client, + SilcClientConnection conn, + SilcClientEntry *clients, + unsigned int clients_count, + void *context); + +/* Finds client entry or entries by the `nickname' and `server'. The + completion callback will be called when the client entries has been found. + + Note: this function is always asynchronous and resolves the client + information from the server. Thus, if you already know the client + information then use the silc_client_get_client_by_id function to + get the client entry since this function may be very slow and should + be used only to initially get the client entries. */ +void silc_client_get_clients(SilcClient client, + SilcClientConnection conn, + char *nickname, + char *server, + SilcGetClientCallback completion, + void *context); + +/* Same as above function but does not resolve anything from the server. + This checks local cache and returns all clients from the cache. */ +SilcClientEntry *silc_client_get_clients_local(SilcClient client, + SilcClientConnection conn, + char *nickname, + char *server, + unsigned int *clients_count); + +/* Find entry for client by the client's ID. Returns the entry or NULL + if the entry was not found. */ +SilcClientEntry silc_client_get_client_by_id(SilcClient client, + SilcClientConnection conn, + SilcClientID *client_id); + +/* Finds entry for channel by the channel name. Returns the entry or NULL + if the entry was not found. It is found only if the client is joined + to the channel. */ +SilcChannelEntry silc_client_get_channel(SilcClient client, + SilcClientConnection conn, + char *channel); + +#endif -- 2.24.0