From: Pekka Riikonen Date: Fri, 1 Jun 2001 22:02:28 +0000 (+0000) Subject: updates X-Git-Tag: 1.2.beta1~2225 X-Git-Url: http://git.silcnet.org/gitweb/?a=commitdiff_plain;h=89329650d986e09749d9c6a039797aaccfb30f27;p=crypto.git updates --- diff --git a/CHANGES b/CHANGES index aa26761d..1942c338 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,26 @@ +Fri Jun 1 22:19:37 EEST 2001 Pekka Riikonen + + * Added checking to the server code not to start the server if + ciphers and stuff are not configured properly. Affected files + silcd/serverconfig.[h] and silcd/server.c. + + * Changed the layout of the header files of the public interfaces + in the SILC libraries. The new layout supports ROBODoc + documentation tool (and some others) so that it is easy to create + a library reference manual. All the other headers and source + code must still follow the CodingStyle document. Also source + code must not include these ROBODoc stuffs, only the headers. + Furthermore, all public interface headers must now be named + by using `silc' prefix, example: silcapi.h, silccipher.h. + Some files were renamed due to this. All the other headers + must not be used as public interfaces. I will update the + CodingStyle document later. Changed following headers, so far: + + lib/silcclient/silcapi.h + lib/silccore/silcauth.h + lib/silccore/silcprivate.h + lib/silccrypt/silcdh.h + Fri Jun 1 10:28:09 EEST 2001 Pekka Riikonen * Updated TODO. diff --git a/apps/silcd/server.c b/apps/silcd/server.c index da3f7df4..56d107c0 100644 --- a/apps/silcd/server.c +++ b/apps/silcd/server.c @@ -145,10 +145,14 @@ int silc_server_init(SilcServer server) silc_server_config_setlogfiles(server->config); /* Register all configured ciphers, PKCS and hash functions. */ - silc_server_config_register_ciphers(server->config); - silc_server_config_register_pkcs(server->config); - silc_server_config_register_hashfuncs(server->config); - silc_server_config_register_hmacs(server->config); + if (!silc_server_config_register_ciphers(server->config)) + silc_cipher_register_default(); + if (!silc_server_config_register_pkcs(server->config)) + silc_pkcs_register_default(); + if (!silc_server_config_register_hashfuncs(server->config)) + silc_hash_register_default(); + if (!silc_server_config_register_hmacs(server->config)) + silc_hmac_register_default(); /* Initialize random number generator for the server. */ server->rng = silc_rng_alloc(); diff --git a/apps/silcd/serverconfig.c b/apps/silcd/serverconfig.c index b0f3b1db..894d4fd3 100644 --- a/apps/silcd/serverconfig.c +++ b/apps/silcd/serverconfig.c @@ -1220,13 +1220,16 @@ void silc_server_config_setlogfiles(SilcServerConfig config) /* Registers configured ciphers. These can then be allocated by the server when needed. */ -void silc_server_config_register_ciphers(SilcServerConfig config) +bool silc_server_config_register_ciphers(SilcServerConfig config) { SilcServerConfigSectionAlg *alg; SilcServer server = (SilcServer)config->server; SILC_LOG_DEBUG(("Registering configured ciphers")); + if (!config->cipher) + return FALSE; + alg = config->cipher; while(alg) { @@ -1303,17 +1306,22 @@ void silc_server_config_register_ciphers(SilcServerConfig config) alg = alg->next; } + + return TRUE; } /* Registers configured PKCS's. */ -void silc_server_config_register_pkcs(SilcServerConfig config) +bool silc_server_config_register_pkcs(SilcServerConfig config) { SilcServerConfigSectionAlg *alg = config->pkcs; SilcServer server = (SilcServer)config->server; SILC_LOG_DEBUG(("Registering configured PKCS")); + if (!config->pkcs) + return FALSE; + while(alg) { int i; @@ -1331,18 +1339,23 @@ void silc_server_config_register_pkcs(SilcServerConfig config) alg = alg->next; } + + return TRUE; } /* Registers configured hash functions. These can then be allocated by the server when needed. */ -void silc_server_config_register_hashfuncs(SilcServerConfig config) +bool silc_server_config_register_hashfuncs(SilcServerConfig config) { SilcServerConfigSectionAlg *alg; SilcServer server = (SilcServer)config->server; SILC_LOG_DEBUG(("Registering configured hash functions")); + if (!config->hash_func) + return FALSE; + alg = config->hash_func; while(alg) { @@ -1409,24 +1422,22 @@ void silc_server_config_register_hashfuncs(SilcServerConfig config) alg = alg->next; } + + return TRUE; } /* Registers configure HMACs. These can then be allocated by the server when needed. */ -void silc_server_config_register_hmacs(SilcServerConfig config) +bool silc_server_config_register_hmacs(SilcServerConfig config) { SilcServerConfigSectionAlg *alg; SilcServer server = (SilcServer)config->server; SILC_LOG_DEBUG(("Registering configured HMACs")); - if (!config->hmac) { - SILC_LOG_ERROR(("HMACs are not configured. SILC cannot work without " - "HMACs")); - silc_server_stop(server); - exit(1); - } + if (!config->hmac) + return FALSE; alg = config->hmac; while(alg) { @@ -1446,6 +1457,8 @@ void silc_server_config_register_hmacs(SilcServerConfig config) alg = alg->next; } + + return TRUE; } /* Returns client authentication information from server configuration diff --git a/apps/silcd/serverconfig.h b/apps/silcd/serverconfig.h index e8ced3e0..f6612d4d 100644 --- a/apps/silcd/serverconfig.h +++ b/apps/silcd/serverconfig.h @@ -257,10 +257,10 @@ int silc_server_config_parse_lines(SilcServerConfig config, SilcServerConfigParse parse_config); int silc_server_config_check_sections(uint32 checkmask); void silc_server_config_setlogfiles(SilcServerConfig config); -void silc_server_config_register_ciphers(SilcServerConfig config); -void silc_server_config_register_pkcs(SilcServerConfig config); -void silc_server_config_register_hashfuncs(SilcServerConfig config); -void silc_server_config_register_hmacs(SilcServerConfig config); +bool silc_server_config_register_ciphers(SilcServerConfig config); +bool silc_server_config_register_pkcs(SilcServerConfig config); +bool silc_server_config_register_hashfuncs(SilcServerConfig config); +bool silc_server_config_register_hmacs(SilcServerConfig config); SilcServerConfigSectionClientConnection * silc_server_config_find_client_conn(SilcServerConfig config, char *host, int port); diff --git a/includes/silcincludes.h b/includes/silcincludes.h index c19b4971..9868f727 100644 --- a/includes/silcincludes.h +++ b/includes/silcincludes.h @@ -214,8 +214,8 @@ typedef uint32 * void *; #include "silcschedule.h" /* SILC core library includes */ -#include "id.h" -#include "idcache.h" +#include "silcid.h" +#include "silcidcache.h" #include "silcprotocol.h" #include "silcsockconn.h" #include "silcpayload.h" diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h index 239078cd..06704abd 100644 --- a/lib/silcclient/silcapi.h +++ b/lib/silcclient/silcapi.h @@ -1,57 +1,104 @@ -/* - - silcapi.h - - Author: Pekka Riikonen - - Copyright (C) 2000 - 2001 Pekka Riikonen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -*/ +/****h* silcclient/silcapi.h + * + * NAME + * + * silcapi.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 2000 - 2001 Pekka Riikonen + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * DESCRIPTION + * + * 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. + * + * o 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. + * + * o 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. + * + * Please, refer to the README file in this directory for the directions + * of how to use the SILC Client Library. + * + ***/ #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. -*/ - /* General definitions */ -/* Key agreement status types indicating the status of the protocol. */ +/****d* silcclient/SilcClientAPI/SilcKeyAgreementStatus + * + * NAME + * + * SilcKeyAgreementStatus + * + * DESCRIPTION + * + * Key agreement status types indicating the status of the key + * agreement protocol. These types are returned to the application + * in the SilcKeyAgreementCallback callback function. + * + * SOURCE + */ typedef enum { SILC_KEY_AGREEMENT_OK, /* Everything is Ok */ SILC_KEY_AGREEMENT_ERROR, /* Unknown error occurred */ SILC_KEY_AGREEMENT_FAILURE, /* The protocol failed */ SILC_KEY_AGREEMENT_TIMEOUT, /* The protocol timeout */ } SilcKeyAgreementStatus; - -/* Key agreement callback that is called after the key agreement protocol - has been performed. This is called also if error occurred during the - key agreement protocol. The `key' is the allocated key material and - the caller is responsible of freeing it. The `key' is NULL if error - has occurred. The application can freely use the `key' to whatever - purpose it needs. See lib/silcske/silcske.h for the definition of - the SilcSKEKeyMaterial structure. */ +/***/ + +/****f* silcclient/SilcClientAPI/SilcKeyAgreementCallback + * + * SYNOPSIS + * + * typedef void (*SilcKeyAgreementCallback)(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * SilcKeyAgreementStatus status, + * SilcSKEKeyMaterial *key, + * void *context); + * + * DESCRIPTION + * + * Key agreement callback that is called after the key agreement protocol + * has been performed. This is called also if error occurred during the + * key agreement protocol. The `key' is the allocated key material and + * the caller is responsible of freeing it. The `key' is NULL if error + * has occurred. The application can freely use the `key' to whatever + * purpose it needs. See lib/silcske/silcske.h for the definition of + * the SilcSKEKeyMaterial structure. + * + ***/ typedef void (*SilcKeyAgreementCallback)(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry, @@ -59,9 +106,20 @@ typedef void (*SilcKeyAgreementCallback)(SilcClient client, SilcSKEKeyMaterial *key, void *context); -/* 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. */ +/****s* silcclient/SilcClientAPI/SilcPrivateMessageKeys + * + * NAME + * + * SilcPrivateMessageKeys + * + * DESCRIPTION + * + * 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. + * + * SOURCE + */ typedef struct { SilcClientEntry client_entry; /* The remote client entry */ char *cipher; /* The cipher name */ @@ -71,32 +129,58 @@ typedef struct { the SKE key material was used. */ uint32 key_len; /* The key length */ } *SilcPrivateMessageKeys; - -/****************************************************************************** - - 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. - -******************************************************************************/ - -/* Ask passphrase callback. This is called by the application when the - library calls `ask_passphrase' client operation. The callback delivers - the passphrase to the library. */ +/***/ + + +/****f* silcclient/SilcClientAPI/SilcAskPassphrase + * + * SYNOPSIS + * + * typedef void (*SilcAskPassphrase)(unsigned char *passphrase, + * uint32 passphrase_len, + * void *context); + * + * DESCRIPTION + * + * Ask passphrase callback. This is called by the application when the + * library calls `ask_passphrase' client operation. The callback delivers + * the passphrase to the library. + * + ***/ typedef void (*SilcAskPassphrase)(unsigned char *passphrase, uint32 passphrase_len, void *context); -/* Public key (or certificate) verification callback. This is called - by the application to indicate that the public key verification was - either success or failure. */ +/****f* silcclient/SilcClientAPI/SilcVerifyPublicKey + * + * SYNOPSIS + * + * typedef void (*SilcVerifyPublicKey)(bool success, void *context); + * + * DESCRIPTION + * + * Public key (or certificate) verification callback. This is called + * by the application to indicate that the public key verification was + * either success or failure. + * + ***/ typedef void (*SilcVerifyPublicKey)(bool success, void *context); -/* SILC Client Operations. These must be implemented by the application. */ +/****s* silcclient/SilcClientAPI/SilcClientOperations + * + * NAME + * + * SilcClientOperations + * + * DESCRIPTION + * + * SILC Client Operations. These must be implemented by the application. + * The Client library may call any of these routines at any time. The + * routines are used to deliver certain information to the application + * or from the application to the client library. + * + * SOURCE + */ typedef struct { /* Message sent to the application by library. `conn' associates the message to a specific connection. `conn', however, may be NULL. */ @@ -214,96 +298,225 @@ typedef struct { SilcKeyAgreementCallback *completion, void **context); } 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 (client.c) */ -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_alloc + * + * SYNOPSIS + * + * SilcClient silc_client_alloc(SilcClientOperations *ops, + * void *application); + * + * 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. + * + ***/ SilcClient silc_client_alloc(SilcClientOperations *ops, void *application); -/* Frees client object and its internals. */ +/****f* silcclient/SilcClientAPI/silc_client_free + * + * SYNOPSIS + * + * void silc_client_free(SilcClient client); + * + * DESCRIPTION + * + * Frees client object and its internals. The execution of the client + * should be stopped with silc_client_stop function before calling + * this function. + * + ***/ 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 occurred, TRUE otherwise. */ +/****f* silcclient/SilcClientAPI/silc_client_init + * + * SYNOPSIS + * + * int silc_client_init(SilcClient client); + * + * DESCRIPTION + * + * 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 occurred, 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. */ +/****f* silcclient/SilcClientAPI/silc_client_run + * + * SYNOPSIS + * + * void silc_client_run(SilcClient client); + * + * DESCRIPTION + * + * 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. */ +/****f* silcclient/SilcClientAPI/silc_client_stop + * + * SYNOPSIS + * + * void silc_client_stop(SilcClient client); + * + * DESCRIPTION + * + * Stops the client. This is called to stop the client and thus to stop + * the program. The client context must be freed with the silc_client_free + * function. + * + ***/ void silc_client_stop(SilcClient client); /* Connecting functions (client.c) */ -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_connect_to_server + * + * SYNOPSIS + * + * int silc_client_connect_to_server(SilcClient client, int port, + * char *host, void *context); + * + * DESCRIPTION + * + * 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. */ +/****f* silcclient/SilcClientAPI/silc_client_add_connection + * + * SYNOPSIS + * + * SilcClientConnection silc_client_add_connection(SilcClient client, + * char *hostname, + * int port, + * void *context); + * + * DESCRIPTION + * + * 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. */ +/****f* silcclient/SilcClientAPI/silc_client_del_connection + * + * SYNOPSIS + * + * void silc_client_del_connection(SilcClient client, + * SilcClientConnection conn); + * + * DESCRIPTION + * + * Removes connection from client. Frees all memory. The library + * call this function automatically for all connection contexts. + * The application however may free the connection contexts it has + * allocated. + * + ***/ void silc_client_del_connection(SilcClient client, SilcClientConnection conn); -/* Adds listener socket to the listener sockets table. This function is - used to add socket objects that are listeners to the client. This should - not be used to add other connection objects. */ +/****f* silcclient/SilcClientAPI/silc_client_add_socket + * + * SYNOPSIS + * + * void silc_client_add_socket(SilcClient client, + * SilcSocketConnection sock); + * + * DESCRIPTION + * + * Adds listener socket to the listener sockets table. This function is + * used to add socket objects that are listeners to the client. This should + * not be used to add other connection objects. + * + ***/ void silc_client_add_socket(SilcClient client, SilcSocketConnection sock); -/* Deletes listener socket from the listener sockets table. */ +/****f* silcclient/SilcClientAPI/silc_client_del_socket + * + * SYNOPSIS + * + * void silc_client_del_socket(SilcClient client, + * SilcSocketConnection sock); + * + * DESCRIPTION + * + * Deletes listener socket from the listener sockets table. If the + * application has added a socket with silc_client_add_socket it must + * also free it using this function. + * + ***/ void silc_client_del_socket(SilcClient client, SilcSocketConnection sock); -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_start_key_exchange + * + * SYNOPSIS + * + * int silc_client_start_key_exchange(SilcClient client, + * SilcClientConnection conn, + * int fd); + * + * DESCRIPTION + * + * 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. - If the `sock' is NULL then the conn->sock will be used. If `sock' is - provided it will be checked whether the sock and `conn->sock' are the - same (they can be different, ie. a socket can use `conn' as its - connection but `conn->sock' might be actually a different connection - than the `sock'). */ +/****f* silcclient/SilcClientAPI/silc_client_close_connection + * + * SYNOPSIS + * + * void silc_client_close_connection(SilcClient client, + * SilcSocketConnection sock, + * SilcClientConnection conn); + * + * DESCRIPTION + * + * Closes connection to remote end. Free's all allocated data except + * for some information such as nickname etc. that are valid at all time. + * If the `sock' is NULL then the conn->sock will be used. If `sock' is + * provided it will be checked whether the sock and `conn->sock' are the + * same (they can be different, ie. a socket can use `conn' as its + * connection but `conn->sock' might be actually a different connection + * than the `sock'). + * + ***/ void silc_client_close_connection(SilcClient client, SilcSocketConnection sock, SilcClientConnection conn); @@ -311,18 +524,35 @@ void silc_client_close_connection(SilcClient client, /* Message sending functions (client_channel.c and client_prvmsg.c) */ -/* 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. - - If `key' is provided then that private key is used to encrypt the - channel message. If it is not provided, private keys has not been - set at all, the normal channel key is used automatically. If private - keys are set then the first key (the key that was added first as - private key) is used. */ +/****f* silcclient/SilcClientAPI/silc_client_send_channel_message + * + * SYNOPSIS + * + * void silc_client_send_channel_message(SilcClient client, + * SilcClientConnection conn, + * SilcChannelEntry channel, + * SilcChannelPrivateKey key, + * SilcMessageFlags flags, + * unsigned char *data, + * uint32 data_len, + * int force_send); + * + * DESCRIPTION + * + * 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. + * + * If `key' is provided then that private key is used to encrypt the + * channel message. If it is not provided, private keys has not been + * set at all, the normal channel key is used automatically. If private + * keys are set then the first key (the key that was added first as + * private key) is used. + * + ***/ void silc_client_send_channel_message(SilcClient client, SilcClientConnection conn, SilcChannelEntry channel, @@ -332,13 +562,29 @@ void silc_client_send_channel_message(SilcClient client, uint32 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 similar - 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. */ +/****f* silcclient/SilcClientAPI/silc_client_send_private_message + * + * SYNOPSIS + * + * void silc_client_send_private_message(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * SilcMessageFlags flags, + * unsigned char *data, + * uint32 data_len, + * int force_send); + * + * DESCRIPTION + * + * 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 similar + * 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, @@ -350,24 +596,56 @@ void silc_client_send_private_message(SilcClient client, /* Client and Channel entry retrieval (idlist.c) */ -/* 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. */ +/****f* silcclient/SilcClientAPI/SilcGetClientCallback + * + * SYNOPSIS + * + * typedef void (*SilcGetClientCallback)(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry *clients, + * uint32 clients_count, + * void *context); + * + * DESCRIPTION + * + * 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, uint32 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. */ +/****f* silcclient/SilcClientAPI/silc_client_get_clients + * + * SYNOPSIS + * + * void silc_client_get_clients(SilcClient client, + * SilcClientConnection conn, + * char *nickname, + * char *server, + * SilcGetClientCallback completion, + * void *context); + * + * DESCRIPTION + * + * Finds client entry or entries by the `nickname' and `server'. The + * completion callback will be called when the client entries has been + * found. + * + * NOTES + * + * 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, @@ -375,20 +653,50 @@ void silc_client_get_clients(SilcClient client, 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. */ +/****f* silcclient/SilcClientAPI/silc_client_get_clients_local + * + * SYNOPSIS + * + * SilcClientEntry *silc_client_get_clients_local(SilcClient client, + * SilcClientConnection conn, + * char *nickname, + * char *server, + * 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. + * + ***/ SilcClientEntry *silc_client_get_clients_local(SilcClient client, SilcClientConnection conn, char *nickname, char *server, uint32 *clients_count); -/* Gets client entries by the list of client ID's `client_id_list'. This - always resolves those client ID's it does not know yet from the server - so this function might take a while. The `client_id_list' is a list - of ID Payloads added one after other. JOIN command reply and USERS - command reply for example returns this sort of list. The `completion' - will be called after the entries are available. */ +/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list + * + * SYNOPSIS + * + * void silc_client_get_clients_by_list(SilcClient client, + * SilcClientConnection conn, + * uint32 list_count, + * SilcBuffer client_id_list, + * SilcGetClientCallback completion, + * void *context); + * + * DESCRIPTION + * + * Gets client entries by the list of client ID's `client_id_list'. This + * always resolves those client ID's it does not know yet from the server + * so this function might take a while. The `client_id_list' is a list + * of ID Payloads added one after other. JOIN command reply and USERS + * command reply for example returns this sort of list. The `completion' + * will be called after the entries are available. + * + ***/ void silc_client_get_clients_by_list(SilcClient client, SilcClientConnection conn, uint32 list_count, @@ -396,24 +704,64 @@ void silc_client_get_clients_by_list(SilcClient client, SilcGetClientCallback completion, void *context); -/* Find entry for client by the client's ID. Returns the entry or NULL - if the entry was not found. */ +/****f* silcclient/SilcClientAPI/silc_client_get_client_by_id + * + * SYNOPSIS + * + * SilcClientEntry silc_client_get_client_by_id(SilcClient client, + * SilcClientConnection conn, + * SilcClientID *client_id); + * + * DESCRIPTION + * + * 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); -/* Same as above but will always resolve the information from the server. - Use this only if you know that you don't have the entry and the only - thing you know about the client is its ID. */ +/****f* silcclient/SilcClientAPI/silc_client_get_client_by_id_resolve + * + * SYNOPSIS + * + * void + * silc_client_get_client_by_id_resolve(SilcClient client, + * SilcClientConnection conn, + * SilcClientID *client_id, + * SilcGetClientCallback completion, + * void *context); + * + * DESCRIPTION + * + * Same as silc_client_get_client_by_id but will always resolve the + * information from the server. Use this only if you know that you + * do not have the entry and the only thing you know about the client + * is its ID. + * + ***/ void silc_client_get_client_by_id_resolve(SilcClient client, SilcClientConnection conn, SilcClientID *client_id, SilcGetClientCallback completion, void *context); -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_get_channel + * + * SYNOPSIS + * + * SilcChannelEntry silc_client_get_channel(SilcClient client, + * SilcClientConnection conn, + * char *channel); + * + * DESCRIPTION + * + * 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); @@ -421,42 +769,124 @@ SilcChannelEntry silc_client_get_channel(SilcClient client, /* Command management (command.c) */ -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_command_alloc + * + * SYNOPSIS + * + * SilcClientCommandContext silc_client_command_alloc(); + * + * 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(); -/* Free command context and its internals */ +/****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); -/* Duplicate Command Context by adding reference counter. The context won't - be free'd untill it hits zero. */ +/****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); -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_command_find + * + * SYNOPSIS + * + * SilcClientCommand *silc_client_command_find(const char *name); + * + * 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. + * + ***/ SilcClientCommand *silc_client_command_find(const char *name); -/* Generic function to send any command. The arguments must be sent already - encoded into correct form and in correct order. */ +/****f* silcclient/SilcClientAPI/silc_client_send_command + * + * SYNOPSIS + * + * void silc_client_send_command(SilcClient client, + * SilcClientConnection conn, + * SilcCommand command, uint16 ident, + * uint32 argc, ...); + * + * DESCRIPTION + * + * Generic function to send any command. The arguments must be sent already + * encoded into correct form and in correct order. + * + ***/ void silc_client_send_command(SilcClient client, SilcClientConnection conn, SilcCommand command, uint16 ident, uint32 argc, ...); -/* Pending Command callback destructor. This is called after calling the - pending callback or if error occurs while processing the pending command. - If error occurs then the callback won't be called at all, and only this - destructor is called. The `context' is the context given for the function - silc_client_command_pending. */ +/****f* silcclient/SilcClientAPI/SilcClientPendingDestructor + * + * SYNOPSIS + * + * typedef void (*SilcClientPendingDestructor)(void *context); + * + * DESCRIPTION + * + * Pending Command callback destructor. This is called after calling the + * pending callback or if error occurs while processing the pending command. + * If error occurs then the callback won't be called at all, and only this + * destructor is called. The `context' is the context given for the function + * silc_client_command_pending. + * + ***/ typedef void (*SilcClientPendingDestructor)(void *context); -/* 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'. */ +/****f* silcclient/SilcClientAPI/silc_client_command_pending + * + * SYNOPSIS + * + * void silc_client_command_pending(SilcClientConnection conn, + * SilcCommand reply_cmd, + * uint16 ident, + * SilcClientPendingDestructor destructor, + * SilcCommandCb callback, + * void *context); + * + * 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'. + * + ***/ void silc_client_command_pending(SilcClientConnection conn, SilcCommand reply_cmd, uint16 ident, @@ -467,21 +897,37 @@ void silc_client_command_pending(SilcClientConnection conn, /* Private Message key management (client_prvmsg.c) */ -/* 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 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. - - 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. - - Returns FALSE if the key is already set for the `client_entry', TRUE - otherwise. */ +/****f* silcclient/SilcClientAPI/silc_client_add_private_message_key + * + * SYNOPSIS + * + * int silc_client_add_private_message_key(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * char *cipher, + * unsigned char *key, + * uint32 key_len, + * int generate_key); + * + * DESCRIPTION + * + * 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 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. + * + * 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. + * + * 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, SilcClientEntry client_entry, @@ -490,52 +936,115 @@ int silc_client_add_private_message_key(SilcClient client, uint32 key_len, int generate_key); -/* 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. */ +/****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); + * + * 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. + * + ***/ int silc_client_add_private_message_key_ske(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry, char *cipher, SilcSKEKeyMaterial *key); -/* Sends private message key payload to the remote client indicated by - the `client_entry'. If the `force_send' is TRUE the packet is sent - immediately. Returns FALSE if error occurs, TRUE otherwise. The - application should call this function after setting the key to the - client. - - Note that the key sent using this function is sent to the remote client - through the SILC network. The packet is protected using normal session - keys. */ +/****f* silcclient/SilcClientAPI/silc_client_send_private_message_key + * + * SYNOPSIS + * + * int silc_client_send_private_message_key(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * int force_send); + * + * DESCRIPTION + * + * Sends private message key payload to the remote client indicated by + * the `client_entry'. If the `force_send' is TRUE the packet is sent + * immediately. Returns FALSE if error occurs, TRUE otherwise. The + * application should call this function after setting the key to the + * client. + * + * Note that the key sent using this function is sent to the remote client + * through the SILC network. The packet is protected using normal session + * keys. + * + ***/ int silc_client_send_private_message_key(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry, int force_send); -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_del_private_message_key + * + * SYNOPSIS + * + * int silc_client_del_private_message_key(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry); + * + * DESCRIPTION + * + * 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); -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys + * + * SYNOPSIS + * + * SilcPrivateMessageKeys + * silc_client_list_private_message_keys(SilcClient client, + * SilcClientConnection conn, + * uint32 *key_count); + * + * DESCRIPTION + * + * 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, uint32 *key_count); -/* Frees the SilcPrivateMessageKeys array returned by the function - silc_client_list_private_message_keys. */ +/****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys + * + * SYNOPSIS + * + * void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys, + * uint32 key_count); + * + * DESCRIPTION + * + * Frees the SilcPrivateMessageKeys array returned by the function + * silc_client_list_private_message_keys. + * + ***/ void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys, uint32 key_count); @@ -543,31 +1052,49 @@ void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys, /* Channel private key management (client_channel.c, SilcChannelPrivateKey is defined in idlist.h) */ -/* 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 know 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. - - NOTE: If the key material was originated by the SKE protocol (using - silc_client_send_key_agreement) then the `key' MUST be the - key->send_enc_key as this is dictated by the SILC protocol. However, - currently it is not expected that the SKE key material would be used - as channel private key. However, this API allows it. */ +/****f* silcclient/SilcClientAPI/silc_client_add_channel_private_key + * + * SYNOPSIS + * + * int silc_client_add_channel_private_key(SilcClient client, + * SilcClientConnection conn, + * SilcChannelEntry channel, + * char *cipher, + * char *hmac, + * unsigned char *key, + * uint32 key_len); + * + * DESCRIPTION + * + * 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 know 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. + * + * NOTES + * + * NOTE: This is entirely local setting. The key set using this function + * is not sent to the network at any phase. + * + * NOTE: If the key material was originated by the SKE protocol (using + * silc_client_send_key_agreement) then the `key' MUST be the + * key->send_enc_key as this is dictated by the SILC protocol. However, + * currently it is not expected that the SKE key material would be used + * as channel private key. However, this API allows it. + * + ***/ int silc_client_add_channel_private_key(SilcClient client, SilcClientConnection conn, SilcChannelEntry channel, @@ -576,74 +1103,144 @@ int silc_client_add_channel_private_key(SilcClient client, unsigned char *key, uint32 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. */ +/****f* silcclient/SilcClientAPI/silc_client_del_channel_private_keys + * + * SYNOPSIS + * + * int silc_client_del_channel_private_keys(SilcClient client, + * SilcClientConnection conn, + * SilcChannelEntry channel); + * + * DESCRIPTION + * + * 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); -/* 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. */ +/****f* silcclient/SilcClientAPI/silc_client_del_channel_private_key + * + * SYNOPSIS + * + * int silc_client_del_channel_private_key(SilcClient client, + * SilcClientConnection conn, + * SilcChannelEntry channel, + * SilcChannelPrivateKey key); + * + * DESCRIPTION + * + * 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. */ +/****f* silcclient/SilcClientAPI/silc_client_list_channel_private_keys + * + * SYNOPSIS + * + * SilcChannelPrivateKey * + * silc_client_list_channel_private_keys(SilcClient client, + * SilcClientConnection conn, + * SilcChannelEntry channel, + * uint32 *key_count); + * + * DESCRIPTION + * + * 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, uint32 *key_count); -/* Frees the SilcChannelPrivateKey array. */ +/****f* silcclient/SilcClientAPI/silc_client_free_channel_private_keys + * + * SYNOPSIS + * + * void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys, + * uint32 key_count); + * + * DESCRIPTION + * + * Frees the SilcChannelPrivateKey array. + * + ***/ void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys, uint32 key_count); /* Key Agreement routines (client_keyagr.c) */ -/* Sends key agreement request to the remote client indicated by the - `client_entry'. If the caller provides the `hostname' and the `port' - arguments then the library will bind the client to that hostname and - that port for the key agreement protocol. It also sends the `hostname' - and the `port' in the key agreement packet to the remote client. This - would indicate that the remote client may initiate the key agreement - protocol to the `hostname' on the `port'. If port is zero then the - bound port is undefined (the operating system defines it). - - If the `hostname' and `port' is not provided then empty key agreement - packet is sent to the remote client. The remote client may reply with - the same packet including its hostname and port. If the library receives - the reply from the remote client the `key_agreement' client operation - callback will be called to verify whether the user wants to perform the - key agreement or not. - - NOTE: If the application provided the `hostname' and the `port' and the - remote side initiates the key agreement protocol it is not verified - from the user anymore whether the protocol should be executed or not. - By setting the `hostname' and `port' the user gives permission to - perform the protocol (we are responder in this case). - - NOTE: If the remote side decides not to initiate the key agreement - or decides not to reply with the key agreement packet then we cannot - perform the key agreement at all. If the key agreement protocol is - performed the `completion' callback with the `context' will be called. - If remote side decides to ignore the request the `completion' will be - called after the specified timeout, `timeout_secs'. - - 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 - silc_client_abort_key_agreement must be called. */ +/****f* silcclient/SilcClientAPI/silc_client_send_key_agreement + * + * SYNOPSIS + * + * void silc_client_send_key_agreement(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * char *hostname, + * int port, + * uint32 timeout_secs, + * SilcKeyAgreementCallback completion, + * void *context); + * + * DESCRIPTION + * + * Sends key agreement request to the remote client indicated by the + * `client_entry'. If the caller provides the `hostname' and the `port' + * arguments then the library will bind the client to that hostname and + * that port for the key agreement protocol. It also sends the `hostname' + * and the `port' in the key agreement packet to the remote client. This + * would indicate that the remote client may initiate the key agreement + * protocol to the `hostname' on the `port'. If port is zero then the + * bound port is undefined (the operating system defines it). + * + * If the `hostname' and `port' is not provided then empty key agreement + * packet is sent to the remote client. The remote client may reply with + * the same packet including its hostname and port. If the library receives + * the reply from the remote client the `key_agreement' client operation + * callback will be called to verify whether the user wants to perform the + * key agreement or not. + * + * NOTES + * + * NOTE: If the application provided the `hostname' and the `port' and the + * remote side initiates the key agreement protocol it is not verified + * from the user anymore whether the protocol should be executed or not. + * By setting the `hostname' and `port' the user gives permission to + * perform the protocol (we are responder in this case). + * + * NOTE: If the remote side decides not to initiate the key agreement + * or decides not to reply with the key agreement packet then we cannot + * perform the key agreement at all. If the key agreement protocol is + * performed the `completion' callback with the `context' will be called. + * If remote side decides to ignore the request the `completion' will be + * called after the specified timeout, `timeout_secs'. + * + * 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 + * silc_client_abort_key_agreement must be called. + * + ***/ void silc_client_send_key_agreement(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry, @@ -653,25 +1250,44 @@ void silc_client_send_key_agreement(SilcClient client, SilcKeyAgreementCallback completion, void *context); -/* Performs the actual key agreement protocol. Application may use this - to initiate the key agreement protocol. This can be called for example - after the application has received the `key_agreement' client operation, - and did not return TRUE from it. - - The `hostname' is the remote hostname (or IP address) and the `port' - is the remote port. The `completion' callback with the `context' will - be called after the key agreement protocol. - - NOTE: If the application returns TRUE in the `key_agreement' client - operation the library will automatically start the key agreement. In this - case the application must not call this function. However, application - may choose to just ignore the `key_agreement' client operation (and - merely just print information about it on the screen) and call this - function when the user whishes to do so (by, for example, giving some - specific command). Thus, the API provides both, automatic and manual - initiation of the key agreement. Calling this function is the manual - initiation and returning TRUE in the `key_agreement' client operation - is the automatic initiation. */ +/****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement + * + * SYNOPSIS + * + * void + * silc_client_perform_key_agreement(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * char *hostname, + * int port, + * SilcKeyAgreementCallback completion, + * void *context); + * + * DESCRIPTION + * + * Performs the actual key agreement protocol. Application may use this + * to initiate the key agreement protocol. This can be called for example + * after the application has received the `key_agreement' client operation, + * and did not return TRUE from it. + * + * The `hostname' is the remote hostname (or IP address) and the `port' + * is the remote port. The `completion' callback with the `context' will + * be called after the key agreement protocol. + * + * NOTES + * + * NOTE: If the application returns TRUE in the `key_agreement' client + * operation the library will automatically start the key agreement. In this + * case the application must not call this function. However, application + * may choose to just ignore the `key_agreement' client operation (and + * merely just print information about it on the screen) and call this + * function when the user whishes to do so (by, for example, giving some + * specific command). Thus, the API provides both, automatic and manual + * initiation of the key agreement. Calling this function is the manual + * initiation and returning TRUE in the `key_agreement' client operation + * is the automatic initiation. + * + ***/ void silc_client_perform_key_agreement(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry, @@ -680,10 +1296,27 @@ void silc_client_perform_key_agreement(SilcClient client, SilcKeyAgreementCallback completion, void *context); -/* Same as above but application has created already the connection to - the remote host. The `sock' is the socket to the remote connection. - Application can use this function if it does not want the client library - to create the connection. */ +/****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement_fd + * + * SYNOPSIS + * + * void + * silc_client_perform_key_agreement_fd(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry, + * int sock, + * char *hostname, + * SilcKeyAgreementCallback completion, + * void *context); + * + * DESCRIPTION + * + * Same as above but application has created already the connection to + * the remote host. The `sock' is the socket to the remote connection. + * Application can use this function if it does not want the client library + * to create the connection. + * + ***/ void silc_client_perform_key_agreement_fd(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry, @@ -692,12 +1325,24 @@ void silc_client_perform_key_agreement_fd(SilcClient client, SilcKeyAgreementCallback completion, void *context); -/* This function can be called to unbind the hostname and the port for - the key agreement protocol. However, this function has effect only - before the key agreement protocol has been performed. After it has - been performed the library will automatically unbind the port. The - `client_entry' is the client to which we sent the key agreement - request. */ +/****f* silcclient/SilcClientAPI/silc_client_abort_key_agreement + * + * SYNOPSIS + * + * void silc_client_abort_key_agreement(SilcClient client, + * SilcClientConnection conn, + * SilcClientEntry client_entry); + * + * DESCRIPTION + * + * This function can be called to unbind the hostname and the port for + * the key agreement protocol. However, this function has effect only + * before the key agreement protocol has been performed. After it has + * been performed the library will automatically unbind the port. The + * `client_entry' is the client to which we sent the key agreement + * request. + * + ***/ void silc_client_abort_key_agreement(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry); @@ -705,14 +1350,25 @@ void silc_client_abort_key_agreement(SilcClient client, /* Misc functions */ -/* Sets away `message'. The away message may be set when the client's - mode is changed to SILC_UMODE_GONE and the client whishes to reply - to anyone who sends private message. The `message' will be sent - automatically back to the the client who send private message. If - away message is already set this replaces the old message with the - new one. If `message' is NULL the old away message is removed. - The sender may freely free the memory of the `message'. */ - +/****f* silcclient/SilcClientAPI/silc_client_set_away_message + * + * SYNOPSIS + * + * void silc_client_set_away_message(SilcClient client, + * SilcClientConnection conn, + * char *message); + * + * DESCRIPTION + * + * Sets away `message'. The away message may be set when the client's + * mode is changed to SILC_UMODE_GONE and the client whishes to reply + * to anyone who sends private message. The `message' will be sent + * automatically back to the the client who send private message. If + * away message is already set this replaces the old message with the + * new one. If `message' is NULL the old away message is removed. + * The sender may freely free the memory of the `message'. + * + ***/ void silc_client_set_away_message(SilcClient client, SilcClientConnection conn, char *message); diff --git a/lib/silccore/Makefile.am b/lib/silccore/Makefile.am index 8eed24f8..c6564e74 100644 --- a/lib/silccore/Makefile.am +++ b/lib/silccore/Makefile.am @@ -21,8 +21,8 @@ AUTOMAKE_OPTIONS = 1.0 no-dependencies foreign noinst_LIBRARIES = libsilccore.a libsilccore_a_SOURCES = \ - id.c \ - idcache.c \ + silcid.c \ + silcidcache.c \ silcchannel.c \ silccommand.c \ silcpacket.c \ diff --git a/lib/silccore/silcauth.h b/lib/silccore/silcauth.h index ba742308..008f727a 100644 --- a/lib/silccore/silcauth.h +++ b/lib/silccore/silcauth.h @@ -1,80 +1,362 @@ -/* - - siclauth.h - - Author: Pekka Riikonen - - Copyright (C) 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* silccore/silcauth.h + * + * NAME + * + * silcauth.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 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. + * + * DESCRIPTION + * + * Implementations of the Silc Authentication Payload and authentication + * routines. The SILC Authentication Payload is used to deliver + * authentication data usually from client to server in purpose of + * gaining access to some service. The Payload and the authentication + * routines supports both passphrase and public key (signature) based + * authentication. + * + * This interface defines also the SILC Key Agreement Payload that is + * used by client to agree on key material usually with another client + * in the network. + * + ***/ #ifndef SILCAUTH_H #define SILCAUTH_H -/* Forward declaration of the Authentication Payload */ +/****s* silccore/SilcAuthAPI/SilcAuthPayload + * + * NAME + * + * typedef struct SilcAuthPayloadStruct *SilcAuthPayload; + * + * DESCRIPTION + * + * This context is the actual Authentication Payload and is allocated + * by silc_auth_payload_parse and given as argument usually to all + * silc_auth_payload_* functions. It is freed by silc_auth_payload_free + * function. + * + ***/ typedef struct SilcAuthPayloadStruct *SilcAuthPayload; -/* Forward declaration of the Key Agreement Payload */ +/****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload + * + * NAME + * + * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; + * + * DESCRIPTION + * + * This context is the actual Key Agreement Payload and is allocated + * by silc_key_agreement_payload_parse and given as argument usually to all + * silc_key_agreement_* functions. It is freed by the function + * silc_key_agreement_payload_free. + * + ***/ typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; -/* Authentication method type */ +/****d* silccore/SilcAuthAPI/SilcAuthMethod + * + * NAME + * + * typedef uint16 SilcAuthMethod; + * + * DESCRIPTION + * + * Authentication method type definition, the authentication methods + * and the authentication status'. The status defines are used by + * all authentication protocols in the SILC. + * + * SOURCE + */ typedef uint16 SilcAuthMethod; -/* Authentication methods in SILC protocol */ -#define SILC_AUTH_NONE 0 -#define SILC_AUTH_PASSWORD 1 -#define SILC_AUTH_PUBLIC_KEY 2 +#define SILC_AUTH_NONE 0 /* No authentication */ +#define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */ +#define SILC_AUTH_PUBLIC_KEY 2 /* Public key authentication */ /* Authentication protocol status message (used by all authentication - procols in the SILC). */ + protocols in the SILC). */ #define SILC_AUTH_OK 0 #define SILC_AUTH_FAILED 1 +/***/ /* Prototypes */ + +/****f* silccore/SilcAuthAPI/silc_auth_payload_parse + * + * SYNOPSIS + * + * SilcAuthPayload silc_auth_payload_parse(unsigned char *data, + * uint32 data_len); + * + * DESCRIPTION + * + * Parses and returns Authentication Payload. The `data' and the + * `data_len' are the raw payload buffer. + * + ***/ SilcAuthPayload silc_auth_payload_parse(unsigned char *data, uint32 data_len); + +/****f* silccore/SilcAuthAPI/silc_auth_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method, + * unsigned char *random_data, + * uint16 random_len, + * unsigned char *auth_data, + * uint16 auth_len); + * + * DESCRIPTION + * + * Encodes authentication payload into buffer and returns it. + * The `random_data' is provided only if doing public key authentication. + * The `auth_data' is the actual authentication data. + * + ***/ SilcBuffer silc_auth_payload_encode(SilcAuthMethod method, unsigned char *random_data, uint16 random_len, unsigned char *auth_data, uint16 auth_len); + +/****f* silccore/SilcAuthAPI/silc_auth_payload_free + * + * SYNOPSIS + * + * void silc_auth_payload_free(SilcAuthPayload payload); + * + * DESCRIPTION + * + * Frees authentication payload and all data in it. + * + ***/ void silc_auth_payload_free(SilcAuthPayload payload); + +/****f* silccore/SilcAuthAPI/silc_auth_get_method + * + * SYNOPSIS + * + * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload); + * + * DESCRIPTION + * + * Get authentication method. + * + ***/ SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload); + +/****f* silccore/SilcAuthAPI/silc_auth_get_data + * + * SYNOPSIS + * + * unsigned char *silc_auth_get_data(SilcAuthPayload payload, + * uint32 *auth_len); + * + * DESCRIPTION + * + * Get the authentication data. The caller must not free the data. + * + ***/ unsigned char *silc_auth_get_data(SilcAuthPayload payload, uint32 *auth_len); + +/****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate + * + * SYNOPSIS + * + * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key, + * SilcPrivateKey private_key, + * SilcHash hash, + * void *id, SilcIdType type); + * + * DESCRIPTION + * + * Generates Authentication Payload with authentication data. This is used + * to do public key based authentication. This generates the random data + * and the actual authentication data. Returns NULL on error and the + * encoded Authentication Payload on success. + * + ***/ SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key, SilcPrivateKey private_key, SilcHash hash, void *id, SilcIdType type); + +/****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify + * + * SYNOPSIS + * + * int silc_auth_public_key_auth_verify(SilcAuthPayload payload, + * SilcPublicKey public_key, + * SilcHash hash, + * void *id, SilcIdType type); + * + * DESCRIPTION + * + * Verifies the authentication data. Returns TRUE if authentication was + * successful. + * + ***/ int silc_auth_public_key_auth_verify(SilcAuthPayload payload, SilcPublicKey public_key, SilcHash hash, void *id, SilcIdType type); + +/****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data + * + * SYNOPSIS + * + * int silc_auth_public_key_auth_verify_data(SilcBuffer payload, + * SilcPublicKey public_key, + * SilcHash hash, + * void *id, SilcIdType type); + * + * DESCRIPTION + * + * Same as silc_auth_public_key_auth_verify but the payload has not + * been parsed yet. This will parse it. Returns TRUE if authentication + * was successful. + * + ***/ int silc_auth_public_key_auth_verify_data(SilcBuffer payload, SilcPublicKey public_key, SilcHash hash, void *id, SilcIdType type); + +/****f* silccore/SilcAuthAPI/silc_auth_verify + * + * SYNOPSIS + * + * int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method, + * void *auth_data, uint32 auth_data_len, + * SilcHash hash, void *id, SilcIdType type); + * + * DESCRIPTION + * + * Verifies the authentication data directly from the Authentication + * Payload. Supports all authentication methods. If the authentication + * method is passphrase based then the `auth_data' and `auth_data_len' + * are the passphrase and its length. If the method is public key + * authentication then the `auth_data' is the SilcPublicKey and the + * `auth_data_len' is ignored. + * + ***/ int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method, void *auth_data, uint32 auth_data_len, SilcHash hash, void *id, SilcIdType type); + +/****f* silccore/SilcAuthAPI/silc_auth_verify_data + * + * SYNOPSIS + * + * int silc_auth_verify_data(unsigned char *payload, uint32 payload_len, + * SilcAuthMethod auth_method, void *auth_data, + * uint32 auth_data_len, SilcHash hash, + * void *id, SilcIdType type); + * + * DESCRIPTION + * + * Same as silc_auth_verify but the payload has not been parsed yet. + * Verifies the authentication data directly from the Authentication + * Payload. Supports all authentication methods. If the authentication + * method is passphrase based then the `auth_data' and `auth_data_len' + * are the passphrase and its length. If the method is public key + * authentication then the `auth_data' is the SilcPublicKey and the + * `auth_data_len' is ignored. + * + ***/ int silc_auth_verify_data(unsigned char *payload, uint32 payload_len, SilcAuthMethod auth_method, void *auth_data, uint32 auth_data_len, SilcHash hash, void *id, SilcIdType type); + +/****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse + * + * SYNOPSIS + * + * SilcKeyAgreementPayload + * silc_key_agreement_payload_parse(SilcBuffer buffer); + * + * DESCRIPTION + * + * Parses and returns an allocated Key Agreement payload. + * + ***/ SilcKeyAgreementPayload silc_key_agreement_payload_parse(SilcBuffer buffer); + +/****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_key_agreement_payload_encode(char *hostname, + * uint32 port); + * + * DESCRIPTION + * + * Encodes the Key Agreement protocol and returns the encoded buffer + * + ***/ SilcBuffer silc_key_agreement_payload_encode(char *hostname, uint32 port); + +/****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free + * + * SYNOPSIS + * + * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload); + * + * DESCRIPTION + * + * Frees the Key Agreement protocol and all data in it. + * + ***/ void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload); + +/****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname + * + * SYNOPSIS + * + * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload); + * + * DESCRIPTION + * + * Returns the hostname in the payload. Caller must not free it. + * The hostname is the host that is able to accept key negotiation + * using the SILC Key Exchange protocol. + * + ***/ char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload); + +/****f* silccore/SilcAuthAPI/silc_key_agreement_get_port + * + * SYNOPSIS + * + * uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); + * + * DESCRIPTION + * + * Returns the port in the payload. The port is the port on the + * host returned by silc_key_agreement_get_hostname that is running + * the SILC Key Exchange protocol. + * + ***/ uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); #endif diff --git a/lib/silccore/id.c b/lib/silccore/silcid.c similarity index 99% rename from lib/silccore/id.c rename to lib/silccore/silcid.c index ef05bef5..f9ca89dc 100644 --- a/lib/silccore/id.c +++ b/lib/silccore/silcid.c @@ -20,7 +20,7 @@ /* $Id$ */ #include "silcincludes.h" -#include "id.h" +#include "silcid.h" /* ID lengths (in bytes) without the IP address part */ #define ID_SERVER_LEN_PART 4 diff --git a/lib/silccore/id.h b/lib/silccore/silcid.h similarity index 99% rename from lib/silccore/id.h rename to lib/silccore/silcid.h index 114583bb..5604fd2a 100644 --- a/lib/silccore/id.h +++ b/lib/silccore/silcid.h @@ -1,6 +1,6 @@ /* - id.h + silcid.h Author: Pekka Riikonen diff --git a/lib/silccore/idcache.c b/lib/silccore/silcidcache.c similarity index 99% rename from lib/silccore/idcache.c rename to lib/silccore/silcidcache.c index e5665f42..b99859b5 100644 --- a/lib/silccore/idcache.c +++ b/lib/silccore/silcidcache.c @@ -1,6 +1,6 @@ /* - idcache.c + silcidcache.c Author: Pekka Riikonen @@ -20,7 +20,7 @@ /* $Id$ */ #include "silcincludes.h" -#include "idcache.h" +#include "silcidcache.h" /* Static prototypes */ static void silc_idcache_destructor(void *key, void *context, diff --git a/lib/silccore/idcache.h b/lib/silccore/silcidcache.h similarity index 99% rename from lib/silccore/idcache.h rename to lib/silccore/silcidcache.h index e1c2b063..c3608c4d 100644 --- a/lib/silccore/idcache.h +++ b/lib/silccore/silcidcache.h @@ -1,6 +1,6 @@ /* - idcache.h + silcidcache.h Author: Pekka Riikonen diff --git a/lib/silccore/silcprivate.c b/lib/silccore/silcprivate.c index 25e749f2..48a31b65 100644 --- a/lib/silccore/silcprivate.c +++ b/lib/silccore/silcprivate.c @@ -126,7 +126,7 @@ SilcBuffer silc_private_message_payload_encode(uint16 flags, return buffer; } -/* Free's Private Message Payload */ +/* Frees Private Message Payload */ void silc_private_message_payload_free(SilcPrivateMessagePayload payload) { diff --git a/lib/silccore/silcprivate.h b/lib/silccore/silcprivate.h index 79e00b89..0f274f24 100644 --- a/lib/silccore/silcprivate.h +++ b/lib/silccore/silcprivate.h @@ -1,43 +1,136 @@ -/* - - silcprivate.h - - Author: Pekka Riikonen - - Copyright (C) 1997 - 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* silccore/silcprivate.h + * + * NAME + * + * silcprivate.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 1997 - 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. + * + * DESCRIPTION + * + * Implementation of the SILC Private Message Payload that is used to + * deliver private messages. + * + ***/ #ifndef SILCPRIVATE_H #define SILCPRIVATE_H -/* Forward declaration of the Private Message Payload. */ +/****s* silccore/SilcPrivateAPI/SilcPrivateMessagePayload + * + * NAME + * + * typedef struct SilcPrivateMessagePayloadStruct + * *SilcPrivateMessagePayload; + * + * + * DESCRIPTION + * + * This context is the actual Private Message Payload and is allocated + * by silc_private_message_payload_parse and given as argument usually + * to all silc_private_message_* functions. It is freed by the + * silc_private_message_payload_free function. + * + ***/ typedef struct SilcPrivateMessagePayloadStruct *SilcPrivateMessagePayload; /* Prototypes */ +/****f* silccore/SilcPrivateAPI/silc_private_message_payload_parse + * + * SYNOPSIS + * + * SilcPrivateMessagePayload + * silc_private_message_payload_parse(SilcBuffer buffer, SilcCipher cipher); + * + * DESCRIPTION + * + * Parses private message payload returning new private mesage payload + * structure. This also decrypts the message if the `cipher' is provided. + * + ***/ SilcPrivateMessagePayload silc_private_message_payload_parse(SilcBuffer buffer, SilcCipher cipher); + +/****f* silccore/SilcPrivateAPI/silc_private_message_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_private_message_payload_encode(uint16 flags, + * uint16 data_len, + * unsigned char *data, + * SilcCipher cipher); + * + * DESCRIPTION + * + * Encodes private message payload into a buffer and returns it. If + * the cipher is provided the packet is also encrypted here. It is provided + * if the private message private keys are used. + * + ***/ SilcBuffer silc_private_message_payload_encode(uint16 flags, uint16 data_len, unsigned char *data, SilcCipher cipher); + +/****f* silccore/SilcPrivateAPI/silc_private_message_payload_free + * + * SYNOPSIS + * + * void + * silc_private_message_payload_free(SilcPrivateMessagePayload payload); + * + * DESCRIPTION + * + * Frees Private Message Payload + * + ***/ void silc_private_message_payload_free(SilcPrivateMessagePayload payload); + +/****f* silccore/SilcPrivateAPI/silc_private_message_get_flags + * + * SYNOPSIS + * + * uint16 + * silc_private_message_get_flags(SilcPrivateMessagePayload payload); + * + * DESCRIPTION + * + * Returns flags from the payload. Message flags may indicate some + * status of the message. Private message flags are equivalent to the + * channel message flags. + * + ***/ uint16 silc_private_message_get_flags(SilcPrivateMessagePayload payload); -unsigned char * -silc_private_message_get_nickname(SilcPrivateMessagePayload payload, - uint32 *nickname_len); + +/****f* silccore/SilcPrivateAPI/silc_private_message_get_message + * + * SYNOPSIS + * + * unsigned char * + * silc_private_message_get_nickname(SilcPrivateMessagePayload payload, + * uint32 *nickname_len); + * + * DESCRIPTION + * + * Returns the actual private message. The caller must not free it. + * + ***/ unsigned char * silc_private_message_get_message(SilcPrivateMessagePayload payload, uint32 *message_len); diff --git a/lib/silccrypt/silcdh.h b/lib/silccrypt/silcdh.h index 13c76a34..02f1129e 100644 --- a/lib/silccrypt/silcdh.h +++ b/lib/silccrypt/silcdh.h @@ -1,24 +1,30 @@ -/* - - silcdh.h - - Author: Pekka Riikonen - - Copyright (C) 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. - -*/ -/* PKCS #3 compliant Diffie Hellman key agreement protocol implementation. - This is used as part of SKE (SILC Key Exchange) protocol. */ +/****h* silccrypt/SilcDH/silcdh.h + * + * NAME + * + * silcdh.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 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. + * + * DESCRIPTION + * + * PKCS #3 compliant Diffie Hellman key agreement protocol implementation. + * This is used as part of SKE (SILC Key Exchange) protocol. + ***/ #ifndef SILCDH_H #define SILCDH_H @@ -26,7 +32,18 @@ #include "silcmp.h" #include "silcrng.h" -/* Forward declaration of Diffie Hellman context */ +/****s* silccrypt/SilcDH/SilcDH + * + * NAME + * + * typedef struct SilcDHStruct *SilcDH; + * + * DESCRIPTION + * + * This context is allocated by silc_dh_alloc and is given as argument + * to all silc_dh_* functions. It is freed by silc_dh_free function. + * + ***/ typedef struct SilcDHStruct *SilcDH; /* XXX Move to source file */ @@ -44,43 +61,115 @@ struct SilcDHStruct { SilcRng rng; /* RNG */ }; -/* Allocate DH context. The `rng' must be initialized random number generator - context, the `g' is the public base generator used in the negotiation, - the `p' is the public prime used in the negotiation and the `lpf' is - largest prime factor of p defined publicly as well. The `lpf' is optional - and if it is not supplied then the private values generated satifies - 0 < x < p - 1 instead of 0 < x < lpf. Returns NULL on error or allocated - DH context on success. */ +/****f* silccrypt/SilcDH/silc_dh_alloc + * + * SYNOPSIS + * + * SilcDH silc_dh_alloc(SilcRng rng, SilcInt *g, SilcInt *p, SilcInt *lpf); + * + * DESCRIPTION + * + * Allocate SilcDH context. The `rng' must be initialized random number + * generator context, the `g' is the public base generator used in the + * negotiation, the `p' is the public prime used in the negotiation and + * the `lpf' is largest prime factor of p defined publicly as well. The + * `lpf' is optional and if it is not supplied then the private values + * generated satifies 0 < x < p - 1 instead of 0 < x < lpf. Returns NULL + * on error or allocated SilcDH context on success. + * + ***/ SilcDH silc_dh_alloc(SilcRng rng, SilcInt *g, SilcInt *p, SilcInt *lpf); -/* Frees the DH context. Does not free the RNG context given in the - allocation. Frees all the allocated data inside the DH context. */ +/****f* silccrypt/SilcDH/silc_dh_free + * + * SYNOPSIS + * + * void silc_dh_free(SilcDH dh); + * + * DESCRIPTION + * + * Frees the SilcDH context. Does not free the RNG context given in the + * allocation. Frees all the allocated data inside the SilcDH context. + * + ***/ void silc_dh_free(SilcDH dh); -/* Generates random private value `x' such that 0 < x < lpf at most of - length of lpf. Returns FALSE if the random number could not be generated. - Returns the generated value into `x' pointer sent as argument, unless - the `x' is NULL. The returned `x' must no be freed by the caller. */ +/****f* silccrypt/SilcDH/silc_dh_generate_private + * + * SYNOPSIS + * + * int silc_dh_generate_private(SilcDH dh, SilcInt **x); + * + * DESCRIPTION + * + * Generates random private value `x' such that 0 < x < lpf at most of + * length of lpf. Returns FALSE if the random number could not be generated. + * Returns the generated value into `x' pointer sent as argument, unless + * the `x' is NULL. The returned `x' must no be freed by the caller. + * + ***/ int silc_dh_generate_private(SilcDH dh, SilcInt **x); -/* Computes the public key y = g ^ x mod p, and returns it to the `y' - pointer sent as argument, unless the `y' is NULL. Returns FALSE if - the computation could not be performed. The returned `y' must not be - freed by the caller. */ +/****f* silccrypt/SilcDH/silc_dh_compute_public + * + * SYNOPSIS + * + * int silc_dh_compute_public(SilcDH dh, SilcInt **y); + * + * DESCRIPTION + * + * Computes the public key y = g ^ x mod p, and returns it to the `y' + * pointer sent as argument, unless the `y' is NULL. Returns FALSE if + * the computation could not be performed. The returned `y' must not be + * freed by the caller. + * + ***/ int silc_dh_compute_public(SilcDH dh, SilcInt **y); -/* Sets the remote end's public value y' into the DH context. This must be - done before computing the secret key. Returns FALSE on error. */ +/****f* silccrypt/SilcDH/silc_dh_remote_public + * + * SYNOPSIS + * + * int silc_dh_compute_public(SilcDH dh, SilcInt **y); + * + * DESCRIPTION + * + * Sets the remote end's public value y' into the SilcDH context. + * This must be done before computing the secret key. Returns FALSE + * on error. + * + ***/ int silc_dh_set_remote_public(SilcDH dh, SilcInt *y); -/* Computes the secret key z = y' ^ x mod p, and returns the key to the - `z' pointer sent as argument, unless the `z' is NULL. Returns FALSE if - the computation could not be performed. The returned `z' must not be - freed by the caller. */ +/****f* silccrypt/SilcDH/silc_dh_compute_key + * + * SYNOPSIS + * + * int silc_dh_compute_key(SilcDH dh, SilcInt **z); + * + * DESCRIPTION + * + * Computes the secret key z = y' ^ x mod p, and returns the key to the + * `z' pointer sent as argument, unless the `z' is NULL. Returns FALSE if + * the computation could not be performed. The returned `z' must not be + * freed by the caller. + * + ***/ int silc_dh_compute_key(SilcDH dh, SilcInt **z); -/* Same as above but returns the computed secret key as octet binary - string. */ +/****f* silccrypt/SilcDH/silc_dh_remote_public + * + * SYNOPSIS + * + * int silc_dh_compute_key_data(SilcDH dh, unsigned char **z, + * uint32 *z_len); + * + * DESCRIPTION + * + * Same as above but returns the computed secret key as octet binary + * string. + * + ***/ int silc_dh_compute_key_data(SilcDH dh, unsigned char **z, uint32 *z_len);