* Common data
*/
+ /* Current command identifier for a command that was sent last.
+ Application may get the value from this variable to find out the
+ command identifier for last command. */
+ SilcUInt16 cmd_ident;
+
/* User data context. Library does not touch this. Application may
freely set and use this pointer for its needs. */
void *context;
structure. */
SilcSocketConnection sock;
- /* Current command identifier, 0 not used */
- SilcUInt16 cmd_ident;
-
/* Internal data for client library. Application cannot access this
data at all. */
SilcClientConnectionInternal internal;
};
/***/
+/****s* silcclient/SilcClientAPI/SilcClientEntry
+ *
+ * NAME
+ *
+ * typedef struct SilcClientEntryStruct { ... } *SilcClientEntry
+ *
+ * DESCRIPTION
+ *
+ * This structure represents a client or a user in the SILC network.
+ * The local user has this structure also and it can be accessed from
+ * SilcClientConnection structure. All other users in the SILC network
+ * that are accessed using the Client Library routines will have their
+ * own SilcClientEntry structure. For example, when finding users by
+ * their nickname the Client Library returns this structure back to
+ * the application.
+ *
+ * SOURCE
+ */
+struct SilcClientEntryStruct {
+ /* General information */
+ char *nickname; /* nickname */
+ char *username; /* username */
+ char *hostname; /* hostname */
+ char *server; /* SILC server name */
+ char *realname; /* Realname (userinfo) */
+
+ /* Mode, ID and other information */
+ SilcUInt32 mode; /* User mode in SILC */
+ SilcClientID *id; /* The Client ID */
+ SilcDList attrs; /* Requested Attributes (maybe NULL) */
+ unsigned char *fingerprint; /* Fingerprint of client's public key */
+ SilcUInt32 fingerprint_len; /* Length of the fingerprint */
+
+ /* Private message keys */
+ SilcCipher send_key; /* Private message key for sending */
+ SilcCipher receive_key; /* Private message key for receiving */
+ SilcHmac hmac_send; /* Private mesage key HMAC for sending */
+ SilcHmac hmac_receive; /* Private mesage key HMAC for receiving */
+ unsigned char *key; /* Set only if application provided the
+ key material. NULL if the library
+ generated the key. */
+ SilcUInt32 key_len; /* Key length */
+ SilcClientKeyAgreement ke; /* Current key agreement context or NULL */
+
+ /* SilcClientEntry status information */
+ SilcEntryStatus status; /* Status mask */
+ SilcHashTable channels; /* All channels client has joined */
+ SilcUInt16 resolve_cmd_ident; /* Command identifier when resolving */
+ bool generated; /* TRUE if library generated `key' */
+ bool valid; /* FALSE if this entry is not valid */
+};
+/***/
+
+/****s* silcclient/SilcClientAPI/SilcChannelEntry
+ *
+ * NAME
+ *
+ * typedef struct SilcChannelEntryStruct { ... } *SilcChannelEntry
+ *
+ * DESCRIPTION
+ *
+ * This structure represents a channel in the SILC network. All
+ * channels that the client are aware of or have joined in will be
+ * represented as SilcChannelEntry. The structure includes information
+ * about the channel.
+ *
+ * SOURCE
+ */
+struct SilcChannelEntryStruct {
+ /* General information */
+ char *channel_name; /* Channel name */
+ SilcChannelID *id; /* Channel ID */
+ SilcUInt32 mode; /* Channel mode */
+
+ /* All clients that has joined this channel */
+ SilcHashTable user_list;
+
+ /* Channel keys */
+ SilcCipher channel_key; /* The channel key */
+ unsigned char *key; /* Raw key data */
+ SilcUInt32 key_len; /* Raw key data length */
+ unsigned char iv[SILC_CIPHER_MAX_IV_SIZE]; /* Current IV */
+ SilcHmac hmac; /* Current HMAC */
+
+ /* Channel private keys */
+ SilcDList private_keys; /* List of private keys or NULL */
+ SilcChannelPrivateKey curr_key; /* Current private key */
+
+ /* SilcChannelEntry status information */
+ SilcCipher old_channel_key;
+ SilcHmac old_hmac;
+ SilcTask rekey_task;
+ SilcUInt16 resolve_cmd_ident; /* Command identifier when
+ resolving this entry */
+};
+/***/
+
+/****s* silcclient/SilcClientAPI/SilcServerEntry
+ *
+ * NAME
+ *
+ * typedef struct SilcServerEntryStruct { ... } *SilcServerEntry
+ *
+ * DESCRIPTION
+ *
+ * This structure represents a server in the SILC network. All servers
+ * that the client is aware of and have for example resolved with
+ * SILC_COMMAND_INFO command have their on SilcServerEntry structure.
+ *
+ * SOURCE
+ */
+struct SilcServerEntryStruct {
+ /* General information */
+ char *server_name; /* Server name */
+ char *server_info; /* Server info */
+ SilcServerID *server_id; /* Server ID */
+ SilcUInt16 resolve_cmd_ident; /* Command identifier when
+ resolving this entry */
+};
+/***/
+
/****d* silcclient/SilcClientAPI/SilcKeyAgreementStatus
*
* NAME
*
* NAME
*
- * typedef struct { ... } SilcChannelPrivateKey;
+ * typedef struct SilcChannelPrivateKeyStruct { ... }
+ * *SilcChannelPrivateKey;
*
* DESCRIPTION
*
*
* SOURCE
*/
-typedef struct SilcChannelPrivateKeyStruct {
+struct SilcChannelPrivateKeyStruct {
char *name; /* Application given name */
SilcCipher cipher; /* The cipher and key */
SilcHmac hmac; /* The HMAC and hmac key */
unsigned char *key; /* The key data */
SilcUInt32 key_len; /* The key length */
-} *SilcChannelPrivateKey;
+};
/***/
/****f* silcclient/SilcClientAPI/SilcAskPassphrase
*
* SYNOPSIS
*
- * int silc_client_init(SilcClient client);
+ * bool silc_client_init(SilcClient client);
*
* DESCRIPTION
*
* client. Returns FALSE if error occurred, TRUE otherwise.
*
***/
-int silc_client_init(SilcClient client);
+bool silc_client_init(SilcClient client);
/****f* silcclient/SilcClientAPI/silc_client_run
*
*
* SYNOPSIS
*
- * int silc_client_connect_to_server(SilcClient client,
+ * bool silc_client_connect_to_server(SilcClient client,
* SilcClientConnectionParams *params,
* int port, char *host, void *context);
*
* If the `params' is provided they are used by the routine.
*
***/
-int silc_client_connect_to_server(SilcClient client,
- SilcClientConnectionParams *params,
- int port, char *host, void *context);
+bool silc_client_connect_to_server(SilcClient client,
+ SilcClientConnectionParams *params,
+ int port, char *host, void *context);
/****f* silcclient/SilcClientAPI/silc_client_add_connection
*
* SilcMessageFlags flags,
* unsigned char *data,
* SilcUInt32 data_len,
- * int force_send);
+ * bool_force_send);
*
* DESCRIPTION
*
SilcMessageFlags flags,
unsigned char *data,
SilcUInt32 data_len,
- int force_send);
+ bool force_send);
/****f* silcclient/SilcClientAPI/silc_client_send_private_message
*
* SilcMessageFlags flags,
* unsigned char *data,
* SilcUInt32 data_len,
- * int force_send);
+ * bool force_send);
*
* DESCRIPTION
*
SilcMessageFlags flags,
unsigned char *data,
SilcUInt32 data_len,
- int force_send);
+ bool force_send);
/* Client and Channel entry retrieval (idlist.c) */
/* Command management (command.c) */
-/****f* silcclient/SilcClientAPI/silc_client_command_alloc
- *
- * SYNOPSIS
- *
- * SilcClientCommandContext silc_client_command_alloc(void);
- *
- * DESCRIPTION
- *
- * Allocate Command Context. The context is defined in `command.h' file.
- * The context is used by the library commands and applications should use
- * it as well. However, application may choose to use some own context
- * for its local commands. All library commands, however, must use this
- * context.
- *
- ***/
-SilcClientCommandContext silc_client_command_alloc(void);
-
-/****f* silcclient/SilcClientAPI/silc_client_command_free
- *
- * SYNOPSIS
- *
- * void silc_client_command_free(SilcClientCommandContext ctx);
- *
- * DESCRIPTION
- *
- * Free command context and its internals. If the contex was duplicated
- * with silc_client_command_dup this may not actually free the data,
- * instead it will decrease the reference counter of the context. The
- * context will be freed when the reference counter hits zero.
- *
- ***/
-void silc_client_command_free(SilcClientCommandContext ctx);
-
-/****f* silcclient/SilcClientAPI/silc_client_command_dup
- *
- * SYNOPSIS
- *
- * SilcClientCommandContext
- * silc_client_command_dup(SilcClientCommandContext ctx);
- *
- * DESCRIPTION
- *
- * Duplicate Command Context by adding reference counter. The context won't
- * be free'd untill it hits zero.
- *
- ***/
-SilcClientCommandContext silc_client_command_dup(SilcClientCommandContext ctx);
-
-/****f* silcclient/SilcClientAPI/silc_client_command_find
+/****f* silcclient/SilcClientAPI/silc_client_command_call
*
* SYNOPSIS
*
- * SilcClientCommand silc_client_command_find(SilcClient client,
- * const char *name);
+ * bool silc_client_command_call(SilcClient client,
+ * SilcClientConnection conn,
+ * const char *command_line, ...);
*
* DESCRIPTION
*
- * Finds and returns a pointer to the command list. Return NULL if the
- * command is not found. See the `command.[ch]' for the command list.
- * Command names are not case-sensitive.
- *
- ***/
-SilcClientCommand silc_client_command_find(SilcClient client,
- const char *name);
-
-/****f* silcclient/SilcClientAPI/silc_client_command_call
+ * Calls and executes the command indicated by the `command_name'.
+ * The `command_line' is a string which includes the command's name and
+ * its arguments separated with whitespaces (' '). If `command_line'
+ * is non-NULL then all variable arguments are ignored by default.
*
- * SYNOPSIS
+ * If `command_line' is NULL, then the variable arguments define the
+ * command's name and its arguments. The first variable argument must
+ * be the command name. The variable argument list must be terminated
+ * with NULL.
*
- * void silc_client_command_call(SilcClientCommand command);
+ * Returns FALSE if the command is not known and TRUE after command.
+ * execution. The "command" client operation is called when the
+ * command is executed to indicate whether the command executed
+ * successfully or not.
*
- * DESCRIPTION
+ * The "command_reply" client operation will be called when reply is
+ * received from the server to the command. Application may also use
+ * the silc_client_command_pending to attach to the command reply.
+ * The command identifier for silc_client_command_pending function after
+ * this function call is conn->cmd_ident, which application may use.
*
- * Calls the command (executes it). Application can call this after
- * it has allocated the SilcClientCommandContext with the function
- * silc_client_command_alloc and found the command from the client
- * library by calling silc_client_command_find. This will execute
- * the command.
+ * EXAMPLE
*
- * Application can call the command function directly too if it
- * wishes to do so. See the command.h for details of the
- * SilcClientCommand structure.
+ * silc_client_command_call(client, conn, NULL, "PING", "silc.silcnet.org",
+ * NULL);
+ * silc_client_command_call(client, conn, "PING silc.silcnet.org");
*
***/
-void silc_client_command_call(SilcClientCommand command,
- SilcClientCommandContext cmd);
+bool silc_client_command_call(SilcClient client,
+ SilcClientConnection conn,
+ const char *command_line, ...);
/****f* silcclient/SilcClientAPI/silc_client_command_send
*
* to perform the commands by itself, it can do so and send the data
* directly to the server using this function. If application is using
* the silc_client_command_call, this function is usually not used.
+ * Note that this overriders the Client Librarys commands and sends
+ * the command packet directly to server.
*
* The variable arguments are a pair of { type, data, data_length },
* and the `argc' is the number of these pairs.
*
* DESCRIPTION
*
- * Add new pending command to be executed when reply to a command has been
- * received. The `reply_cmd' is the command that will call the `callback'
- * with `context' when reply has been received. If `ident' is non-zero
- * the `callback' will be executed when received reply with command
- * identifier `ident'.
+ * This function can be used to add pending command callback to be
+ * called when an command reply is received to an earlier sent command.
+ * The `reply_cmd' is the command that must be received in order for
+ * the pending command callback indicated by `callback' to be called.
+ *
+ * The `ident' is a command identifier which was set for the earlier
+ * sent command. The command reply will include the same identifier
+ * and pending command callback will be called when the reply is
+ * received with the same command identifier. It is possible to
+ * add multiple pending command callbacks for same command and for
+ * same identifier.
*
- * Note that the application is notified about the received command
+ * Application may use this function to add its own command reply
+ * handlers if it wishes not to use the standard `command_reply'
+ * client operation. However, note that the pending command callback
+ * does not deliver parsed command reply, but application must parse
+ * it itself.
+ *
+ * Note also that the application is notified about the received command
* reply through the `command_reply' client operation before calling
- * the `callback` pending command callback.
+ * the `callback` pending command callback. That is the normal
+ * command reply handling, and is called regardless whether pending
+ * command callbacks are used or not.
+ *
+ * Commands that application calls with silc_client_command_call
+ * will use a command identifier from conn->cmd_ident variable. After
+ * calling the silc_client_command_call, the conn->cmd_ident includes
+ * the command identifier that was used for the command sending.
+ *
+ * EXAMPLE
+ *
+ * silc_client_command_call(client, conn, "PING silc.silcnet.org");
+ * silc_client_command_pending(conn, SILC_COMMAND_PING, conn->cmd_ident,
+ * my_ping_handler, my_ping_context);
*
***/
void silc_client_command_pending(SilcClientConnection conn,
*
* SYNOPSIS
*
- * int silc_client_add_private_message_key(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry,
- * char *cipher,
- * unsigned char *key,
- * SilcUInt32 key_len,
- * bool generate_key,
- * bool responder);
+ * bool silc_client_add_private_message_key(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * const char *cipher,
+ * const char *hmac,
+ * unsigned char *key,
+ * SilcUInt32 key_len,
+ * bool generate_key,
+ * bool responder);
*
* DESCRIPTION
*
* indicated by the `client_entry'. If the `key' is NULL and the boolean
* value `generate_key' is TRUE the library will generate random key.
* The `key' maybe for example pre-shared-key, passphrase or similar.
- * The `cipher' MAY be provided but SHOULD be NULL to assure that the
- * requirements of the SILC protocol are met. The API, however, allows
- * to allocate any cipher.
+ * The `cipher' and `hmac' MAY be provided but SHOULD be NULL to assure
+ * that the requirements of the SILC protocol are met. The API, however,
+ * allows to allocate any cipher and HMAC.
*
* If `responder' is TRUE then the sending and receiving keys will be
* set according the client being the receiver of the private key. If
* otherwise.
*
***/
-int silc_client_add_private_message_key(SilcClient client,
- SilcClientConnection conn,
- SilcClientEntry client_entry,
- char *cipher,
- unsigned char *key,
- SilcUInt32 key_len,
- bool generate_key,
- bool responder);
+bool silc_client_add_private_message_key(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ const char *cipher,
+ const char *hmac,
+ unsigned char *key,
+ SilcUInt32 key_len,
+ bool generate_key,
+ bool responder);
/****f* silcclient/SilcClientAPI/silc_client_add_private_message_key_ske
*
* SYNOPSIS
*
- * int silc_client_add_private_message_key_ske(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry,
- * char *cipher,
- * SilcSKEKeyMaterial *key);
+ * bool
+ * silc_client_add_private_message_key_ske(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * const char *cipher,
+ * const char *hmac,
+ * SilcSKEKeyMaterial *key);
*
* DESCRIPTION
*
* 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.
+ * the key material. The `cipher' and `hmac' 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,
- bool responder);
+bool silc_client_add_private_message_key_ske(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ const char *cipher,
+ const char *hmac,
+ SilcSKEKeyMaterial *key,
+ bool responder);
/****f* silcclient/SilcClientAPI/silc_client_del_private_message_key
*
* SYNOPSIS
*
- * int silc_client_del_private_message_key(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry);
+ * bool silc_client_del_private_message_key(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry);
*
* DESCRIPTION
*
* client. Returns FALSE on error, TRUE otherwise.
*
***/
-int silc_client_del_private_message_key(SilcClient client,
- SilcClientConnection conn,
- SilcClientEntry client_entry);
+bool silc_client_del_private_message_key(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry);
/****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys
*
*
* SYNOPSIS
*
- * int silc_client_add_channel_private_key(SilcClient client,
- * SilcClientConnection conn,
- * SilcChannelEntry channel,
- * const char *name,
- * char *cipher,
- * char *hmac,
- * unsigned char *key,
- * SilcUInt32 key_len);
+ * bool silc_client_add_channel_private_key(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelEntry channel,
+ * const char *name,
+ * char *cipher,
+ * char *hmac,
+ * unsigned char *key,
+ * SilcUInt32 key_len);
*
* DESCRIPTION
*
* as channel private key. However, this API allows it.
*
***/
-int silc_client_add_channel_private_key(SilcClient client,
- SilcClientConnection conn,
- SilcChannelEntry channel,
- const char *name,
- char *cipher,
- char *hmac,
- unsigned char *key,
- SilcUInt32 key_len);
+bool silc_client_add_channel_private_key(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelEntry channel,
+ const char *name,
+ char *cipher,
+ char *hmac,
+ unsigned char *key,
+ SilcUInt32 key_len);
/****f* silcclient/SilcClientAPI/silc_client_del_channel_private_keys
*
* SYNOPSIS
*
- * int silc_client_del_channel_private_keys(SilcClient client,
- * SilcClientConnection conn,
- * SilcChannelEntry channel);
+ * bool silc_client_del_channel_private_keys(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelEntry channel);
*
* DESCRIPTION
*
* on error, TRUE otherwise.
*
***/
-int silc_client_del_channel_private_keys(SilcClient client,
- SilcClientConnection conn,
- SilcChannelEntry channel);
+bool silc_client_del_channel_private_keys(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelEntry channel);
/****f* silcclient/SilcClientAPI/silc_client_del_channel_private_key
*
* SYNOPSIS
*
- * int silc_client_del_channel_private_key(SilcClient client,
+ * bool silc_client_del_channel_private_key(SilcClient client,
* SilcClientConnection conn,
* SilcChannelEntry channel,
* SilcChannelPrivateKey key);
* on error, TRUE otherwise.
*
***/
-int silc_client_del_channel_private_key(SilcClient client,
- SilcClientConnection conn,
- SilcChannelEntry channel,
- SilcChannelPrivateKey key);
+bool silc_client_del_channel_private_key(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelEntry channel,
+ SilcChannelPrivateKey key);
/****f* silcclient/SilcClientAPI/silc_client_list_channel_private_keys
*
* void *monitor_context,
* const char *local_ip,
* SilcUInt32 local_port,
+ * bool do_not_bind,
* SilcClientEntry client_entry,
* const char *filepath);
* SilcUInt32 *session_id);
* transmission of the file.
*
* This returns a file session ID for the file transmission to the
- * `session_id' pointer.. It can be used to close the session (and
+ * `session_id' pointer. It can be used to close the session (and
* abort the file transmission) by calling the silc_client_file_close
* function. The session ID is also returned in the `monitor' callback.
*
* listener for key exchange protocol to that IP. If `local_port' is
* non-zero that port is used. If `local_ip' is NULL then this will
* automatically attempt to bind it to local IP address of the machine.
- * If that fails then this does not bind to any address and port, and
- * assume that the remote client will provide the listener for the
- * key exchange protocol.
+ * If `do_not_bind' is TRUE then the `local_ip' and `local_port' are
+ * ignored and it is expected that the receiver will provide the
+ * point of contact. This is usefull if the sender is behind NAT.
*
* If error will occur during the file transfer process the error
* status will be returned in the monitor callback. In this case
void *monitor_context,
const char *local_ip,
SilcUInt32 local_port,
+ bool do_not_bind,
SilcClientEntry client_entry,
const char *filepath,
SilcUInt32 *session_id);
/* Low level packet sending functions */
-/****f* silcclient/SilcClientAPI/silc_client_packet_send
+/****f* silcclient/SilcClientAPI/silc_client_send_packet
*
* SYNOPSIS
*
- * void silc_client_packet_send(SilcClient client,
- * SilcSocketConnection sock,
- * SilcPacketType type,
- * void *dst_id,
- * SilcIdType dst_id_type,
- * SilcCipher cipher,
- * SilcHmac hmac,
- * unsigned char *data,
- * SilcUInt32 data_len,
- * bool force_send);
+ * bool silc_client_send_packet(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcPacketType type,
+ * const unsigned char *data,
+ * SilcUInt32 data_len);
*
* DESCRIPTION
*
- * Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
- * then all attributes are requested. Alternatively, `attribute' and
- * all variable arguments can each be requested attribute. In this case
- * the last must be set to zero (0) to complete the variable list of
- * requested attributes. See SilcAttribute for all attributes.
- * You can give the returned buffer as argument to for example
- * silc_client_get_client_by_id_resolve function.
+ * This routine can be used by application to send packets directly
+ * to a connection indicated by `conn'. Usually application does not
+ * need this routine since the Client Library handles the packet
+ * sending. The `type' indicates the packet type. If `data' is
+ * NULL then empty packet is sent. This returns FALSE if packet cannot
+ * be sent.
*
***/
-void silc_client_packet_send(SilcClient client,
- SilcSocketConnection sock,
+bool silc_client_send_packet(SilcClient client,
+ SilcClientConnection conn,
SilcPacketType type,
- void *dst_id,
- SilcIdType dst_id_type,
- SilcCipher cipher,
- SilcHmac hmac,
- unsigned char *data,
- SilcUInt32 data_len,
- bool force_send);
+ const unsigned char *data,
+ SilcUInt32 data_len);
#include "command.h"
#include "command_reply.h"