-/****h* silcclient/silcapi.h
- *
- * NAME
- *
- * silcapi.h
- *
- * COPYRIGHT
- *
- * 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.
+/*
+
+ silcapi.h
+
+ Author: Pekka Riikonen <priikone@silcnet.org>
+
+ 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.
+
+*/
+
+/****h* silcclient/SilcClientAPI
*
* DESCRIPTION
*
- * This file defines the SILC Client Library API for the application. The
- * client operations are defined first. These are callback functions that
+ * This interface 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
***/
typedef void (*SilcVerifyPublicKey)(bool success, void *context);
+/****f* silcclient/SilcClientAPI/SilcGetAuthMeth
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcGetAuthMeth)(bool success,
+ * SilcProtocolAuthMeth auth_meth,
+ * const unsigned char *auth_data,
+ * uint32 auth_data_len, void *context);
+ *
+ * DESCRIPTION
+ *
+ * Authentication method resolving callback. This is called by the
+ * application to return the resolved authentication method. The client
+ * library has called the get_auth_method client operation and given
+ * this function pointer as argument. The `success' will indicate whether
+ * the authentication method could be resolved. The `auth_meth' is the
+ * resolved authentication method. The `auth_data' and the `auth_data_len'
+ * are the resolved authentication data. The `context' is the libary's
+ * context sent to the get_auth_method client operation.
+ *
+ ***/
+typedef void (*SilcGetAuthMeth)(bool success,
+ SilcProtocolAuthMeth auth_meth,
+ const unsigned char *auth_data,
+ uint32 auth_data_len, void *context);
+
+/****d* silcclient/SilcClientAPI/SilcClientMessageType
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcClientMessageType;
+ *
+ * DESCRIPTION
+ *
+ * Different message types for `say' client operation. The application
+ * may filter the message sent by the library according this type.
+ *
+ * SOURCE
+ */
+typedef enum {
+ SILC_CLIENT_MESSAGE_INFO, /* Informational */
+ SILC_CLIENT_MESSAGE_WARNING, /* Warning */
+ SILC_CLIENT_MESSAGE_ERROR, /* Error */
+ SILC_CLIENT_MESSAGE_AUDIT, /* Auditable */
+} SilcClientMessageType;
+/***/
+
/****s* silcclient/SilcClientAPI/SilcClientOperations
*
* NAME
*/
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 to a specific connection. `conn', however, may be NULL.
+ The `type' indicates the type of the message sent by the library.
+ The applicationi can for example filter the message according the
+ type. */
+ void (*say)(SilcClient client, SilcClientConnection conn,
+ SilcClientMessageType type, char *msg, ...);
/* Message for a channel. The `sender' is the sender of the message
The `channel' is the channel. */
/* 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. */
+ the SilcClientConnection objecet which it should save somewhere.
+ If the `success' is FALSE the application must always call the function
+ silc_client_close_connection. */
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, uint16 port,
- SilcProtocolAuthMeth *auth_meth,
- unsigned char **auth_data,
- uint32 *auth_data_len);
+ port. The hostname may be IP address as well. When the authentication
+ method has been resolved the `completion' callback with the found
+ authentication method and authentication data is called. The `conn'
+ may be NULL. */
+ void (*get_auth_method)(SilcClient client, SilcClientConnection conn,
+ char *hostname, uint16 port,
+ SilcGetAuthMeth completion, void *context);
/* Verifies received public key. The `conn_type' indicates which entity
(server, client etc.) has sent the public key. If user decides to trust
} SilcClientOperations;
/***/
+/****f* silcclient/SilcClientAPI/SilcNicknameFormatParse
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcNicknameFormatParse)(const char *nickname,
+ * char **ret_nickname);
+ *
+ * DESCRIPTION
+ *
+ * A callback function provided by the application for the library in
+ * SilcClientParams structure. This function parses the formatted
+ * nickname string `nickname' and returns the true nickname to the
+ * `ret_nickname' pointer. The library can call this function at
+ * any time.
+ *
+ ***/
+typedef void (*SilcNicknameFormatParse)(const char *nickname,
+ char **ret_nickname);
+
+/****s* silcclient/SilcClientAPI/SilcClientParams
+ *
+ * NAME
+ *
+ * typedef struct { ... } SilcClientParams;
+ *
+ * DESCRIPTION
+ *
+ * Client parameters. This can be filled with proper values and
+ * given as argument to the silc_client_alloc function. The structure
+ * hold various parameters which affects the function of the client.
+ *
+ * SOURCE
+ */
+typedef struct {
+ /* Number of maximum tasks the client library's scheduler can handle.
+ If set to zero, the default value will be used (200). For WIN32
+ systems this should be set to 64 as it is the hard limit dictated
+ by the WIN32. */
+ int task_max;
+
+ /* Rekey timeout in seconds. The client will perform rekey in this
+ time interval. If set to zero, the default value will be used. */
+ unsigned int rekey_secs;
+
+ /* Connection authentication method request timeout. If server does not
+ reply back the current authentication method when we've requested it
+ in this time interval we'll assume the reply will not come at all.
+ If set to zero, the default value (2 seconds) will be used. */
+ unsigned int connauth_request_secs;
+
+ /* Nickname format string. This can be used to order the client library
+ to save the nicknames in the library in a certain format. Since
+ nicknames are not unique in SILC it is possible to have multiple same
+ nicknames. Using this format string it is possible to order the library
+ to separate the multiple same nicknames from each other. The format
+ types are defined below and they can appear in any order in the format
+ string. If this is NULL then default format is used which is the
+ default nickname without anything else. The string MUST be NULL
+ terminated.
+
+ Following format types are available:
+
+ %n nickname - the real nickname returned by the server (mandatory)
+ %h hostname - the stripped hostname of the client
+ %H full hostname - the full hostname of the client
+ %s server name - the server name the client is connected
+ %S full server - the full server name the client is connected
+ %a number - ascending number in case there are several
+ same nicknames (fe. nick@host and nick@host2)
+
+ Example format strings: "%n@%h%a" (fe. nick@host, nick@host2)
+ "%a!%n@%s" (fe. nick@server, 2!nick@server)
+ "%n@%H" (fe. nick@host.domain.com)
+
+ By default this format is employed to the nicknames by the libary
+ only when there appears multiple same nicknames. If the library has
+ only one nickname cached the nickname is saved as is and without the
+ defined format. If you want always to save the nickname in the defined
+ format set the boolean field `nickname_force_format' to value TRUE.
+ */
+ char nickname_format[32];
+
+ /* If this is set to TRUE then the `nickname_format' is employed to all
+ saved nicknames even if there are no multiple same nicknames in the
+ cache. By default this is FALSE, which means that the `nickname_format'
+ is employed only if the library will receive a nickname that is
+ already saved in the cache. It is recommended to leave this to FALSE
+ value. */
+ bool nickname_force_format;
+
+ /* A callback function provided by the application for the library to
+ parse the nickname from the formatted nickname string. Even though
+ the libary formats the nicknames the application knows generally the
+ format better so this function should be provided for the library
+ if the application sets the `nickname_format' field. The library
+ will call this to get the true nickname from the provided formatted
+ nickname string whenever it needs the true nickname. */
+ SilcNicknameFormatParse nickname_parse;
+
+} SilcClientParams;
+/***/
+
+
/* Initialization functions (client.c) */
/****f* silcclient/SilcClientAPI/silc_client_alloc
* SYNOPSIS
*
* SilcClient silc_client_alloc(SilcClientOperations *ops,
- * void *application);
+ * SilcClientParams *params,
+ * void *application,
+ * const char *silc_version);
*
* DESCRIPTION
*
* 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.
+ * and caller must free it. The `silc_version' is the application version
+ * that will be used to compare against remote host's (usually a server)
+ * version string.
*
***/
-SilcClient silc_client_alloc(SilcClientOperations *ops, void *application);
+SilcClient silc_client_alloc(SilcClientOperations *ops,
+ SilcClientParams *params,
+ void *application,
+ const char *silc_version);
/****f* silcclient/SilcClientAPI/silc_client_free
*
* 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.
+ * library. The library however may use this internally. Returns FALSE
+ * if the key exchange could not be started.
*
***/
-int silc_client_start_key_exchange(SilcClient client,
- SilcClientConnection conn,
- int fd);
+bool silc_client_start_key_exchange(SilcClient client,
+ SilcClientConnection conn,
+ int fd);
/****f* silcclient/SilcClientAPI/silc_client_close_connection
*
*
* 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
+ * not be freed by the receiver, the library will free it later. If the
* `clients' is NULL, no such clients exist in the SILC Network.
*
***/
*
* void silc_client_get_clients(SilcClient client,
* SilcClientConnection conn,
- * char *nickname,
- * char *server,
+ * const char *nickname,
+ * const char *server,
* SilcGetClientCallback completion,
* void *context);
*
***/
void silc_client_get_clients(SilcClient client,
SilcClientConnection conn,
- char *nickname,
- char *server,
+ const char *nickname,
+ const char *server,
SilcGetClientCallback completion,
void *context);
*
* SilcClientEntry *silc_client_get_clients_local(SilcClient client,
* SilcClientConnection conn,
- * char *nickname,
- * char *server,
+ * const char *nickname,
+ * const char *format,
* uint32 *clients_count);
*
* DESCRIPTION
*
* Same as silc_client_get_clients function but does not resolve anything
- * from the server. This checks local cache and returns all clients from
- * the local cache.
+ * from the server. This checks local cache and returns all matching
+ * clients from the local cache. If none was found this returns NULL.
+ * The `nickname' is the real nickname of the client, and the `format'
+ * is the formatted nickname to find exact match from multiple found
+ * entries. The format must be same as given in the SilcClientParams
+ * structure to the client library. If the `format' is NULL all found
+ * clients by `nickname' are returned.
*
***/
SilcClientEntry *silc_client_get_clients_local(SilcClient client,
SilcClientConnection conn,
- char *nickname,
- char *server,
+ const char *nickname,
+ const char *format,
uint32 *clients_count);
/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list
SilcGetClientCallback completion,
void *context);
+/****f* silcclient/SilcClientAPI/silc_client_del_client
+ *
+ * SYNOPSIS
+ *
+ * bool silc_client_del_client(SilcClient client, SilcClientConnection conn,
+ * SilcClientEntry client_entry)
+ *
+ * DESCRIPTION
+ *
+ * Removes client from local cache by the client entry indicated by
+ * the `client_entry'. Returns TRUE if the deletion were successful.
+ *
+ ***/
+bool silc_client_del_client(SilcClient client, SilcClientConnection conn,
+ SilcClientEntry client_entry);
+
+/****f* silcclient/SilcClientAPI/SilcGetChannelCallback
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcGetClientCallback)(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry *clients,
+ * uint32 clients_count,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Callback function given to the silc_client_get_channel_* functions.
+ * The found entries are allocated into the `channels' array. The array
+ * must not be freed by the receiver, the library will free it later.
+ * If the `channel' is NULL, no such channel exist in the SILC Network.
+ *
+ ***/
+typedef void (*SilcGetChannelCallback)(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelEntry *channels,
+ uint32 channels_count,
+ void *context);
+
/****f* silcclient/SilcClientAPI/silc_client_get_channel
*
* SYNOPSIS
SilcClientConnection conn,
char *channel);
+/****f* silcclient/SilcClientAPI/silc_client_get_channel_id_resolve
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_client_get_channel_by_id_resolve(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelID *channel_id,
+ * SilcGetClientCallback completion,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Finds channel entry by the channel name. Returns the entry or NULL
+ * if it was not found.
+ *
+ ***/
+SilcChannelEntry silc_client_get_channel_by_id(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelID *channel_id);
+
+/****f* silcclient/SilcClientAPI/silc_client_get_channel
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_client_get_channel_by_id_resolve(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelID *channel_id,
+ * SilcGetClientCallback completion,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Resolves the channel information (its name mainly) from the server
+ * by the `channel_id'. Use this only if you know that you do not have
+ * the entry cached locally.
+ *
+ ***/
+void silc_client_get_channel_by_id_resolve(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelID *channel_id,
+ SilcGetChannelCallback completion,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_del_channel
+ *
+ * SYNOPSIS
+ *
+ * bool silc_client_del_channel(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelEntry channel)
+ *
+ * DESCRIPTION
+ *
+ * Removes channel from local cache by the channel entry indicated by
+ * the `channel'. Returns TRUE if the deletion were successful.
+ *
+ ***/
+bool silc_client_del_channel(SilcClient client, SilcClientConnection conn,
+ SilcChannelEntry channel);
+
+/****f* silcclient/SilcClientAPI/silc_client_get_server
+ *
+ * SYNOPSIS
+ *
+ * SilcServerEntry silc_client_get_server(SilcClient client,
+ * SilcClientConnection conn,
+ * char *server_name)
+ *
+ * DESCRIPTION
+ *
+ * Finds entry for server by the server name. Returns the entry or NULL
+ * if the entry was not found.
+ *
+ ***/
+SilcServerEntry silc_client_get_server(SilcClient client,
+ SilcClientConnection conn,
+ char *server_name);
+
+/****f* silcclient/SilcClientAPI/silc_client_get_server_by_id
+ *
+ * SYNOPSIS
+ *
+ * SilcServerEntry silc_client_get_server_by_id(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcServerID *server_id);
+ *
+ * DESCRIPTION
+ *
+ * Finds entry for server by the server ID. Returns the entry or NULL
+ * if the entry was not found.
+ *
+ ***/
+SilcServerEntry silc_client_get_server_by_id(SilcClient client,
+ SilcClientConnection conn,
+ SilcServerID *server_id);
+
+/****f* silcclient/SilcClientAPI/silc_client_del_server
+ *
+ * SYNOPSIS
+ *
+ * bool silc_client_del_server(SilcClient client, SilcClientConnection conn,
+ * SilcServerEntry server);
+ *
+ * DESCRIPTION
+ *
+ * Removes server from local cache by the server entry indicated by
+ * the `server'. Returns TRUE if the deletion were successful.
+ *
+ ***/
+bool silc_client_del_server(SilcClient client, SilcClientConnection conn,
+ SilcServerEntry server);
/* Command management (command.c) */
* char *cipher,
* unsigned char *key,
* uint32 key_len,
- * int generate_key);
+ * bool generate_key,
+ * bool responder);
*
* DESCRIPTION
*
* requirements of the SILC protocol are met. The API, however, allows
* to allocate any cipher.
*
+ * If `responder' is TRUE then the sending and receiving keys will be
+ * set according the client being the receiver of the private key. If
+ * FALSE the client is being the sender (or negotiator) of the private
+ * 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.
char *cipher,
unsigned char *key,
uint32 key_len,
- int generate_key);
+ bool generate_key,
+ bool responder);
/****f* silcclient/SilcClientAPI/silc_client_add_private_message_key_ske
*
*
* DESCRIPTION
*
- * Same as above but takes the key material from the SKE key material
- * structure. This structure is received if the application uses the
- * silc_client_send_key_agreement to negotiate the key material. The
- * `cipher' SHOULD be provided as it is negotiated also in the SKE
- * protocol.
+ * Same as silc_client_add_private_message_key but takes the key material
+ * from the SKE key material structure. This structure is received if
+ * the application uses the silc_client_send_key_agreement to negotiate
+ * the key material. The `cipher' SHOULD be provided as it is negotiated
+ * also in the SKE protocol.
*
***/
int silc_client_add_private_message_key_ske(SilcClient client,
SilcClientConnection conn,
SilcClientEntry client_entry,
char *cipher,
- SilcSKEKeyMaterial *key);
+ SilcSKEKeyMaterial *key,
+ bool responder);
/****f* silcclient/SilcClientAPI/silc_client_send_private_message_key
*
SilcClientConnection conn,
uint32 *key_count);
-/****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys
+/****f* silcclient/SilcClientAPI/silc_client_free_private_message_keys
*
* SYNOPSIS
*
* If remote side decides to ignore the request the `completion' will be
* called after the specified timeout, `timeout_secs'.
*
+ * NOTE: If the `hostname' and the `port' was not provided the `completion'
+ * will not be called at all since this does nothing more than sending
+ * a packet to the remote host.
+ *
* NOTE: There can be only one active key agreement for one client entry.
* Before setting new one, the old one must be finished (it is finished
* after calling the completion callback) or the function
SilcClientConnection conn,
char *message);
+
+/****f* silcclient/SilcClientAPI/SilcConnectionAuthRequest
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcConnectionAuthRequest)(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcAuthMethod auth_meth,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Connection authentication method request callback. This is called
+ * by the client library after it has received the authentication method
+ * that the application requested by calling the function
+ * silc_client_request_authentication_method.
+ *
+ ***/
+typedef void (*SilcConnectionAuthRequest)(SilcClient client,
+ SilcClientConnection conn,
+ SilcAuthMethod auth_meth,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_request_authentication_method
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_client_request_authentication_method(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcConnectionAuthRequest
+ * callback,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * This function can be used to request the current authentication method
+ * from the server. This may be called when connecting to the server
+ * and the client library requests the authentication data from the
+ * application. If the application does not know the current authentication
+ * method it can request it from the server using this function.
+ * The `callback' with `context' will be called after the server has
+ * replied back with the current authentication method.
+ *
+ ***/
+void
+silc_client_request_authentication_method(SilcClient client,
+ SilcClientConnection conn,
+ SilcConnectionAuthRequest callback,
+ void *context);
+
#endif