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 ............................... 33
+3 SILC Status Types ............................................. 33
+4 Security Considerations ....................................... 38
+5 References .................................................... 38
+6 Author's Address .............................................. 40
+Appendix A ...................................................... xx
.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 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
1 SILC_COMMAND_WHOIS
Max Arguments: 256
- Arguments: (1) [<nickname>[@<server>]] (2) [<count>]
- (3) [<Client ID>] (n) [...]
+ 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
<count> option were defined in the query there will be only
<count> many replies from the server.
- The server may return the list of channels if the client has
+ 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 (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
+ 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
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
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
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
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
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.
+ 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
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 noticising that the network connection is not active.
+ 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.
+
If the <client mode mask> was not provided this command merely
returns the mode mask to the client.
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.
+
+
Reply messages to the command:
Max Arguments: 4
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_DETACH
- 21 <deprecated command>
+ 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.
- 22 <deprecated command>
+ 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 the status indication.
+
+ Status messages:
+
+ SILC_STATUS_OK
+ SILC_STATUS_ERR_NOT_REGISTERED
+
+
+ 22 SILC_COMMAND_WATCH
+
+ 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.
+
+ 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 the status indication.
+
+ 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_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
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 sepcific identifier, and the
+ <auth payload> MAY be used to authenticate the requestor to the
+ remote service. The authentication to a service may be based
+ on previous agreement with the requestor 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
.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.
+
+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.
-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 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.
-List of all defined command status messages following.
+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:
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.
.in 3
EMail: priikone@iki.fi
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 requestor. 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 enroute 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