+++ /dev/null
-/*
-
- ops.h
-
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
- 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
--- /dev/null
+/*
+
+ silcapi.h
+
+ Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+
+ 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
projects / silc.git / commitdiff