Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2000 - 2006 Pekka Riikonen
+ Copyright (C) 2000 - 2007 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
} SilcClientConnectionStatus;
/***/
+/****f* silcclient/SilcClientAPI/SilcClientRunning
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcClientRunning)(SilcClient client, void *context);
+ *
+ * DESCRIPTION
+ *
+ * The callback given as argument to silc_client_init function. Once
+ * this is called the client library is running and application may
+ * start using the Client library API.
+ *
+ ***/
+typedef void (*SilcClientRunning)(SilcClient client, void *context);
+
+/****f* silcclient/SilcClientAPI/SilcClientStopped
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcClientStopped)(SilcClient client, void *context);
+ *
+ * DESCRIPTION
+ *
+ * The callback given as argument to silc_client_stop. Once this is
+ * called the client library has stopped and can be freed by calling
+ * silc_client_free. Note that this won't be called if there are
+ * active connections in the client. Connections must first be closed
+ * by calling silc_client_close_connection or by sending QUIT command to
+ * the server connection.
+ *
+ ***/
+typedef void (*SilcClientStopped)(SilcClient client, void *context);
+
/****f* silcclient/SilcClientAPI/SilcClientConnectCallback
*
* SYNOPSIS
SILC_KEY_AGREEMENT_ABORTED, /* The protocol aborted */
SILC_KEY_AGREEMENT_ALREADY_STARTED, /* Already started */
SILC_KEY_AGREEMENT_SELF_DENIED, /* Negotiationg with itself denied */
+ SILC_KEY_AGREEMENT_NO_MEMORY, /* System out of memory */
} SilcKeyAgreementStatus;
/***/
SilcClientConnection conn,
SilcClientEntry client_entry,
SilcKeyAgreementStatus status,
- SilcSKEKeyMaterial *key,
+ SilcSKEKeyMaterial key,
void *context);
/****s* silcclient/SilcClientAPI/SilcPrivateMessageKeys
SilcClientEntry client_entry; /* The remote client entry */
char *cipher; /* The cipher name */
unsigned char *key; /* The original key, If the appliation
- provided it. This is NULL if the
- library generated the key or if
+ provided it. This is NULL if
the SKE key material was used. */
SilcUInt32 key_len; /* The key length */
} *SilcPrivateMessageKeys;
*
* DESCRIPTION
*
- * Authentication method resolving callback. This is called by the
- * application to return the resolved authentication method. The client
+ * Authentication data resolving callback. This is called by the
+ * application to return the resolved authentication data. The client
* library has called the get_auth_method client operation and given
- * this function pointer as argument. The `success' will indicate whether
- * the authentication method could be resolved. The `auth_meth' is the
- * resolved authentication method. The `auth_data' and the `auth_data_len'
+ * this function pointer as argument. The `auth_meth' is the selected
+ * authentication method. The `auth_data' and the `auth_data_len'
* are the resolved authentication data. The `context' is the libary's
* context sent to the get_auth_method client operation.
*
+ * If the `auth_method' is SILC_AUTH_PASSWORD then `auth' and `auth_len'
+ * is the passphrase and its length. If it is SILC_AUTH_PUBLIC_KEY the
+ * `auth' must be NULL. The library will use the private key given as
+ * argument to silc_client_connect_to_server, silc_client_connect_to_client
+ * or silc_client_key_exchange. If it is SILC_AUTH_NONE, both `auth' and
+ * `auth_len' are ignored.
+ *
***/
-typedef void (*SilcGetAuthMeth)(SilcBool success,
- SilcAuthMethod auth_meth,
+typedef void (*SilcGetAuthMeth)(SilcAuthMethod auth_meth,
void *auth, SilcUInt32 auth_len,
void *context);
SilcStatus error, va_list ap);
/* Find authentication method and authentication data by hostname and
- port. The hostname may be IP address as well. When the authentication
- method has been resolved the `completion' callback with the found
- authentication method and authentication data is called. The `conn'
- may be NULL. */
+ port. The hostname may be IP address as well. The `auth_method' is
+ the authentication method the remote connection requires. It is
+ however possible that remote accepts also some other authentication
+ method. Application should use the method that may have been
+ configured for this connection. If none has been configured it should
+ use the required `auth_method'. If the `auth_method' is
+ SILC_AUTH_NONE, server does not require any authentication or the
+ required authentication method is not known. The `completion'
+ callback must be called to deliver the chosen authentication method
+ and data. The `conn' may be NULL. */
void (*get_auth_method)(SilcClient client, SilcClientConnection conn,
char *hostname, SilcUInt16 port,
+ SilcAuthMethod auth_method,
SilcGetAuthMeth completion, void *context);
/* Verifies received public key. The `conn_type' indicates which entity
- (server, client etc.) has sent the public key. If user decides to trust
- the application may save the key as trusted public key for later
- use. The `completion' must be called after the public key has been
- verified. */
+ (server or client) has sent the public key. If user decides to trust
+ the key the application may save the key as trusted public key for
+ later use. The `completion' must be called after the public key has
+ been verified. */
void (*verify_public_key)(SilcClient client, SilcClientConnection conn,
SilcConnectionType conn_type,
SilcPublicKey public_key,
void (*ask_passphrase)(SilcClient client, SilcClientConnection conn,
SilcAskPassphrase completion, void *context);
- /* Asks whether the user would like to perform the key agreement protocol.
- This is called after we have received an key agreement packet or an
- reply to our key agreement packet. This returns TRUE if the user wants
- the library to perform the key agreement protocol and FALSE if it is not
- desired (application may start it later by calling the function
- silc_client_perform_key_agreement). If TRUE is returned also the
- `completion' and `context' arguments must be set by the application. */
- SilcBool (*key_agreement)(SilcClient client, SilcClientConnection conn,
- SilcClientEntry client_entry,
- const char *hostname, SilcUInt16 port,
- SilcKeyAgreementCallback *completion,
- void **context);
+ /* Called to indicate that incoming key agreement request has been
+ received. If the application wants to perform key agreement it may
+ call silc_client_perform_key_agreement to initiate key agreementn or
+ silc_client_send_key_agreement to provide connection point to the
+ remote client in case the `hostname' is NULL. If key agreement is
+ not desired this request can be ignored. The `protocol' is either
+ value 0 for TCP or value 1 for UDP. */
+ void (*key_agreement)(SilcClient client, SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ const char *hostname, SilcUInt16 protocol,
+ SilcUInt16 port);
/* Notifies application that file transfer protocol session is being
requested by the remote client indicated by the `client_entry' from
void (*ftp)(SilcClient client, SilcClientConnection conn,
SilcClientEntry client_entry, SilcUInt32 session_id,
const char *hostname, SilcUInt16 port);
-
- /* Delivers SILC session detachment data indicated by `detach_data' to the
- application. If application has issued SILC_COMMAND_DETACH command
- the client session in the SILC network is not quit. The client remains
- in the network but is detached. The detachment data may be used later
- to resume the session in the SILC Network. The appliation is
- responsible of saving the `detach_data', to for example in a file.
-
- The detachment data can be given as argument to the functions
- silc_client_connect_to_server or silc_client_key_exchange when creating
- connection to remote host, inside SilcClientConnectionParams structure.
- If it is provided the client library will attempt to resume the session
- in the network. After the connection is created successfully, the
- application is responsible of setting the user interface for user into
- the same state it was before detaching (showing same channels, channel
- modes, etc). It can do this by fetching the information (like joined
- channels) from the client library. */
- void (*detach)(SilcClient client, SilcClientConnection conn,
- const unsigned char *detach_data,
- SilcUInt32 detach_data_len);
-
- /* Called when the client library is up and running. After this callback
- is called the application may start using the client library APIs. */
- void (*running)(SilcClient client, void *application);
} SilcClientOperations;
/***/
-/****f* silcclient/SilcClientAPI/SilcNicknameFormatParse
- *
- * SYNOPSIS
- *
- * typedef void (*SilcNicknameFormatParse)(const char *nickname,
- * char **ret_nickname);
- *
- * DESCRIPTION
- *
- * A callback function provided by the application for the library in
- * SilcClientParams structure. This function parses the formatted
- * nickname string `nickname' and returns the true nickname to the
- * `ret_nickname' pointer. The library can call this function at
- * any time.
- *
- ***/
-typedef void (*SilcNicknameFormatParse)(const char *nickname,
- char **ret_nickname);
-
/****s* silcclient/SilcClientAPI/SilcClientParams
*
* NAME
in the callbacks to protect application specific data. */
SilcBool threads;
- /* Number of maximum tasks the client library's scheduler can handle.
- If set to zero default value will be used. For WIN32 systems this
- should be set to 64 as it is the hard limit dictated by the WIN32. */
- int task_max;
-
- /* Rekey timeout in seconds. The client will perform rekey in this
- time interval. If set to zero, the default value will be used. */
- unsigned int rekey_secs;
-
- /* Connection authentication method request timeout. If server does not
- reply back the current authentication method when we've requested it
- in this time interval we'll assume the reply will not come at all.
- If set to zero, the default value (2 seconds) will be used. */
- unsigned int connauth_request_secs;
-
/* Nickname format string. This can be used to order the client library
to save the nicknames in the library in a certain format. Since
nicknames are not unique in SILC it is possible to have multiple same
nicknames. Using this format string it is possible to order the library
- to separate the multiple same nicknames from each other. The format
- types are defined below and they can appear in any order in the format
- string. If this is NULL then default format is used which is the
- default nickname without anything else. The string MUST be NULL
- terminated.
+ to separate the multiple same nicknames from each other. If this is
+ empty then default format is used which is the default nickname
+ without anything else. The string MUST be NULL terminated.
Following format types are available:
"%a!%n@%s" (fe. nick@server, 2!nick@server)
"%n@%H" (fe. nick@host.domain.com)
- By default this format is employed to the nicknames by the libary
- only when there appears multiple same nicknames. If the library has
- only one nickname cached the nickname is saved as is and without the
- defined format. If you want always to save the nickname in the defined
- format set the boolean field `nickname_force_format' to value TRUE.
+ Note that there must always be some separator characters around '%n'
+ format. It is not possible to put format characters before or after
+ '%n' without separators (such ash '@'). Also note that the separator
+ character should be a character that cannot be part of normal nickname.
*/
char nickname_format[32];
value. */
SilcBool nickname_force_format;
- /* A callback function provided by the application for the library to
- parse the nickname from the formatted nickname string. Even though
- the libary formats the nicknames the application knows generally the
- format better so this function should be provided for the library
- if the application sets the `nickname_format' field. The library
- will call this to get the true nickname from the provided formatted
- nickname string whenever it needs the true nickname. */
- SilcNicknameFormatParse nickname_parse;
-
- /* If this is set to TRUE then the client will ignore all incoming
- Requested Attributes queries and does not reply anything back. This
- usually leads into situation where server does not anymore send
- the queries after seeing that client does not reply anything back.
- If your application does not support Requested Attributes or you do
- not want to use them set this to TRUE. See SilcAttribute and
- silc_client_attribute_add for more information on attributes. */
- SilcBool ignore_requested_attributes;
-
/* If this is set to TRUE, the silcclient library will not register and
deregister the cipher, pkcs, hash and hmac algorithms. The application
itself will need to handle that. */
* SYNOPSIS
*
* SilcBool silc_client_init(SilcClient client, const char *username,
- * const char *hostname, const char *realname);
+ * const char *hostname, const char *realname,
+ * SilcClientRunning running, void *context);
*
* DESCRIPTION
*
* the client ready to be run. One must call silc_client_run to run the
* client. Returns FALSE if error occurred, TRUE otherwise.
*
- * The `username', `hostname' and `realname' strings must be given and
- * they must be UTF-8 encoded. The `username' is the client's username
- * in the operating system, `hostname' is the client's host name and
- * the `realname' is the user's real name.
+ * The `username' and `hostname' strings must be given and they must be
+ * UTF-8 encoded. The `username' is the client's username in the
+ * operating system, `hostname' is the client's host name and the
+ * `realname' is the user's real name.
+ *
+ * The `running' callback is called after the client is running after
+ * silc_client_run or silc_client_run_one has been called. Application
+ * may start using the Client library API after that. Setting the
+ * callback is optional, but recommended.
*
***/
SilcBool silc_client_init(SilcClient client, const char *username,
- const char *hostname, const char *realname);
+ const char *hostname, const char *realname,
+ SilcClientRunning running, void *context);
/****f* silcclient/SilcClientAPI/silc_client_run
*
*
* DESCRIPTION
*
- * Runs the client. This starts the scheduler from the utility library.
+ * Runs the client. This starts the scheduler from the utility library.
* When this functions returns the execution of the application is over.
* The client must be initialized before calling this.
*
***/
void silc_client_run_one(SilcClient client);
+
/****f* silcclient/SilcClientAPI/silc_client_stop
*
* SYNOPSIS
*
- * void silc_client_stop(SilcClient client);
+ * void silc_client_stop(SilcClient client, SilcClientStopped stopped,
+ * void *context);
*
* 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.
+ * function. All connections that exist in this client must be closed
+ * before calling this function. Connections can be closed by calling
+ * silc_client_close_connection.
+ *
+ * The `stopped' will be called once the client and all connections have
+ * finished. The client may be freed after that. Note that the `stopped'
+ * won't be called before all connections have finished. Setting the
+ * callback is optional.
*
***/
-void silc_client_stop(SilcClient client);
-
+void silc_client_stop(SilcClient client, SilcClientStopped stopped,
+ void *context);
/* Connecting functions */
*
* Client connection parameters. This can be filled by the application
* and given as argument to silc_client_connect_to_server,
- * silc_client_connect_to_client or silc_client_key_exchange.
+ * silc_client_connect_to_client, silc_client_key_exchange or
+ * silc_client_send_key_agreement.
*
* SOURCE
*/
void *auth;
SilcUInt32 auth_len;
- /* If this boolean is set to TRUE then the client's connection to the
- remote host will use UDP instead of TCP. The `local_ip' specifies
- the local IP address used with the UDP connection, and it must be
- non-NULL. If the `local_port' is non-zero it will be used as local
- port with the UDP connection. The remote host will also send packets
- to the specified address and port. */
+ /* If this boolean is set to TRUE then the connection will use UDP instead
+ of TCP. If UDP is set then also the next `local_ip' and `local_port'
+ must be set. */
SilcBool udp;
+
+ /* The `local_ip' specifies the local IP address used with the connection.
+ It must be non-NULL if `udp' boolean is TRUE. If the `local_port' is
+ non-zero it will be used as local port with UDP connection. The remote
+ host will also send packets to the specified address and port. If the
+ `bind_ip' is non-NULL a listener is bound to that address instead of
+ `local_ip'. */
char *local_ip;
+ char *bind_ip;
int local_port;
/* If this boolean is set to TRUE then the key exchange is done with
client, but must be FALSE with server connections. */
SilcBool no_authentication;
- /* The SILC session detachment data that was returned by `detach' client
- operation when the application detached from the network. Application
- is responsible of saving the data and giving it as argument here
- for resuming the session in the SILC network.
-
- If this is provided here the client library will attempt to resume
- the session in the network. After the connection is created
- successfully, the application is responsible of setting the user
- interface for user into the same state it was before detaching (showing
- same channels, channel modes, etc). It can do this by fetching the
- information (like joined channels) from the client library. */
+ /* The SILC session detachment data that was returned in the `command_reply'
+ client operation for SILC_COMMAND_DETACH command. If this is provided
+ here the client library will attempt to resume the session in the network.
+ After the connection is created and the session has been resumed the
+ client will receive SILC_COMMAND_NICK command_reply for the client's
+ nickname in the network and SILC_COMMAND_JOIN command reply for all the
+ channels that the client has joined in the network. It may also receive
+ SILC_COMMAND_UMODE command reply to set user's mode on the network. */
unsigned char *detach_data;
SilcUInt32 detach_data_len;
+ /* Connection timeout. If non-zero, the connection will timeout unless
+ the SILC connection is completed in the specified amount of time. */
+ SilcUInt32 timeout_secs;
+
+ /* Rekey timeout in seconds. The client will perform rekey in this
+ time interval. If set to zero, the default value will be used
+ (3600 seconds, 1 hour). */
+ unsigned int rekey_secs;
+
+ /* If this is set to TRUE then the client will ignore all incoming
+ Requested Attributes queries and does not reply anything back. This
+ usually leads into situation where server does not anymore send
+ the queries after seeing that client does not reply anything back.
+ If your application does not support Requested Attributes or you do
+ not want to use them set this to TRUE. See SilcAttribute and
+ silc_client_attribute_add for more information on attributes. */
+ SilcBool ignore_requested_attributes;
+
} SilcClientConnectionParams;
/***/
*
* SYNOPSIS
*
- * SilcBool
+ * SilcAsyncOperation
* silc_client_connect_to_server(SilcClient client,
* SilcClientConnectionParams *params,
* SilcPublicKey public_key,
+ * SilcPrivateKey private_key,
* char *remote_host, int port,
* SilcClientConnectCallback callback,
* void *context);
* the silc_client_key_exchange after creating the connection to start
* key exchange and authentication with the server.
*
- * Returns when connecting is started and FALSE if connection was not
- * created at all.
+ * Returns SilcAsyncOperation which can be used to cancel the connecting,
+ * or NULL on error. Note that the returned pointer becomes invalid
+ * after the `callback' is called.
*
***/
-SilcBool silc_client_connect_to_server(SilcClient client,
- SilcClientConnectionParams *params,
- SilcPublicKey public_key,
- SilcPrivateKey private_key,
- char *remote_host, int port,
- SilcClientConnectCallback callback,
- void *context);
+SilcAsyncOperation
+silc_client_connect_to_server(SilcClient client,
+ SilcClientConnectionParams *params,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
+ char *remote_host, int port,
+ SilcClientConnectCallback callback,
+ void *context);
/****f* silcclient/SilcClientAPI/silc_client_connect_to_client
*
* SYNOPSIS
*
- * SilcBool
+ * SilcAsyncOperation
* silc_client_connect_to_client(SilcClient client,
* SilcClientConnectionParams *params,
* SilcPublicKey public_key,
+ * SilcPrivateKey private_key,
* char *remote_host, int port,
* SilcClientConnectCallback callback,
* void *context);
* the silc_client_key_exchange after creating the connection to start
* key exchange with the client.
*
- * Returns when connecting is started and FALSE if connection was not
- * created at all.
+ * Returns SilcAsyncOperation which can be used to cancel the connecting,
+ * or NULL on error. Note that the returned pointer becomes invalid
+ * after the `callback' is called.
*
***/
-SilcBool silc_client_connect_to_client(SilcClient client,
- SilcClientConnectionParams *params,
- SilcPublicKey public_key,
- SilcPrivateKey private_key,
- char *remote_host, int port,
- SilcClientConnectCallback callback,
- void *context);
+SilcAsyncOperation
+silc_client_connect_to_client(SilcClient client,
+ SilcClientConnectionParams *params,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
+ char *remote_host, int port,
+ SilcClientConnectCallback callback,
+ void *context);
/****f* silcclient/SilcClientAPI/silc_client_key_exchange
*
* SYNOPSIS
*
- * SilcBool
+ * SilcAsyncOperation
* silc_client_key_exchange(SilcClient client,
* SilcClientConnectionParams *params,
* SilcPublicKey public_key,
* disconnects. The `conn_type' is the type of session this is going to
* be.
*
- * Returns TRUE when key exchange is started and FALSE if it is not started
- * at all.
+ * Returns SilcAsyncOperation which can be used to cancel the connecting,
+ * or NULL on error. Note that the returned pointer becomes invalid
+ * after the `callback' is called.
*
* EXAMPLE
*
* }
*
***/
-SilcBool silc_client_key_exchange(SilcClient client,
- SilcClientConnectionParams *params,
- SilcPublicKey public_key,
- SilcPrivateKey private_key,
- SilcStream stream,
- SilcConnectionType conn_type,
- SilcClientConnectCallback callback,
- void *context);
+SilcAsyncOperation
+silc_client_key_exchange(SilcClient client,
+ SilcClientConnectionParams *params,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
+ SilcStream stream,
+ SilcConnectionType conn_type,
+ SilcClientConnectCallback callback,
+ void *context);
/****f* silcclient/SilcClientAPI/silc_client_close_connection
*
* const char *cipher,
* const char *hmac,
* unsigned char *key,
- * SilcUInt32 key_len,
- * SilcBool generate_key,
- * SilcBool responder);
+ * SilcUInt32 key_len);
*
* 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' 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.
+ * Adds a static 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'. The `key' can
+ * be for example a pre-shared-key, passphrase or similar shared secret
+ * string. 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
- * FALSE the client is being the sender (or negotiator) of the private
- * key.
+ * If the private message key is added to client without first receiving
+ * a request for it from the remote `client_entry' this function will
+ * send the request to `client_entry'. Note that, the actual key is
+ * not sent to the network.
*
* 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.
+ * session keys. Setting the private key, however, increases the security.
*
* Returns FALSE if the key is already set for the `client_entry', TRUE
* otherwise.
const char *cipher,
const char *hmac,
unsigned char *key,
- SilcUInt32 key_len,
- SilcBool generate_key,
- SilcBool responder);
+ SilcUInt32 key_len);
/****f* silcclient/SilcClientAPI/silc_client_add_private_message_key_ske
*
* 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
+ * 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' and `hmac' SHOULD be provided as it is
+ * the key material. The `cipher' and `hmac' SHOULD be provided as it is
* negotiated also in the SKE protocol.
*
***/
SilcClientEntry client_entry,
const char *cipher,
const char *hmac,
- SilcSKEKeyMaterial key,
- SilcBool responder);
+ SilcSKEKeyMaterial key);
/****f* silcclient/SilcClientAPI/silc_client_del_private_message_key
*
SilcClientConnection conn,
SilcUInt32 *key_count);
-/****f* silcclient/SilcClientAPI/silc_client_send_private_message_key_request
- *
- * SYNOPSIS
- *
- * SilcBool
- * silc_client_send_private_message_key_request(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry);
- *
- * DESCRIPTION
- *
- * This function can be used to send an private message key indicator
- * request to the remote client indicated by 'client_entry'. This can
- * be used when setting a static or pre-shared private message key.
- * The sender of this packet is the initiator and must set the 'responder'
- * argument in silc_client_add_private_message_key function to FALSE.
- * The receiver of this indicator request must set it to TRUE, if the
- * receiver decides to set a private message key. By using this
- * function applications may automate initiator/responder setting in
- * private message key functions, without asking from user which one is
- * the initiator and which one is responder.
- *
- * NOTES
- *
- * The sender of this packet must set the private message key for
- * 'client_entry' before calling this function. The 'responder'
- * argument MUST be set to FALSE when setting the key.
- *
- ***/
-SilcBool
-silc_client_send_private_message_key_request(SilcClient client,
- SilcClientConnection conn,
- SilcClientEntry client_entry);
-
/****f* silcclient/SilcClientAPI/silc_client_free_private_message_keys
*
* SYNOPSIS
* DESCRIPTION
*
* Returns list of private keys associated to the `channel'. The caller
- * must free the returned list. The pointers in the list may be
- * used to delete the specific key by giving the pointer as argument to the
- * function silc_client_del_channel_private_key. Each entry in the list
- * is SilcChannelPrivateKey.
+ * must free the returned list with silc_dlist_uninit. The pointers in
+ * the list may be used to delete the specific key by giving the pointer
+ * as argument to the function silc_client_del_channel_private_key. Each
+ * entry in the list is SilcChannelPrivateKey.
*
***/
SilcDList silc_client_list_channel_private_keys(SilcClient client,
SilcChannelPrivateKey key);
-/* Key Agreement routines (client_keyagr.c) */
+/* Key Agreement routines */
/****f* silcclient/SilcClientAPI/silc_client_send_key_agreement
*
* void silc_client_send_key_agreement(SilcClient client,
* SilcClientConnection conn,
* SilcClientEntry client_entry,
- * char *hostname,
- * int port,
- * SilcUInt32 timeout_secs,
+ * SilcClientConnectionParams *params,
+ * SilcPublicKey public_key,
+ * SilcPrivateKey private_key,
* 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).
+ * `client_entry'.
+ *
+ * If `params' is non-NULL and it has the `local_ip' and `local_port' set
+ * the caller will provide the connection endpoint for the key agreement
+ * connection. The `bind_ip' can be used to bind to that IP instead of
+ * `local_ip'. If the `udp' is set to TRUE the connection will be UDP
+ * instead of TCP. Caller may also set the `repository', `verify_notfound'
+ * and `timeout_secs' fields in `params'. Other fields are ignored.
+ * If `params' is NULL, then the `client_entry' is expected to provide
+ * the connection endpoint for us. It is recommended the `timeout_secs'
+ * is specified in case the remote client does not reply anything to
+ * the request.
+ *
+ * The `public_key' and `private_key' is our identity in the key agreement.
+ *
+ * In case we do not provide the connection endpoint, we will receive
+ * the `key_agreement' client operation when the remote send its own
+ * key agreement request packet. We may then there start the key
+ * agreement with silc_client_perform_key_agreement. If we provided the
+ * the connection endpoint, the client operation will not be called.
+ *
+ * There can be only one active key agreement for `client_entry'. Old
+ * key agreement may be aborted by calling silc_client_abort_key_agreement.
*
- * 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: If the `hostname' and the `port' was not provided the `completion'
- * will not be called at all since this does nothing more than sending
- * a packet to the remote host.
+ * EXAMPLE
*
- * 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.
+ * // Send key agreement request (we don't provide connection endpoint)
+ * silc_client_send_key_agreement(client, conn, remote_client,
+ * NULL, public_key, private_key,
+ * my_keyagr_completion, my_context);
+ *
+ * // Another example where we provide connection endpoint (TCP).
+ * SilcClientConnectionParams params;
+ * memset(¶ms, 0, sizeof(params));
+ * params.local_ip = local_ip;
+ * params.local_port = local_port;
+ * params.timeout_secs = 60;
+ * silc_client_send_key_agreement(client, conn, remote_client,
+ * ¶ms, public_key, private_key,
+ * my_keyagr_completion, my_context);
*
***/
void silc_client_send_key_agreement(SilcClient client,
SilcClientConnection conn,
SilcClientEntry client_entry,
- const char *hostname,
- const char *bindhost,
- int port,
- SilcUInt32 timeout_secs,
+ SilcClientConnectionParams *params,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
SilcKeyAgreementCallback completion,
void *context);
* silc_client_perform_key_agreement(SilcClient client,
* SilcClientConnection conn,
* SilcClientEntry client_entry,
- * char *hostname,
- * int port,
+ * SilcClientConnectionParams *params,
+ * SilcPublicKey public_key,
+ * SilcPrivateKey private_key,
+ * 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.
+ * Performs the key agreement protocol. Application may use this to
+ * initiate the key agreement protocol. Usually this is called after
+ * receiving the `key_agreement' client operation.
*
* The `hostname' is the remote hostname (or IP address) and the `port'
- * is the remote port. The `completion' callback with the `context' will
+ * 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.
+ * The `params' is connection parameters and it may be used to define
+ * the key agreement connection related parameters. It may be NULL.
*
***/
void silc_client_perform_key_agreement(SilcClient client,
SilcClientConnection conn,
SilcClientEntry client_entry,
- char *hostname,
- int port,
+ SilcClientConnectionParams *params,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
+ char *hostname, int port,
SilcKeyAgreementCallback completion,
void *context);
-/****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement_fd
+/****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement_stream
*
* SYNOPSIS
*
* void
- * silc_client_perform_key_agreement_fd(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry,
- * int sock,
- * char *hostname,
- * SilcKeyAgreementCallback completion,
- * void *context);
+ * silc_client_perform_key_agreement_stream(
+ * SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * SilcClientConnectionParams *params,
+ * SilcPublicKey public_key,
+ * SilcPrivateKey private_key,
+ * SilcStream stream,
+ * 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.
+ * Same as silc_client_perform_key_agreement but the caller has created
+ * the connection. The `stream' is the created connection.
*
***/
-void silc_client_perform_key_agreement_fd(SilcClient client,
- SilcClientConnection conn,
- SilcClientEntry client_entry,
- int sock,
- char *hostname,
- SilcKeyAgreementCallback completion,
- void *context);
+void
+silc_client_perform_key_agreement_stream(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ SilcClientConnectionParams *params,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
+ SilcStream stream,
+ SilcKeyAgreementCallback completion,
+ void *context);
/****f* silcclient/SilcClientAPI/silc_client_abort_key_agreement
*
SilcClientConnection conn,
char *message);
-/****f* silcclient/SilcClientAPI/SilcConnectionAuthRequest
- *
- * SYNOPSIS
- *
- * typedef void (*SilcConnectionAuthRequest)(SilcClient client,
- * SilcClientConnection conn,
- * SilcAuthMethod auth_meth,
- * void *context);
- *
- * DESCRIPTION
- *
- * Connection authentication method request callback. This is called
- * by the client library after it has received the authentication method
- * that the application requested by calling the function
- * silc_client_request_authentication_method.
- *
- ***/
-typedef void (*SilcConnectionAuthRequest)(SilcClient client,
- SilcClientConnection conn,
- SilcAuthMethod auth_meth,
- void *context);
-
-/****f* silcclient/SilcClientAPI/silc_client_request_authentication_method
- *
- * SYNOPSIS
- *
- * void
- * silc_client_request_authentication_method(SilcClient client,
- * SilcClientConnection conn,
- * SilcConnectionAuthRequest
- * callback,
- * void *context);
- *
- * DESCRIPTION
- *
- * This function can be used to request the current authentication method
- * from the server. This may be called when connecting to the server
- * and the client library requests the authentication data from the
- * application. If the application does not know the current authentication
- * method it can request it from the server using this function.
- * The `callback' with `context' will be called after the server has
- * replied back with the current authentication method.
- *
- ***/
-void
-silc_client_request_authentication_method(SilcClient client,
- SilcClientConnection conn,
- SilcConnectionAuthRequest callback,
- void *context);
-
/****d* silcclient/SilcClientAPI/SilcClientMonitorStatus
*
* NAME
***/
SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
+/****f* silcclient/SilcClientAPI/silc_client_nickname_format
+ *
+ * SYNOPSIS
+ *
+ * SilcClientEntry
+ * silc_client_nickname_format(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * SilcBool priority);
+ *
+ * DESCRIPTION
+ *
+ * Formats the nickname of `client_entry' according to the nickname
+ * formatting rules set in SilcClientParams. If the `priority' is TRUE
+ * then the `client_entry' will always get the unformatted nickname.
+ * If FALSE and there are more than one same nicknames in the client
+ * the nickname will be formatted.
+ *
+ * This returns NULL on error. Otherwise, the client entry that was
+ * formatted is returned. If `priority' is FALSE this always returns
+ * the `client_entry'. If it is TRUE, this may return the client entry
+ * that was formatted after giving the `client_entry' the unformatted
+ * nickname.
+ *
+ * Usually application does not need to call this function, as the library
+ * automatically formats nicknames. However, if application wants to
+ * for example force the `client_entry' to always have the unformatted
+ * nickname it may call this function to do so.
+ *
+ ***/
+SilcClientEntry silc_client_nickname_format(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ SilcBool priority);
+
#ifdef __cplusplus
}
#endif