.ds RF FORMFEED[Page %]
.ds CF
.ds LH Internet Draft
-.ds RH XXX
+.ds RH 25 November 2002
.ds CH
.na
.hy 0
.nf
Network Working Group P. Riikonen
Internet-Draft
-draft-riikonen-silc-commands-04.txt XXX
-Expires: XXX
+draft-riikonen-silc-commands-04.txt 25 November 2002
+Expires: 25 April 2003
.in 3
1 Introduction .................................................. 2
1.1 Requirements Terminology .................................. 2
2 SILC Commands ................................................. 2
- 2.1 SILC Commands Syntax ...................................... 2
- 2.2 SILC Commands List ........................................ 4
- 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
+ 2.1 SILC Commands Syntax ...................................... 4
+ 2.2 SILC Command Argument Idioms .............................. 4
+ 2.3 SILC Commands List ........................................ 4
+ 2.4 SILC Command Status Payload ............................... 42
+3 SILC Status Types ............................................. 43
+4 Security Considerations ....................................... 49
+5 References .................................................... 49
+6 Author's Address .............................................. 51
+Appendix A ...................................................... 51
.ti 0
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 Payload
-
+The status messages defined with the command are recommendations.
+It is possible to return other status messages not listed with
+the command reply definition.
.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. Also note that
-all passphrases that may be sent in commands MUST be UTF-8 [RFC2279]
-encoded.
.ti 0
-2.2 SILC Commands List
+2.2 SILC Command Argument Idioms
+
+All commands that has an 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.
+
+All passphrases that may be sent in commands as arguments MUST be
+UTF-8 [RFC2279] encoded.
+
+All public keys and certificates that are sent as arguments are actually
+Public Key Payloads [SILC2]. This way it is possible to send different
+kind of public keys and certificate types as arguments.
+
+
+.ti 0
+2.3 SILC Commands List
This section lists all SILC commands, however, it is expected that a
implementation and especially client implementation has many more
The command replies include the Client ID of the nickname,
nickname and server name, user name and host name and user's real
- name. Client SHOULD process these replies only after the last
+ name. Client should process these replies only after the last
reply has been received with the STATUS_LIST_END status. If the
<count> option were defined in the query there will be only
<count> many replies from the server.
Identify command is used to query information about an entity by
the entity's name or ID. This command can be used to query
- information about clients, server and channels.
+ information about clients, servers and channels.
The query may find multiple matching entities. The <count> option
may be given to narrow down the number of accepted results. If
Implementations may not want to give interface access to this
command as it is hardly a command that would be used by an end
- user. However, it must be implemented as it is used with private
- message sending.
+ user. However, it must be implemented as it is most likely used
+ with private message sending.
The IDENTIFY command MUST be always sent to the router by server
so that all users are searched. However, server MUST still search
When nickname is changed new Client ID is generated. Server MUST
distribute SILC_NOTIFY_TYPE_NICK_CHANGE to local clients on the
channels (if any) the client is joined on. Then it MUST send
- SILC_PACKET_REPLACE_ID to its primary route to replace the old
- Client ID with the new one.
+ SILC_NOTIFY_TYPE_NICK_CHANGE notify to its primary route to
+ notify about nickname and Client ID change.
Reply messages to the command:
Arguments: (1) <Status Payload> (2) <New ID Payload>
(3) <nickname>
- This command is replied always with New ID Payload that is
+ This command replies 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
Max Arguments: 4
Arguments: (1) <Channel ID> (2) [<Client ID>]
- (3) [<adding client>] (4) [<removing client>]
+ (3) [<add | del>] (4) [<invite list>]
+
+ This command can be used to invite other clients to join to a
+ channel, and to manage the channel's invite list. The <Client
+ ID> argument is the target client's ID that is being invited.
+ The <Channel ID> is the Channel ID of the requested channel.
+ The sender of this command MUST be on the channel. The server
+ MUST also send the notify type SILC_NOTIFY_TYPE_INVITE to its
+ primary router and then to the client indicated by the <Client
+ ID>.
+
+ The <add | del> is an argument of size of 1 byte where 0x00 means
+ adding a client to invite list, and 0x01 means deleting a client
+ from invite list. The <invite list>, if present, indicates
+ the information to be added to or removed from the invite list.
+ It may include a string for matching clients, public key of a
+ client or Client ID of a client. The <invite list> format is
+ as follows:
+
+ 2 bytes - Number of arguments in the list
+ variable length - Argument Payloads
+
+ The following Argument Types has been defined for invite list
+ Argument Payloads:
- This command is used to invite other clients to join to the
- channel. The <Client ID> argument is the target client's ID that
- is being invited. The <Channel ID> is the Channel ID of the
- requested channel. The sender of this command MUST be on the
- channel. The server MUST also send the notify type
- SILC_NOTIFY_TYPE_INVITE to its primary router and then to the
- client indicated by the <Client ID>.
+ 0x01 - Argument is an invite string of following format:
- The <adding client> and <removing client> can be used to add to
- and remove from the invite list. The format of the <adding client>
- and <removing client> is as follows:
+ [<nickname>[@<server>]!][<username>]@[<hostname or IP/MASK>]
- [<nickname>[@<server>]!][<username>]@[<hostname>]
+ The <hostname> may also be in format of IP/MASK to indicate
+ a network.
+
+ 0x02 - Argument is the public key of a client
+ 0x03 - Argument is the Client ID of a client
+
+ If unknown type value is received or there is invalid amount of
+ Argument Payloads present in the list, the command MUST be
+ discarded. When argument that is to be deleted from the invite
+ list does not exist in the list the argument is ignored.
When adding to or removing from the invite list the server MUST
- send the notify type SILC_NOTIFY_TYPE_INVITE to its primary router
- and MUST NOT send it to the client which was added to the list.
+ send the notify type SILC_NOTIFY_TYPE_INVITE to its primary router.
The client which executes this command MUST have at least channel
operator privileges to be able to add to or remove from the invite
- list. The wildcards MAY be used with this command. If adding or
- removing more than one client then the lists are an comma (`,')
- separated.
-
- Note that the <Client ID> provided MUST be resolved into correct
- nickname and host name and add to the invite list before sending
- the notify packet.
-
+ list. The wildcards MAY be used with this command. When this
+ command is used to invite explicit client with <Client ID> the
+ ID MUST be added to the invite list by the server.
+
When this command is given with only <Channel ID> argument then
the command merely returns the invite list of the channel. This
command MUST fail if the requested channel does not exist, the
requested <Client ID> is already on the channel or if the channel
is invite only channel and the caller of this command does not
- have at least channel operator privileges.
+ have at least channel operator privileges on the channel.
Reply messages to the command:
9 SILC_COMMAND_KILL
- Max Arguments: 2
- Arguments: (1) <Client ID> (2) [<comment>]
+ Max Arguments: 3
+ Arguments: (1) <Client ID> (2) [<comment>]
+ (3) [<auth payload>]
- This command is used by SILC operators to remove a client from
- SILC network. The removing has temporary effects and client may
- reconnect to SILC network. The <Client ID> is the client to be
- removed from SILC. The <comment> argument may be provided to
- give to the removed client some information why it was removed
- from the network.
+ This command can be used by SILC operators to remove a client from
+ SILC network. It also can be used by a normal client to remove
+ its own client from network by providing correct authentication
+ data.
+
+ Router operator killing a client:
+
+ The removing has temporary effects and client may reconnect to
+ SILC network. The <Client ID> is the client to be removed from SILC.
+ The <comment> argument may be provided to give to the removed client
+ some information why it was removed from the network. The killer
+ MUST have SILC operator privileges.
When killing a client the router MUST first send notify type
SILC_NOTIFY_TYPE_KILLED to all channels the client has joined.
The packet MUST NOT be sent to the killed client on the channels.
Then, the router MUST send the same notify type to its primary
router. Finally, the router MUST send the same notify type
- directly to the client which was killed.
+ directly to the client which was killed. The killed client MUST
+ also be removed from the invite lists of joined channels if it
+ is explicitly added in the invite lists.
+
+ Normal client killing by authentication:
+
+ When normal client executes this command the <Client ID> is the
+ destination client to be removed from the network. The client
+ MUST provide the <auth payload> which includes a digital signature
+ that MUST be verified with the public key of the client indicated
+ by <Client ID>. The <Client ID> MUST be local client to the server.
+ If the signature verification is successful the server sends
+ SILC_NOTIFY_TYPE_SIGNOFF to network and to the destination client.
+ The SILC_NOTIFY_TYPE_KILLED MUST NOT be used in this case. If the
+ verification fails the destination client remains in network.
+ The hash function used in <auth payload> computing is SHA1.
Reply messages to the command:
The <username> is the username set in the server configurations
as operator. The <authentication payload> is the data that the
client is authenticated against. It may be passphrase prompted
- for user on client's screen or it may be public key or certificate
- authentication data (data signed with private key). The public
- key that server will use to verify the signature found in the
- payload should be verified. It is recommended that the public
- key is saved locally in the server and server would not use
- any public keys received during the SKE.
+ for user on client's screen or it may be public key authentication
+ based on digital signatures. The public key used to verify the
+ signature should be locally saved in the server, and server should
+ not use public key received during the SKE to verify this signature.
After changing the mode the server MUST send the notify type
SILC_NOTIFY_TYPE_UMODE_CHANGE to its primary router.
o The user MUST be invited to the channel if the channel
is invite-only channel.
- o The Client ID/nickname/username/host name MUST NOT match
- any active bans.
+ o The Client ID/nickname/username/host name/public key
+ MUST NOT match any active bans.
o The correct passphrase MUST be provided if passphrase
is set to the channel.
channel. The <Client ID list> is formed by adding the ID Payloads
one after the other. The <client mode list> is formed by adding
32 bit MSB first order values one after the other. The <founder
- pubkey> is the public key of the channel founder.
+ pubkey> is the public key (or certificate) of the channel founder.
Client receives the channel key in the reply message as well
inside <Channel Key Payload>.
17 SILC_COMMAND_CMODE
- Max Arguments: 7
+ Max Arguments: 8
Arguments: (1) <Channel ID> (2) [<channel mode mask>]
(3) [<user limit>] (4) [<passphrase>]
(5) [<cipher>] (6) [<hmac>]
- (7) [<auth payload>]
+ (7) [<auth payload>] (8) [<founder pubkey>]
This command is used by client to set or change channel flags on
a channel. Channel has several modes that set various properties
channel key that even servers do not know. Naturally,
this requires that every client on the channel knows
the key before hand (it is considered to be pre-shared-
- key). The key material is RECOMMENDED to be processed
- as stated in the [SILC3] in the section Processing the
- Key Material.
+ key). The key material SHOULD be processed as stated
+ in the [SILC3] in the section Processing the Key Material.
As it is local setting it is possible to have several
private channel keys on one channel. In this case several
channel founder rights even if the client leaves the
channel. The <auth payload> is the Authentication Payload
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.
+ digital signature for that method. The passphrase or NONE
+ authentication methods MUST NOT be accepted.
+
+ The server does not save <auth payload> but MUST verify it.
+ The public key used to verify the payload is the <founder
+ pubkey> if present, or the public key of the client sending
+ this command. If <founder pubkey> is present also that
+ public key MUST be saved as founder's public key. This
+ mode may be set only if the <auth payload> was verified
+ successfully. 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
user mode, or during joining procedure with the command
SILC_COMMAND_JOIN.
+ If this mode is already set but the <founder pubkey> is
+ different the new key will replace the old founder key and
+ the new key is distributed in the network with the
+ SILC_NOTIFY_TYPE_CMODE_CHANGE notify. Only the original
+ founder may set this mode multiple times and the client
+ MUST have SILC_CUMODE_FOUNDER mode on the channel.
+
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.
+ many channels a user can own and how long they remain
+ persistent.
Typical implementation would use [+|-]f on user interface
to set/unset this mode.
Reply messages to the command:
- Max Arguments: 3
- Arguments: (1) <Status Payload> (2) <Channel ID>
- (3) <channel mode mask>
+ Max Arguments: 4
+ Arguments: (1) <Status Payload> (2) <Channel ID>
+ (3) <channel mode mask> (4) [<founder pubkey>]
This command replies with the changed channel mode mask that
- client MUST keep locally.
+ client MUST keep locally. It may also return the channel
+ founder's public key if it is set.
Status messages:
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 be 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.
19 SILC_COMMAND_KICK
Max Arguments: 3
- Arguments: (1) <Channel ID> (2) <Client ID>
+ Arguments: (1) <Channel ID> (2) <Client ID>
(3) [<comment>]
This command is used by channel operators to remove a client from
After kicking the client the server MUST send the notify type
SILC_NOTIFY_TYPE_KICKED to the channel and to its primary router.
- The channel key MUST also be re-generated after kicking, unless
- the SILC_CMODE_PRIVKEY mode is set.
+ The kicked client MUST be removed from the invite list of the
+ channel if it is explicitly added in the list. The channel key
+ MUST also be re-generated after kicking, unless the
+ SILC_CMODE_PRIVKEY mode is set.
Reply messages to the command:
20 SILC_COMMAND_BAN
Max Arguments: 3
- Arguments: (1) <Channel ID> (2) [<adding client>]
- (3) [<removing client>]
+ Arguments: (1) <Channel ID> (2) [<add | del>]
+ (3) [<ban list>]
This command is used to manage the ban list of the channel
indicated by the <Channel ID>. A client that is banned from
is executing this command MUST have at least channel operator
privileges on the channel.
- The <adding client> and <removing client> are used to add to and
- remove from the ban list. The format of the <adding client> and
- the <removing client> is of following format:
+ The <add | del> is an argument of size of 1 byte where 0x00 means
+ adding a client to ban list, and 0x01 means deleting a client
+ from ban list. The <ban list>, if present, indicates the
+ information to be added to or removed from the ban list. It
+ may include a string for matching clients, public key of a
+ client or Client ID of a client. The <ban list> format is
+ as follows:
- [<nickname>[@<server>]!][<username>]@[<hostname>]
+ 2 bytes - Number of arguments in the list
+ variable length - Argument Payloads
- The server MUST send the notify type SILC_NOTIFY_TYPE_BAN to its
- primary router after adding to or removing from the ban list.
- The wildcards MAY be used with this command. If adding or removing
- from than one clients then the lists are an comma (`,') separated.
+ The following Argument Types has been defined for ban list
+ Argument Payloads:
+
+ 0x01 - Argument is an ban string of following format:
+
+ [<nickname>[@<server>]!][<username>]@[<hostname or IP/MASK>]
- If this command is executed without the ban arguments the command
- merely replies with the current ban list.
+ The <hostname> may also be in format of IP/MASK to indicate
+ a network.
+ 0x02 - Argument is the public key of a client
+ 0x03 - Argument is the Client ID of a client
+
+ If unknown type value is received or there is invalid amount of
+ Argument Payloads present in the list, the command MUST be
+ discarded. When argument that is to be deleted from the ban
+ list does not exist in the list the argument is ignored.
+
+ The server MUST send the notify type SILC_NOTIFY_TYPE_BAN to its
+ primary router after adding to or removing from the ban list.
+ The wildcards MAY be used with this command. If this command
+ is executed without the ban arguments the command merely replies
+ with the current ban list.
Reply messages to the command:
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, but error is returned
- to the sender, except if the sender is on the channel, or the
- sender is server.
+ command MUST NOT send the list of users, except if the sender is
+ on the channel, or the sender is a server. Otherwise, error is
+ returned to the sender.
Reply messages to the command:
.ti 0
-2.3.1 SILC Command Status Payload
+2.4 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
.ti 0
-2.3.2 SILC Status Types
+3 SILC Status Types
Status messages are returned in SILC protocol in command reply
packet and in notify packet. The SILC_PACKET_COMMAND_REPLY is
"Bad version". Protocol or software version mismatch.
+ 54 SILC_STATUS_ERR_TIMEDOUT
+
+ "Operation timed out". Operation or service request timed
+ out, and thus was not processed.
+
+ 55 SILC_STATUS_ERR_UNSUPPORTED_PUBLIC_KEY
+
+ "Unsupported public key type". The public key or certificate
+ type is not supported in this implementation.
+
+ 56 SILC_STATUS_ERR_OPERATION_ALLOWED
+
+ "Operation is not allowed". A operation, for example a command,
+ is not allowed or it's execution is not allowed.
+
.in 3
.ti 0
-3 Security Considerations
+4 Security Considerations
Security is central to the design of this protocol, and these security
considerations permeate the specification. Common security considerations
.ti 0
-4 References
+5 References
[SILC1] Riikonen, P., "Secure Internet Live Conferencing (SILC),
Protocol Specification", Internet Draft, May 2002.
.ti 0
-5 Author's Address
+6 Author's Address
.nf
Pekka Riikonen
EMail: priikone@iki.fi
-This Internet-Draft expires XXX
+This Internet-Draft expires 25 April 2003
.ti 0
projects / silc.git / blobdiff