.ds RF FORMFEED[Page %]
.ds CF
.ds LH Internet Draft
-.ds RH XXX
+.ds RH 15 May 2002
.ds CH
.na
.hy 0
.nf
Network Working Group P. Riikonen
Internet-Draft
-draft-riikonen-silc-commands-03.txt XXX
-Expires: XXX
+draft-riikonen-silc-commands-03.txt 15 May 2002
+Expires: 15 November 2002
.in 3
2 SILC Commands ................................................. 2
2.1 SILC Commands Syntax ...................................... 2
2.2 SILC Commands List ........................................ 4
- 2.3 SILC Command Status Types ................................. 33
- 2.3.1 SILC Command Status Payload ......................... 33
- 2.3.2 SILC Command Status List ............................ 33
-3 Security Considerations ....................................... 38
-4 References .................................................... 38
-5 Author's Address .............................................. 40
+ 2.3 SILC Command Status Payload ............................... 40
+3 SILC Status Types ............................................. 41
+4 Security Considerations ....................................... 47
+5 References .................................................... 47
+6 Author's Address .............................................. 49
+Appendix A ...................................................... 49
.ti 0
Status messages:
SILC_STATUS_OK
- SILC_STATUS_ERR_TOO_MANY_TARGETS
SILC_STATUS_ERR_NOT_ENOUGH_PARAMS
SILC_STATUS_ERR_NO_SUCH_NICK
Every command reply also defines set of status message that it
may return inside the <Status Payload>. All status messages
-are defined in the section 2.3 SILC Command Status Types.
+are defined in the section 2.3 SILC Command Status Payload
.in 3
Every command that has some kind of ID as argument (for example
<Client ID>) are actually ID Payloads, defined in [SILC2] that includes
the type of the ID, length of the ID and the actual ID data. This
-way variable length ID's can be sent as arguments.
+way variable length ID's can be sent as arguments. Also note that
+all passphrases that may be sent in commands MUST be UTF-8 [RFC2279]
+encoded.
.ti 0
1 SILC_COMMAND_WHOIS
- Max Arguments: 3328
- Arguments: (1) [<nickname>[@<server>]] (2) [<count>]
- (3) [<Client ID>] (n) [...]
+ Max Arguments: 256
+ Arguments: (1) [<nickname>[@<server>]] (2) [<count>]
+ (3) [<Requested Attributes>] (4) [<Client ID>]
+ (n) [...]
Whois command is used to query various information about specific
user. The user may be requested by their nickname and server name.
down the number of accepted results. If this is not defined there
are no limit of accepted results. The query may also be narrowed
down by defining the server name of the nickname. The <count> is
- int string format.
+ 32 bit MSB first order integer.
It is also possible to search the user by Client ID. If the
<Client ID> is provided server MUST use it as the search value
To prevent miss-use of this command wildcards in the nickname
or in the server name are not permitted. It is not allowed
to request all users on some server. The WHOIS requests MUST
- be based on specific nickname request.
+ be based on explicit nickname request.
The WHOIS request MUST be always sent to the router by server
so that all users are searched. However, the server still MUST
search its locally connected clients. The router MUST send
- this command to the server which owns the requested client. That
- server MUST reply to the command. Server MUST NOT send whois
- replies to the client until it has received the reply from its
- router.
+ this command to the server which owns the requested client, if
+ the router is unable to provide all mandatory information about
+ the client. That server MUST reply to the command. Server MUST
+ NOT send whois replies to the client until it has received the
+ reply from its router.
+
+ The <Requested Attributes> is defined in [ATTRS] and can be used
+ to request various information about the client. See Appendix A
+ for definition of using these attributes in SILC.
Reply messages to the command:
- Max Arguments: 9
+ Max Arguments: 11
Arguments: (1) <Status Payload> (2) <Client ID>
(3) <nickname>[@<server>] (4) <username@host>
(5) <real name> (6) [<Channel Payload
list>]
(7) [<user mode>] (8) [<idle time>]
- (9) [<fingerprint>]
+ (9) [<fingerprint>] (10) <channel user
+ mode list>
+ (11) [<Attributes>]
This command may reply with several command reply messages to
include STATUS_LIST_START status in the first reply and
STATUS_LIST_END in the last reply to indicate the end of the
list. If there are only one reply the status is set to normal
- STATUS_OK.
+ STATUS_OK. If multiple Client IDs was requested then each found
+ and unfound client must cause successful or error reply,
+ respectively.
The command replies include the Client ID of the nickname,
nickname and server name, user name and host name and user's real
<count> option were defined in the query there will be only
<count> many replies from the server.
- The server may return the list of channel the client has joined.
- In this case the list is list of Channel Payloads. The Mode Mask
- in the Channel Payload (see [SILC2] and section 2.3.2.3 for the
- Channel Payload) is the client's mode on the channel. The list
- is encoded by adding the Channel Payloads one after the other.
-
- The server may also send client's user mode, idle time, and the
+ The server returns the list of channels if the client has
+ joined channels. In this case the list is list of Channel
+ Payloads. The Mode Mask in the Channel Payload is the channel's
+ mode. The list is encoded by adding the Channel Payloads one
+ after the other. Private and secret channels MUST NOT be sent,
+ except if the sender of this command is on those channels, or
+ the sender is server. The <channel user mode list> MUST also
+ be sent if client is joined channels. This list includes 32 bit
+ MSB first order values one after the other and each indicate
+ the user's mode on a channel. The order of these values MUST
+ be same as the channel order in the <Channel Payload list>.
+
+ The server also returns client's user mode, idle time, and the
fingerprint of the client's public key. The <fingerprint> is the
binary hash digest of the public key. The fingerprint MUST NOT
- be sent if the server has not verified the proof of posession of
+ be sent if the server has not verified the proof of possession of
the corresponding private key. Server can do this during the
SILC Key Exchange protocol. The <fingerprint> is SHA1 digest.
+ The <Attributes> is the reply to the <Requested Attributes>.
+ See the Appendix A for more information.
+
Status messages:
SILC_STATUS_OK
given to narrow down the number of accepted results. If this
is not defined there are no limit of accepted results. The query
may also be narrowed down by defining the server name of the
- nickname. The <count> is in string format.
+ nickname. The <count> is 32 bit MSB first order integer.
To prevent miss-use of this command wildcards in the nickname
or in the server name are not permitted. The WHOWAS requests MUST
3 SILC_COMMAND_IDENTIFY
- Max Arguments: 3328
+ Max Arguments: 256
Arguments: (1) [<nickname>[@<server>]] (2) [<server name>]
(3) [<channel name>] (4) [<count>]
(5) [<ID Payload>] (n) [...]
The query may find multiple matching entities. The <count> option
may be given to narrow down the number of accepted results. If
this is not defined there are no limit of accepted results. The
- <count> is in string format.
+ <count> is 32 bit MSB first order integer.
It is also possible to search the entity by its ID. If the
<ID Payload> is provided server must use it as the search value
a list of results. In this case the status payload will include
STATUS_LIST_START status in the first reply and STATUS_LIST_END in
the last reply to indicate the end of the list. If there are only
- one reply the status is set to normal STATUS_OK.
+ one reply the status is set to normal STATUS_OK. If multiple Client
+ IDs was requested then each found and unfound client must cause
+ successful or error reply, respectively.
When querying clients the <entity's name> must include the client's
nickname in the following format: nickname[@server]. The
Set/change nickname. This command is used to set nickname for
user. Nickname MUST NOT include any spaces (` '), non-printable
- characters, commas (`,') and any wildcard characters. Note that
- nicknames in SILC are case-sensitive which must be taken into
- account when searching clients by nickname.
+ characters, commas (`,') and any wildcard characters.
When nickname is changed new Client ID is generated. Server MUST
distribute SILC_NOTIFY_TYPE_NICK_CHANGE to local clients on the
Reply messages to the command:
- Max Arguments: 2
+ Max Arguments: 3
Arguments: (1) <Status Payload> (2) <New ID Payload>
+ (3) <nickname>
This command is replied always with New ID Payload that is
generated by the server every time user changes their nickname.
Client receiving this payload MUST start using the received
Client ID as its current valid Client ID. The New ID Payload
- is described in [SILC2].
+ is described in [SILC2]. The <nickname> is the user's new
+ nickname.
Status messages:
(3) [<invite list>]
This command replies with the invite list of the channel if it
- exists. The <invite list> may be omitted if the list was not
- altered.
+ exists.
Status messages:
SILC_STATUS_ERR_NOT_ON_CHANNEL
SILC_STATUS_ERR_USER_ON_CHANNEL
SILC_STATUS_ERR_NO_CHANNEL_PRIV
+ SILC_STATUS_ERR_RESOURCE_LIMIT
8 SILC_COMMAND_QUIT
SILC_STATUS_ERR_NO_SERVER_ID
- 11 SILC_COMMAND_CONNECT
-
- Max Arguments: 2
- Arguments: (1) <remote server/router> (2) [<port>]
-
- This command is used by operators to force a server to try to
- establish a new connection to remote server or router. The
- Operator MUST specify the server/router to be connected by
- setting <remote server> argument. The port is 32 bit MSB value.
-
- Reply messages to the command:
+ 11 SILC_COMMAND_STATS
Max Arguments: 1
- Arguments: (1) <Status Payload>
+ Arguments: (1) <Server ID>
- This command replies only with Status Payload.
+ This command is used to fetch various statistical information
+ from the server indicated by <Server ID>, which is the ID of
+ server where sender is connected to. Server receiving this
+ command MAY also send this further to its router for fetching
+ other cell and network wide statistics to accompany the reply.
+ Reply messages to the command:
+ Max Arguments: 3
+ Arguments: (1) <Status Payload> (2) <Server ID>
+ (3) [<statistics structure>]
+
+ This command replies with the Server ID of the server and
+ optional statistics structure which includes 32 bit MSB first
+ ordered integer values to represent various statistical
+ information. The structure is as follows:
+
+ starttime - time when server was started
+ uptime - uptime of the server
+ my clients - number of locally connected clients
+ my channels - number of locally created channels
+ my server ops - number of local server operators
+ my router ops - number of local router operators
+ cell clients - number of clients in local cell
+ cell channels - number of channels in local cell
+ cell servers - number of servers in local cell
+ clients - number of client in SILC network
+ channels - number of channels in SILC network
+ servers - number of servers in SILC network
+ routers - number of routers in SILC network
+ server ops - number of server operators in SILC network
+ router ops - number of router operators in SILC network
+
+ If some value is unknown it is set to zero (0) value. The
+ "starttime" is the start time of the server, and is seconds
+ since Epoch (POSIX.1). The "uptime" is time difference of
+ current time and "starttime" in the server, and is seconds
+ in value.
Status messages:
SILC_STATUS_OK
- SILC_STATUS_ERR_WILDCARDS
SILC_STATUS_ERR_NOT_REGISTERED
SILC_STATUS_ERR_NOT_ENOUGH_PARAMS
SILC_STATUS_ERR_TOO_MANY_PARAMS
- SILC_STATUS_ERR_NO_SERVER_PRIV
- SILC_STATUS_ERR_NO_ROUTER_PRIV
+ SILC_STATUS_ERR_NO_SUCH_SERVER_ID
+ SILC_STATUS_ERR_NO_SUCH_SERVER
+ SILC_STATUS_ERR_NO_SERVER_ID
12 SILC_COMMAND_PING
14 SILC_COMMAND_JOIN
- Max Arguments: 5
+ Max Arguments: 6
Arguments: (1) <channel> (2) <Client ID>
(3) [<passphrase>] (4) [<cipher>]
- (5) [<hmac>]
+ (5) [<hmac>] (6) [<founder auth>]
Join to channel/create new channel. This command is used to
join to a channel. If the channel does not exist the channel is
of the channel message are produced by the default HMAC or by
the <hmac> provided for the command.
+ The <founder auth> is Authentication Payload providing the
+ authentication for gaining founder privileges on the channel
+ when joining the channel. The client may provide this if it
+ knows that it is the founder of the channel and that the
+ SILC_CMODE_FOUNDER_AUTH mode is set on the channel. The server
+ MUST verify whether the client is able to gain the founder
+ privileges the same way as the client had given the
+ SILC_COMMAND_CUMODE command to gain founder privileges. The
+ client is still able to join the channel even if the founder
+ privileges could not be gained. The hash function used with
+ the <founder payload> MUST be sha1.
+
The server MUST check whether the user is allowed to join to
the requested channel. Various modes set to the channel affect
the ability of the user to join the channel. These conditions
o The user count limit, if set, MUST NOT be reached.
+ If the client provided correct <founder auth> payload it can
+ override these conditions, except the condition for the passphrase.
+ The correct passphrase MUST be provided even if <founder auth>
+ payload is provided.
+
Reply messages to the command:
Max Arguments: 14
16 SILC_COMMAND_UMODE
Max Arguments: 2
- Arguments: (1) <Client ID> (2) <client mode mask>
+ Arguments: (1) <Client ID> (2) [<client mode mask>]
This command is used by client to set/unset modes for itself.
However, there are some modes that the client MUST NOT set itself,
The following client modes are defined:
- 0x0000 SILC_UMODE_NONE
+ 0x00000000 SILC_UMODE_NONE
No specific mode for client. This is the initial
setting when new client is created. The client is
- normal client now.
+ normal client and is present in the network.
- 0x0001 SILC_UMODE_SERVER_OPERATOR
+ 0x00000001 SILC_UMODE_SERVER_OPERATOR
Marks the user as server operator. Client MUST NOT
set this mode itself. Server sets this mode to the
MAY unset the mode itself.
- 0x0002 SILC_UMODE_ROUTER_OPERATOR
+ 0x00000002 SILC_UMODE_ROUTER_OPERATOR
Marks the user as router (SILC) operator. Client
- MUST NOT this mode itself. Router sets this mode to
- the client when client attains the router operator
+ MUST NOT set this mode itself. Router sets this mode
+ to the client when client attains the router operator
privileges by SILC_COMMAND_SILCOPER command. Client
MAY unset the mode itself.
- 0x0004 SILC_UMODE_GONE
+ 0x00000004 SILC_UMODE_GONE
Marks that the user is not currently present in the
SILC Network. Client MAY set and unset this mode.
+
+ 0x00000008 SILC_UMODE_INDISPOSED
+
+ Marks that the user is currently indisposed and may
+ not be able to receive any messages, and that user may
+ not be present in the network. Client MAY set and
+ unset this mode.
+
+
+ 0x00000010 SILC_UMODE_BUSY
+
+ Marks that the user is currently busy and may not
+ want to receive any messages, and that user may not
+ be present in the network. Client MAY set and unset
+ this mode.
+
+
+ 0x00000020 SILC_UMODE_PAGE
+
+ User is not currently present or is unable to receive
+ messages, and prefers to be paged in some mechanism
+ if the user needs to be reached. Client MAY set and
+ unset this mode.
+
+
+ 0x00000040 SILC_UMODE_HYPER
+
+ Marks that the user is hyper active and is eager to
+ receive and send messages. Client MAY set and unset
+ this mode.
+
+
+ 0x00000080 SILC_UMODE_ROBOT
+
+ Marks that the client is actually a robot program.
+ Client MAY set and unset this mode.
+
+
+ 0x00000100 SILC_UMODE_ANONYMOUS
+
+ Marks that the client is anonymous client. Server
+ that specifically is designed for anonymous services
+ can set and unset this mode. Client MUST NOT set or
+ unset this mode itself. A client with this mode set
+ would have the username and the hostname information
+ scrambled by the server which set this mode.
+
+
+ 0x00000200 SILC_UMODE_BLOCK_PRIVMSG
+
+ Marks that the client wishes to block private
+ messages sent to the client, unless the Private
+ Message Key flag is set in the SILC packet header.
+ If this mode is set server MUST NOT deliver private
+ messages to the client without the Private Message
+ Key flag being set. The Private Message Key flag set
+ indicates that the private message is protected with
+ a key shared between the sender and the recipient.
+
+ A separate service could provide additional filtering
+ features for accepting private messages from certain
+ sender. However, this document does not specify such
+ service.
+
+ The client MAY set and unset this mode.
+
+
+ 0x00000400 SILC_UMODE_DETACHED
+
+ Marks that the client is detached from the SILC network.
+ This means that the actual network connection to the
+ client is lost but the client entry is still valid. The
+ detached client can be resumed at a later time. This
+ mode MUST NOT be set by client. It can only be set when
+ client has issued command SILC_COMMAND_DETACH. The server
+ sets this mode. This mode cannot be unset with this
+ command. It is unset when the client is resuming back to
+ the network and SILC_PACKET_RESUME_CLIENT packet is
+ received.
+
+ This flag MUST NOT be used to determine whether a packet
+ can be sent to the client or not. Only the server that
+ had the original client connection can make the decision
+ by knowing that the network connection is not active.
+ In this case the default case is to discard the packet.
+
+
+ 0x00000800 SILC_UMODE_REJECT_WATCHING
+
+ Marks that the client rejects that it could be watched
+ by someone else. If this mode is set notifications about
+ this client is not send, even if someone is watching the
+ same nickname this client has. Client MAY set and unset
+ this mode. Any changes for this client MUST NOT be
+ notified to any watcher when this mode is set.
+
+ A separate service could provide additional filtering
+ features for rejecting and accepting the watching from
+ certain users. However, this document does not specify
+ such service.
+
+
+ 0x00001000 SILC_UMODE_BLOCK_INVITE
+
+ Marks that the client wishes to block incoming invite
+ notifications. Client MAY set and unset this mode.
+ When set server does not deliver invite notifications
+ to the client. Note that this mode may make it harder
+ to join invite-only channels.
+
+ If the <client mode mask> was not provided this command merely
+ returns the mode mask to the client.
+
+
Reply messages to the command:
Max Arguments: 2
17 SILC_COMMAND_CMODE
Max Arguments: 7
- Arguments: (1) <Channel ID> (2) <channel mode mask>
+ Arguments: (1) <Channel ID> (2) [<channel mode mask>]
(3) [<user limit>] (4) [<passphrase>]
(5) [<cipher>] (6) [<hmac>]
(7) [<auth payload>]
of a channel. Modes may be masked together by ORing them thus
having several modes set. The <Channel ID> is the ID of the
target channel. The client changing channel mode MUST be on
- the same channel and poses sufficient privileges to be able to
+ the same channel and posses sufficient privileges to be able to
change the mode.
When the mode is changed SILC_NOTIFY_TYPE_CMODE_CHANGE notify
The following channel modes are defined:
- 0x0000 SILC_CMODE_NONE
+ 0x00000000 SILC_CMODE_NONE
No specific mode on channel. This is the default when
channel is created. This means that channel is just plain
normal channel.
- 0x0001 SILC_CMODE_PRIVATE
+ 0x00000001 SILC_CMODE_PRIVATE
Channel is private channel. Private channels are shown
in the channel list listed with SILC_COMMAND_LIST command
to set/unset this mode.
- 0x0002 SILC_CMODE_SECRET
+ 0x00000002 SILC_CMODE_SECRET
Channel is secret channel. Secret channels are not shown
in the list listed with SILC_COMMAND_LIST command. Secret
to set/unset this mode.
- 0x0004 SILC_CMODE_PRIVKEY
+ 0x00000004 SILC_CMODE_PRIVKEY
Channel uses private channel key to protect the traffic
on the channel. When this mode is set the client will be
to set/unset this mode.
- 0x0008 SILC_CMODE_INVITE
+ 0x00000008 SILC_CMODE_INVITE
Channel is invite only channel. Client may join to this
channel only if it is invited to the channel. Channel
to set/unset this mode.
- 0x0010 SILC_CMODE_TOPIC
+ 0x00000010 SILC_CMODE_TOPIC
The topic of the channel may only be set by client that
is channel founder or channel operator. Normal clients
to set/unset this mode.
- 0x0020 SILC_CMODE_ULIMIT
+ 0x00000020 SILC_CMODE_ULIMIT
User limit has been set to the channel. New clients
may not join to the channel when the limit set is
to set/unset this mode.
- 0x0040 SILC_CMODE_PASSPHRASE
+ 0x00000040 SILC_CMODE_PASSPHRASE
Passphrase has been set to the channel. Client may
join to the channel only if it is able to provide the
to set/unset this mode.
- 0x0080 SILC_CMODE_CIPHER
+ 0x00000080 SILC_CMODE_CIPHER
Sets specific cipher to be used to protect channel
traffic. The <cipher> argument is the requested cipher.
to set/unset this mode.
- 0x0100 SILC_CMODE_HMAC
+ 0x00000100 SILC_CMODE_HMAC
Sets specific hmac to be used to compute the MACs of the
channel message. The <hmac> argument is the requested hmac.
to set/unset this mode.
- 0x0200 SILC_CMODE_FOUNDER_AUTH
+ 0x00000200 SILC_CMODE_FOUNDER_AUTH
Channel founder may set this mode to be able to regain
channel founder rights even if the client leaves the
channel. The <auth payload> is the Authentication Payload
- consisting of the authentication method and authentication
- data to be used in the authentication. The server MUST
- NOT accept NONE authentication method. Also, if the
- method is public key authentication the server MUST NOT
- save the authentication data from the payload as the
- data is different on all authentications. In this case the
- server only saves the authentication method. However,
- server MUST verify the sent authentication payload and
- set the mode only if the verification was successful.
-
- Note that this mode is effective only in the current server.
- The client MUST connect to the same server later to be able
- to regain the channel founder rights. The server MUST save
- the public key of the channel founder and use that to identify
- the client which is claiming the channel founder rights.
- The rights may be claimed by the SILC_CUMODE_FOUNDER
- channel user mode using SILC_COMMAND_CUMODE command. The
- set authentication data remains valid as long as the channel
- exists or until the founder unsets this mode.
+ consisting of the public key authentication method and the
+ authentication data for that method. The passphrase
+ method cannot be used with this mode. The server MUST NOT
+ accept NONE authentication method. The server does not
+ save <auth payload> but MUST verify it. The public key
+ used to verify the payload is the public key of the
+ client sending this command. The mode may be set only
+ if the <auth payload> was verified successfully. The
+ server also MUST save the founder's public key. The
+ hash function used with the <auth payload> MUST be sha1.
+
+ The public key of the founder is sent in the
+ SILC_NOTIFY_TYPE_CMODE_CHANGE notify type so that other
+ routers and servers in the network may save the public key.
+ This way the founder can reclaim the founder rights back
+ to the channel from any server in the network. The founder
+ rights can be regained by the SILC_CUMODE_FOUNDER channel
+ user mode, or during joining procedure with the command
+ SILC_COMMAND_JOIN.
+
+ When this channel mode is set the channel also becomes
+ permanent. If all clients leave the channel while this
+ mode is set the channel MUST NOT be destroyed. The founder
+ can reclaim the founder mode back on these empty channels
+ at any time. Implementations MAY limit the number of how
+ many channels a user can own.
Typical implementation would use [+|-]f on user interface
to set/unset this mode.
+
+ 0x00000400 SILC_CMODE_SILENCE_USERS
+
+ Channel founder may set this mode to silence normal users
+ on the channel. Users with operator privileges are not
+ affected by this mode. Messages sent by normal users
+ are dropped by servers when this mode is set. This mode
+ can be used to moderate the channel. Only channel founder
+ may set/unset this mode.
+
+
+ 0x00000800 SILC_CMODE_SILENCE_OPERS
+
+ Channel founder may set this mode to silence operators
+ on the channel. When used with SILC_CMODE_SILENCE_USERS
+ mode this can be used to set the channel in state where only
+ the founder of the channel may send messages to the channel.
+ Messages sent by operators are dropped by servers when this
+ mode is set. Only channel founder may set/unset this mode.
+
+
To make the mode system work, client MUST keep the channel mode
mask locally so that the mode setting and unsetting would work
without problems. The client receives the initial channel mode
channel the server MUST distribute the changed channel mode mask
to all clients on the channel by sending the notify type
SILC_NOTIFY_TYPE_CMODE_CHANGE. The notify type MUST also be sent
- to the server's primary router.
+ to the server's primary router. If the <channel mode mask> was
+ not provided this command merely returns the mode mask to the
+ client.
Reply messages to the command:
SILC_STATUS_ERR_BAD_CHANNEL_ID
SILC_STATUS_ERR_NO_CHANNEL_ID
SILC_STATUS_ERR_NO_CHANNEL_PRIV
+ SILC_STATUS_ERR_NO_CHANNEL_FOPRIV
SILC_STATUS_ERR_UNKNOWN_MODE
SILC_STATUS_ERR_NO_SUCH_CLIENT_ID
SILC_STATUS_ERR_AUTH_FAILED
The <Channel ID> is the ID of the target channel. The <mode mask>
is OR'ed mask of modes. The <Client ID> is the target client.
The client changing channel user modes MUST be on the same channel
- as the target client and poses sufficient privileges to be able to
+ as the target client and posses sufficient privileges to be able to
change the mode.
When the mode is changed SILC_NOTIFY_TYPE_CUMODE_CHANGE notify
The following channel modes are defined:
- 0x0000 SILC_CUMODE_NONE
+ 0x00000000 SILC_CUMODE_NONE
No specific mode. This is the normal situation for client.
Also, this is the mode set when removing all modes from
the target client.
- 0x0001 SILC_CUMODE_FOUNDER
+ 0x00000001 SILC_CUMODE_FOUNDER
The client is channel founder of the channel. Usually this
mode is set only by the server when the channel was created.
been set, the client can claim channel founder privileges
by providing the <auth payload> that the server will use
to authenticate the client. The public key that server will
- use to verify the <auth payload> must the same public key
+ use to verify the <auth payload> MUST the same public key
that was saved when the SILC_CMODE_FOUNDER_AUTH channel
mode was set. The client MAY remove this mode at any time.
- 0x0002 SILC_CUMODE_OPERATOR
+ 0x00000002 SILC_CUMODE_OPERATOR
Sets channel operator privileges on the channel for a
client on the channel. Channel founder and channel operator
- MAY set/unset this mode.
+ MAY set/unset this mode. The client MAY remove this mode
+ at any time.
+
+
+ 0x00000004 SILC_CUMODE_BLOCK_MESSAGES
+
+ Marks that the client wishes not to receive any channel
+ messages sent for the channel. Client MAY set and unset
+ this mode to itself. Client MUST NOT set it to anyone else.
+ When this mode is set server MUST NOT deliver channel
+ messages to this client. Other packets such as channel
+ key packets are still sent to the client.
+
+ A separate service could provide additional filtering
+ features for accepting channel messages from certain
+ sender. However, this document does not specify such
+ service.
+
+
+ 0x00000008 SILC_CUMODE_BLOCK_MESSAGES_USERS
+
+ Marks that the client wishes not to receive any channel
+ messages sent from normal users. Only messages sent by
+ channel founder or channel operator is accepted. Client
+ MAY set and unset this mode to itself. Client MUST NOT
+ set it to anyone else. When this mode is set server MUST
+ NOT deliver channel messages that are sent by normal users
+ to this client.
+
+ A separate service could provide additional filtering
+ features for accepting channel messages from certain
+ sender. However, this document does not specify such
+ service.
+
+
+ 0x00000010 SILC_CUMODE_BLOCK_MESSAGES_ROBOTS
+
+ Marks that the client wishes not to receive any channel
+ messages sent from robots. Messages sent by users with
+ the SILC_UMODE_ROBOT user mode set are not delivered.
+ Client MAY set and unset this mode to itself. Client MUST
+ NOT set it to anyone else. When this mode is set server
+ MUST NOT deliver channel messages that are sent by robots
+ to this client.
+
+
+ 0x00000020 SILC_CUMODE_QUIET
+
+ Marks that the client cannot talk on the channel. This
+ mode can be set by channel operator or channel founder to
+ some other user that is not operator or founder. The
+ target client MUST NOT unset this mode. When this mode
+ is set the server MUST drop messages sent by this client
+ to the channel.
+
Reply messages to the command:
SILC_STATUS_ERR_BAD_CHANNEL_ID
SILC_STATUS_ERR_NO_CHANNEL_ID
SILC_STATUS_ERR_NO_CHANNEL_PRIV
+ SILC_STATUS_ERR_NO_CHANNEL_FOPRIV
SILC_STATUS_ERR_UNKNOWN_MODE
SILC_STATUS_ERR_NO_SUCH_CLIENT_ID
SILC_STATUS_ERR_AUTH_FAILED
SILC_STATUS_ERR_NO_CLIENT_ID
+
+
20 SILC_COMMAND_BAN
Max Arguments: 3
SILC_STATUS_ERR_NO_CHANNEL_ID
SILC_STATUS_ERR_NOT_ON_CHANNEL
SILC_STATUS_ERR_NO_CHANNEL_PRIV
+ SILC_STATUS_ERR_RESOURCE_LIMIT
- 21 SILC_COMMAND_CLOSE
- Max Arguments: 2
- Arguments: (1) <remote server/router> (2) [<port>]
- This command is used only by operator to close connection to a
- remote site.
+ 21 SILC_COMMAND_DETACH
+
+ Max Arguments: 0
+ Arguments:
+
+ This command is used to detach from the network. Client can
+ send this command to its server to indicate that it will be
+ detached. By detaching the client remains in the network but
+ the actual network connection to the server is closed. The
+ client may then later resume the old session back.
+
+ When this command is received the server MUST check that the
+ client is locally connected client, and set the user mode
+ SILC_UMODE_DETACHED flag. The SILC_NOTIFY_TYPE_UMODE_CHANGE
+ MUST be also sent to routers. The server then sends command
+ reply to this command and closes the network connection.
+ The server MUST NOT remove the client from its lists, or send
+ any signoff notifications for this client. See the [SILC1]
+ for detailed information about detaching.
Reply messages to the command:
Max Arguments: 1
Arguments: (1) <Status Payload>
- This command replies only with Status Payload.
+ This command replies only with the status indication.
Status messages:
SILC_STATUS_OK
- SILC_STATUS_ERR_NOT_ENOUGH_PARAMS
- SILC_STATUS_ERR_TOO_MANY_PARAMS
SILC_STATUS_ERR_NOT_REGISTERED
- SILC_STATUS_ERR_NO_SUCH_SERVER
- SILC_STATUS_ERR_NO_SERVER_PRIV
- SILC_STATUS_ERR_NO_SUCH_SERVER_ID
- 22 SILC_COMMAND_SHUTDOWN
+ 22 SILC_COMMAND_WATCH
- Max Arguments: 0
- Arguments: None
+ Max Arguments: 3
+ Arguments: (1) <Client ID> (2) [<add nickname>]
+ (3) [<del nickname>]
+
+ This command is used to set up a watch for <add nickname>
+ nickname. When a user in the network appears with the
+ nickname, or signoffs the network or user's mode is changed
+ the client which set up the watch will be notified about
+ this change. This can be used to watch for certain nicknames
+ in the network and receive notifications when for example a
+ friend appears in the network or leaves the network.
+
+ The <del nickname> is a nickname that has been previously
+ added to watch list and is now removed from it. Notifications
+ for that nickname will not be delivered anymore.
- This command is used only by operator to shutdown the server.
- All connections to the server will be closed and the server is
- shutdown.
+ The <Client ID> is the Client ID of the sender of this command.
+
+ The nickname set to watch MUST NOT include any wildcards.
+ Note also that a nickname may match several users since
+ nicknames are not unique. Implementations MAY set limits
+ for how many nicknames client can watch.
+
+ When normal server receives this command from client it
+ MUST send it to its router. Router will process the command
+ and actually keeps the watch list.
Reply messages to the command:
Max Arguments: 1
Arguments: (1) <Status Payload>
- This command replies only with Status Payload.
+ This command replies only with the status indication.
Status messages:
SILC_STATUS_OK
SILC_STATUS_ERR_NOT_REGISTERED
- SILC_STATUS_ERR_NO_SERVER_PRIV
+ SILC_STATUS_ERR_NOT_ENOUGH_PARAMS
+ SILC_STATUS_ERR_TOO_MANY_PARAMS
+ SILC_STATUS_ERR_BAD_NICKNAME
+ SILC_STATUS_ERR_WILDCARDS
+ SILC_STATUS_ERR_RESOURCE_LIMIT
+ SILC_STATUS_ERR_NO_SUCH_NICK
+ SILC_STATUS_ERR_NICKNAME_IN_USE
23 SILC_COMMAND_SILCOPER
Reply messages to the command:
- Max Arguments: 1
- Arguments: (1) <Status Payload>
+ Max Arguments: 2
+ Arguments: (1) <Status Payload> (2) <Channel ID>
- This command replies only with Status Payload.
+ The <Channel ID> is the ID of left channel.
Status messages:
This command is used to list user names currently on the requested
channel; either the argument <Channel ID> or the <channel name>.
One of these arguments must be present. The server MUST resolve
- the user names and send a comma (`,') separated list of user names
- on the channel. Server or router MAY resolve the names by sending
- SILC_COMMAND_WHOIS or SILC_COMMAND_IDENTIFY commands.
+ the joined clients and reply with a lists of users on the channel
+ and with list of user modes on the channel.
If the requested channel is a private or secret channel, this
- command MUST NOT send the list of users, as private and secret
- channels cannot be seen by outside. In this case the returned
- name list MAY include a indication that the server could not
- resolve the names of the users on the channel. Also, in this case
- Client ID's or client modes are not sent either.
+ command MUST NOT send the list of users, but error is returned
+ to the sender, except if the sender is on the channel, or the
+ sender is server.
Reply messages to the command:
SILC_STATUS_ERR_NO_SUCH_SERVER_ID
- 27 - 199
+ 27 SILC_COMMAND_SERVICE
+
+ Max Arguments: 256
+ Arguments: (1) [<service name>] (2) [<auth payload>]
+ (n) [...]
+
+ This command is used to negotiate a service agreement with a
+ remote server. If this command is given without arguments it
+ MAY return the service list, if it is publicly available. The
+ <service name> is a service specific identifier, and the
+ <auth payload> MAY be used to authenticate the requester to the
+ remote service. The authentication to a service may be based
+ on previous agreement with the requester and the service
+ provider. The command MAY also take additional service
+ specific arguments.
+
+ This document does not specify any services. How the services
+ are configured and put available in a server is also out of
+ scope of this document.
+
+ This command MAY be used by client to start using some service
+ in a server, but it also MAY be used by server to negotiate
+ to start using a service in some other server or router.
+
+ After the negotiation is done both of the parties need to know
+ from the service identifier how the service can be used. The
+ service can be considered to be a protocol which both of the
+ parties need to support.
+
+ Reply messages to the command:
+
+ Max Arguments: 256
+ Arguments: (1) <Status Payload> (2) [<service list>]
+ (3) [<service name>] (n) [...]
+
+
+ This command MAY reply with the <service list> when command is
+ given without arguments, and the list is a comma separated list
+ of service identifiers. The <service name> is the service that
+ the sender requested and this is provided when the server has
+ accepted the sender to use the <service name>. The command
+ reply MAY also have additional service specific arguments.
+
+ Status messages:
+
+ SILC_STATUS_OK
+ SILC_STATUS_ERR_NOT_REGISTERED
+ SILC_STATUS_ERR_NOT_ENOUGH_PARAMS
+ SILC_STATUS_ERR_TOO_MANY_PARAMS
+ SILC_STATUS_ERR_NO_SUCH_SERVICE
+ SILC_STATUS_ERR_AUTH_FAILED
+ SILC_STATUS_ERR_PERM_DENIED
+
+
+
+
+ 28 - 199
Currently undefined commands.
.in 3
-.ti 0
-2.3 SILC Command Status Types
-
.ti 0
2.3.1 SILC Command Status Payload
Command Status Payload is sent in command reply messages to indicate
the status of the command. The payload is one of argument in the
command thus this is the data area in Command Argument Payload described
-in [SILC2]. The payload is only 2 bytes of length. The following diagram
-represents the Command Status Payload (field is always in MSB order).
+in [SILC2]. The payload is only 2 bytes of length. The following
+diagram represents the Command Status Payload (field is always in
+MSB first order).
.in 21
1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| Status Message |
+| Status | Error |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
.in 3
.in 6
-o Status Message (2 bytes) - Indicates the status message.
- All Status messages are described in the next section.
+o Status (1 byte) - Indicates the status message type,
+ error, start of list, entry of list or end of list.
+
+o Error (1 byte) - Indicates the error if the Status
+ field is some list status, which means there are list
+ of errors.
+.in 3
+
+The values in Status and Error fields are set according
+the following rules:
+
+.in 6
+o If there is single reply and error has not occurred
+ then Status field includes value SILC_STATUS_OK, and
+ the Error field MUST be ignored (and set to zero
+ value).
+
+o If there is single error, then Status field includes
+ one of the error values, and the Error field MUST be
+ ignored (and set to zero value).
+
+o If there will be multiple successful command replies
+ then Status field includes SILC_STATUS_LIST_START,
+ SILC_STATUS_LIST_ITEM or SILC_STATUS_LIST_END value,
+ and Error field is set to SILC_STATUS_OK.
+
+o If there are multiple error replies then Status field
+ includes SILC_STATUS_LIST_START, SILC_STATUS_LIST_ITEM
+ or SILC_STATUS_LIST_END value, and the Error field
+ includes the error value.
.in 3
+This way it is possible to send single successful or
+single error reply, but also multiple successful and
+multiple error replies. Note that it is possible to
+send both list of successful replies and list of error
+replies at the same time, however in this case the
+list of error replies MUST be sent after the successful
+replies. This way the recipient may ignore the multiple
+errors if it wishes to do so. Also note that in this
+case the successful and error replies belong to the
+same list.
+
+All Status messages are described in the next section.
+
.ti 0
-2.3.2 SILC Command Status List
+2.3.2 SILC Status Types
+
+Status messages are returned in SILC protocol in command reply
+packet and in notify packet. The SILC_PACKET_COMMAND_REPLY is
+the command reply packet and status types are sent inside the
+Status Payload as one of command reply argument, as defined in
+previous sections. For SILC_PACKET_NOTIFY packet they can be sent
+as defined in [SILC2] for SILC_NOTIFY_TYPE_ERROR type. The same
+types defined in this section are used in both cases.
-Command Status messages are returned in the command reply messages
-to indicate whether the command were executed without errors. If error
-has occurred the status indicates which error occurred. Status payload
-only sends numeric reply about the status. Receiver of the payload must
-convert the numeric values into human readable error messages. The
-list of status messages below has an example human readable error
-messages that client may display for the user.
+When returning status messages in the command reply message they
+indicate whether the command was executed without errors. If error
+occurred the status indicates which error occurred.
-List of all defined command status messages following.
+When sending status messages in SILC_NOTIFY_TYPE_ERROR notify type
+they always send some error status. Usually they are sent to
+indicate that error occurred while processing some SILC packet.
+Please see the [SILC1] and [SILC2] for more information sending
+status types in SILC_NOTIFY_TYPE_ERROR notify.
+
+The Status Types are only numeric values and the receiver must
+convert the numeric values into human readable messages if this
+is desired in the application.
+
+List of all defined status types:
.in 0
Generic status messages:
"No such server". Requested server name does not exist.
- 13 SILC_STATUS_ERR_TOO_MANY_TARGETS
+ 13 SILC_STATUS_ERR_INCOMPLETE_INFORMATION
- "Duplicate recipients. No message delivered". Message were
- tried to be sent to recipient which has several occurrences in
- the recipient list.
+ "Incomplete registration information". Information remote
+ sent was incomplete.
14 SILC_STATUS_ERR_NO_RECIPIENT
22 SILC_STATUS_ERR_NO_SUCH_CLIENT_ID
"No such Client ID". Client ID provided does not exist.
+ The unknown Client ID MUST be provided as next argument
+ in the reply.
23 SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID
"No such Channel ID". Channel ID provided does not exist.
+ The unknown Channel ID MUST be provided as next argument
+ in the reply.
24 SILC_STATUS_ERR_NICKNAME_IN_USE
47 SILC_STATUS_ERR_NO_SUCH_SERVER_ID
"No such Server ID". Server ID provided does not exist.
+ The unknown Server ID MUST be provided as next argument
+ in the reply.
+
+ 48 SILC_STATUS_ERR_RESOURCE_LIMIT
+
+ "No more resources available". This can mean that server cannot
+ or will not accept something due to resource limitations.
+
+ 49 SILC_STATUS_ERR_NO_SUCH_SERVICE
+
+ "Service does not exist". Requested service identifier is
+ unknown.
+
+ 50 SILC_STATUS_ERR_NOT_AUTHENTICATED
+
+ "You have not been authenticated". Remote connection is not
+ authenticated even though it is supposed to be.
+
+ 51 SILC_STATUS_ERR_BAD_SERVER_ID
+
+ "Server ID is not valid". Provided server ID is not valid.
+
+ 52 SILC_STATUS_ERR_KEY_EXCHANGE_FAILED
+
+ "Key exchange failed". Key Exchange protocol failed.
+
+ 53 SILC_STATUS_ERR_BAD_VERSION
+
+ "Bad version". Protocol or software version mismatch.
.in 3
4 References
[SILC1] Riikonen, P., "Secure Internet Live Conferencing (SILC),
- Protocol Specification", Internet Draft, April 2001.
+ Protocol Specification", Internet Draft, May 2002.
[SILC2] Riikonen, P., "SILC Packet Protocol", Internet Draft,
- April 2001.
+ May 2002.
[SILC3] Riikonen, P., "SILC Key Exchange and Authentication
- Protocols", Internet Draft, April 2001.
+ Protocols", Internet Draft, May 2002.
[IRC] Oikarinen, J., and Reed D., "Internet Relay Chat Protocol",
RFC 1459, May 1993.
[RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
+[RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", RFC 2279, January 1998.
-
-
-
-
+[ATTRS] Riikonen, P., "User Online Presence and Information
+ Attributes", Internet Draft, May 2002.
.ti 0
.nf
Pekka Riikonen
-Snellmanninkatu 34 A 15
+Snellmaninkatu 34 A 15
70100 Kuopio
Finland
-EMail: priikone@silcnet.org
+EMail: priikone@iki.fi
+
+This Internet-Draft expires 15 November 2002
-This Internet-Draft expires XXX
-
+
+.ti 0
+Appendix A
+
+This appendix defines the usage of the <Requested Attributes> argument in
+the SILC_COMMAND_WHOIS command. The attributes are defined in [ATTRS],
+and may be used to request additional information about the user. Since
+the information that may be requested using the attributes is something
+that server cannot deliver to the sender, it is possible to send the WHOIS
+command directly to the destination client whom will then provide the
+requested attributes. This requires the servers to relay the WHOIS
+command to the client, and it requires capability for handling the WHOIS
+command in the client end.
+
+The <Requested Attributes> MAY include several attributes that are
+requested. The format and encoding of the <Requested Attributes> is as
+defined in [ATTRS]. When <Requested Attributes> argument is set the
+server MAY process the attributes to see whether it can narrow down
+the WHOIS search, for example when searching with a nickname. The
+normal servers MUST process the WHOIS command as normal WHOIS command,
+that is to send the command directly to the router. The router MAY
+process the attributes, but it MUST send the command to the server
+that owns the requested client.
+
+The server that owns the client and receives the command MUST check
+whether the client is detached from the network. If it is detached,
+that is the user mode has the SILC_UMODE_DETACHED mode set, it SHOULD
+process the attributes and provide as many of the requested attributes
+as possible and then send reply back to the sender. If the client is
+active in the network it MUST send the command to the client for
+processing.
+
+The client receiving WHOIS command SHOULD check whether the
+<Requested Attributes> argument is set. If it is not set then the
+WHOIS command SHOULD be discarded. The client processes the requested
+attributes and SHOULD reply to each of the requested attribute with
+either valid value, or with an indication that the requested attribute
+is not known or supported. This is to be done as defined in [ATTRS].
+The client always MUST send a reply to the command when some attributes
+were requested. The client MAY also add additional attributes to the
+reply even if they were not requested. The client MAY also digitally
+sign the attributes with ATTRIBUTE_USER_DIGITAL_SIGNATURE as defined
+in [ATTRS]. Then the client sends the reply back to the sender of
+the command. The command reply that client assembles does not need
+to include any other argument but the <Status Payload> (1), and the
+<Attributes> (11). The server receiving reply from client MUST allow
+this sort of command reply for WHOIS command.
+
+The information received from the client MAY be cached in the
+server's end. The caching may be desired for example if the client
+can be detached from the network. This way the server is then able
+to provide at least partial information for a requester. The
+server MAY also process the command reply and verify whether the
+attributes provided in the reply are actually valid. If it can do
+this, and verify that they indeed are valid values it MAY append
+a digital signature at the end of the attributes with the
+ATTRIBUTE_SERVER_DIGITAL_SIGNATURE as defined in [ATTRS]. The
+server then MUST provide valid WHOIS command reply to the sender
+of the command. Other servers and routers that receive the command
+reply en route to the original sender MAY also cache the information.
+
+The client which receives the command reply to the WHOIS command
+SHOULD verify the ATTRIBUTE_USER_DIGITAL_SIGNATURE and the
+ATTRIBUTE_SERVER_DIGITAL_SIGNATURE if they are provided.
projects / silc.git / blobdiff