5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2006 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcclient/Client Library Interface
24 * This interface defines the SILC Client Library API for the application.
25 * The client operations are defined first. These are callback functions that
26 * the application MUST implement since the library may call the functions
27 * at any time. At the end of file is the API for the application that
28 * it can use from the library. This is the only file that the application
29 * may include from the SIlC Client Library.
31 * o SILC Client Operations
33 * These functions must be implemented by the application calling the SILC
34 * client library. The client library can call these functions at any time.
36 * To use this structure: define a static SilcClientOperations variable,
37 * fill it and pass its pointer to silc_client_alloc function.
39 * o SILC Client Library API
41 * This is the API that is published by the SILC Client Library for the
42 * applications. These functions are implemented in the SILC Client Library.
43 * Application may freely call these functions from the library.
55 #include "silcclient_entry.h"
57 /* General definitions */
59 /****d* silcclient/SilcClientAPI/SilcClientConnectionStatus
63 * typedef enum { ... } SilcClientConnectionStatus
67 * This type is returned to the `connect' client operation to indicate
68 * the status of the created connection. It can indicate if it was
69 * successful or whether an error occurred.
74 SILC_CLIENT_CONN_SUCCESS, /* Successfully connected */
75 SILC_CLIENT_CONN_SUCCESS_RESUME, /* Successfully connected and
76 resumed old detached session */
77 SILC_CLIENT_CONN_DISCONNECTED, /* Remote host disconnected */
78 SILC_CLIENT_CONN_ERROR, /* Error occurred during connecting */
79 SILC_CLIENT_CONN_ERROR_KE, /* Key Exchange failed */
80 SILC_CLIENT_CONN_ERROR_AUTH, /* Authentication failed */
81 SILC_CLIENT_CONN_ERROR_RESUME, /* Resuming failed */
82 SILC_CLIENT_CONN_ERROR_TIMEOUT, /* Timeout during connecting */
83 } SilcClientConnectionStatus;
86 /****f* silcclient/SilcClientAPI/SilcClientConnectCallback
90 * void (*SilcClientConnectCallback)(SilcClient client,
91 * SilcClientConnection conn,
92 * SilcClientConnectionStatus status,
94 * const char *message,
99 * Connect callbak given as argument to silc_client_connect_to_server,
100 * silc_client_connect_to_client and silc_client_key_exchange functions.
101 * It is called to indicate the status of the connection, indicated
102 * by the `status'. It is called after the connection has been
103 * established to the remote host and when connection is disconnected
104 * by the remote host. The `context' is the context given as argument
105 * to the connecting function.
107 * When the `status' is SILC_CLIENT_CONN_DISCONNECTED the `error' will
108 * indicate the reason for disconnection. If the `message' is non-NULL
109 * it delivers error or disconnection message.
112 typedef void (*SilcClientConnectCallback)(SilcClient client,
113 SilcClientConnection conn,
114 SilcClientConnectionStatus status,
119 /****s* silcclient/SilcClientAPI/SilcClient
123 * typedef struct SilcClientStruct { ... } *SilcClient
127 * This is the actual SILC Client structure which represents one
128 * SILC Client. It is allocated with the silc_client_alloc function
129 * and given as argument to all SILC Client Library functions. It
130 * is initialized with silc_client_init function, and freed with
131 * silc_client_free function.
133 * This context represents the client. Each connection to remote server
134 * is represented by SilcClientConnection context.
138 struct SilcClientStruct {
139 char *username; /* Username */
140 char *hostname; /* hostname */
141 char *realname; /* Real name */
142 SilcSchedule schedule; /* Client scheduler */
143 SilcRng rng; /* Random number generator */
144 void *application; /* Application specific context, set with
145 silc_client_alloc. */
147 /* Internal data for client library. Application cannot access this. */
148 SilcClientInternal internal;
152 /****s* silcclient/SilcClientAPI/SilcClientConnection
156 * typedef struct SilcClientConnectionStruct { ... }
157 * *SilcClientConnection
161 * This structure represents a connection. It is allocated and freed by
162 * the library. It is returned to application in SilcClientConnectCallback.
163 * It includes all the important data for the session such as local
164 * client entry (which includes current nickname), local and remote IDs,
165 * and other information. All strings in the structure are UTF-8 encoded.
169 struct SilcClientConnectionStruct {
170 SilcClientEntry local_entry; /* Our own Client Entry */
171 SilcClientID *local_id; /* Our current Client ID */
173 char *remote_host; /* Remote host name */
174 int remote_port; /* Remote port */
175 SilcID remote_id; /* Remote ID */
177 SilcChannelEntry current_channel; /* Current joined channel */
178 SilcPublicKey public_key; /* Public key used in this connection */
179 SilcPrivateKey private_key; /* Private key */
180 SilcPacketStream stream; /* Connection to remote host */
181 SilcConnectionType type; /* Connection type */
182 SilcClientConnectCallback callback; /* Connection callback */
183 void *callback_context; /* Connection context */
184 SilcClient client; /* Pointer back to SilcClient */
186 /* Application specific data. Application may set here whatever it wants. */
189 /* Internal data for client library. Application cannot access this. */
190 SilcClientConnectionInternal internal;
194 /****s* silcclient/SilcClientAPI/SilcChannelUser
198 * typedef struct SilcChannelUserStruct { ... } *SilcChannelUser
202 * This structure represents a client that has joined to a channel.
203 * It shows the client and the channel and the client's mode (channel
204 * user mode) on the channel.
208 struct SilcChannelUserStruct {
209 SilcClientEntry client; /* Client joined on channel */
210 SilcUInt32 mode; /* mode, ChannelUserModes */
211 SilcChannelEntry channel; /* The channel user has joined */
213 /* Application specific data. Application may set here whatever it wants. */
218 /****s* silcclient/SilcClientAPI/SilcClientStats
222 * typedef struct { ... } SilcClientStats;
226 * This structure holds SILC network statistics returned by the
227 * SILC_COMMAND_STATS command reply to the application.
232 SilcUInt32 starttime; /* SILC server start time */
233 SilcUInt32 uptime; /* SILC server uptime*/
234 SilcUInt32 my_clients; /* Number of clients in the server */
235 SilcUInt32 my_channels; /* Number of channel in the server */
236 SilcUInt32 my_server_ops; /* Number of server operators in the server */
237 SilcUInt32 my_router_ops; /* Number of router operators in the router */
238 SilcUInt32 cell_clients; /* Number of clients in the cell */
239 SilcUInt32 cell_channels; /* Number of channels in the cell */
240 SilcUInt32 cell_servers; /* Number of server in the cell */
241 SilcUInt32 clients; /* All clients in SILC network */
242 SilcUInt32 channels; /* All channels in SILC network */
243 SilcUInt32 servers; /* All servers in SILC network */
244 SilcUInt32 routers; /* All routers in SILC network */
245 SilcUInt32 server_ops; /* All server operators in SILC network */
246 SilcUInt32 router_ops; /* All router operators in SILC network */
250 /****d* silcclient/SilcClientAPI/SilcKeyAgreementStatus
254 * typedef enum { ... } SilcKeyAgreementStatus;
258 * Key agreement status types indicating the status of the key
259 * agreement protocol. These types are returned to the application
260 * in the SilcKeyAgreementCallback callback function.
265 SILC_KEY_AGREEMENT_OK, /* Everything is Ok */
266 SILC_KEY_AGREEMENT_ERROR, /* Unknown error occurred */
267 SILC_KEY_AGREEMENT_FAILURE, /* The protocol failed */
268 SILC_KEY_AGREEMENT_TIMEOUT, /* The protocol timeout */
269 SILC_KEY_AGREEMENT_ABORTED, /* The protocol aborted */
270 SILC_KEY_AGREEMENT_ALREADY_STARTED, /* Already started */
271 SILC_KEY_AGREEMENT_SELF_DENIED, /* Negotiationg with itself denied */
272 SILC_KEY_AGREEMENT_NO_MEMORY, /* System out of memory */
273 } SilcKeyAgreementStatus;
276 /****f* silcclient/SilcClientAPI/SilcKeyAgreementCallback
280 * typedef void (*SilcKeyAgreementCallback)(SilcClient client,
281 * SilcClientConnection conn,
282 * SilcClientEntry client_entry,
283 * SilcKeyAgreementStatus status,
284 * SilcSKEKeyMaterial *key,
289 * Key agreement callback that is called after the key agreement protocol
290 * has been performed. This is called also if error occurred during the
291 * key agreement protocol. The `key' is the allocated key material and
292 * the caller is responsible of freeing it. The `key' is NULL if error
293 * has occurred. The application can freely use the `key' to whatever
294 * purpose it needs. See lib/silcske/silcske.h for the definition of
295 * the SilcSKEKeyMaterial structure.
298 typedef void (*SilcKeyAgreementCallback)(SilcClient client,
299 SilcClientConnection conn,
300 SilcClientEntry client_entry,
301 SilcKeyAgreementStatus status,
302 SilcSKEKeyMaterial *key,
305 /****s* silcclient/SilcClientAPI/SilcPrivateMessageKeys
309 * typedef struct { ... } SilcPrivateMessageKeys;
313 * Structure to hold the list of private message keys. The list of these
314 * structures is returned by the silc_client_list_private_message_keys
320 SilcClientEntry client_entry; /* The remote client entry */
321 char *cipher; /* The cipher name */
322 unsigned char *key; /* The original key, If the appliation
323 provided it. This is NULL if the
324 library generated the key or if
325 the SKE key material was used. */
326 SilcUInt32 key_len; /* The key length */
327 } *SilcPrivateMessageKeys;
330 /****s* silcclient/SilcClientAPI/SilcChannelPrivateKey
334 * typedef struct SilcChannelPrivateKeyStruct { ... }
335 * *SilcChannelPrivateKey;
339 * Structure to hold one channel private key. The array of this structure
340 * is returned by silc_client_list_channel_private_keys function.
344 struct SilcChannelPrivateKeyStruct {
345 char *name; /* Application given name */
346 SilcCipher cipher; /* The cipher and key */
347 SilcHmac hmac; /* The HMAC and hmac key */
351 /****f* silcclient/SilcClientAPI/SilcAskPassphrase
355 * typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
356 * SilcUInt32 passphrase_len,
361 * Ask passphrase callback. This is called by the application when the
362 * library calls `ask_passphrase' client operation. The callback delivers
363 * the passphrase to the library. The passphrases in SILC protocol
364 * MUST be in UTF-8 encoding, therefore the `passphrase' SHOULD be UTF-8
365 * encoded, and if it is not then library will attempt to encode it.
368 typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
369 SilcUInt32 passphrase_len,
372 /****f* silcclient/SilcClientAPI/SilcVerifyPublicKey
376 * typedef void (*SilcVerifyPublicKey)(SilcBool success, void *context);
380 * Public key (or certificate) verification callback. This is called
381 * by the application to indicate that the public key verification was
382 * either success or failure.
385 typedef void (*SilcVerifyPublicKey)(SilcBool success, void *context);
387 /****f* silcclient/SilcClientAPI/SilcGetAuthMeth
391 * typedef void (*SilcGetAuthMeth)(SilcBool success,
392 * SilcAuthMethod auth_meth,
393 * void *auth, SilcUInt32 auth_len,
398 * Authentication method resolving callback. This is called by the
399 * application to return the resolved authentication method. The client
400 * library has called the get_auth_method client operation and given
401 * this function pointer as argument. The `success' will indicate whether
402 * the authentication method could be resolved. The `auth_meth' is the
403 * resolved authentication method. The `auth_data' and the `auth_data_len'
404 * are the resolved authentication data. The `context' is the libary's
405 * context sent to the get_auth_method client operation.
408 typedef void (*SilcGetAuthMeth)(SilcBool success,
409 SilcAuthMethod auth_meth,
410 void *auth, SilcUInt32 auth_len,
413 /****d* silcclient/SilcClientAPI/SilcClientMessageType
417 * typedef enum { ... } SilcClientMessageType;
421 * Different message types for `say' client operation. The application
422 * may filter the message sent by the library according this type.
427 SILC_CLIENT_MESSAGE_INFO, /* Informational */
428 SILC_CLIENT_MESSAGE_WARNING, /* Warning */
429 SILC_CLIENT_MESSAGE_ERROR, /* Error */
430 SILC_CLIENT_MESSAGE_AUDIT, /* Auditable */
431 } SilcClientMessageType;
434 /****s* silcclient/SilcClientAPI/SilcClientOperations
438 * typedef struct { ... } SilcClientOperations;
442 * SILC Client Operations. These must be implemented by the application.
443 * The Client library may call any of these routines at any time. The
444 * routines are used to deliver certain information to the application
445 * or from the application to the client library.
450 /* Message sent to the application by library. `conn' associates the
451 message to a specific connection. `conn', however, may be NULL.
452 The `type' indicates the type of the message sent by the library.
453 The application can for example filter the message according the
454 type. The variable argument list is arguments to the formatted
455 message that `msg' may be. */
456 void (*say)(SilcClient client, SilcClientConnection conn,
457 SilcClientMessageType type, char *msg, ...);
459 /* Message for a channel. The `sender' is the sender of the message
460 The `channel' is the channel. The `message' is the message. Note
461 that `message' maybe NULL. The `flags' indicates message flags
462 and it is used to determine how the message can be interpreted
463 (like it may tell the message is multimedia message). */
464 void (*channel_message)(SilcClient client, SilcClientConnection conn,
465 SilcClientEntry sender, SilcChannelEntry channel,
466 SilcMessagePayload payload,
467 SilcChannelPrivateKey key, SilcMessageFlags flags,
468 const unsigned char *message,
469 SilcUInt32 message_len);
471 /* Private message to the client. The `sender' is the sender of the
472 message. The message is `message'and maybe NULL. The `flags'
473 indicates message flags and it is used to determine how the message
474 can be interpreted (like it may tell the message is multimedia
476 void (*private_message)(SilcClient client, SilcClientConnection conn,
477 SilcClientEntry sender, SilcMessagePayload payload,
478 SilcMessageFlags flags, const unsigned char *message,
479 SilcUInt32 message_len);
481 /* Notify message to the client. The notify arguments are sent in the
482 same order as servers sends them. The arguments are same as received
483 from the server except for ID's. If ID is received application receives
484 the corresponding entry to the ID. For example, if Client ID is received
485 application receives SilcClientEntry. Also, if the notify type is
486 for channel the channel entry is sent to application (even if server
487 does not send it because client library gets the channel entry from
488 the Channel ID in the packet's header). */
489 void (*notify)(SilcClient client, SilcClientConnection conn,
490 SilcNotifyType type, ...);
492 /* Command handler. This function is called always after application has
493 called a command. It will be called to indicate that the command
494 was processed. It will also be called if error occurs while processing
495 the command. The `success' indicates whether the command was sent
496 or if error occurred. The `status' indicates the actual error.
497 The `argc' and `argv' are the command line arguments sent to the
498 command by application. Note that, this is not reply to the command
499 from server, this is merely and indication to application that the
500 command was processed. */
501 void (*command)(SilcClient client, SilcClientConnection conn,
502 SilcBool success, SilcCommand command, SilcStatus status,
503 SilcUInt32 argc, unsigned char **argv);
505 /* Command reply handler. This function is called always in the command reply
506 function. If error occurs it will be called as well. Normal scenario
507 is that it will be called after the received command data has been parsed
508 and processed. The function is used to pass the received command data to
511 `conn' is the associated client connection. `cmd_payload' is the command
512 payload data received from server and it can be ignored. It is provided
513 if the application would like to re-parse the received command data,
514 however, it must be noted that the data is parsed already by the library
515 thus the payload can be ignored. `success' is FALSE if error occurred.
516 In this case arguments are not sent to the application. The `status' is
517 the command reply status server returned. The `command' is the command
518 reply being processed. The function has variable argument list and each
519 command defines the number and type of arguments it passes to the
520 application (on error they are not sent).
522 The arguments are sent in the same order as servers sends them. The
523 arguments are same as received from the server except for ID's. If
524 ID is received application receives the corresponding entry to the
525 ID. For example, if Client ID is receives application receives
527 void (*command_reply)(SilcClient client, SilcClientConnection conn,
528 SilcCommand command, SilcStatus status,
529 SilcStatus error, va_list ap);
531 /* Find authentication method and authentication data by hostname and
532 port. The hostname may be IP address as well. When the authentication
533 method has been resolved the `completion' callback with the found
534 authentication method and authentication data is called. The `conn'
536 void (*get_auth_method)(SilcClient client, SilcClientConnection conn,
537 char *hostname, SilcUInt16 port,
538 SilcGetAuthMeth completion, void *context);
540 /* Verifies received public key. The `conn_type' indicates which entity
541 (server, client etc.) has sent the public key. If user decides to trust
542 the application may save the key as trusted public key for later
543 use. The `completion' must be called after the public key has been
545 void (*verify_public_key)(SilcClient client, SilcClientConnection conn,
546 SilcConnectionType conn_type,
547 SilcPublicKey public_key,
548 SilcVerifyPublicKey completion, void *context);
550 /* Ask (interact, that is) a passphrase from user. The passphrase is
551 returned to the library by calling the `completion' callback with
552 the `context'. The returned passphrase SHOULD be in UTF-8 encoded,
553 if not then the library will attempt to encode. */
554 void (*ask_passphrase)(SilcClient client, SilcClientConnection conn,
555 SilcAskPassphrase completion, void *context);
557 /* Asks whether the user would like to perform the key agreement protocol.
558 This is called after we have received an key agreement packet or an
559 reply to our key agreement packet. This returns TRUE if the user wants
560 the library to perform the key agreement protocol and FALSE if it is not
561 desired (application may start it later by calling the function
562 silc_client_perform_key_agreement). If TRUE is returned also the
563 `completion' and `context' arguments must be set by the application. */
564 SilcBool (*key_agreement)(SilcClient client, SilcClientConnection conn,
565 SilcClientEntry client_entry,
566 const char *hostname, SilcUInt16 port,
567 SilcKeyAgreementCallback *completion,
570 /* Notifies application that file transfer protocol session is being
571 requested by the remote client indicated by the `client_entry' from
572 the `hostname' and `port'. The `session_id' is the file transfer
573 session and it can be used to either accept or reject the file
574 transfer request, by calling the silc_client_file_receive or
575 silc_client_file_close, respectively. */
576 void (*ftp)(SilcClient client, SilcClientConnection conn,
577 SilcClientEntry client_entry, SilcUInt32 session_id,
578 const char *hostname, SilcUInt16 port);
580 /* Delivers SILC session detachment data indicated by `detach_data' to the
581 application. If application has issued SILC_COMMAND_DETACH command
582 the client session in the SILC network is not quit. The client remains
583 in the network but is detached. The detachment data may be used later
584 to resume the session in the SILC Network. The appliation is
585 responsible of saving the `detach_data', to for example in a file.
587 The detachment data can be given as argument to the functions
588 silc_client_connect_to_server or silc_client_key_exchange when creating
589 connection to remote host, inside SilcClientConnectionParams structure.
590 If it is provided the client library will attempt to resume the session
591 in the network. After the connection is created successfully, the
592 application is responsible of setting the user interface for user into
593 the same state it was before detaching (showing same channels, channel
594 modes, etc). It can do this by fetching the information (like joined
595 channels) from the client library. */
596 void (*detach)(SilcClient client, SilcClientConnection conn,
597 const unsigned char *detach_data,
598 SilcUInt32 detach_data_len);
600 /* Called when the client library is up and running. After this callback
601 is called the application may start using the client library APIs. */
602 void (*running)(SilcClient client, void *application);
603 } SilcClientOperations;
606 /****f* silcclient/SilcClientAPI/SilcNicknameFormatParse
610 * typedef void (*SilcNicknameFormatParse)(const char *nickname,
611 * char **ret_nickname);
615 * A callback function provided by the application for the library in
616 * SilcClientParams structure. This function parses the formatted
617 * nickname string `nickname' and returns the true nickname to the
618 * `ret_nickname' pointer. The library can call this function at
622 typedef void (*SilcNicknameFormatParse)(const char *nickname,
623 char **ret_nickname);
625 /****s* silcclient/SilcClientAPI/SilcClientParams
629 * typedef struct { ... } SilcClientParams;
633 * Client parameters. This can be filled with proper values and
634 * given as argument to the silc_client_alloc function. The structure
635 * hold various parameters which affects the function of the client.
640 /* If this boolean is set to TRUE then the client library will use
641 threads. Any of the callback functions in the SilcClientOperations
642 and other callbacks may be called at any time in a thread. The
643 application may need to employ appropriate concurrency control
644 in the callbacks to protect application specific data. */
647 /* Rekey timeout in seconds. The client will perform rekey in this
648 time interval. If set to zero, the default value will be used. */
649 unsigned int rekey_secs;
651 /* Connection authentication method request timeout. If server does not
652 reply back the current authentication method when we've requested it
653 in this time interval we'll assume the reply will not come at all.
654 If set to zero, the default value (2 seconds) will be used. */
655 unsigned int connauth_request_secs;
657 /* Nickname format string. This can be used to order the client library
658 to save the nicknames in the library in a certain format. Since
659 nicknames are not unique in SILC it is possible to have multiple same
660 nicknames. Using this format string it is possible to order the library
661 to separate the multiple same nicknames from each other. The format
662 types are defined below and they can appear in any order in the format
663 string. If this is NULL then default format is used which is the
664 default nickname without anything else. The string MUST be NULL
667 Following format types are available:
669 %n nickname - the real nickname returned by the server (mandatory)
670 %h hostname - the stripped hostname of the client
671 %H full hostname - the full hostname of the client
672 %s server name - the server name the client is connected
673 %S full server - the full server name the client is connected
674 %a number - ascending number in case there are several
675 same nicknames (fe. nick@host and nick@host2)
677 Example format strings: "%n@%h%a" (fe. nick@host, nick@host2)
678 "%a!%n@%s" (fe. nick@server, 2!nick@server)
679 "%n@%H" (fe. nick@host.domain.com)
681 By default this format is employed to the nicknames by the libary
682 only when there appears multiple same nicknames. If the library has
683 only one nickname cached the nickname is saved as is and without the
684 defined format. If you want always to save the nickname in the defined
685 format set the boolean field `nickname_force_format' to value TRUE.
687 char nickname_format[32];
689 /* If this is set to TRUE then the `nickname_format' is employed to all
690 saved nicknames even if there are no multiple same nicknames in the
691 cache. By default this is FALSE, which means that the `nickname_format'
692 is employed only if the library will receive a nickname that is
693 already saved in the cache. It is recommended to leave this to FALSE
695 SilcBool nickname_force_format;
697 /* A callback function provided by the application for the library to
698 parse the nickname from the formatted nickname string. Even though
699 the libary formats the nicknames the application knows generally the
700 format better so this function should be provided for the library
701 if the application sets the `nickname_format' field. The library
702 will call this to get the true nickname from the provided formatted
703 nickname string whenever it needs the true nickname. */
704 SilcNicknameFormatParse nickname_parse;
706 /* If this is set to TRUE then the client will ignore all incoming
707 Requested Attributes queries and does not reply anything back. This
708 usually leads into situation where server does not anymore send
709 the queries after seeing that client does not reply anything back.
710 If your application does not support Requested Attributes or you do
711 not want to use them set this to TRUE. See SilcAttribute and
712 silc_client_attribute_add for more information on attributes. */
713 SilcBool ignore_requested_attributes;
715 /* If this is set to TRUE, the silcclient library will not register and
716 deregister the cipher, pkcs, hash and hmac algorithms. The application
717 itself will need to handle that. */
718 SilcBool dont_register_crypto_library;
724 /* Initialization functions (client.c) */
726 /****f* silcclient/SilcClientAPI/silc_client_alloc
730 * SilcClient silc_client_alloc(SilcClientOperations *ops,
731 * SilcClientParams *params,
733 * const char *silc_version);
737 * Allocates new client object. This has to be done before client may
738 * work. After calling this one must call silc_client_init to initialize
739 * the client. The `application' is application specific user data pointer
740 * and caller must free it. The `silc_version' is the application version
741 * that will be used to compare against remote host's (usually a server)
742 * version string. The `application' context is accessible by the
743 * application by client->application, client being SilcClient.
746 SilcClient silc_client_alloc(SilcClientOperations *ops,
747 SilcClientParams *params,
749 const char *version_string);
751 /****f* silcclient/SilcClientAPI/silc_client_free
755 * void silc_client_free(SilcClient client);
759 * Frees client object and its internals. The execution of the client
760 * should be stopped with silc_client_stop function before calling
764 void silc_client_free(SilcClient client);
766 /****f* silcclient/SilcClientAPI/silc_client_init
770 * SilcBool silc_client_init(SilcClient client, const char *username,
771 * const char *hostname, const char *realname);
775 * Initializes the client. This makes all the necessary steps to make
776 * the client ready to be run. One must call silc_client_run to run the
777 * client. Returns FALSE if error occurred, TRUE otherwise.
779 * The `username', `hostname' and `realname' strings must be given and
780 * they must be UTF-8 encoded. The `username' is the client's username
781 * in the operating system, `hostname' is the client's host name and
782 * the `realname' is the user's real name.
785 SilcBool silc_client_init(SilcClient client, const char *username,
786 const char *hostname, const char *realname);
788 /****f* silcclient/SilcClientAPI/silc_client_run
792 * void silc_client_run(SilcClient client);
796 * Runs the client. This starts the scheduler from the utility library.
797 * When this functions returns the execution of the application is over.
798 * The client must be initialized before calling this.
801 void silc_client_run(SilcClient client);
803 /****f* silcclient/SilcClientAPI/silc_client_run_one
807 * void silc_client_run_one(SilcClient client);
811 * Runs the client and returns immeadiately. This function is used when
812 * the SILC Client object indicated by the `client' is run under some
813 * other scheduler, or event loop or main loop. On GUI applications,
814 * for example this may be desired to used to run the client under the
815 * GUI application's main loop. Typically the GUI application would
816 * register an idle task that calls this function multiple times in
817 * a second to quickly process the SILC specific data.
820 void silc_client_run_one(SilcClient client);
822 /****f* silcclient/SilcClientAPI/silc_client_stop
826 * void silc_client_stop(SilcClient client);
830 * Stops the client. This is called to stop the client and thus to stop
831 * the program. The client context must be freed with the silc_client_free
835 void silc_client_stop(SilcClient client);
838 /* Connecting functions */
840 /****s* silcclient/SilcClientAPI/SilcClientConnectionParams
844 * typedef struct { ... } SilcClientConnectionParams;
848 * Client connection parameters. This can be filled by the application
849 * and given as argument to silc_client_connect_to_server,
850 * silc_client_connect_to_client or silc_client_key_exchange.
855 /* If this is provided the user's nickname in the network will be the
856 string given here. If it is given, it must be UTF-8 encoded. If this
857 string is not given, the user's username by default is used as nickname.
858 The nickname may later be changed by using NICK command. The maximum
859 length for the nickname string is 128 bytes. */
862 /* If this key repository pointer is non-NULL then public key received in
863 the key exchange protocol will be verified from this repository. If
864 this is not provided then the `verify_public_key' client operation will
865 be called back to application. If the boolean `verify_notfound' is set
866 to TRUE then the `verify_public_key' client operation will be called
867 in case the public key is not found in `repository'. Only public keys
868 added with at least SILC_SKR_USAGE_KEY_AGREEMENT in the repository will
869 be checked, other keys will be ignored. */
871 SilcBool verify_notfound;
873 /* Authentication data. Application may set here the authentication data
874 and authentication method to be used in connecting. If `auth_set'
875 boolean is TRUE then authentication data is provided by application.
876 If the authentication method is public key authentication then the key
877 pair given as argument when connecting will be used and `auth' field
878 is NULL. If it is passphrase authentication, it can be provided in
879 `auth' and `auth_len' fields. If `auth_set' is FALSE
880 the `get_auth_method' client operation will be called to get the
881 authentication method and data from application. */
883 SilcAuthMethod auth_method;
887 /* If this boolean is set to TRUE then the client's connection to the
888 remote host will use UDP instead of TCP. The `local_ip' specifies
889 the local IP address used with the UDP connection, and it must be
890 non-NULL. If the `local_port' is non-zero it will be used as local
891 port with the UDP connection. The remote host will also send packets
892 to the specified address and port. */
897 /* If this boolean is set to TRUE then the key exchange is done with
898 perfect forward secrecy. */
901 /* If this boolean is set to TRUE then connection authentication protocol
902 is not performed during connecting. Only key exchange protocol is
903 performed. This usually must be set to TRUE when connecting to another
904 client, but must be FALSE with server connections. */
905 SilcBool no_authentication;
907 /* The SILC session detachment data that was returned by `detach' client
908 operation when the application detached from the network. Application
909 is responsible of saving the data and giving it as argument here
910 for resuming the session in the SILC network.
912 If this is provided here the client library will attempt to resume
913 the session in the network. After the connection is created
914 successfully, the application is responsible of setting the user
915 interface for user into the same state it was before detaching (showing
916 same channels, channel modes, etc). It can do this by fetching the
917 information (like joined channels) from the client library. */
918 unsigned char *detach_data;
919 SilcUInt32 detach_data_len;
921 } SilcClientConnectionParams;
924 /****f* silcclient/SilcClientAPI/silc_client_connect_to_server
929 * silc_client_connect_to_server(SilcClient client,
930 * SilcClientConnectionParams *params,
931 * SilcPublicKey public_key,
932 * char *remote_host, int port,
933 * SilcClientConnectCallback callback,
938 * Connects to remote server `remote_host' at port `port'. This function
939 * can be used to create connection to remote SILC server and start
940 * SILC session in the SILC network. The `params' may be provided
941 * to provide various connection parameters. The `public_key' and the
942 * `private_key' is your identity used in this connection. When
943 * authentication method is based on digital signatures, this key pair
944 * will be used. The `callback' with `context' will be called after the
945 * connection has been created. It will also be called later when remote
948 * If application wishes to create the network connection itself, use
949 * the silc_client_key_exchange after creating the connection to start
950 * key exchange and authentication with the server.
952 * Returns when connecting is started and FALSE if connection was not
956 SilcBool silc_client_connect_to_server(SilcClient client,
957 SilcClientConnectionParams *params,
958 SilcPublicKey public_key,
959 SilcPrivateKey private_key,
960 char *remote_host, int port,
961 SilcClientConnectCallback callback,
964 /****f* silcclient/SilcClientAPI/silc_client_connect_to_client
969 * silc_client_connect_to_client(SilcClient client,
970 * SilcClientConnectionParams *params,
971 * SilcPublicKey public_key,
972 * char *remote_host, int port,
973 * SilcClientConnectCallback callback,
978 * Connects to remote client `remote_host' at port `port'. This function
979 * can be used to create peer-to-peer connection to another SILC client,
980 * for example, for direct conferencing, or file transfer or for other
981 * purposes. The `params' may be provided to provide various connection
982 * parameters. The `public_key' and the `private_key' is your identity
983 * used in this connection. The `callback' with `context' will be called
984 * after the connection has been created. It will also be called later
985 * when remote host disconnects.
987 * If application wishes to create the network connection itself, use
988 * the silc_client_key_exchange after creating the connection to start
989 * key exchange with the client.
991 * Returns when connecting is started and FALSE if connection was not
995 SilcBool silc_client_connect_to_client(SilcClient client,
996 SilcClientConnectionParams *params,
997 SilcPublicKey public_key,
998 SilcPrivateKey private_key,
999 char *remote_host, int port,
1000 SilcClientConnectCallback callback,
1003 /****f* silcclient/SilcClientAPI/silc_client_key_exchange
1008 * silc_client_key_exchange(SilcClient client,
1009 * SilcClientConnectionParams *params,
1010 * SilcPublicKey public_key,
1011 * SilcPrivateKey private_key,
1012 * SilcStream stream,
1013 * SilcConnectionType conn_type,
1014 * SilcClientConnectCallback callback,
1019 * Starts key exchange protocol and authentication protocol in the
1020 * connection indicated by `stream'. This function can be be used to
1021 * start SILC session with remote host (usually server) when the caller
1022 * has itself created the connection, instead of calling the function
1023 * silc_client_connect_to_server or silc_client_connect_to_client. If
1024 * one of those functions was used this function must not be called as
1025 * in that case the key exchange is performed automatically.
1027 * Use this function only if you have created the connection by yourself.
1028 * After creating the connection the socket must be wrapped into a
1029 * socket stream. See silcsocketstream.h for more information. Note that
1030 * the `stream' must have valid remote IP address (and optionally also
1031 * hostname) and port set.
1033 * The `params' may be provided to provide various connection parameters.
1034 * The `public_key' and the `private_key' is your identity used in this
1035 * session. The `callback' with `context' will be called after the session
1036 * has been set up. It will also be called later when remote host
1037 * disconnects. The `conn_type' is the type of session this is going to
1040 * Returns TRUE when key exchange is started and FALSE if it is not started
1047 * // Create remote connection stream. Resolve hostname and IP also.
1048 * sock = create_connection(remote_host, port);
1049 * silc_socket_tcp_stream_create(sock, TRUE, FALSE, schedule,
1050 * stream_create_cb, app);
1052 * // Stream callback delivers our new SilcStream context
1053 * void stream_create_cb(SilcSocketStreamStatus status, SilcStream stream,
1057 * if (status != SILC_SOCKET_OK)
1060 * // Start key exchange
1061 * silc_client_key_exchange(client, NULL, public_key, private_key,
1062 * stream, SILC_CONN_SERVER, connection_cb, app);
1067 SilcBool silc_client_key_exchange(SilcClient client,
1068 SilcClientConnectionParams *params,
1069 SilcPublicKey public_key,
1070 SilcPrivateKey private_key,
1072 SilcConnectionType conn_type,
1073 SilcClientConnectCallback callback,
1076 /****f* silcclient/SilcClientAPI/silc_client_close_connection
1080 * void silc_client_close_connection(SilcClient client,
1081 * SilcClientConnection conn);
1085 * Closes the remote connection `conn'. The `conn' will become invalid
1086 * after this call. Usually this function is called only when explicitly
1087 * closing connection for example in case of error, or when the remote
1088 * connection was created by the application or when the remote is client
1089 * connection. Server connections are usually closed by sending QUIT
1090 * command to the server. However, this call may also be used.
1093 void silc_client_close_connection(SilcClient client,
1094 SilcClientConnection conn);
1096 /* Message sending functions (client_channel.c and client_prvmsg.c) */
1098 /****f* silcclient/SilcClientAPI/silc_client_send_channel_message
1102 * SilcBool silc_client_send_channel_message(SilcClient client,
1103 * SilcClientConnection conn,
1104 * SilcChannelEntry channel,
1105 * SilcChannelPrivateKey key,
1106 * SilcMessageFlags flags,
1108 * unsigned char *data,
1109 * SilcUInt32 data_len);
1113 * Sends packet to the `channel'. Packet to channel is always encrypted
1114 * differently from "normal" packets. SILC header of the packet is
1115 * encrypted with the next receiver's key and the rest of the packet is
1116 * encrypted with the channel specific key. Padding and HMAC is computed
1117 * with the next receiver's key. The `data' is the channel message.
1119 * If `key' is provided then that private key is used to encrypt the
1120 * channel message. If it is not provided, private keys has not been
1121 * set at all, the normal channel key is used automatically. If private
1122 * keys are set then the first key (the key that was added first as
1123 * private key) is used.
1125 * If the `flags' includes SILC_MESSAGE_FLAG_SIGNED the message will be
1126 * digitally signed with the SILC key pair.
1128 * Returns TRUE if the message was sent, and FALSE if error occurred or
1129 * the sending is not allowed due to channel modes (like sending is
1130 * blocked). This function is thread safe and private messages can be
1131 * sent from multiple threads.
1134 SilcBool silc_client_send_channel_message(SilcClient client,
1135 SilcClientConnection conn,
1136 SilcChannelEntry channel,
1137 SilcChannelPrivateKey key,
1138 SilcMessageFlags flags,
1140 unsigned char *data,
1141 SilcUInt32 data_len);
1143 /* Block process until channel message from `channel' is received */
1145 silc_client_receive_channel_message(SilcClient client,
1146 SilcClientConnection conn,
1147 SilcChannelEntry channel,
1148 SilcClientEntry *return_sender,
1149 SilcMessageFlags *return_flags,
1150 const unsigned char **return_message,
1151 SilcUInt32 *return_message_len);
1153 /****f* silcclient/SilcClientAPI/silc_client_send_private_message
1157 * SilcBool silc_client_send_private_message(SilcClient client,
1158 * SilcClientConnection conn,
1159 * SilcClientEntry client_entry,
1160 * SilcMessageFlags flags,
1162 * unsigned char *data,
1163 * SilcUInt32 data_len);
1167 * Sends private message to remote client. If private message key has
1168 * not been set with this client then the message will be encrypted using
1169 * normal session keys. If the `flags' includes SILC_MESSAGE_FLAG_SIGNED
1170 * the message will be digitally signed with the SILC key pair. In this
1171 * case the caller must also provide the `hash' pointer. By default, the
1172 * hash function must be SHA-1.
1174 * Returns TRUE if the message was sent, and FALSE if error occurred.
1175 * This function is thread safe and private messages can be sent from
1179 SilcBool silc_client_send_private_message(SilcClient client,
1180 SilcClientConnection conn,
1181 SilcClientEntry client_entry,
1182 SilcMessageFlags flags,
1184 unsigned char *data,
1185 SilcUInt32 data_len);
1187 /****f* silcclient/SilcClientAPI/silc_client_on_channel
1191 * SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
1192 * SilcClientEntry client_entry);
1196 * Returns the SilcChannelUser entry if the `client_entry' is joined on the
1197 * channel indicated by the `channel'. NULL if client is not joined on
1201 SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
1202 SilcClientEntry client_entry);
1205 /* Command management */
1207 /****f* silcclient/SilcClientAPI/silc_client_command_call
1211 * SilcUInt16 silc_client_command_call(SilcClient client,
1212 * SilcClientConnection conn,
1213 * const char *command_line, ...);
1217 * Calls and executes the command indicated by the `command_name'.
1218 * The `command_line' is a string which includes the command's name and
1219 * its arguments separated with whitespaces (' '). If `command_line'
1220 * is non-NULL then all variable arguments are ignored by default.
1222 * If `command_line' is NULL, then the variable arguments define the
1223 * command's name and its arguments. The first variable argument must
1224 * be the command name. The variable argument list must be terminated
1227 * Returns FALSE if the command is not known and TRUE after command.
1228 * execution. The "command" client operation is called when the
1229 * command is executed to indicate whether the command executed
1230 * successfully or not.
1232 * The "command_reply" client operation will be called when reply is
1233 * received from the server to the command. Application may also use
1234 * the silc_client_command_pending to attach to the command reply.
1235 * The command identifier for silc_client_command_pending function after
1236 * this function call is conn->cmd_ident, which application may use.
1240 * silc_client_command_call(client, conn, NULL, "PING", "silc.silcnet.org",
1242 * silc_client_command_call(client, conn, "PING silc.silcnet.org");
1246 * This command executes the commands implemented inside the client
1247 * library. These commands are designed for command line applications,
1248 * but GUI application may call them too if needed. Alternatively
1249 * application may override the library and use silc_client_command_send
1253 SilcUInt16 silc_client_command_call(SilcClient client,
1254 SilcClientConnection conn,
1255 const char *command_line, ...);
1257 /* If FALSE is returned the callback will not be called again, even if there
1258 is more data coming in in the command reply. If there are other pending
1259 commands waiting for the reply, they will receive it even if some other
1260 command reply has returned FALSE. */
1261 typedef SilcBool (*SilcClientCommandReply)(SilcClient client,
1262 SilcClientConnection conn,
1263 SilcCommand command,
1269 /****f* silcclient/SilcClientAPI/silc_client_command_send
1273 * SilcUInt16 silc_client_command_send(SilcClient client,
1274 * SilcClientConnection conn,
1275 * SilcCommand command,
1276 * SilcClientCommandReply reply,
1277 * void *reply_context,
1278 * SilcUInt32 argc, ...);
1282 * Generic function to send any command. The arguments must be given
1283 * already encoded into correct format and in correct order. If application
1284 * wants to perform the commands by itself, it can do so and send the data
1285 * directly to the server using this function. If application is using
1286 * the silc_client_command_call, this function is usually not used.
1287 * Programmer should get familiar with the SILC protocol commands
1288 * specification when using this function, as the arguments needs to
1289 * be encoded as specified in the protocol.
1291 * The variable arguments are a set of { type, data, data_length },
1292 * and the `argc' is the number of these sets.
1294 * The `reply' callback must be provided, and it is called when the
1295 * command reply is received from the server. Note that, when using this
1296 * function the default `command_reply' client operation will not be
1297 * called, when reply is received. Note however that, `reply' is almost
1298 * identical with `command_reply' callback, and application may forward
1299 * the reply from `reply' to `command_reply' callback, if desired.
1301 * Returns command identifier for this sent command. It can be used
1302 * to additionally attach to the command reply using the function
1303 * silc_client_command_pending, if needed. Returns 0 on error,
1307 * silc_client_command_send(client, conn, SILC_COMMAND_WHOIS,
1308 * my_whois_command_reply, cmd_ctx,
1309 * 1, 1, nickname, strlen(nickname));
1312 SilcUInt16 silc_client_command_send(SilcClient client,
1313 SilcClientConnection conn,
1314 SilcCommand command,
1315 SilcClientCommandReply reply,
1316 void *reply_context,
1317 SilcUInt32 argc, ...);
1319 /****f* silcclient/SilcClientAPI/silc_client_command_pending
1323 * void silc_client_command_pending(SilcClientConnection conn,
1324 * SilcCommand reply_cmd,
1325 * SilcUInt16 cmd-ident,
1326 * SilcCommandCb callback,
1331 * This function can be used to add pending command callback to be
1332 * called when an command reply is received to an earlier sent command.
1333 * The `reply_cmd' is the command that must be received in order for
1334 * the pending command callback indicated by `callback' to be called.
1335 * The `callback' will deliver the `context' and
1336 * SilcClientCommandReplyContext which includes the internals of the
1339 * The `cmd_ident' is a command identifier which was set for the earlier
1340 * sent command. The command reply will include the same identifier
1341 * and pending command callback will be called when the reply is
1342 * received with the same command identifier. It is possible to
1343 * add multiple pending command callbacks for same command and for
1346 * Application may use this function to add its own command reply
1347 * handlers if it wishes not to use the standard `command_reply'
1348 * client operation. However, note that the pending command callback
1349 * does not deliver parsed command reply, but application must parse
1352 * Note also that the application is notified about the received command
1353 * reply through the `command_reply' client operation before calling
1354 * the `callback` pending command callback. That is the normal
1355 * command reply handling, and is called regardless whether pending
1356 * command callbacks are used or not.
1358 * Commands that application calls with silc_client_command_call
1359 * will use a command identifier from conn->cmd_ident variable. After
1360 * calling the silc_client_command_call, the conn->cmd_ident includes
1361 * the command identifier that was used for the command sending.
1365 * silc_client_command_call(client, conn, "PING silc.silcnet.org");
1366 * silc_client_command_pending(conn, SILC_COMMAND_PING, conn->cmd_ident,
1367 * my_ping_handler, my_ping_context);
1370 SilcBool silc_client_command_pending(SilcClientConnection conn,
1371 SilcCommand command,
1372 SilcUInt16 cmd_ident,
1373 SilcClientCommandReply reply,
1377 /* Private Message key management (client_prvmsg.c) */
1379 /****f* silcclient/SilcClientAPI/silc_client_add_private_message_key
1384 * silc_client_add_private_message_key(SilcClient client,
1385 * SilcClientConnection conn,
1386 * SilcClientEntry client_entry,
1387 * const char *cipher,
1389 * unsigned char *key,
1390 * SilcUInt32 key_len,
1391 * SilcBool generate_key,
1392 * SilcBool responder);
1396 * Adds private message key to the client library. The key will be used to
1397 * encrypt all private message between the client and the remote client
1398 * indicated by the `client_entry'. If the `key' is NULL and the boolean
1399 * value `generate_key' is TRUE the library will generate random key.
1400 * The `key' maybe for example pre-shared-key, passphrase or similar.
1401 * The `cipher' and `hmac' MAY be provided but SHOULD be NULL to assure
1402 * that the requirements of the SILC protocol are met. The API, however,
1403 * allows to allocate any cipher and HMAC.
1405 * If `responder' is TRUE then the sending and receiving keys will be
1406 * set according the client being the receiver of the private key. If
1407 * FALSE the client is being the sender (or negotiator) of the private
1410 * It is not necessary to set key for normal private message usage. If the
1411 * key is not set then the private messages are encrypted using normal
1412 * session keys. Setting the private key, however, increases the security.
1414 * Returns FALSE if the key is already set for the `client_entry', TRUE
1418 SilcBool silc_client_add_private_message_key(SilcClient client,
1419 SilcClientConnection conn,
1420 SilcClientEntry client_entry,
1425 SilcBool generate_key,
1426 SilcBool responder);
1428 /****f* silcclient/SilcClientAPI/silc_client_add_private_message_key_ske
1433 * silc_client_add_private_message_key_ske(SilcClient client,
1434 * SilcClientConnection conn,
1435 * SilcClientEntry client_entry,
1436 * const char *cipher,
1438 * SilcSKEKeyMaterial key);
1442 * Same as silc_client_add_private_message_key but takes the key material
1443 * from the SKE key material structure. This structure is received if
1444 * the application uses the silc_client_send_key_agreement to negotiate
1445 * the key material. The `cipher' and `hmac' SHOULD be provided as it is
1446 * negotiated also in the SKE protocol.
1449 SilcBool silc_client_add_private_message_key_ske(SilcClient client,
1450 SilcClientConnection conn,
1451 SilcClientEntry client_entry,
1454 SilcSKEKeyMaterial key,
1455 SilcBool responder);
1457 /****f* silcclient/SilcClientAPI/silc_client_del_private_message_key
1461 * SilcBool silc_client_del_private_message_key(SilcClient client,
1462 * SilcClientConnection conn,
1463 * SilcClientEntry client_entry);
1467 * Removes the private message from the library. The key won't be used
1468 * after this to protect the private messages with the remote `client_entry'
1469 * client. Returns FALSE on error, TRUE otherwise.
1472 SilcBool silc_client_del_private_message_key(SilcClient client,
1473 SilcClientConnection conn,
1474 SilcClientEntry client_entry);
1476 /****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys
1480 * SilcPrivateMessageKeys
1481 * silc_client_list_private_message_keys(SilcClient client,
1482 * SilcClientConnection conn,
1483 * SilcUInt32 *key_count);
1487 * Returns array of set private message keys associated to the connection
1488 * `conn'. Returns allocated SilcPrivateMessageKeys array and the array
1489 * count to the `key_count' argument. The array must be freed by the caller
1490 * by calling the silc_client_free_private_message_keys function. Note:
1491 * the keys returned in the array is in raw format. It might not be desired
1492 * to show the keys as is. The application might choose not to show the keys
1493 * at all or to show the fingerprints of the keys.
1496 SilcPrivateMessageKeys
1497 silc_client_list_private_message_keys(SilcClient client,
1498 SilcClientConnection conn,
1499 SilcUInt32 *key_count);
1501 /****f* silcclient/SilcClientAPI/silc_client_send_private_message_key_request
1506 * silc_client_send_private_message_key_request(SilcClient client,
1507 * SilcClientConnection conn,
1508 * SilcClientEntry client_entry);
1512 * This function can be used to send an private message key indicator
1513 * request to the remote client indicated by 'client_entry'. This can
1514 * be used when setting a static or pre-shared private message key.
1515 * The sender of this packet is the initiator and must set the 'responder'
1516 * argument in silc_client_add_private_message_key function to FALSE.
1517 * The receiver of this indicator request must set it to TRUE, if the
1518 * receiver decides to set a private message key. By using this
1519 * function applications may automate initiator/responder setting in
1520 * private message key functions, without asking from user which one is
1521 * the initiator and which one is responder.
1525 * The sender of this packet must set the private message key for
1526 * 'client_entry' before calling this function. The 'responder'
1527 * argument MUST be set to FALSE when setting the key.
1531 silc_client_send_private_message_key_request(SilcClient client,
1532 SilcClientConnection conn,
1533 SilcClientEntry client_entry);
1535 /****f* silcclient/SilcClientAPI/silc_client_free_private_message_keys
1539 * void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
1540 * SilcUInt32 key_count);
1544 * Frees the SilcPrivateMessageKeys array returned by the function
1545 * silc_client_list_private_message_keys.
1548 void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
1549 SilcUInt32 key_count);
1552 /* Channel private key management (client_channel.c,
1553 SilcChannelPrivateKey is defined in idlist.h) */
1555 /****f* silcclient/SilcClientAPI/silc_client_add_channel_private_key
1559 * SilcBool silc_client_add_channel_private_key(SilcClient client,
1560 * SilcClientConnection conn,
1561 * SilcChannelEntry channel,
1565 * unsigned char *key,
1566 * SilcUInt32 key_len,
1567 * SilcChannelPrivateKey *ret_key);
1571 * Adds private key for channel. When channel has private key then the
1572 * messages are encrypted using that key. All clients on the channel
1573 * must also know the key in order to decrypt the messages. However,
1574 * it is possible to have several private keys per one channel. In this
1575 * case only some of the clients on the channel may know the one key
1576 * and only some the other key. The `name' can be application given
1577 * name for the key. This returns the created key to the 'ret_key'
1578 * pointer if it is non-NULL;
1580 * If `cipher' and/or `hmac' is NULL then default values will be used
1581 * (aes-256-cbc for cipher and hmac-sha1-96 for hmac).
1583 * The private key for channel is optional. If it is not set then the
1584 * channel messages are encrypted using the channel key generated by the
1585 * server. However, setting the private key (or keys) for the channel
1586 * significantly adds security. If more than one key is set the library
1587 * will automatically try all keys at the message decryption phase. Note:
1588 * setting many keys slows down the decryption phase as all keys has to
1589 * be tried in order to find the correct decryption key. However, setting
1590 * a few keys does not have big impact to the decryption performace.
1594 * NOTE: This is entirely local setting. The key set using this function
1595 * is not sent to the network at any phase.
1597 * NOTE: If the key material was originated by the SKE protocol (using
1598 * silc_client_send_key_agreement) then the `key' MUST be the
1599 * key->send_enc_key as this is dictated by the SILC protocol. However,
1600 * currently it is not expected that the SKE key material would be used
1601 * as channel private key. However, this API allows it.
1604 SilcBool silc_client_add_channel_private_key(SilcClient client,
1605 SilcClientConnection conn,
1606 SilcChannelEntry channel,
1612 SilcChannelPrivateKey *ret_key);
1614 /****f* silcclient/SilcClientAPI/silc_client_del_channel_private_keys
1618 * SilcBool silc_client_del_channel_private_keys(SilcClient client,
1619 * SilcClientConnection conn,
1620 * SilcChannelEntry channel);
1624 * Removes all private keys from the `channel'. The old channel key is used
1625 * after calling this to protect the channel messages. Returns FALSE on
1626 * on error, TRUE otherwise.
1629 SilcBool silc_client_del_channel_private_keys(SilcClient client,
1630 SilcClientConnection conn,
1631 SilcChannelEntry channel);
1633 /****f* silcclient/SilcClientAPI/silc_client_del_channel_private_key
1637 * SilcBool silc_client_del_channel_private_key(SilcClient client,
1638 * SilcClientConnection conn,
1639 * SilcChannelEntry channel,
1640 * SilcChannelPrivateKey key);
1644 * Removes and frees private key `key' from the channel `channel'.
1645 * The `key' is retrieved by calling the function
1646 * silc_client_list_channel_private_keys. The key is not used after
1647 * this. If the key was last private key then the old channel key is
1648 * used hereafter to protect the channel messages. This returns FALSE
1649 * on error, TRUE otherwise.
1652 SilcBool silc_client_del_channel_private_key(SilcClient client,
1653 SilcClientConnection conn,
1654 SilcChannelEntry channel,
1655 SilcChannelPrivateKey key);
1657 /****f* silcclient/SilcClientAPI/silc_client_list_channel_private_keys
1662 * silc_client_list_channel_private_keys(SilcClient client,
1663 * SilcClientConnection conn,
1664 * SilcChannelEntry channel);
1668 * Returns list of private keys associated to the `channel'. The caller
1669 * must free the returned list. The pointers in the list may be
1670 * used to delete the specific key by giving the pointer as argument to the
1671 * function silc_client_del_channel_private_key. Each entry in the list
1672 * is SilcChannelPrivateKey.
1675 SilcDList silc_client_list_channel_private_keys(SilcClient client,
1676 SilcClientConnection conn,
1677 SilcChannelEntry channel);
1679 /****f* silcclient/SilcClientAPI/silc_client_current_channel_private_key
1683 * void silc_client_current_channel_private_key(SilcClient client,
1684 * SilcClientConnection conn,
1685 * SilcChannelEntry channel,
1686 * SilcChannelPrivateKey key);
1690 * Sets the `key' to be used as current channel private key on the
1691 * `channel'. Packet sent after calling this function will be secured
1695 void silc_client_current_channel_private_key(SilcClient client,
1696 SilcClientConnection conn,
1697 SilcChannelEntry channel,
1698 SilcChannelPrivateKey key);
1701 /* Key Agreement routines (client_keyagr.c) */
1703 /****f* silcclient/SilcClientAPI/silc_client_send_key_agreement
1707 * void silc_client_send_key_agreement(SilcClient client,
1708 * SilcClientConnection conn,
1709 * SilcClientEntry client_entry,
1712 * SilcUInt32 timeout_secs,
1713 * SilcKeyAgreementCallback completion,
1718 * Sends key agreement request to the remote client indicated by the
1719 * `client_entry'. If the caller provides the `hostname' and the `port'
1720 * arguments then the library will bind the client to that hostname and
1721 * that port for the key agreement protocol. It also sends the `hostname'
1722 * and the `port' in the key agreement packet to the remote client. This
1723 * would indicate that the remote client may initiate the key agreement
1724 * protocol to the `hostname' on the `port'. If port is zero then the
1725 * bound port is undefined (the operating system defines it).
1727 * If the `hostname' and `port' is not provided then empty key agreement
1728 * packet is sent to the remote client. The remote client may reply with
1729 * the same packet including its hostname and port. If the library receives
1730 * the reply from the remote client the `key_agreement' client operation
1731 * callback will be called to verify whether the user wants to perform the
1732 * key agreement or not.
1736 * NOTE: If the application provided the `hostname' and the `port' and the
1737 * remote side initiates the key agreement protocol it is not verified
1738 * from the user anymore whether the protocol should be executed or not.
1739 * By setting the `hostname' and `port' the user gives permission to
1740 * perform the protocol (we are responder in this case).
1742 * NOTE: If the remote side decides not to initiate the key agreement
1743 * or decides not to reply with the key agreement packet then we cannot
1744 * perform the key agreement at all. If the key agreement protocol is
1745 * performed the `completion' callback with the `context' will be called.
1746 * If remote side decides to ignore the request the `completion' will be
1747 * called after the specified timeout, `timeout_secs'.
1749 * NOTE: If the `hostname' and the `port' was not provided the `completion'
1750 * will not be called at all since this does nothing more than sending
1751 * a packet to the remote host.
1753 * NOTE: There can be only one active key agreement for one client entry.
1754 * Before setting new one, the old one must be finished (it is finished
1755 * after calling the completion callback) or the function
1756 * silc_client_abort_key_agreement must be called.
1759 void silc_client_send_key_agreement(SilcClient client,
1760 SilcClientConnection conn,
1761 SilcClientEntry client_entry,
1762 const char *hostname,
1763 const char *bindhost,
1765 SilcUInt32 timeout_secs,
1766 SilcKeyAgreementCallback completion,
1769 /****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement
1774 * silc_client_perform_key_agreement(SilcClient client,
1775 * SilcClientConnection conn,
1776 * SilcClientEntry client_entry,
1779 * SilcKeyAgreementCallback completion,
1784 * Performs the actual key agreement protocol. Application may use this
1785 * to initiate the key agreement protocol. This can be called for example
1786 * after the application has received the `key_agreement' client operation,
1787 * and did not return TRUE from it.
1789 * The `hostname' is the remote hostname (or IP address) and the `port'
1790 * is the remote port. The `completion' callback with the `context' will
1791 * be called after the key agreement protocol.
1795 * NOTE: If the application returns TRUE in the `key_agreement' client
1796 * operation the library will automatically start the key agreement. In this
1797 * case the application must not call this function. However, application
1798 * may choose to just ignore the `key_agreement' client operation (and
1799 * merely just print information about it on the screen) and call this
1800 * function when the user whishes to do so (by, for example, giving some
1801 * specific command). Thus, the API provides both, automatic and manual
1802 * initiation of the key agreement. Calling this function is the manual
1803 * initiation and returning TRUE in the `key_agreement' client operation
1804 * is the automatic initiation.
1807 void silc_client_perform_key_agreement(SilcClient client,
1808 SilcClientConnection conn,
1809 SilcClientEntry client_entry,
1812 SilcKeyAgreementCallback completion,
1815 /****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement_fd
1820 * silc_client_perform_key_agreement_fd(SilcClient client,
1821 * SilcClientConnection conn,
1822 * SilcClientEntry client_entry,
1825 * SilcKeyAgreementCallback completion,
1830 * Same as above but application has created already the connection to
1831 * the remote host. The `sock' is the socket to the remote connection.
1832 * Application can use this function if it does not want the client library
1833 * to create the connection.
1836 void silc_client_perform_key_agreement_fd(SilcClient client,
1837 SilcClientConnection conn,
1838 SilcClientEntry client_entry,
1841 SilcKeyAgreementCallback completion,
1844 /****f* silcclient/SilcClientAPI/silc_client_abort_key_agreement
1848 * void silc_client_abort_key_agreement(SilcClient client,
1849 * SilcClientConnection conn,
1850 * SilcClientEntry client_entry);
1854 * This function can be called to unbind the hostname and the port for
1855 * the key agreement protocol. However, this function has effect only
1856 * before the key agreement protocol has been performed. After it has
1857 * been performed the library will automatically unbind the port. The
1858 * `client_entry' is the client to which we sent the key agreement
1859 * request. The key agreement completion callback will be called
1860 * with SILC_KEY_AGREEMENT_ABORTED status.
1863 void silc_client_abort_key_agreement(SilcClient client,
1864 SilcClientConnection conn,
1865 SilcClientEntry client_entry);
1868 /* Misc functions */
1870 /****f* silcclient/SilcClientAPI/silc_client_set_away_message
1874 * void silc_client_set_away_message(SilcClient client,
1875 * SilcClientConnection conn,
1880 * Sets away `message'. The away message may be set when the client's
1881 * mode is changed to SILC_UMODE_GONE and the client whishes to reply
1882 * to anyone who sends private message. The `message' will be sent
1883 * automatically back to the the client who send private message. If
1884 * away message is already set this replaces the old message with the
1885 * new one. If `message' is NULL the old away message is removed.
1886 * The sender may freely free the memory of the `message'.
1889 void silc_client_set_away_message(SilcClient client,
1890 SilcClientConnection conn,
1893 /****f* silcclient/SilcClientAPI/SilcConnectionAuthRequest
1897 * typedef void (*SilcConnectionAuthRequest)(SilcClient client,
1898 * SilcClientConnection conn,
1899 * SilcAuthMethod auth_meth,
1904 * Connection authentication method request callback. This is called
1905 * by the client library after it has received the authentication method
1906 * that the application requested by calling the function
1907 * silc_client_request_authentication_method.
1910 typedef void (*SilcConnectionAuthRequest)(SilcClient client,
1911 SilcClientConnection conn,
1912 SilcAuthMethod auth_meth,
1915 /****f* silcclient/SilcClientAPI/silc_client_request_authentication_method
1920 * silc_client_request_authentication_method(SilcClient client,
1921 * SilcClientConnection conn,
1922 * SilcConnectionAuthRequest
1928 * This function can be used to request the current authentication method
1929 * from the server. This may be called when connecting to the server
1930 * and the client library requests the authentication data from the
1931 * application. If the application does not know the current authentication
1932 * method it can request it from the server using this function.
1933 * The `callback' with `context' will be called after the server has
1934 * replied back with the current authentication method.
1938 silc_client_request_authentication_method(SilcClient client,
1939 SilcClientConnection conn,
1940 SilcConnectionAuthRequest callback,
1943 /****d* silcclient/SilcClientAPI/SilcClientMonitorStatus
1947 * typedef enum { ... } SilcClientMonitorStatus;
1951 * File transmission session status types. These will indicate
1952 * the status of the file transmission session.
1957 SILC_CLIENT_FILE_MONITOR_KEY_AGREEMENT, /* In key agreemenet phase */
1958 SILC_CLIENT_FILE_MONITOR_SEND, /* Sending file */
1959 SILC_CLIENT_FILE_MONITOR_RECEIVE, /* Receiving file */
1960 SILC_CLIENT_FILE_MONITOR_GET,
1961 SILC_CLIENT_FILE_MONITOR_PUT,
1962 SILC_CLIENT_FILE_MONITOR_CLOSED, /* Session closed */
1963 SILC_CLIENT_FILE_MONITOR_ERROR, /* Error during session */
1964 } SilcClientMonitorStatus;
1967 /****d* silcclient/SilcClientAPI/SilcClientFileError
1971 * typedef enum { ... } SilcClientFileError;
1975 * File transmission error types. These types are returned by
1976 * some of the file transmission functions, and by the monitor
1977 * callback to indicate error.
1982 SILC_CLIENT_FILE_OK,
1983 SILC_CLIENT_FILE_ERROR,
1984 SILC_CLIENT_FILE_UNKNOWN_SESSION,
1985 SILC_CLIENT_FILE_ALREADY_STARTED,
1986 SILC_CLIENT_FILE_NO_SUCH_FILE,
1987 SILC_CLIENT_FILE_PERMISSION_DENIED,
1988 SILC_CLIENT_FILE_KEY_AGREEMENT_FAILED,
1989 } SilcClientFileError;
1992 /****f* silcclient/SilcClientAPI/SilcClientFileMonitor
1996 * typedef void (*SilcClientFileMonitor)(SilcClient client,
1997 * SilcClientConnection conn,
1998 * SilcClientMonitorStatus status,
1999 * SilcClientFileError error,
2000 * SilcUInt64 offset,
2001 * SilcUInt64 filesize,
2002 * SilcClientEntry client_entry,
2003 * SilcUInt32 session_id,
2004 * const char *filepath,
2009 * Monitor callback that is called during the file transmission to
2010 * monitor the transmission process. The `status' indicates the current
2011 * monitoring process. The `error' will indicate the error type
2012 * if `status' is SILC_CLIENT_FILE_MONITOR_ERROR. The `offset' is the
2013 * currently transmitted amount of total `filesize'. The `client_entry'
2014 * indicates the remote client, and the transmission session ID is the
2015 * `session_id'. The filename being transmitted is indicated by the
2019 typedef void (*SilcClientFileMonitor)(SilcClient client,
2020 SilcClientConnection conn,
2021 SilcClientMonitorStatus status,
2022 SilcClientFileError error,
2024 SilcUInt64 filesize,
2025 SilcClientEntry client_entry,
2026 SilcUInt32 session_id,
2027 const char *filepath,
2030 /****f* silcclient/SilcClientAPI/SilcClientFileName
2034 * typedef void (*SilcClientFileName)(const char *filepath,
2039 * Completion callback for the SilcClientFileAskName callback function.
2040 * Application calls this to deliver the filepath and filename where
2041 * the downloaded file is to be saved.
2044 typedef void (*SilcClientFileName)(const char *filepath,
2047 /****f* silcclient/SilcClientAPI/SilcClientFileAskName
2051 * typedef void (*SilcClientFileAskName)(SilcClient client,
2052 * SilcClientConnection conn,
2053 * SilcUInt32 session_id,
2054 * const char *remote_filename,
2055 * SilcClientFileName completion,
2056 * void *completion_context,
2061 * File name asking callback, that is called if it is given to the
2062 * silc_client_file_receive and the path given to that as argument was
2063 * NULL. The library calls this to ask the filename and filepath to
2064 * where the file is to be saved. The 'remote_filename' is the file
2065 * that is being downloaded. Application must call the 'completion'
2066 * with 'completion_context' to continue with the file downloading.
2067 * It is not mandatory to provide this to the silc_client_file_receive.
2070 typedef void (*SilcClientFileAskName)(SilcClient client,
2071 SilcClientConnection conn,
2072 SilcUInt32 session_id,
2073 const char *remote_filename,
2074 SilcClientFileName completion,
2075 void *completion_context,
2078 /****f* silcclient/SilcClientAPI/silc_client_file_send
2082 * SilcClientFileError
2083 * silc_client_file_send(SilcClient client,
2084 * SilcClientConnection conn,
2085 * SilcClientFileMonitor monitor,
2086 * void *monitor_context,
2087 * const char *local_ip,
2088 * SilcUInt32 local_port,
2089 * SilcBool do_not_bind,
2090 * SilcClientEntry client_entry,
2091 * const char *filepath);
2092 * SilcUInt32 *session_id);
2096 * Sends a file indicated by the `filepath' to the remote client
2097 * indicated by the `client_entry'. This will negotiate a secret key
2098 * with the remote client before actually starting the transmission of
2099 * the file. The `monitor' callback will be called to monitor the
2100 * transmission of the file.
2102 * This returns a file session ID for the file transmission to the
2103 * `session_id' pointer. It can be used to close the session (and
2104 * abort the file transmission) by calling the silc_client_file_close
2105 * function. The session ID is also returned in the `monitor' callback.
2107 * If the `local_ip' is provided then this will try to bind the
2108 * listener for key exchange protocol to that IP. If `local_port' is
2109 * non-zero that port is used. If `local_ip' is NULL then this will
2110 * automatically attempt to bind it to local IP address of the machine.
2111 * If `do_not_bind' is TRUE then the `local_ip' and `local_port' are
2112 * ignored and it is expected that the receiver will provide the
2113 * point of contact. This is usefull if the sender is behind NAT.
2115 * If error will occur during the file transfer process the error
2116 * status will be returned in the monitor callback. In this case
2117 * the application must call silc_client_file_close to close the
2122 silc_client_file_send(SilcClient client,
2123 SilcClientConnection conn,
2124 SilcClientFileMonitor monitor,
2125 void *monitor_context,
2126 const char *local_ip,
2127 SilcUInt32 local_port,
2128 SilcBool do_not_bind,
2129 SilcClientEntry client_entry,
2130 const char *filepath,
2131 SilcUInt32 *session_id);
2133 /****f* silcclient/SilcClientAPI/silc_client_file_receive
2137 * SilcClientFileError
2138 * silc_client_file_receive(SilcClient client,
2139 * SilcClientConnection conn,
2140 * SilcClientFileMonitor monitor,
2141 * void *monitor_context,
2143 * SilcUInt32 session_id,
2144 * SilcClientFileAskName ask_name,
2145 * void *ask_name_context);
2149 * Receives a file from a client indicated by the `client_entry'. The
2150 * `session_id' indicates the file transmission session and it has been
2151 * received in the `ftp' client operation function. This will actually
2152 * perform the key agreement protocol with the remote client before
2153 * actually starting the file transmission. The `monitor' callback
2154 * will be called to monitor the transmission. If `path' is non-NULL
2155 * the file will be saved into that directory. If NULL the file is
2156 * saved in the current working directory, unless the 'ask_name'
2157 * callback is non-NULL. In this case the callback is called to ask
2158 * the path and filename from application.
2160 * If error will occur during the file transfer process the error
2161 * status will be returned in the monitor callback. In this case
2162 * the application must call silc_client_file_close to close the
2167 silc_client_file_receive(SilcClient client,
2168 SilcClientConnection conn,
2169 SilcClientFileMonitor monitor,
2170 void *monitor_context,
2172 SilcUInt32 session_id,
2173 SilcClientFileAskName ask_name,
2174 void *ask_name_context);
2176 /****f* silcclient/SilcClientAPI/silc_client_file_close
2180 * SilcClientFileError silc_client_file_close(SilcClient client,
2181 * SilcClientConnection conn,
2182 * SilcUInt32 session_id);
2186 * Closes file transmission session indicated by the `session_id'.
2187 * If file transmission is being conducted it will be aborted
2188 * automatically. This function is also used to close the session
2189 * after successful file transmission. This function can be used
2190 * also to reject incoming file transmission request. If the
2191 * session was already started and the monitor callback was set
2192 * the monitor callback will be called with the monitor status
2193 * SILC_CLIENT_FILE_MONITOR_CLOSED.
2196 SilcClientFileError silc_client_file_close(SilcClient client,
2197 SilcClientConnection conn,
2198 SilcUInt32 session_id);
2200 /****f* silcclient/SilcClientAPI/silc_client_attribute_add
2204 * SilcAttributePayload
2205 * silc_client_attribute_add(SilcClient client,
2206 * SilcClientConnection conn,
2207 * SilcAttribute attribute,
2209 * SilcUInt32 object_size);
2213 * Add new Requsted Attribute for WHOIS command to the client library.
2214 * The `attribute' object indicated by `object' is added and allocated
2215 * SilcAttributePayload is returned. The `object' must be of correct
2216 * type and of correct size. See the SilcAttribute for object types
2217 * for different attributes. You may also get all added attributes
2218 * from the client with silc_client_attributes_get function.
2220 * Requested Attributes are different personal information about the
2221 * user, status information and other information which other users
2222 * may query with WHOIS command. Application may set these so that
2223 * if someone sends WHOIS query these attributes will be replied back
2224 * to the sender. The library always puts the public key to the
2225 * Requested Attributes, but if application wishes to add additional
2226 * public keys (or certificates) it can be done with this interface.
2227 * Library also always computes digital signature of the attributes
2228 * automatically, so application does not need to do that.
2231 SilcAttributePayload silc_client_attribute_add(SilcClient client,
2232 SilcClientConnection conn,
2233 SilcAttribute attribute,
2235 SilcUInt32 object_size);
2237 /****f* silcclient/SilcClientAPI/silc_client_attribute_del
2241 * SilcBool silc_client_attribute_del(SilcClient client,
2242 * SilcClientConnection conn,
2243 * SilcAttribute attribute,
2244 * SilcAttributePayload attr);
2248 * Delete a Requested Attribute from the client. If the `attribute'
2249 * is non-zero then all attributes of that type are deleted and the
2250 * `attr' is ignored. If `attr' is non-NULL then that specific
2251 * attribute is deleted and `attribute' is ignored.
2253 * You may get all added attributes with the function
2254 * silc_client_attributes_get and to get the SilcAttributePayload.
2255 * This function Returns TRUE if the attribute was found and deleted.
2258 SilcBool silc_client_attribute_del(SilcClient client,
2259 SilcClientConnection conn,
2260 SilcAttribute attribute,
2261 SilcAttributePayload attr);
2263 /****f* silcclient/SilcClientAPI/silc_client_attributes_get
2267 * const SilcHashTable
2268 * silc_client_attributes_get(SilcClient client,
2269 * SilcClientConnection conn);
2273 * Returns pointer to the SilcHashTable which includes all the added
2274 * Requested Attributes. The caller must not free the hash table.
2275 * The caller may use SilcHashTableList and silc_hash_table_list to
2276 * traverse the table. Each entry in the hash table is one added
2277 * SilcAttributePayload. It is possible to delete a attribute
2278 * payload while traversing the table.
2281 SilcHashTable silc_client_attributes_get(SilcClient client,
2282 SilcClientConnection conn);
2284 /****f* silcclient/SilcClientAPI/silc_client_attributes_request
2288 * SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
2292 * Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
2293 * then all attributes are requested. Alternatively, `attribute' and
2294 * all variable arguments can each be requested attribute. In this case
2295 * the last must be set to zero (0) to complete the variable list of
2296 * requested attributes. See SilcAttribute for all attributes.
2297 * You can give the returned buffer as argument to for example
2298 * silc_client_get_client_by_id_resolve function.
2302 * Request all attributes
2303 * buffer = silc_client_attributes_request(0);
2305 * Request only the following attributes
2306 * buffer = silc_client_attributes_request(SILC_ATTRIBUTE_USER_INFO,
2307 * SILC_ATTRIBUTE_SERVICE,
2308 * SILC_ATTRIBUTE_MOOD, 0);
2311 SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
2317 #endif /* SILCCLIENT_H */