X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilcclient%2Fsilcclient.h;h=d87dff84b92f2054edc34d15498df2fa459195e0;hp=8a7bd07d4622fdcfe41f2fbe79546b6abe3e9507;hb=382d15d447b7a95390decfa783836ae4fe255b3d;hpb=b2a16ce70a6acc8352dae8c826028a5184bf6222 diff --git a/lib/silcclient/silcclient.h b/lib/silcclient/silcclient.h index 8a7bd07d..d87dff84 100644 --- a/lib/silcclient/silcclient.h +++ b/lib/silcclient/silcclient.h @@ -179,6 +179,127 @@ struct SilcClientConnectionStruct { }; /***/ +/****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 @@ -262,7 +383,8 @@ typedef struct { * * NAME * - * typedef struct { ... } SilcChannelPrivateKey; + * typedef struct SilcChannelPrivateKeyStruct { ... } + * *SilcChannelPrivateKey; * * DESCRIPTION * @@ -271,13 +393,13 @@ typedef struct { * * 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 @@ -416,7 +538,7 @@ typedef struct { (like it may tell the message is multimedia message). */ void (*channel_message)(SilcClient client, SilcClientConnection conn, SilcClientEntry sender, SilcChannelEntry channel, - SilcMessageFlags flags, + SilcMessagePayload payload, SilcMessageFlags flags, const unsigned char *message, SilcUInt32 message_len); @@ -426,7 +548,8 @@ typedef struct { can be interpreted (like it may tell the message is multimedia message). */ void (*private_message)(SilcClient client, SilcClientConnection conn, - SilcClientEntry sender, SilcMessageFlags flags, + SilcClientEntry sender, SilcMessagePayload payload, + SilcMessageFlags flags, const unsigned char *message, SilcUInt32 message_len); @@ -733,7 +856,7 @@ void silc_client_free(SilcClient client); * * SYNOPSIS * - * int silc_client_init(SilcClient client); + * bool silc_client_init(SilcClient client); * * DESCRIPTION * @@ -742,7 +865,7 @@ void silc_client_free(SilcClient client); * 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 * @@ -832,7 +955,7 @@ typedef struct { * * 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); * @@ -849,9 +972,9 @@ typedef struct { * 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 * @@ -987,7 +1110,7 @@ void silc_client_close_connection(SilcClient client, * SilcMessageFlags flags, * unsigned char *data, * SilcUInt32 data_len, - * int force_send); + * bool_force_send); * * DESCRIPTION * @@ -1004,6 +1127,9 @@ void silc_client_close_connection(SilcClient client, * keys are set then the first key (the key that was added first as * private key) is used. * + * If the `flags' includes SILC_MESSAGE_FLAG_SIGNED the message will be + * digitally signed with the SILC key pair. + * ***/ void silc_client_send_channel_message(SilcClient client, SilcClientConnection conn, @@ -1012,7 +1138,7 @@ void silc_client_send_channel_message(SilcClient client, SilcMessageFlags flags, unsigned char *data, SilcUInt32 data_len, - int force_send); + bool force_send); /****f* silcclient/SilcClientAPI/silc_client_send_private_message * @@ -1024,7 +1150,7 @@ void silc_client_send_channel_message(SilcClient client, * SilcMessageFlags flags, * unsigned char *data, * SilcUInt32 data_len, - * int force_send); + * bool force_send); * * DESCRIPTION * @@ -1036,6 +1162,9 @@ void silc_client_send_channel_message(SilcClient client, * message. The `data' is the private message. If the `force_send' is * TRUE the packet is sent immediately. * + * If the `flags' includes SILC_MESSAGE_FLAG_SIGNED the message will be + * digitally signed with the SILC key pair. + * ***/ void silc_client_send_private_message(SilcClient client, SilcClientConnection conn, @@ -1043,7 +1172,7 @@ void silc_client_send_private_message(SilcClient client, SilcMessageFlags flags, unsigned char *data, SilcUInt32 data_len, - int force_send); + bool force_send); /* Client and Channel entry retrieval (idlist.c) */ @@ -1413,7 +1542,7 @@ SilcChannelUser silc_client_on_channel(SilcChannelEntry channel, * * SYNOPSIS * - * void silc_client_command_call(SilcClient client, + * bool silc_client_command_call(SilcClient client, * SilcClientConnection conn, * const char *command_line, ...); * @@ -1467,6 +1596,8 @@ bool silc_client_command_call(SilcClient client, * 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. @@ -1497,6 +1628,9 @@ void silc_client_command_send(SilcClient client, SilcClientConnection conn, * 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 `callback' will deliver the `context' and + * SilcClientCommandReplyContext which includes the internals of the + * command reply. * * The `ident' is a command identifier which was set for the earlier * sent command. The command reply will include the same identifier @@ -1542,14 +1676,15 @@ 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 * @@ -1558,9 +1693,9 @@ void silc_client_command_pending(SilcClientConnection conn, * 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 @@ -1575,48 +1710,52 @@ void silc_client_command_pending(SilcClientConnection conn, * 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 * @@ -1625,9 +1764,9 @@ int silc_client_add_private_message_key_ske(SilcClient client, * 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 * @@ -1678,14 +1817,14 @@ void silc_client_free_private_message_keys(SilcPrivateMessageKeys 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 * @@ -1719,22 +1858,22 @@ void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys, * 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 * @@ -1743,15 +1882,15 @@ int silc_client_add_channel_private_key(SilcClient client, * 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); @@ -1766,10 +1905,10 @@ int silc_client_del_channel_private_keys(SilcClient client, * 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 * @@ -2173,6 +2312,7 @@ typedef void (*SilcClientFileMonitor)(SilcClient client, * void *monitor_context, * const char *local_ip, * SilcUInt32 local_port, + * bool do_not_bind, * SilcClientEntry client_entry, * const char *filepath); * SilcUInt32 *session_id); @@ -2186,7 +2326,7 @@ typedef void (*SilcClientFileMonitor)(SilcClient client, * 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. * @@ -2194,9 +2334,9 @@ typedef void (*SilcClientFileMonitor)(SilcClient client, * 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 @@ -2211,6 +2351,7 @@ silc_client_file_send(SilcClient client, void *monitor_context, const char *local_ip, SilcUInt32 local_port, + bool do_not_bind, SilcClientEntry client_entry, const char *filepath, SilcUInt32 *session_id); @@ -2378,42 +2519,31 @@ SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...); /* 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"