From 95c9a2d555c2262629cc8900bc887b527c3a77bf Mon Sep 17 00:00:00 2001 From: Pekka Riikonen Date: Thu, 17 Apr 2003 11:09:44 +0000 Subject: [PATCH] updates. --- doc/draft-riikonen-presence-attrs-02.nroff | 638 +++++ doc/draft-riikonen-silc-commands-05.nroff | 2554 +++++++++++++++++ doc/draft-riikonen-silc-ke-auth-07.nroff | 1148 ++++++++ doc/draft-riikonen-silc-pp-07.nroff | 2917 ++++++++++++++++++++ doc/draft-riikonen-silc-spec-07.nroff | 14 +- 5 files changed, 7270 insertions(+), 1 deletion(-) create mode 100644 doc/draft-riikonen-presence-attrs-02.nroff create mode 100644 doc/draft-riikonen-silc-commands-05.nroff create mode 100644 doc/draft-riikonen-silc-ke-auth-07.nroff create mode 100644 doc/draft-riikonen-silc-pp-07.nroff diff --git a/doc/draft-riikonen-presence-attrs-02.nroff b/doc/draft-riikonen-presence-attrs-02.nroff new file mode 100644 index 00000000..0b0e70fe --- /dev/null +++ b/doc/draft-riikonen-presence-attrs-02.nroff @@ -0,0 +1,638 @@ +.pl 10.0i +.po 0 +.ll 7.2i +.lt 7.2i +.nr LL 7.2i +.nr LT 7.2i +.ds LF Riikonen +.ds RF FORMFEED[Page %] +.ds CF +.ds LH Internet Draft +.ds RH XXX +.ds CH +.na +.hy 0 +.in 0 +.nf +Network Working Group P. Riikonen +Internet-Draft +draft-riikonen-presence-attrs-02.txt XXX +Expires: XXX + +.in 3 + +.ce 2 +User Online Presence and Information Attributes + + +.ti 0 +Status of this Memo + +This document is an Internet-Draft and is in full conformance with +all provisions of Section 10 of RFC 2026. Internet-Drafts are +working documents of the Internet Engineering Task Force (IETF), its +areas, and its working groups. Note that other groups may also +distribute working documents as Internet-Drafts. + +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any +time. It is inappropriate to use Internet-Drafts as reference +material or to cite them other than as "work in progress." + +The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt + +The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html + +The distribution of this memo is unlimited. + + +.ti 0 +Abstract + +This document defines set of attributes that can represent the online +user's presence in a network, and to provide general information about +the user. The purpose is to provide a generic mechanism to share +online presence and status, and general information about the user +to be used in several kind of network protocols and applications. +These attributes could be used by for example chat and conferencing +protocols (such as Instant Message protocols), network games, and +other similar network protocols and applications that has online +users in a network. + + + + + + + +.ti 0 +Table of Contents + +.nf +1 Introduction .................................................. 2 + 1.1 Requirements Terminology .................................. 2 +2 Attributes Concept ............................................ 3 + 2.1 Requesting Attributes ..................................... 3 + 2.2 Replying Attributes ....................................... 3 + 2.3 Attribute Data Types ...................................... 4 + 2.4 Attribute Payload ......................................... 4 + 2.5 Attributes ................................................ 5 +3 Security Considerations ....................................... 11 +4 References .................................................... 12 +5 Author's Address .............................................. 13 + + +.ti 0 +1. Introduction + +This document defines set of attributes that can represent the online +user's presence in a network, and to provide general information about +the user. The purpose is to provide a generic mechanism to share +online presence and status, and general information about the user +to be used in several kind of network protocols and applications. +These attributes could be used by for example chat and conferencing +protocols (such as Instant Message protocols), network games, and +other similar network protocols and applications that has online +users in a network. + +This document does not define these attributes to be used in any +specific protocol, but assumes that they can be used generally in +any kind of online network protocol. Furthermore, the document +pays attention to special needs of various protocols, such as +mobile network protocols, which requires the attributes to be +both robust and compact. The attributes are also considered to be +easily implementable and for this reason a clear and robust structure +was chosen for the attributes. + +This document is strongly influenced by Wireless Village Initiative +where similar attributes are defined, and credits for the ideas are +due there. However, they are defined only in the context of the +Wireless Village, and the format of the attributes used is not +suitable for general purpose usage. + + +.ti 0 +1.1 Requirements Terminology + +The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, +MAY, and OPTIONAL, when they appear in this document, are to be +interpreted as described in [RFC2119]. + + +.ti 0 +2 Attributes Concept + +Many network protocols needs a way to transfer and retrieve status +information about users in a network. For example, many chat and +conferencing protocols such as IRC, and all Instant Message (IM) +protocols, such as ICQ has a way to retrieve presence and status +information about the users in the network. This could be added to +several other kind of network protocols as well, and for this reason +a defined mechanism to provide these informations is needed. + +The attributes are usually requested by an entity in the network +from other entity, usually a user or end user's device in the network. +The recipient then replies to each of the requested attributes and +sends the reply to the requester. + +This document does not define the actual transport for requesting and +providing the replies to the requests, since this is irrelevant. +This document defines a payload for requesting, and providing the +information, but how the payload is transported is not defined in +this document. In a client-server network model the user requesting +attributes usually destine the request to a remote user and the +server relays the attributes to the remote user. It is also possible +that the concept is not user-to-user, but the server replies to the +requested attributes on behalf of the user. + + +.ti 0 +2.1 Requesting Attributes + +When an entity requests attributes from a user in the network, +it assembles a list of Attribute Payloads, and sets the requested +attribute value into the payload. Each requested attribute is a separate +Attribute Payload and they MUST be appended one after the other. The +requester need to understand that the recipient may not understand all +the requested attributes, and may not reply to all of the requested +attributes. The requester also need to understand that the recipient +may reply with additional attributes that were not requested. + + +.ti 0 +2.2 Replying Attributes + +When en entity receives the Attribute Payloads it parses them one after +the other. The entity can parse each of the Attribute Payload separately +since it knows the length of the current attribute; next attribute +begins after the current attribute ends. The entity then checks the +requested attribute and SHOULD reply either with valid value or with +an indication that the attribute is unsupported or unknown. It is +also possible to reply with additional attributes that were not +requested. + +When replying to the requested attributes the entity assembles a list +of Attribute Payloads, each including the attribute type and the +actual attribute data. + + +.ti 0 +2.3 Attribute Data Types + +This section defines basic data types that can appear in the attributes +in this document. + +All integer values are stored in the MSB first order. The size of the +integer is provided separately with the attribute. Integer is +represented as "integer" in this documentation. + +Strings are always UTF-8 [RFC2279] encoded, and include 2 bytes length +field indicating the length of the string. Hence, when "string" value +appears in this documentation it is encoded as: + +.in 6 +Length Type Value +2 bytes integer Length of String field +variable UTF-8 String +.in 3 + +If string is not present then the length field includes zero (0) +value. + +Boolean value is represented as "boolean" and its size is 1 byte. +Value 0x00 indicates false value and value 0x01 indicates true value. + + +.ti 0 +2.4 Attribute Payload + +The Attribute Payload is used to request an attribute, and to reply +to the requested attribute. One payload includes one attribute. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Attribute | Attr Flags | Attribute Length | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Attribute Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 1: Attribute Payload + + +.in 6 +o Attribute (1 byte) - Indicates the attribute included in this + Attribute Payload. + +o Attribute Flags (1 byte) - Indicates the flags associated + with this attribute. The following flags are defined: + + 0x01 ATTRIBUTE_FLAG_INVALID + + The attribute value in Attribute Data is invalid, or + unknown. This may be set to indicate that a requested + attribute is not available, its value is unknown, or + sender does not understand it. + + 0x02 ATTRIBUTE_FLAG_VALID + + The attribute value is included in the Attribute Data. + + When sending this payload to request attributes this value + MUST be set to zero (0) value. When sending a reply to the + request this field MUST NOT include a zero (0) value. + +o Attribute Length (2 bytes) - Indicates the length of the + Attribute Data field, not including any other field. + +o Attribute Data (variable length) - The Attribute Data. + The contents of this field is attribute specific, defined + subsequently. +.in 3 + + +.ti 0 +2.5 Attributes + +The following values can appear in the Attribute field in the +Attribute Payload to indicate the content of the attribute. The +format of the attribute data is represented as length, type and +value. Example: + +.in 6 +Length Type Value +2 bytes integer Some integer value +variable string Some string +1 byte boolean Boolean value +.in 3 + +When sending multiple Attribute Payloads it is possible to include +multiple same attributes in the packet. + + +.in 6 +0 ATTRIBUTE_NONE + + This attribute is reserved and it is never sent. + + +1 ATTRIBUTE_USER_INFO + + This attribute includes general information about the user, their + name and contact information. The content of this attribute is + a VCard version 3.0 as defined in RFC 2426 [RFC2426] and RFC 2425 + [RFC2425]. Note that some of the information that VCard provides + can be also provided in the means of providing other attributes. + The rationale for this is that the VCard does not provide all the + information, or with the required precision that may be desired in + some applications. It is therefore RECOMMENDED that this attribute + would be used to provide only basic and constant user information, + such as name and contact information, but not online status + information. + + Length Type Value + variable VCard Basic user information + + +2 ATTRIBUTE_SERVICE + + This attribute indicates a service in the Internet that the user + is currently using or has logged in. It also shows when the user + started using the service, and how long user has been idle in the + service. The value of this attribute is as follows: + + Length Type Value + 4 bytes integer Service Port (IANA specified) + variable string Service Address + 1 byte boolean Online status. If this is set to + 0x01 (true) it means the user is online + in the service. Set to 0x00 (false) when + out of reach. + variable string Signon date and time, UTC date, format as + in ISO 8601 + 4 bytes integer Idle time + + +3 ATTRIBUTE_STATUS_MOOD + + This attribute indicates the mood of the user. It can indicate + whether the user is eager to participate in the network. The + value of this attribute is as follows: + + Length Type Value + 4 bytes integer Mood mask (values ORed together) + + The following mood values are defined: + + 0x00000000 MOOD_NORMAL No specific mood, normal mood + 0x00000001 MOOD_HAPPY The user feels happy + 0x00000002 MOOD_SAD The user feels sad + 0x00000004 MOOD_ANGRY The user feels angry + 0x00000008 MOOD_JEALOUS The user feels jealous + 0x00000010 MOOD_ASHAMED The user feels ashamed + 0x00000020 MOOD_INVINCIBLE The user feels invincible + 0x00000040 MOOD_INLOVE The user feels being in love + 0x00000080 MOOD_SLEEPY The user feels sleepy + 0x00000100 MOOD_BORED The user feels bored + 0x00000200 MOOD_EXCITED The user feels excited + 0x00000400 MOOD_ANXIOUS The user feels anxious + + +4 ATTRIBUTE_STATUS_FREETEXT + + This attribute includes the user's online status free text. It + can provide personal status as a text message. The contents of + this attribute is a UTF-8 encoded free text string. + + Length Type Value + variable string Free text status string + + +5 ATTRIBUTE_STATUS_MESSAGE + + This attribute includes the user's online status message. It + could provide for example a multi media message showing the status + of the user. The contents of this attribute is a MIME object, + which can be used to provide for example video, audio, image or + other similar status message. It could also provide a reference + to the message, for example an URL address. + + Length Type Value + variable MIME Status message as MIME object + + +6 ATTRIBUTE_PREFERRED_LANGUAGE + + This attribute indicates the preferred language to be used when + communicating. The encoding of this attribute is as follows: + + Length Type Value + variable string ISO 639-2/T three letter code + + +7 ATTRIBUTE_PREFERRED_CONTACT + + This attribute indicates the preferred contact methods. It can + indicate the method the user prefers when contacting. The value + of this attribute is as follows: + + Length Type Value + 4 bytes integer Contact mask (values ORed together) + + The following contact methods are defined: + + 0x00000000 CONTACT_NONE No specific preferred contact method + 0x00000001 CONTACT_EMAIL Email is preferred + 0x00000002 CONTACT_CALL Phone call is preferred + 0x00000004 CONTACT_PAGE Paging is preferred + 0x00000008 CONTACT_SMS SMS is preferred + 0x00000010 CONTACT_MMS MMS is preferred + 0x00000020 CONTACT_CHAT Chatting is preferred + + +8 ATTRIBUTE_TIMEZONE + + This attribute can be used to provide the current local time for + the user. The contents of this attribute is a UTF-8 encoded + string and the format of the string is UTC time zone defined + in the ISO 8601. + + Length Type Value + variable string UTC date, format as in ISO 8601 + + Note that ATTRIBUTE_USER_INFO may also provide this information. + However it is RECOMMENDED that this attribute is used when + current time zone information is provided. + + +9 ATTRIBUTE_GEOLOCATION + + This attribute can be used to provide measured global location of + the user. How this information is gathered is out of scope of + this document. The attribute can provide latitude and longitude + lateral positions, but also a vertical position. A parameter + describing the accuracy of the information can also be provided. + + Length Type Value + variable string Longitude (ex. 31 17 14.321W) + variable string Latitude (ex. 12 11 21.2N) + variable string Altitude + variable string Accuracy in meters + + Note that ATTRIBUTE_USER_INFO may also provide this information, + however it does not have the vertical position, or the accuracy + parameter. It is RECOMMENDED that this attribute is used when + providing current global position information. + + +10 ATTRIBUTE_DEVICE_INFO + + This attribute includes information about the user's device. + The encoding of this attribute is as follows: + + Length Type Value + 4 bytes integer Device type + variable string Name of the device manufacturer + variable string Device version + variable string Device model + variable string Device language (ISO 639-2/T) + + The following Device types are defined: + + 0 DEVICE_COMPUTER Device is a computer + 1 DEVICE_MOBILE_PHONE Device is a mobile phone + 2 DEVICE_PDA Device is a PDA + 3 DEVICE_TERMINAL Device is a terminal + + +11 ATTRIBUTE_EXTENSION + + This attribute indicates that the attribute value is vendor, + application or service specific attribute extension. This field + MUST include a MIME object, which is the extension value. This + document does not specify any explicit MIME objects for this + attribute. + + Length Type Value + variable MIME Attribute extension as MIME object + + +12 ATTRIBUTE_USER_PUBLIC_KEY + + This attribute includes the user's public key or certificate. + As the public key and certificate format depends on which sort + of algorithm or certificate encoding user is using we need to + define a mechanism to differentiate the public key types from + each other. This document specifies the most common public keys + and certificates. This attribute can be used to deliver the + user's public key, and it MUST be present if also the + ATTRIBUTE_USER_DIGITAL_SIGNATURE is present. Note that the + recipient of this attribute SHOULD verify the public key from + a third party, for example from Certification Authority. If + there are more than one ATTRIBUTE_USER_PUBLIC_KEY attributes set + and ATTRIBUTE_USER_DIGITAL_SIGNATURE is also set, the digital + signature SHOULD be verifiable with the first set public key. + + Length Type Value + variable string Public key/certificate type + variable data Public key/certificate data + + The following public key/certificate types are defined: + + ssh-rsa SSH RSA public key [SSH-TRANS] + ssh-dss SSH DSS public key [SSH-TRANS] + silc-rsa SILC RSA public key [SILC1] + silc-dss SILC DSS public key [SILC1] + pgp-sign-rsa OpenPGP RSA certificate [RFC2440] + pgp-sign-dss OpenPGP DSS certificate [RFC2440] + x509v3-sign-rsa X.509 Version 3 RSA certificate [RFC2459] + x509v3-sign-dss X.509 Version 3 DSS certificate [RFC2459] + + Most of these public key/certificate types are equivalent to + the types specified for SSH protocol [SSH-TRANS] and are expected + to be officially assigned by IANA. + + The encoding of the public key/certificate data in the attribute + is done in the manner defined in their respective definitions. + + Note that these public keys are intended for signing. Some + certificates may have a key usage restrictions and same key cannot + be used for both encryption and signing. Therefore, the name + of the certificate type indicates if they are intended for + signing only. + + +13 ATTRIBUTE_SERVER_PUBLIC_KEY + + This attribute includes a third party server or authority public + key or CA certificate and MUST be present if the attribute + ATTRIBUTE_SERVER_DIGITAL_SIGNATURE is also present. The format + for this attribute is identical to the ATTRIBUTE_USER_PUBLIC_KEY + attribute. If there are more than one ATTRIBUTE_SERVER_PUBLIC_KEY + attributes set and ATTRIBUTE_SERVER_DIGITAL_SIGNATURE is also set, + the digital signature SHOULD be verifiable with the first set public + key. + + +14 ATTRIBUTE_USER_DIGITAL_SIGNATURE + + This attribute value includes digital signature of all Attribute + Payloads except this attribute. This signature can be provided by + the user. This attribute SHOULD be last attribute provided in the + reply so that it is easier for the receiver to compute the signature + data to be verified. The format and encoding of this attribute + depends on the public key or certificate used to produce the + signature. See the ATTRIBUTE_USER_PUBLIC_KEY for all public keys + and certificates that can be used to produce a signature. + + Length Type Value + variable data Digital signature data + + The encodings are as follows per public key/certificate type: + + ssh-rsa and ssh-dss Defined in [SSH-TRANS] + silc-rsa and silc-dss Defined in [SILC1] + pgp-sign-rsa and pgp-sign-dss Defined in [RFC2440] + x509v3-sign-rsa and x509v3-sign-dss Defined in [PKCS7] + + The procedure producing the signature and encoding it are done + in the manner defined in their respective definitions, see the + provided references. Also the hash function used with the + signature procedure is defined by the public key/certificate type. + + +15 ATTRIBUTE_SERVER_DIGITAL_SIGNATURE + + This attribute value includes digital signature of all Attribute + Payloads except this attribute, but including the attribute + ATTRIBUTE_USER_DIGITAL_SIGNATURE. This signature can be provided + by a third party server or an authority which has verified the + information provided by the user. How it verifies this information + is out of scope of this document, however it may base its + information to a previous registration information and current + online status of the user in a service. This attribute SHOULD be + last when provided, so that it is easier for the receiver to + compute the signature data to be verified. The format for this + attribute is identical to the ATTRIBUTE_USER_DIGITAL_SIGNATURE + attribute. +.in 3 + + +.ti 0 +3 Security Considerations + +The use of these attributes dictates whether the attributes need to +be secured or not. However, as the attributes are considered to provide +accurate status information about specific user, it is suggested that +the attributes would be secured. The attributes should be digitally +signed whenever it is possible. Attributes can also be encrypted +if it is provided by the protocol using the attributes. A third party, +like a server in the network, could also verify the information and provide +digital signature in case the information is accurate. + +Even though the attributes would be digitally signed by the sender of +the attributes, the information contained in the attribute may still +be incorrect. The third party server should not apply digital signature +unless it can verify every attribute. The receiver of the attributes +should also not trust that the information in fact is correct. + +However, it is possible that the context where these attributes are used +the attributes are provided by a party that can provide the accurate +information. For example a server in the network could reply to the +attributes on behalf of the actual user for some of the attributes. + + +.ti 0 +4 References + +[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. + +[RFC2425] Howes, T., et al, "A MIME Content-Type for Directory + Information", RFC 2425, September 1998. + +[RFC2426] Dawson, F., et al, "vCard MIME Directory Profile", + RFC 2426, September 1998. + +[SILC1] Riikonen, P., "Secure Internet Live Conferencing (SILC), + Protocol Specification", Internet Draft, May 2002. + +[RFC2440] Callas, J., et al, "OpenPGP Message Format", RFC 2440, + November 1998. + +[RFC2459] Housley, R., et al, "Internet X.509 Public Key + Infrastructure, Certificate and CRL Profile", RFC 2459, + January 1999. + +[SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", + Internet Draft. + +[PKCS7] Kalinski, B., "PKCS #7: Cryptographic Message Syntax, + Version 1.5", RFC 2315, March 1998. + + + + +.ti 0 +5 Author's Address + +Pekka Riikonen +Snellmaninkatu 34 A 15 +70100 Kuopio +Finland + +EMail: priikone@iki.fi + +This Internet-Draft expires XXX diff --git a/doc/draft-riikonen-silc-commands-05.nroff b/doc/draft-riikonen-silc-commands-05.nroff new file mode 100644 index 00000000..7a58385b --- /dev/null +++ b/doc/draft-riikonen-silc-commands-05.nroff @@ -0,0 +1,2554 @@ +.pl 10.0i +.po 0 +.ll 7.2i +.lt 7.2i +.nr LL 7.2i +.nr LT 7.2i +.ds LF Riikonen +.ds RF FORMFEED[Page %] +.ds CF +.ds LH Internet Draft +.ds RH XXX +.ds CH +.na +.hy 0 +.in 0 +.nf +Network Working Group P. Riikonen +Internet-Draft +draft-riikonen-silc-commands-05.txt XXX +Expires: XXX + +.in 3 + +.ce 2 +SILC Commands + + +.ti 0 +Status of this Memo + +This document is an Internet-Draft and is in full conformance with +all provisions of Section 10 of RFC 2026. Internet-Drafts are +working documents of the Internet Engineering Task Force (IETF), its +areas, and its working groups. Note that other groups may also +distribute working documents as Internet-Drafts. + +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any +time. It is inappropriate to use Internet-Drafts as reference +material or to cite them other than as "work in progress." + +The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt + +The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html + +The distribution of this memo is unlimited. + + +.ti 0 +Abstract + +This memo describes the commands used in the Secure Internet Live +Conferencing (SILC) protocol, specified in the Secure Internet Live +Conferencing, Protocol Specification Internet Draft [SILC1]. The +SILC Commands are very important part of the SILC protocol. Usually +the commands are used by SILC clients to manage the SILC session, but +also SILC servers may use the commands. This memo specifies detailed +command messages and command reply messages. + + + + + + + + +.ti 0 +Table of Contents + +.nf +1 Introduction .................................................. 2 + 1.1 Requirements Terminology .................................. 2 +2 SILC Commands ................................................. 2 + 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 +1. Introduction + +This document describes the commands used in the Secure Internet Live +Conferencing (SILC) protocol, specified in the Secure Internet Live +Conferencing, Protocol Specification Internet Draft [SILC1]. This +document specifies detailed command messages and command reply messages. + +Commands are very important part on SILC network especially for client +which uses commands to operate on the SILC network. Commands are used +to set nickname, join to channel, change modes and many other things. + +See the [SILC1] for the requirements and the restrictions for the usage +of the SILC commands. The [SILC2] defines the command packet type and +the Command Payload which is actually used to deliver the commands and +command reply messages. + + +.ti 0 +1.1 Requirements Terminology + +The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, +MAY, and OPTIONAL, when they appear in this document, are to be +interpreted as described in [RFC2119]. + + +.ti 0 +2 SILC Commands + +.ti 0 +2.1 SILC Commands Syntax + +This section briefly describes the syntax of the command notions +in this document. Every field in command is separated from each +other by whitespaces (` ') indicating that each field is independent +argument and each argument MUST have own Command Argument Payload. +The number of maximum arguments are defined with each command +separately. The Command Argument Payload is described in [SILC2]. + +Every command defines specific number for each argument. Currently, +they are defined in ascending order; first argument has number one +(1), second has number two (2) and so on. This number is set into the +Argument Type field in the Command Argument Payload. This makes it +possible to send the arguments in free order as the number MUST be +used to identify the type of the argument. This makes is it also +possible to have multiple optional arguments in commands and in +command replies. The number of argument is marked in parentheses +before the actual argument. + + + +.in 6 +Example: Arguments: (1) (2) +.in 3 + + +Every command replies with Status Payload. This payload tells the +sender of the command whether the command was completed successfully or +whether there was an error. If error occurred the payload includes the +error type. In the next section the Status Payload is not described +as it is common to all commands and has been described here. Commands +MAY reply with other arguments as well. These arguments are command +specific and are described in the next section. + +Example command: +.in 6 + +EXAMPLE_COMMAND + +.in 8 +Max Arguments: 3 + Arguments: (1) [@] (2) + (3) [] + +The command has maximum of 3 arguments. However, only first +and second arguments are mandatory. + +First argument is mandatory but may have optional + format as well. Second argument is mandatory + argument. Third argument is optional argument. + +The numbers in parentheses are the argument specific numbers +that specify the type of the argument in Command Argument Payload. +The receiver always knows that, say, argument number two (2) is + argument, regardless of the ordering of the arguments in +the Command Payload. + +Reply messages to the command: + +Max Arguments: 4 + Arguments: (1) (2) [] + (3) (4) [] + +This command may reply with maximum of 4 arguments. However, +only the first and third arguments are mandatory. The numbers +in the parentheses have the same meaning as in the upper +command sending specification. + +Every command reply with , it is mandatory +argument for all command replies and for this reason it is not +described in the command reply descriptions. + + + +Status messages: + + SILC_STATUS_OK + 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 . 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 + + +.ti 0 +2.2 SILC Command Argument Idioms + +All commands that has an ID as argument (for example ) 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 +commands that has only local affect. These commands are official +SILC commands that has both client and server sides and cannot be +characterized as local commands. + +List of all defined commands in SILC follows. + +.in 0 + 0 SILC_COMMAND_NONE + + None. This is reserved command and MUST NOT be sent. + + + 1 SILC_COMMAND_WHOIS + + Max Arguments: 256 + Arguments: (1) [[@]] (2) [] + (3) [] (4) [] + (n) [...] + + Whois command is used to query various information about specific + user. The user may be requested by their nickname and server name. + The query may find multiple matching users as there are no unique + nicknames in the SILC. The 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 query may also be narrowed + down by defining the server name of the nickname. The is + 32 bit MSB first order integer. + + It is also possible to search the user by Client ID. If the + is provided server MUST use it as the search value + instead of the . One of the arguments MUST be given. + It is also possible to define multiple Client ID's to search + multiple users sending only one WHOIS command. In this case the + Client ID's are appended as normal arguments. + + 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 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, 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 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: 11 + Arguments: (1) (2) + (3) [@] (4) + (5) (6) [] + (7) [] (8) [] + (9) [] (10) + (11) [] + + + This command may reply with several command reply messages to + form 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. 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 + name. Client should process these replies only after the last + reply has been received with the STATUS_LIST_END status. If the + option were defined in the query there will be only + many replies from the server. + + 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 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 . + + The server also returns client's user mode, idle time, and the + fingerprint of the client's public key. The is the + binary hash digest of the public key. The fingerprint MUST NOT + 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 is SHA1 digest. + + The is the reply to the . + See the Appendix A for more information. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_LIST_START + SILC_STATUS_LIST_END + SILC_STATUS_ERR_NO_SUCH_NICK + SILC_STATUS_ERR_NO_SUCH_CLIENT_ID + SILC_STATUS_ERR_WILDCARDS + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_TOO_MANY_PARAMS + + + 2 SILC_COMMAND_WHOWAS + + Max Arguments: 2 + Arguments: (1) [@] (2) [] + + Whowas. This command is used to query history information about + specific user. The user may be requested by their nickname and + server name. The query may find multiple matching users as there + are no unique nicknames in the SILC. The 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 query + may also be narrowed down by defining the server name of the + nickname. The 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 + be based on specific nickname request. + + The WHOWAS 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. + + Reply messages to the command: + + Max Arguments: 5 + Arguments: (1) (2) + (3) [@] (4) + (5) [] + + This command may reply with several command reply messages to form + 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. + + The command replies with nickname and user name and host name. + Every server MUST keep history for some period of time of its + locally connected clients. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_LIST_START + SILC_STATUS_LIST_END + SILC_STATUS_ERR_NO_SUCH_NICK + SILC_STATUS_ERR_WILDCARDS + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_TOO_MANY_PARAMS + + + 3 SILC_COMMAND_IDENTIFY + + Max Arguments: 256 + Arguments: (1) [[@]] (2) [] + (3) [] (4) [] + (5) [] (n) [...] + + 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, servers and channels. + + The query may find multiple matching entities. The 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 + is 32 bit MSB first order integer. + + It is also possible to search the entity by its ID. If the + is provided server must use it as the search value + instead of the entity's name. One of the arguments must be given. + It is also possible to define multiple ID Payloads to search + multiple entities sending only one IDENTIFY command. In this case + the ID Payloads are appended as normal arguments. The type of the + entity is defined by the type of the ID Payload. + + To prevent miss-use of this command wildcards in the names are + not permitted. It is not allowed to request for example all users + on server. + + 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 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 + its locally connected clients. + + Reply messages to the command: + + Max Arguments: 4 + Arguments: (1) (2) + (3) [] (4) [] + + This command may reply with several command reply messages to form + 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. If multiple Client + IDs was requested then each found and unfound client must cause + successful or error reply, respectively. + + When querying clients the must include the client's + nickname in the following format: nickname[@server]. The + must include the client's username and host in the following + format: username@host. + + When querying servers the must include the server's + full name. The may be omitted. + + When querying channels the must include the + channel's name. The may be omitted. + + If the option were defined in the query there will be only + many replies from the server. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_LIST_START + SILC_STATUS_LIST_END + SILC_STATUS_ERR_NO_SUCH_NICK + SILC_STATUS_ERR_NO_SUCH_SERVER + SILC_STATUS_ERR_NO_SUCH_CHANNEL + SILC_STATUS_ERR_NO_SUCH_CLIENT_ID + SILC_STATUS_ERR_NO_SUCH_SERVER_ID + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + SILC_STATUS_ERR_WILDCARDS + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_TOO_MANY_PARAMS + + + 4 SILC_COMMAND_NICK + + Max Arguments: 1 + Arguments: (1) + + 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. + + 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_NOTIFY_TYPE_NICK_CHANGE notify to its primary route to + notify about nickname and Client ID change. + + Reply messages to the command: + + Max Arguments: 3 + Arguments: (1) (2) + (3) + + This command replies always with 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]. The is the user's new + nickname. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_ERR_WILDCARDS + SILC_STATUS_ERR_NICKNAME_IN_USE + SILC_STATUS_ERR_BAD_NICKNAME + SILC_STATUS_ERR_NOT_REGISTERED + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_TOO_MANY_PARAMS + + + 5 SILC_COMMAND_LIST + + Max Arguments: 1 + Arguments: (1) [] + + The list command is used to list channels and their topics on the + current server. If the parameter is used, only the + status of that channel is displayed. Secret channels are not + listed at all. Private channels are listed with status indicating + that the channel is private. Router MAY reply with all channels + it knows about. + + Reply messages to the command: + + Max Arguments: 5 + Arguments: (1) (2) + (3) (4) [] + (5) [] + + This command may reply with several command reply messages to form + 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. + + This command replies with Channel ID, name and the topic of the + channel. If the channel is private channel the SHOULD + include the "*private*" string. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_LIST_START + SILC_STATUS_LIST_END + SILC_STATUS_ERR_WILDCARDS + SILC_STATUS_ERR_NOT_REGISTERED + SILC_STATUS_ERR_TOO_MANY_PARAMS + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + SILC_STATUS_ERR_NO_CHANNEL_ID + SILC_STATUS_ERR_NO_SUCH_SERVER + + + 6 SILC_COMMAND_TOPIC + + Max Arguments: 2 + Arguments: (1) (2) [] + + This command is used to change or view the topic of a channel. + The topic for channel is returned if there is no + given. If the parameter is present, the topic + for that channel will be changed, if the channel modes permit + this action. + + After setting the topic the server MUST send the notify type + SILC_NOTIFY_TYPE_TOPIC_SET to its primary router and then to + the channel which topic was changed. + + Reply messages to the command: + + Max Arguments: 2 + Arguments: (1) (2) + (3) [] + + The command may reply with the topic of the channel if it is + set. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_ERR_NOT_ON_CHANNEL + SILC_STATUS_ERR_WILDCARDS + SILC_STATUS_ERR_NOT_REGISTERED + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_NO_SUCH_CHANNEL + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + SILC_STATUS_ERR_NO_CHANNEL_ID + SILC_STATUS_ERR_BAD_CHANNEL_ID + SILC_STATUS_ERR_TOO_MANY_PARAMS + SILC_STATUS_ERR_NO_CHANNEL_PRIV + + + 7 SILC_COMMAND_INVITE + + Max Arguments: 4 + Arguments: (1) (2) [] + (3) [] (4) [] + + This command can be used to invite other clients to join to a + channel, and to manage the channel's invite list. The argument is the target client's ID that is being invited. + The 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 . + + The 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 , 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 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: + + 0x01 - Argument is an invite string of following format: + + [[@]!][]@[] + + The 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. + 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. When this + command is used to invite explicit client with the + ID MUST be added to the invite list by the server. + + When this command is given with only 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 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 on the channel. + + Reply messages to the command: + + Max Arguments: 3 + Arguments: (1) (2) + (3) [] + + This command replies with the invite list of the channel if it + exists. + + 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_CLIENT_ID + SILC_STATUS_ERR_NO_CLIENT_ID + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + SILC_STATUS_ERR_NO_CHANNEL_ID + 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 + + Max Arguments: 1 + Arguments: (1) [] + + This command is used by client to end SILC session. The server + must close the connection to a client which sends this command. + if is given it will be sent to other clients on + channel if the client is on channel when quitting. + + Reply messages to the command: + + This command does not reply anything. + + + 9 SILC_COMMAND_KILL + + Max Arguments: 3 + Arguments: (1) (2) [] + (3) [] + + 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 is the client to be removed from SILC. + The 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. 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 is the + destination client to be removed from the network. The client + MUST provide the which includes a digital signature + that MUST be verified with the public key of the client indicated + by . The 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 computing is SHA1. + + Reply messages to the command: + + Max Arguments: 1 + Arguments: (1) + + This command replies only with Status Payload. + + 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_SUCH_CLIENT_ID + SILC_STATUS_ERR_NO_CLIENT_ID + SILC_STATUS_ERR_NO_ROUTER_PRIV + + + 10 SILC_COMMAND_INFO + + Max Arguments: 2 + Arguments: (1) [] (2) [] + + This command is used to fetch various information about a server. + If argument is specified the command MUST be sent to + the requested server. + + If the is specified the server information if fetched + by the provided Server ID. One of the arguments must always be + present. + + Reply messages to the command: + + Max Arguments: 4 + Arguments: (1) (2) + (3) (4) + + This command replies with the Server ID of the server and a + string which tells the information about the server. + + 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_SUCH_SERVER + SILC_STATUS_ERR_NO_SUCH_SERVER_ID + SILC_STATUS_ERR_NO_SERVER_ID + + + 11 SILC_COMMAND_STATS + + Max Arguments: 1 + Arguments: (1) + + This command is used to fetch various statistical information + from the server indicated by , 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) (2) + (3) [] + + 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_NOT_REGISTERED + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_TOO_MANY_PARAMS + SILC_STATUS_ERR_NO_SUCH_SERVER_ID + SILC_STATUS_ERR_NO_SUCH_SERVER + SILC_STATUS_ERR_NO_SERVER_ID + + + 12 SILC_COMMAND_PING + + Max Arguments: 1 + Arguments: (1) + + This command is used by client and server to test the communication + channel to its server if one suspects that the communication is not + working correctly. The is the ID of the server the + sender is connected to. + + Reply messages to the command: + + Max Arguments: 1 + Arguments: (1) + + This command replies only with Status Payload. Server returns + SILC_STATUS_OK in Status Payload if pinging was successful. + + + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + SILC_STATUS_ERR_TOO_MANY_PARAMS + SILC_STATUS_ERR_NO_SERVER_ID + SILC_STATUS_ERR_NO_SUCH_SERVER + SILC_STATUS_ERR_NOT_REGISTERED + + + 13 SILC_COMMAND_OPER + + Max Arguments: 2 + Arguments: (1) (2) + + This command is used by normal client to obtain server operator + privileges on some server or router. Note that router operator + has router privileges that supersedes the server operator + privileges and this does not obtain those privileges. Client + MUST use SILCOPER command to obtain router level privileges. + + The is the username set in the server configurations + as operator. The 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 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. + + Reply messages to the command: + + Max Arguments: 1 + Arguments: (1) + + This command replies only with Status Payload. + + 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_AUTH_FAILED + + + 14 SILC_COMMAND_JOIN + + Max Arguments: 6 + Arguments: (1) (2) + (3) [] (4) [] + (5) [] (6) [] + + Join to channel/create new channel. This command is used to + join to a channel. If the channel does not exist the channel is + created. If server is normal server this command MUST be sent + to router which will create the channel. The channel MAY be + protected with passphrase. If this is the case the passphrase + MUST be sent along the join command. + + The name of the MUST NOT include any spaces (` '), + non-printable characters, commas (`,') or any wildcard characters. + + The second argument is the Client ID of the client + which is joining to the client. When client sends this command + to the server the MUST be the client's own ID. + + Cipher to be used to secure the traffic on the channel MAY be + requested by sending the name of the requested . This + is used only if the channel does not exist and is created. If + the channel already exists the cipher set previously for the + channel will be used to secure the traffic. The computed MACs + of the channel message are produced by the default HMAC or by + the provided for the command. + + The 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 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 + are: + + o The user MUST be invited to the channel if the channel + is invite-only channel. + + 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. + + o The user count limit, if set, MUST NOT be reached. + + If the client provided correct payload it can + override these conditions, except the condition for the passphrase. + The correct passphrase MUST be provided even if + payload is provided. + + Reply messages to the command: + + Max Arguments: 15 + Arguments: (1) (2) + (3) (4) + (5) (6) + (7) [] (8) [] + (9) [] (10) [] + (11) [] (12) + (13) (14) + (15) [] + + This command replies with the channel name requested by the + client, channel ID of the channel and topic of the channel + if it exists. The is the Client ID which was joined + to the channel. It also replies with the channel mode mask + which tells all the modes set on the channel. If the + channel is created the mode mask is zero (0). If ban mask + and/or invite list is set they are sent as well. + + The , and are + the clients currently on the channel and their modes on the + channel. The is formed by adding the ID Payloads + one after the other. The is formed by adding + 32 bit MSB first order values one after the other. The is the public key (or certificate) of the channel founder. + + Client receives the channel key in the reply message as well + inside . + + 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_BAD_PASSWORD + SILC_STATUS_ERR_CHANNEL_IS_FULL + SILC_STATUS_ERR_NOT_INVITED + SILC_STATUS_ERR_BANNED_FROM_CHANNEL + SILC_STATUS_ERR_BAD_CHANNEL + SILC_STATUS_ERR_USER_ON_CHANNEL + + + 15 SILC_COMMAND_MOTD + + Max Arguments: 1 + Arguments: (1) + + This command is used to query the Message of the Day of the server. + + Reply messages to the command: + + Max Arguments: 3 + Arguments: (1) (2) + (3) [] + + This command replies with the motd message if it exists. + + 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 + + + 16 SILC_COMMAND_UMODE + + Max Arguments: 2 + Arguments: (1) (2) [] + + This command is used by client to set/unset modes for itself. + However, there are some modes that the client MUST NOT set itself, + but they will be set by server. However, client MAY unset any + mode. Modes may be masked together ORing them thus having + several modes set. Client MUST keep its client mode mask + locally so that the mode setting/unsetting would work without + problems. Client may change only its own modes. + + After changing the mode server MUST send the notify type + SILC_NOTIFY_TYPE_UMODE_CHANGE to its primary router. + + The following client modes are defined: + + 0x00000000 SILC_UMODE_NONE + + No specific mode for client. This is the initial + setting when new client is created. The client is + normal client and is present in the network. + + + 0x00000001 SILC_UMODE_SERVER_OPERATOR + + Marks the user as server operator. Client MUST NOT + set this mode itself. Server sets this mode to the + client when client attains the server operator + privileges by SILC_COMMAND_OPER command. Client + MAY unset the mode itself. + + + 0x00000002 SILC_UMODE_ROUTER_OPERATOR + + Marks the user as router (SILC) operator. Client + 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. + + + 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 was not provided this command merely + returns the mode mask to the client. + + + Reply messages to the command: + + Max Arguments: 2 + Arguments: (1) (2) + + This command replies with the changed client mode mask that + the client MUST to keep locally. + + + 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_CLIENT_ID + SILC_STATUS_ERR_BAD_CLIENT_ID + SILC_STATUS_ERR_NOT_YOU + SILC_STATUS_ERR_PERM_DENIED + SILC_STATUS_ERR_UNKNOWN_MODE + SILC_STATUS_ERR_NO_CLIENT_ID + + + 17 SILC_COMMAND_CMODE + + Max Arguments: 8 + Arguments: (1) (2) [] + (3) [] (4) [] + (5) [] (6) [] + (7) [] (8) [] + + This command is used by client to set or change channel flags on + a channel. Channel has several modes that set various properties + of a channel. Modes may be masked together by ORing them thus + having several modes set. The is the ID of the + target channel. The client changing channel mode MUST be on + 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 + type MUST be distributed to the channel. + + The following channel modes are defined: + + 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. + + + 0x00000001 SILC_CMODE_PRIVATE + + Channel is private channel. Private channels are shown + in the channel list listed with SILC_COMMAND_LIST command + with indication that the channel is private. Also, + client on private channel will no be detected to be on + the channel as the channel is not shown in the client's + currently joined channel list. Channel founder and + channel operator MAY set/unset this mode. + + Typical implementation would use [+|-]p on user interface + to set/unset this mode. + + + 0x00000002 SILC_CMODE_SECRET + + Channel is secret channel. Secret channels are not shown + in the list listed with SILC_COMMAND_LIST command. Secret + channels can be considered to be invisible channels. + Channel founder and channel operator MAY set/unset this + mode. + + Typical implementation would use [+|-]s on user interface + to set/unset this mode. + + + 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 + responsible to set the key it wants to use to encrypt and + decrypt the traffic on channel. Server generated channel + keys are not used at all. This mode provides additional + security as clients on channel may agree to use private + 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 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 + clients can talk on same channel but only those clients + that share the key with the message sender will be able + to hear the talking. Client SHOULD NOT display those + message for the end user that it is not able to decrypt + when this mode is set. + + Only channel founder MAY set/unset this mode. If this + mode is unset the server will distribute new channel + key to all clients on the channel which will be used + thereafter. + + Typical implementation would use [+|-]k on user interface + to set/unset this mode. + + + 0x00000008 SILC_CMODE_INVITE + + Channel is invite only channel. Client may join to this + channel only if it is invited to the channel. Channel + founder and channel operator MAY set/unset this mode. + + Typical implementation would use [+|-]i on user interface + to set/unset this mode. + + + 0x00000010 SILC_CMODE_TOPIC + + The topic of the channel may only be set by client that + is channel founder or channel operator. Normal clients + on channel will not be able to set topic when this mode + is set. Channel founder and channel operator MAY set/ + unset this mode. + + Typical implementation would use [+|-]t on user interface + to set/unset this mode. + + + 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 + reached. Channel founder and channel operator MAY set/ + unset the limit. The argument is the + number of limited users. + + Typical implementation would use [+|-]l on user interface + to set/unset this mode. + + + 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 + correct passphrase. Setting passphrases to channel + is entirely safe as all commands are protected in the + SILC network. Only channel founder MAY set/unset + the passphrase. The argument is the + set passphrase. + + Typical implementation would use [+|-]a on user interface + to set/unset this mode. + + + 0x00000080 SILC_CMODE_CIPHER + + Sets specific cipher to be used to protect channel + traffic. The argument is the requested cipher. + When set or unset the server must re-generate new + channel key. Only channel founder MAY set the cipher of + the channel. When unset the new key is generated using + default cipher for the channel. + + Typical implementation would use [+|-]c on user interface + to set/unset this mode. + + + 0x00000100 SILC_CMODE_HMAC + + Sets specific hmac to be used to compute the MACs of the + channel message. The argument is the requested hmac. + Only channel founder may set the hmac of the channel. + + Typical implementation would use [+|-]h on user interface + to set/unset this mode. + + + 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 is the Authentication Payload + consisting of the public key authentication method and the + digital signature for that method. The passphrase or NONE + authentication methods MUST NOT be accepted. + + The server does not save but MUST verify it. + The public key used to verify the payload is the if present, or the public key of the client sending + this command. If is present also that + public key MUST be saved as founder's public key. This + mode may be set only if the was verified + successfully. The hash function used with the 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. + + If this mode is already set but the 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 and how long they remain + persistent. + + 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 + mask when it joins to the channel. When the mode changes on + 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. If the was + not provided this command merely returns the mode mask to the + client. + + Reply messages to the command: + + Max Arguments: 4 + Arguments: (1) (2) + (3) (4) [] + + This command replies with the changed channel mode mask that + client MUST keep locally. It may also return the channel + founder's public key if it is set. + + 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_NOT_ON_CHANNEL + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + 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 + + + 18 SILC_COMMAND_CUMODE + + Max Arguments: 4 + Arguments: (1) (2) + (3) (4) [] + + This command is used by client to change channel user modes on + channel. Users on channel may have some special modes and this + command is used by channel operators to set or change these modes. + The is the ID of the target channel. The + is OR'ed mask of modes. The is the target client. + The client changing channel user modes MUST be on the same channel + 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 + type is distributed to the channel. + + The following channel modes are defined: + + 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. + + + 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. + However, if the SILC_CMODE_FOUNDER_AUTH channel mode has + been set, the client can claim channel founder privileges + by providing the that the server will use + to authenticate the client. The public key that server will + use to verify the 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. + + + 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. 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: + + Max Arguments: 4 + Arguments: (1) (2) + (3) (4) + + This command replies with the changed channel user mode mask that + client MUST keep locally. The is the specified + channel. The is the target client. + + 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_NOT_ON_CHANNEL + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + 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 + + + 19 SILC_COMMAND_KICK + + Max Arguments: 3 + Arguments: (1) (2) + (3) [] + + This command is used by channel operators to remove a client from + channel. The argument is the channel the client to be + removed is on currently. Note that the "kicker" must be on the same + channel. If is provided it will be sent to the removed + client. + + After kicking the client the server MUST send the notify type + SILC_NOTIFY_TYPE_KICKED to the channel and to its primary router. + 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: + + Max Arguments: 1 + Arguments: (1) + + This command replies only with Status Payload. + + 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_CHANNEL + SILC_STATUS_ERR_NO_SUCH_CLIENT_ID + SILC_STATUS_ERR_NO_CHANNEL_PRIV + SILC_STATUS_ERR_NO_CLIENT_ID + + + + + 20 SILC_COMMAND_BAN + + Max Arguments: 3 + Arguments: (1) (2) [] + (3) [] + + This command is used to manage the ban list of the channel + indicated by the . A client that is banned from + channel is no longer able to join the channel. The client which + is executing this command MUST have at least channel operator + privileges on the channel. + + The 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 , 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 format is + as follows: + + 2 bytes - Number of arguments in the list + variable length - Argument Payloads + + The following Argument Types has been defined for ban list + Argument Payloads: + + 0x01 - Argument is an ban string of following format: + + [[@]!][]@[] + + The 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: + + Max Arguments: 3 + Arguments: (1) (2) + (3) [] + + This command replies with the of the channel and + the current of the channel if it exists. + + Status messages: + + SILC_STATUS_OK + SILC_STATUS_ERR_NOT_REGISTERED + SILC_STATUS_ERR_TOO_MANY_PARAMS + SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID + 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 + + 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) + + 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) (2) [] + (3) [] + + This command is used to set up a watch for + 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 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 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) + + 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 + + Max Arguments: 2 + Arguments: (1) (2) + + This command is used by normal client to obtain router operator + privileges (also known as SILC operator) on the router. Note + that router operator has privileges that supersedes the server + operator privileges. + + The is the username set in the server configurations + as operator. The 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 router 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 router and router would not use + any public keys received during the SKE. + + Difference between router operator and server operator is that + router operator is able to handle cell level properties while + server operator (even on router server) is able to handle only + local properties, such as, local connections and normal server + administration. The router operator is also able to use the + SILC_COMMAND_KILL command. + + After changing the mode server MUST send the notify type + SILC_NOTIFY_TYPE_UMODE_CHANGE to its primary router. + + Reply messages to the command: + + Max Arguments: 1 + Arguments: (1) + + This command replies only with Status Payload. + + 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_AUTH_FAILED + + + 24 SILC_COMMAND_LEAVE + + Max Arguments: 1 + Arguments: (1) + + This command is used by client to leave a channel the client is + joined to. + + When leaving channel the server MUST send the notify type + SILC_NOTIFY_TYPE_LEAVE to its primary router and to the channel. + The channel key MUST also be re-generated when leaving the channel + and distribute it to all clients still currently on the channel. + The key MUST NOT be re-generated if the SILC_CMODE_PRIVKEY mode + is set. + + Reply messages to the command: + + Max Arguments: 2 + Arguments: (1) (2) + + The is the ID of left channel. + + 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_CHANNEL_ID + SILC_STATUS_ERR_BAD_CHANNEL_ID + SILC_STATUS_ERR_NO_CHANNEL_ID + + + 25 SILC_COMMAND_USERS + + Max Arguments: 2 + Arguments: (1) [] (2) [] + + This command is used to list user names currently on the requested + channel; either the argument or the . + One of these arguments must be present. The server MUST resolve + 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, 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: + + Max Arguments: 5 + Arguments: (1) (2) + (3) (4) + (5) + + This command replies with the Channel ID of the requested channel + Client ID list of the users on the channel and list of their modes. + The Client ID list has Client ID's of all users in the list. The + is formed by adding Client ID's one after another. + The is formed by adding client's user modes on + the channel one after another (4 bytes (32 bits) each). The of length of 4 bytes (32 bits), tells the number of entries + in the lists. Both lists MUST have equal number of entries. + + 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_CHANNEL_ID + SILC_STATUS_ERR_BAD_CHANNEL_ID + SILC_STATUS_ERR_NO_CHANNEL_ID + SILC_STATUS_ERR_NOT_ON_CHANNEL + + + 26 SILC_COMMAND_GETKEY + + Max Arguments: 1 + Arguments: (1) + + This command is used to fetch the public key of the client or + server indicated by the . The public key is fetched + from the server where to the client is connected. + + Reply messages to the command: + + Max Arguments: 3 + Arguments: (1) (2) + (3) [] + + This command replies with the client's or server's ID and with + the . + + 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_CLIENT_ID + SILC_STATUS_ERR_NO_SUCH_SERVER_ID + + + 27 SILC_COMMAND_SERVICE + + Max Arguments: 256 + Arguments: (1) [] (2) [] + (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 + is a service specific identifier, and the + 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) (2) [] + (3) [] (n) [...] + + + This command MAY reply with the when command is + given without arguments, and the list is a comma separated list + of service identifiers. The is the service that + the sender requested and this is provided when the server has + accepted the sender to use the . 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. + + + 200 - 254 + + These commands are reserved for private use and will not be defined + in this document. + + + 255 SILC_COMMAND_MAX + + Reserved command. This must not be sent. +.in 3 + + +.ti 0 +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 +command thus this is the data area in Command Argument Payload described +in [SILC2]. The payload is only 2 bytes in length. The following +diagram represents the Command Status Payload (fields are always in +MSB first order). + + +.in 21 +.nf + 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Status | Error | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 6: SILC Command Status Payload + + +.in 6 +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 +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 +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. + +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: + + 0 SILC_STATUS_OK + + Ok status. Everything went Ok. The status payload maybe + safely ignored in this case. + + 1 SILC_STATUS_LIST_START + + Start of the list. There will be several command replies and + this reply is the start of the list. + + 2 SILC_STATUS_LIST_ITEM + + Item in the list. This is one of the item in the list but not the + first or last one. + + 3 SILC_STATUS_LIST_END + + End of the list. There were several command replies and this + reply is the last of the list. There won't be other replies + belonging to this list after this one. + + 4 - 9 + + Currently undefined and has been reserved for the future. + + + Error status message: + + + + 10 SILC_STATUS_ERR_NO_SUCH_NICK + + "No such nickname". Requested nickname does not exist. + + 11 SILC_STATUS_ERR_NO_SUCH_CHANNEL + + "No such channel". Requested channel name does not exist. + + 12 SILC_STATUS_ERR_NO_SUCH_SERVER + + "No such server". Requested server name does not exist. + + 13 SILC_STATUS_ERR_INCOMPLETE_INFORMATION + + "Incomplete registration information". Information remote + sent was incomplete. + + 14 SILC_STATUS_ERR_NO_RECIPIENT + + "No recipient given". Command required recipient which was + not provided. + + 15 SILC_STATUS_ERR_UNKNOWN_COMMAND + + "Unknown command". Command sent to server is unknown by the + server. + + 16 SILC_STATUS_ERR_WILDCARDS + + "Wildcards cannot be used". Wildcards were provided but they + weren't permitted. + + 17 SILC_STATUS_ERR_NO_CLIENT_ID + + "No Client ID given". Client ID were expected as command + parameter but were not found. + + 18 SILC_STATUS_ERR_NO_CHANNEL_ID + + "No Channel ID given". Channel ID were expected as command + parameter but were not found. + + 19 SILC_STATUS_ERR_NO_SERVER_ID + + "No Serve ID given". Server ID were expected as command + parameter but were not found. + + 20 SILC_STATUS_ERR_BAD_CLIENT_ID + + "Bad Client ID". Client ID provided were erroneous. + + 21 SILC_STATUS_ERR_BAD_CHANNEL_ID + + "Bad Channel ID". Channel ID provided were erroneous. + + 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 + + "Nickname already exists". Nickname created could not be + registered because number of same nicknames were already set to + maximum. This is not expected to happen in real life but is + possible to occur. + + 25 SILC_STATUS_ERR_NOT_ON_CHANNEL + + "You are not on that channel". The command were specified for + channel user is not currently on. + + 26 SILC_STATUS_ERR_USER_NOT_ON_CHANNEL + + "They are not on channel". The requested target client is not + on requested channel. + + 27 SILC_STATUS_ERR_USER_ON_CHANNEL + + "User already on channel". User were invited on channel they + already are on. + + 28 SILC_STATUS_ERR_NOT_REGISTERED + + "You have not registered". User executed command that requires + the client to be registered on the server before it may be + executed. + + 29 SILC_STATUS_ERR_NOT_ENOUGH_PARAMS + + "Not enough parameters". Command requires more parameters + than provided. + + 30 SILC_STATUS_ERR_TOO_MANY_PARAMS + + "Too many parameters". Too many parameters were provided + for the command. + + 31 SILC_STATUS_ERR_PERM_DENIED + + "Permission denied". Generic permission denied error status + to indicate disallowed access. + + 32 SILC_STATUS_ERR_BANNED_FROM_SERVER + + "You are banned from this server". The client tried to register + on server that has explicitly denied this host to connect. + + 33 SILC_STATUS_ERR_BAD_PASSWORD + + "Cannot join channel. Incorrect password". Password provided for + channel were not accepted. + + 34 SILC_STATUS_ERR_CHANNEL_IS_FULL + + "Cannot join channel. Channel is full". The channel is full + and client cannot be joined to it. + + 35 SILC_STATUS_ERR_NOT_INVITED + + "Cannot join channel. You have not been invited". The channel + is invite only channel and client has not been invited. + + 36 SILC_STATUS_ERR_BANNED_FROM_CHANNEL + + "Cannot join channel. You have been banned". The client has + been banned from the channel. + + 37 SILC_STATUS_ERR_UNKNOWN_MODE + + "Unknown mode". Mode provided by the client were unknown to + the server. + + 38 SILC_STATUS_ERR_NOT_YOU + + "Cannot change mode for other users". User tried to change + someone else's mode. + + 39 SILC_STATUS_ERR_NO_CHANNEL_PRIV + + "Permission denied. You are not channel operator". Command may + be executed only by channel operator. + + 40 SILC_STATUS_ERR_NO_CHANNEL_FOPRIV + + "Permission denied. You are not channel founder". Command may + be executed only by channel operator. + + 41 SILC_STATUS_ERR_NO_SERVER_PRIV + + "Permission denied. You are not server operator". Command may + be executed only by server operator. + + 42 SILC_STATUS_ERR_NO_ROUTER_PRIV + + "Permission denied. You are not SILC operator". Command may be + executed only by router (SILC) operator. + + 43 SILC_STATUS_ERR_BAD_NICKNAME + + "Bad nickname". Nickname requested contained illegal characters + or were malformed. + + 44 SILC_STATUS_ERR_BAD_CHANNEL + + "Bad channel name". Channel requested contained illegal characters + or were malformed. + + 45 SILC_STATUS_ERR_AUTH_FAILED + + "Authentication failed". The authentication data sent as + argument were wrong and thus authentication failed. + + 46 SILC_STATUS_ERR_UNKOWN_ALGORITHM + + "The algorithm was not supported." The server does not support the + requested algorithm. + + 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. + + 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 +4 Security Considerations + +Security is central to the design of this protocol, and these security +considerations permeate the specification. Common security considerations +such as keeping private keys truly private and using adequate lengths for +symmetric and asymmetric keys must be followed in order to maintain the +security of this protocol. + + +.ti 0 +5 References + +[SILC1] Riikonen, P., "Secure Internet Live Conferencing (SILC), + Protocol Specification", Internet Draft, May 2002. + +[SILC2] Riikonen, P., "SILC Packet Protocol", Internet Draft, + May 2002. + +[SILC3] Riikonen, P., "SILC Key Exchange and Authentication + Protocols", Internet Draft, May 2002. + +[IRC] Oikarinen, J., and Reed D., "Internet Relay Chat Protocol", + RFC 1459, May 1993. + +[IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810, + April 2000. + +[IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC + 2811, April 2000. + +[IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC + 2812, April 2000. + +[IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC + 2813, April 2000. + +[SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", + Internet Draft. + +[PGP] Callas, J., et al, "OpenPGP Message Format", RFC 2440, + November 1998. + +[SPKI] Ellison C., et al, "SPKI Certificate Theory", RFC 2693, + September 1999. + +[PKIX-Part1] Housley, R., et al, "Internet X.509 Public Key + Infrastructure, Certificate and CRL Profile", RFC 2459, + January 1999. + +[Schneier] Schneier, B., "Applied Cryptography Second Edition", + John Wiley & Sons, New York, NY, 1996. + +[Menezes] Menezes, A., et al, "Handbook of Applied Cryptography", + CRC Press 1997. + +[OAKLEY] Orman, H., "The OAKLEY Key Determination Protocol", + RFC 2412, November 1998. + +[ISAKMP] Maughan D., et al, "Internet Security Association and + Key Management Protocol (ISAKMP)", RFC 2408, November + 1998. + +[IKE] Harkins D., and Carrel D., "The Internet Key Exchange + (IKE)", RFC 2409, November 1998. + +[HMAC] Krawczyk, H., "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + +[PKCS1] Kalinski, B., and Staddon, J., "PKCS #1 RSA Cryptography + Specifications, Version 2.0", RFC 2437, October 1998. + +[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 +6 Author's Address + +.nf +Pekka Riikonen +Snellmaninkatu 34 A 15 +70100 Kuopio +Finland + +EMail: priikone@iki.fi + +This Internet-Draft expires XXX + + +.ti 0 +Appendix A + +This appendix defines the usage of the 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 MAY include several attributes that are +requested. The format and encoding of the is as +defined in [ATTRS]. When 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 + 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 (1), and the + (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. diff --git a/doc/draft-riikonen-silc-ke-auth-07.nroff b/doc/draft-riikonen-silc-ke-auth-07.nroff new file mode 100644 index 00000000..c5afca02 --- /dev/null +++ b/doc/draft-riikonen-silc-ke-auth-07.nroff @@ -0,0 +1,1148 @@ +.pl 10.0i +.po 0 +.ll 7.2i +.lt 7.2i +.nr LL 7.2i +.nr LT 7.2i +.ds LF Riikonen +.ds RF FORMFEED[Page %] +.ds CF +.ds LH Internet-Draft +.ds RH XXX +.ds CH +.na +.hy 0 +.in 0 +.nf +Network Working Group P. Riikonen +Internet-Draft +draft-riikonen-silc-ke-auth-07.txt XXX +Expires: XXX + +.in 3 + +.ce 2 +SILC Key Exchange and Authentication Protocols + + +.ti 0 +Status of this Memo + +This document is an Internet-Draft and is in full conformance with +all provisions of Section 10 of RFC 2026. Internet-Drafts are +working documents of the Internet Engineering Task Force (IETF), its +areas, and its working groups. Note that other groups may also +distribute working documents as Internet-Drafts. + +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any +time. It is inappropriate to use Internet-Drafts as reference +material or to cite them other than as "work in progress." + +The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt + +The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html + +The distribution of this memo is unlimited. + + +.ti 0 +Abstract + +This memo describes two protocols used in the Secure Internet Live +Conferencing (SILC) protocol, specified in the Secure Internet Live +Conferencing, Protocol Specification [SILC1]. The SILC Key Exchange +(SKE) protocol provides secure key exchange between two parties +resulting into shared secret key material. The protocol is based +on Diffie-Hellman key exchange algorithm and its functionality is +derived from several key exchange protocols. SKE use best parts +of the SSH2 Key Exchange protocol, Station-To-Station (STS) protocol +and the OAKLEY Key Determination protocol [OAKLEY]. + +The second protocol, SILC Connection Authentication protocol provides +user level authentication used when creating connections in SILC +network. The protocol is transparent to the authentication data +which means that it can be used to authenticate the user with, for +example, passphrase (pre-shared secret) or public key (and certificate) +based on digital signatures. + + + +.ti 0 +Table of Contents + +.nf +1 Introduction .................................................. 2 + 1.1 Requirements Terminology .................................. 3 +2 SILC Key Exchange Protocol .................................... 3 + 2.1 Key Exchange Payloads ..................................... 4 + 2.1.1 Key Exchange Start Payload .......................... 4 + 2.1.2 Key Exchange Payload ................................ 8 + 2.2 Key Exchange Procedure .................................... 11 + 2.3 Processing the Key Material ............................... 12 + 2.4 SILC Key Exchange Groups .................................. 14 + 2.4.1 diffie-hellman-group1 ............................... 14 + 2.4.2 diffie-hellman-group2 ............................... 15 + 2.4.3 diffie-hellman-group3 ............................... 15 + 2.5 Key Exchange Status Types ................................. 16 +3 SILC Connection Authentication Protocol ....................... 17 + 3.1 Connection Auth Payload ................................... 18 + 3.2 Connection Authentication Types ........................... 19 + 3.2.1 Passphrase Authentication ........................... 19 + 3.2.2 Public Key Authentication ........................... 20 + 3.3 Connection Authentication Status Types .................... 21 +4 Security Considerations ....................................... 21 +5 References .................................................... 21 +6 Author's Address .............................................. 23 + + +.ti 0 +List of Figures + +.nf +Figure 1: Key Exchange Start Payload +Figure 2: Key Exchange Payload +Figure 3: Connection Auth Payload + + +.ti 0 +1 Introduction + +This memo describes two protocols used in the Secure Internet Live +Conferencing (SILC) protocol specified in the Secure Internet Live +Conferencing, Protocol Specification [SILC1]. The SILC Key Exchange +(SKE) protocol provides secure key exchange between two parties +resulting into shared secret key material. The protocol is based on +Diffie-Hellman key exchange algorithm and its functionality is derived +from several key exchange protocols. SKE use best parts of the SSH2 +Key Exchange protocol, Station-To-Station (STS) protocol and the +OAKLEY Key Determination protocol [OAKLEY]. + +The second protocol, SILC Connection Authentication protocol provides +user level authentication used when creating connections in SILC +network. The protocol is transparent to the authentication data which +means that it can be used to authenticate the user with, for example, +passphrase (pre-shared secret) or public key (and certificate) based +on digital signatures. + +The basis of secure SILC session requires strong and secure key exchange +protocol and authentication. The authentication protocol is secured and +no authentication data is ever sent in the network without encrypting +and authenticating it first. Thus, authentication protocol may be used +only after the key exchange protocol has been successfully completed. + +This document constantly refers to other SILC protocol specifications +that should be read to be able to fully understand the functionality +and purpose of these protocols. The most important references are +the Secure Internet Live Conferencing, Protocol Specification [SILC1] +and the SILC Packet Protocol [SILC2]. + +The protocol is intended to be used with the SILC protocol thus it +does not define own framework that could be used. The framework is +provided by the SILC protocol. + + +.ti 0 +1.1 Requirements Terminology + +The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, +MAY, and OPTIONAL, when they appear in this document, are to be +interpreted as described in [RFC2119]. + + +.ti 0 +2 SILC Key Exchange Protocol + +SILC Key Exchange Protocol (SKE) is used to exchange shared secret +between connecting entities. The result of this protocol is a key +material used to secure the communication channel. The protocol use +Diffie-Hellman key exchange algorithm and its functionality is derived +from several key exchange protocols. SKE use best parts of the SSH2 +Key Exchange protocol, Station-To-Station (STS) protocol and the OAKLEY +Key Determination protocol. The protocol does not claim any conformance +to any of these protocols, they were only used as a reference when +designing this protocol. + +The purpose of SILC Key Exchange protocol is to create session keys to +be used in current SILC session. The keys are valid only for some period +of time (usually an hour) or at most until the session ends. These keys +are used to protect packets traveling between the two entities. +Usually all traffic is secured with the key material derived from this +protocol. + +The Diffie-Hellman implementation used in the SILC SHOULD be compliant +to the PKCS #3. + + +.ti 0 +2.1 Key Exchange Payloads + +During the key exchange procedure public data is sent between initiator +and responder. This data is later used in the key exchange procedure. +There are several payloads used in the key exchange. As for all SILC +packets, SILC Packet Header, described in [SILC2], is at the start of +all packets sent in during this protocol. All the fields in the +following payloads are in MSB (most significant byte first) order. +Following descriptions of these payloads. + + +.ti 0 +2.1.1 Key Exchange Start Payload + +The key exchange between two entities MUST be started by sending the +SILC_PACKET_KEY_EXCHANGE packet containing Key Exchange Start Payload. +Initiator sends the Key Exchange Start Payload to the responder filled +with all security properties it supports. The responder then checks +whether it supports the security properties. + +It then sends a Key Exchange Start Payload to the initiator filled with +security properties it selected from the original payload. The payload +sent by responder MUST include only one chosen property per list. The +character encoding for the security property values as defined in [SILC1] +SHOULD be UTF-8 [RFC2279] in Key Exchange Start Payload. + +The Key Exchange Start Payload is used to tell connecting entities what +security properties and algorithms should be used in the communication. +The Key Exchange Start Payload is sent only once per session. Even if +the PFS (Perfect Forward Secrecy) flag is set the Key Exchange Start +Payload is not re-sent. When PFS is desired the Key Exchange Payloads +are sent to negotiate new key material. The procedure is equivalent to +the very first negotiation except that the Key Exchange Start Payload +is not sent. + +As this payload is used only with the very first key exchange the payload +is never encrypted, as there are no keys to encrypt it with. + +A cookie is also sent in this payload. A cookie is used to randomize the +payload so that none of the key exchange parties can determine this +payload before the key exchange procedure starts. The cookie MUST be +returned to the original sender unmodified by the responder. + +Following diagram represents the Key Exchange Start Payload. The lists +mentioned below are always comma (`,') separated and the list MUST NOT +include white spaces (` '). + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| RESERVED | Flags | Payload Length | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | ++ + +| | ++ Cookie + +| | ++ + +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Version String Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Version String ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Key Exchange Grp Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Key Exchange Groups ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| PKCS Alg Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ PKCS Algorithms ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Encryption Alg Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Encryption Algorithms ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Hash Alg Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Hash Algorithms ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| HMAC Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ HMACs ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Compression Alg Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Compression Algorithms ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 1: Key Exchange Start Payload + + + +.in 6 +o RESERVED (1 byte) - Reserved field. Sender fills this with + zero (0) value. + +o Flags (1 byte) - Indicates flags to be used in the key + exchange. Several flags can be set at once by ORing the + flags together. The following flags are reserved for this + field: + + No flags 0x00 + + In this case the field is ignored. + + IV Included 0x01 + + This flag is used to indicate that Initial Vector (IV) + in encryption will be included in the ciphertext + which the recipient must use in decryption. The IV + MUST be set after the last ciphertext block. With + this flag it is possible to use SILC protocol on + unreliable transport such as UDP/IP which may cause + packet reordering and packet losses. By default, + this flag is not set and thus IV is not included + in the ciphertext. Setting this flag increases the + ciphertext size by one ciphertext block. Responder + MAY override this flag for the initiator. + + PFS 0x02 + + Perfect Forward Secrecy (PFS) to be used in the + key exchange protocol. If not set, re-keying + is performed using the old key. See the [SILC1] + for more information on this issue. When PFS is + used, re-keying and creating new keys for any + particular purpose MUST cause new key exchange. + In this key exchange only the Key Exchange Payload + is sent and the Key Exchange Start Payload MUST + NOT be sent. When doing PFS the Key Exchange + Payloads are encrypted with the old keys. + + Mutual Authentication 0x04 + + Both of the parties will perform authentication + by providing signed data for the other party to + verify. By default, only responder will provide + the signature data. If this is set then the + initiator must also provide it. Initiator MAY + set this but also responder MAY set this even if + initiator did not set it. + + Rest of the flags are reserved for the future and + MUST NOT be set. + +o Payload Length (2 bytes) - Length of the entire Key Exchange + Start payload, not including any other field. + +o Cookie (16 bytes) - Cookie that randomize this payload so + that each of the party cannot determine the payload before + hand. This field MUST be present. + +o Version String Length (2 bytes) - The length of the Version + String field, not including any other field. + +o Version String (variable length) - Indicates the version of + the sender of this payload. Initiator sets this when sending + the payload and responder sets this when it replies by sending + this payload. See [SILC1] for definition for the version + string format. This field MUST be present and include valid + version string. + +o Key Exchange Grp Length (2 bytes) - The length of the + key exchange group list, not including any other field. + +o Key Exchange Group (variable length) - The list of + key exchange groups. See the section 2.4 SILC Key Exchange + Groups for definitions of these groups. This field MUST + be present. + +o PKCS Alg Length (2 bytes) - The length of the PKCS algorithms + list, not including any other field. + +o PKCS Algorithms (variable length) - The list of PKCS + algorithms. This field MUST be present. + +o Encryption Alg Length (2 bytes) - The length of the encryption + algorithms list, not including any other field. + +o Encryption Algorithms (variable length) - The list of + encryption algorithms. This field MUST be present. + +o Hash Alg Length (2 bytes) - The length of the Hash algorithm + list, not including any other field. + +o Hash Algorithms (variable length) - The list of Hash + algorithms. The hash algorithms are mainly used in the + SKE protocol. This field MUST be present. + +o HMAC Length (2 bytes) - The length of the HMAC list, not + including any other field. + +o HMACs (variable length) - The list of HMACs. The HMAC's + are used to compute the Message Authentication Code (MAC) + of the SILC packets. This field MUST be present. + +o Compression Alg Length (2 bytes) - The length of the + compression algorithms list, not including any other field. + +o Compression Algorithms (variable length) - The list of + compression algorithms. This field MAY be omitted. +.in 3 + + +.ti 0 +2.1.2 Key Exchange Payload + +Key Exchange payload is used to deliver the public key (or certificate), +the computed Diffie-Hellman public value and possibly signature data +from one party to the other. When initiator is using this payload +and the Mutual Authentication flag is not set then the initiator MUST +NOT provide the signature data. If the flag is set then the initiator +MUST provide the signature data so that the responder can verify it. + +The Mutual Authentication flag is usually used when a separate +authentication protocol will not be executed for the initiator of the +protocol. This is case for example when the SKE is performed between +two SILC clients. In normal case, where client is connecting to a +server, or server is connecting to a router the Mutual Authentication +flag MAY be omitted. However, if the connection authentication protocol +for the connecting entity is not based on digital signatures (it is +based on pre-shared key) then the Mutual Authentication flag SHOULD be +enabled. This way the connecting entity has to provide proof of +possession of the private key for the public key it will provide in +this protocol. + +When performing re-key with PFS selected this is the only payload that +is sent in the SKE protocol. The Key Exchange Start Payload MUST NOT +be sent at all. However, this payload does not have all the fields +present. In the re-key with PFS the public key and a possible signature +data SHOULD NOT be present. If they are present they MUST be ignored. +The only field that is present is the Public Data that is used to create +the new key material. In the re-key the Mutual Authentication flag, that +may be set in the initial negotiation, MUST also be ignored. + +This payload is sent inside SILC_PACKET_KEY_EXCHANGE_1 and inside +SILC_PACKET_KEY_EXCHANGE_2 packet types. The initiator uses the +SILC_PACKET_KEY_EXCHANGE_1 and the responder the latter. + +The following diagram represent the Key Exchange Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Public Key Length | Public Key Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Public Key of the party (or certificate) ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Public Data Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Public Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Signature Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Signature Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 2: Key Exchange Payload + + +.in 6 +o Public Key Length (2 bytes) - The length of the Public Key + (or certificate) field, not including any other field. + +o Public Key Type (2 bytes) - The public key (or certificate) + type. This field indicates the type of the public key in + the packet. Following types are defined: + + 1 SILC style public key (mandatory) + 2 SSH2 style public key (optional) + 3 X.509 Version 3 certificate (optional) + 4 OpenPGP certificate (optional) + 5 SPKI certificate (optional) + + The only required type to support is type number 1. See + [SILC1] for the SILC public key specification. See + SSH2 public key specification in [SSH-TRANS]. See X.509v3 + certificate specification in [PKIX-Part1]. See OpenPGP + certificate specification in [PGP]. See SPKI certificate + specification in [SPKI]. If this field includes zero (0) + or unsupported type number the protocol MUST be aborted + sending SILC_PACKET_FAILURE message and the connection SHOULD + be closed immediately. + +o Public Key (or certificate) (variable length) - The + public key or certificate of the party. This public key + is used to verify the digital signature. The public key + or certificate in this field is encoded in the manner as + defined in their respective definitions; see previous field. + +o Public Data Length (2 bytes) - The length of the Public Data + field, not including any other field. + +o Public Data (variable length) - The public data to be + sent to the receiver (Diffie-Hellman public values). See + section 2.2 Key Exchange Procedure for detailed description + how this field is computed. This value is binary encoded. + +o Signature Length (2 bytes) - The length of the signature, + not including any other field. + +o Signature Data (variable length) - The signature signed + by the sender. The receiver of this signature MUST + verify it. The verification is done using the sender's + public key. See section 2.2 Key Exchange Procedure for + detailed description how to produce the signature. If + the Mutual Authentication flag is not set then initiator + MUST NOT provide this field and the Signature Length field + MUST be set to zero (0) value. If the flag is set then + also the initiator MUST provide this field. The responder + always MUST provide this field. +.in 3 + + +.ti 0 +2.2 Key Exchange Procedure + +The key exchange begins by sending SILC_PACKET_KEY_EXCHANGE packet with +Key Exchange Start Payload to select the security properties to be used +in the key exchange and later in the communication. + +After Key Exchange Start Payload has been processed by both of the +parties the protocol proceeds as follows: + + +Setup: p is a large and public safe prime. This is one of the + Diffie Hellman groups. q is order of subgroup (largest + prime factor of p). g is a generator and is defined + along with the Diffie Hellman group. + + 1. Initiator generates a random number x, where 1 < x < q, + and computes e = g ^ x mod p. The result e is then + encoded into Key Exchange Payload, with the public key + (or certificate) and sent to the responder. + + If the Mutual Authentication flag is set then initiator + MUST also produce signature data SIGN_i which the responder + will verify. The initiator MUST compute a hash value + HASH_i = hash(Initiator's Key Exchange Start Payload | + public key (or certificate) | e). The '|' stands for + concatenation. It then signs the HASH_i value with its + private key resulting a signature SIGN_i. + + 2. Responder generates a random number y, where 1 < y < q, + and computes f = g ^ y mod p. It then computes the + shared secret KEY = e ^ y mod p, and, a hash value + HASH = hash(Initiator's Key Exchange Start Payload | + public key (or certificate) | Initiator's public key + (or certificate) | e | f | KEY). It then signs + the HASH value with its private key resulting a signature + SIGN. + + It then encodes its public key (or certificate), f and + SIGN into Key Exchange Payload and sends it to the + initiator. + + If the Mutual Authentication flag is set then the responder + SHOULD verify that the public key provided in the payload + is authentic, or if certificates are used it verifies the + certificate. The responder MAY accept the public key without + verifying it, however, doing so may result to insecure key + exchange (accepting the public key without verifying may be + desirable for practical reasons on many environments. For + long term use this is never desirable, in which case + certificates would be the preferred method to use). It then + computes the HASH_i value the same way initiator did in the + phase 1. It then verifies the signature SIGN_i from the + payload with the hash value HASH_i using the received public + key. + + 3. Initiator verifies that the public key provided in + the payload is authentic, or if certificates are used + it verifies the certificate. The initiator MAY accept + the public key without verifying it, however, doing + so may result to insecure key exchange (accepting the + public key without verifying may be desirable for + practical reasons on many environments. For long term + use this is never desirable, in which case certificates + would be the preferred method to use). + + Initiator then computes the shared secret KEY = + f ^ x mod p, and, a hash value HASH in the same way as + responder did in phase 2. It then verifies the + signature SIGN from the payload with the hash value + HASH using the received public key. + + +If any of these phases is to fail the SILC_PACKET_FAILURE MUST be sent +to indicate that the key exchange protocol has failed, and the connection +SHOULD be closed immediately. Any other packets MUST NOT be sent or +accepted during the key exchange except the SILC_PACKET_KEY_EXCHANGE_*, +SILC_PACKET_FAILURE and SILC_PACKET_SUCCESS packets. + +The result of this protocol is a shared secret key material KEY and +a hash value HASH. The key material itself is not fit to be used as +a key, it needs to be processed further to derive the actual keys to be +used. The key material is also used to produce other security parameters +later used in the communication. See section 2.3 Processing the Key +Material for detailed description how to process the key material. + +If the Mutual Authentication flag was set the protocol produces also +a hash value HASH_i. This value, however, must be discarded. + +After the keys are processed the protocol is ended by sending the +SILC_PACKET_SUCCESS packet. Both entities send this packet to +each other. After this both parties will start using the new keys. + + +.ti 0 +2.3 Processing the Key Material + +Key Exchange protocol produces secret shared key material KEY. This +key material is used to derive the actual keys used in the encryption +of the communication channel. The key material is also used to derive +other security parameters used in the communication. Key Exchange +protocol produces a hash value HASH as well. + +The keys MUST be derived from the key material as follows: + +.in 6 +Sending Initial Vector (IV) = hash(0x0 | KEY | HASH) +Receiving Initial Vector (IV) = hash(0x1 | KEY | HASH) +Sending Encryption Key = hash(0x2 | KEY | HASH) +Receiving Encryption Key = hash(0x3 | KEY | HASH) +Sending HMAC Key = hash(0x4 | KEY | HASH) +Receiving HMAC Key = hash(0x5 | KEY | HASH) +.in 3 + + +The Initial Vector (IV) is used in the encryption when doing for +example CBC mode. As many bytes as needed are taken from the start of +the hash output for IV. Sending IV is for sending key and receiving IV +is for receiving key. For receiving party, the receiving IV is actually +sender's sending IV, and, the sending IV is actually sender's receiving +IV. Initiator uses IV's as they are (sending IV for sending and +receiving IV for receiving). + +The Encryption Keys are derived as well from the hash(). If the hash() +output is too short for the encryption algorithm more key material MUST +be produced in the following manner: + +.in 6 +K1 = hash(0x2 | KEY | HASH) +K2 = hash(KEY | HASH | K1) +K3 = hash(KEY | HASH | K1 | K2) ... + +Sending Encryption Key = K1 | K2 | K3 ... + + +K1 = hash(0x3 | KEY | HASH) +K2 = hash(KEY | HASH | K1) +K3 = hash(KEY | HASH | K1 | K2) ... + +Receiving Encryption Key = K1 | K2 | K3 ... +.in 3 + + +The key is distributed by hashing the previous hash with the original +key material. The final key is a concatenation of the hash values. +For Receiving Encryption Key the procedure is equivalent. Sending key +is used only for encrypting data to be sent. The receiving key is used +only to decrypt received data. For receiving party, the receive key is +actually sender's sending key, and, the sending key is actually sender's +receiving key. Initiator uses generated keys as they are (sending key +for sending and receiving key for receiving). + +The HMAC keys are used to create MAC values to packets in the +communication channel. As many bytes as needed are taken from the start +of the hash output to generate the MAC keys. + +These procedures are performed by all parties of the key exchange +protocol. This MUST be done before the protocol has been ended by +sending the SILC_PACKET_SUCCESS packet, to assure that parties can +successfully process the key material. + +This same key processing procedure MAY be used in the SILC in some +other circumstances as well. Any changes to this procedure is defined +separately when this procedure is needed. See the [SILC1] and the +[SILC2] for these circumstances. + + +.ti 0 +2.4 SILC Key Exchange Groups + +The Following groups may be used in the SILC Key Exchange protocol. +The first group diffie-hellman-group1 is REQUIRED, other groups MAY be +negotiated to be used in the connection with Key Exchange Start Payload +and SILC_PACKET_KEY_EXCHANGE packet. However, the first group MUST be +proposed in the Key Exchange Start Payload regardless of any other +requested group (however, it does not have to be the first in the list). + + +.ti 0 +2.4.1 diffie-hellman-group1 + +The length of this group is 1024 bits. This is REQUIRED group. +The prime is 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }. + +Its hexadecimal value is + +.in 6 +FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 +29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD +EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 +E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED +EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 +FFFFFFFF FFFFFFFF +.in 3 + + +The generator used with this prime is g = 2. The group order q is +(p - 1) / 2. + +This group was taken from the OAKLEY specification. + + +.ti 0 +2.4.2 diffie-hellman-group2 + +The length of this group is 1536 bits. This is OPTIONAL group. +The prime is 2^1536 - 2^1472 - 1 + 2^64 * { [2^1406 pi] + 741804 }. + +Its hexadecimal value is + +.in 6 +FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 +29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD +EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 +E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED +EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D +C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F +83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D +670C354E 4ABC9804 F1746C08 CA237327 FFFFFFFF FFFFFFFF +.in 3 + +The generator used with this prime is g = 2. The group order q is +(p - 1) / 2. + +This group was taken from the OAKLEY specification. + + +.ti 0 +2.4.3 diffie-hellman-group3 + +The length of this group is 2048 bits. This is OPTIONAL group. +This prime is: 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 }. + +Its hexadecimal value is + +.in 6 +FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 +29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD +EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 +E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED +EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D +C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F +83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D +670C354E 4ABC9804 F1746C08 CA18217C 32905E46 2E36CE3B +E39E772C 180E8603 9B2783A2 EC07A28F B5C55DF0 6F4C52C9 +DE2BCBF6 95581718 3995497C EA956AE5 15D22618 98FA0510 +15728E5A 8AACAA68 FFFFFFFF FFFFFFFF +.in 3 + +The generator used with this prime is g = 2. The group order q is +(p - 1) / 2. + + + + + +.ti 0 +2.5 Key Exchange Status Types + +This section defines all key exchange protocol status types that may +be returned in the SILC_PACKET_SUCCESS or SILC_PACKET_FAILURE packets +to indicate the status of the protocol. Implementations may map the +status types to human readable error message. All types except the +SILC_SKE_STATUS_OK type MUST be sent in SILC_PACKET_FAILURE packet. +The length of status is 32 bits (4 bytes). The following status types +are defined: + +.in 6 +0 SILC_SKE_STATUS_OK + + Protocol were executed successfully. + + +1 SILC_SKE_STATUS_ERROR + + Unknown error occurred. No specific error type is defined. + + +2 SILC_SKE_STATUS_BAD_PAYLOAD + + Provided KE payload were malformed or included bad fields. + + +3 SILC_SKE_STATUS_UNSUPPORTED_GROUP + + None of the provided groups were supported. + + +4 SILC_SKE_STATUS_UNSUPPORTED_CIPHER + + None of the provided ciphers were supported. + + +5 SILC_SKE_STATUS_UNSUPPORTED_PKCS + + None of the provided public key algorithms were supported. + + +6 SILC_SKE_STATUS_UNSUPPORTED_HASH_FUNCTION + + None of the provided hash functions were supported. + + +7 SILC_SKE_STATUS_UNSUPPORTED_HMAC + + None of the provided HMACs were supported. + + +8 SILC_SKE_STATUS_UNSUPPORTED_PUBLIC_KEY + + Provided public key type is not supported. + + +9 SILC_SKE_STATUS_INCORRECT_SIGNATURE + + Provided signature was incorrect. + + +10 SILC_SKE_STATUS_BAD_VERSION + + Provided version string was not acceptable. + + +11 SILC_SKE_STATUS_INVALID_COOKIE + + The cookie in the Key Exchange Start Payload was malformed, + because responder modified the cookie. +.in 3 + + +.ti 0 +3 SILC Connection Authentication Protocol + +Purpose of Connection Authentication protocol is to authenticate the +connecting party with server. Usually connecting party is client but +server may connect to router server as well. Its other purpose is to +provide information for the server about which type of connection this +is. The type defines whether this is client, server or router +connection. Server use this information to create the ID for the +connection. + +Server MUST verify the authentication data received and if it is to fail +the authentication MUST be failed by sending SILC_PACKET_FAILURE packet. +If authentication is successful the protocol is ended by server by sending +SILC_PACKET_SUCCESS packet. + +The protocol is executed after the SILC Key Exchange protocol. It MUST +NOT be executed in any other time. As it is performed after key exchange +protocol all traffic in the connection authentication protocol is +encrypted with the exchanged keys. + +The protocol MUST be started by the connecting party by sending the +SILC_PACKET_CONNECTION_AUTH packet with Connection Auth Payload, +described in the next section. This payload MUST include the +authentication data. The authentication data is set according +authentication method that MUST be known by both parties. If connecting +party does not know what is the mandatory authentication method it MAY +request it from the server by sending SILC_PACKET_CONNECTION_AUTH_REQUEST +packet. This packet is not part of this protocol and is described in +section Connection Auth Request Payload in [SILC2]. However, if +connecting party already knows the mandatory authentication method +sending the request is not necessary. + +See [SILC1] and section Connection Auth Request Payload in [SILC2] also +for the list of different authentication methods. Authentication method +MAY also be NONE, in which case the server does not require +authentication. However, in this case the protocol still MUST be +executed; the authentication data is empty indicating no authentication +is required. + +If authentication method is passphrase the authentication data is +plaintext passphrase. As the payload is encrypted it is safe to have +plaintext passphrase. It is also provided as plaintext passphrase +because the receiver may need to pass the entire passphrase into a +passphrase verifier, and a message digest of the passphrase would +prevent this. See the section 3.2.1 Passphrase Authentication for +more information. + +If authentication method is public key authentication the authentication +data is a digital signature of the hash value of hash HASH and Key +Exchange Start Payload, established by the SILC Key Exchange protocol. +This signature MUST then be verified by the server. See the section +3.2.2 Public Key Authentication for more information. + +See the section 4 SILC Procedures in [SILC1] for more information about +client creating connection to server, and server creating connection +to router, and how to register the session in the SILC Network after +successful Connection Authentication protocol. + + +.ti 0 +3.1 Connection Auth Payload + +Client sends this payload to authenticate itself to the server. Server +connecting to another server also sends this payload. Server receiving +this payload MUST verify all the data in it and if something is to fail +the authentication MUST be failed by sending SILC_PACKET_FAILURE packet. + +The payload may only be sent with SILC_PACKET_CONNECTION_AUTH packet. +It MUST NOT be sent in any other packet type. The following diagram +represent the Connection Auth Payload. + + + + + + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload Length | Connection Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Authentication Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 3: Connection Auth Payload + + +.in 6 +o Payload Length (2 bytes) - Length of the entire Connection + Auth Payload. + +o Connection Type (2 bytes) - Indicates the type of the + connection. See section Connection Auth Request Payload + in [SILC2] for the list of connection types. This field MUST + include valid connection type or the packet MUST be discarded + and authentication MUST be failed. + +o Authentication Data (variable length) - The actual + authentication data. Contents of this depends on the + authentication method known by both parties. If no + authentication is required this field does not exist. +.in 3 + + +.ti 0 +3.2 Connection Authentication Types + +SILC supports two authentication types to be used in the connection +authentication protocol; passphrase authentication or public key +authentication based on digital signatures. The following sections +defines the authentication methods. See [SILC2] for defined numerical +authentication method types. + + +.ti 0 +3.2.1 Passphrase Authentication + +Passphrase authentication or pre-shared key based authentication is +simply an authentication where the party that wants to authenticate +itself to the other end sends the passphrase that is required by +the other end, for example server. The plaintext passphrase is put +to the payload, that is then encrypted. The plaintext passphrase +MUST be in UTF-8 [RFC2279] encoding. If the passphrase is in the +sender's system in some other encoding it MUST be UTF-8 encoded +before transmitted. The receiver MAY change the encoding of the +passphrase to its system's default character encoding before verifying +the passphrase. + +If the passphrase matches with the one in the server's end the +authentication is successful. Otherwise SILC_PACKET_FAILURE MUST be +sent to the sender and the protocol execution fails. + +This is REQUIRED authentication method to be supported by all SILC +implementations. + +When password authentication is used it is RECOMMENDED that maximum +amount of padding is applied to the SILC packet. This way it is not +possible to approximate the length of the password from the encrypted +packet. + + + +.ti 0 +3.2.2 Public Key Authentication + +Public key authentication may be used if passphrase based authentication +is not desired. The public key authentication works by sending a +digital signature as authentication data to the other end, say, server. +The server MUST then verify the signature by the public key of the sender, +which the server has received earlier in SKE protocol. + +The signature is computed using the private key of the sender by signing +the HASH value provided by the SKE protocol previously, and the Key +Exchange Start Payload from SKE protocol that was sent to the server. +These are concatenated and hash function is used to compute a hash value +which is then signed. + + auth_hash = hash(HASH | Key Exchange Start Payload); + signature = sign(auth_hash); + +The hash() function used to compute the value is the hash function +negotiated in the SKE protocol. The server MUST verify the data, thus +it must keep the HASH and the Key Exchange Start Payload saved during +SKE and authentication protocols. These values can be discarded after +Connection Authentication protocol is completed. + +If the verified signature matches the sent signature, the authentication +were successful and SILC_PACKET_SUCCESS is sent. If it failed the +protocol execution is stopped and SILC_PACKET_FAILURE is sent. + +This is REQUIRED authentication method to be supported by all SILC +implementations. + + + +.ti 0 +3.3 Connection Authentication Status Types + +This section defines all connection authentication status types that +may be returned in the SILC_PACKET_SUCCESS or SILC_PACKET_FAILURE packets +to indicate the status of the protocol. Implementations may map the +status types to human readable error message. All types except the +SILC_AUTH_STATUS_OK type MUST be sent in SILC_PACKET_FAILURE packet. +The length of status is 32 bits (4 bytes). The following status types +are defined: + +0 SILC_AUTH_OK + + Protocol was executed successfully. + + +1 SILC_AUTH_FAILED + + Authentication failed. + + +.ti 0 +4 Security Considerations + +Security is central to the design of this protocol, and these security +considerations permeate the specification. Common security considerations +such as keeping private keys truly private and using adequate lengths for +symmetric and asymmetric keys must be followed in order to maintain the +security of this protocol. + + +.ti 0 +5 References + +[SILC1] Riikonen, P., "Secure Internet Live Conferencing (SILC), + Protocol Specification", Internet Draft, May 2002. + +[SILC2] Riikonen, P., "SILC Packet Protocol", Internet Draft, + May 2002. + +[SILC4] Riikonen, P., "SILC Commands", Internet Draft, May 2002. + +[IRC] Oikarinen, J., and Reed D., "Internet Relay Chat Protocol", + RFC 1459, May 1993. + +[IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810, + April 2000. + +[IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC + 2811, April 2000. + +[IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC + 2812, April 2000. + +[IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC + 2813, April 2000. + +[SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", + Internet Draft. + +[PGP] Callas, J., et al, "OpenPGP Message Format", RFC 2440, + November 1998. + +[SPKI] Ellison C., et al, "SPKI Certificate Theory", RFC 2693, + September 1999. + +[PKIX-Part1] Housley, R., et al, "Internet X.509 Public Key + Infrastructure, Certificate and CRL Profile", RFC 2459, + January 1999. + +[Schneier] Schneier, B., "Applied Cryptography Second Edition", + John Wiley & Sons, New York, NY, 1996. + +[Menezes] Menezes, A., et al, "Handbook of Applied Cryptography", + CRC Press 1997. + +[OAKLEY] Orman, H., "The OAKLEY Key Determination Protocol", + RFC 2412, November 1998. + +[ISAKMP] Maughan D., et al, "Internet Security Association and + Key Management Protocol (ISAKMP)", RFC 2408, November + 1998. + +[IKE] Harkins D., and Carrel D., "The Internet Key Exchange + (IKE)", RFC 2409, November 1998. + +[HMAC] Krawczyk, H., "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + +[PKCS1] Kalinski, B., and Staddon, J., "PKCS #1 RSA Cryptography + Specifications, Version 2.0", RFC 2437, October 1998. + +[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. + + +.ti 0 +6 Author's Address + +.nf +Pekka Riikonen +Snellmaninkatu 34 A 15 +70100 Kuopio +Finland + +EMail: priikone@iki.fi + +This Internet-Draft expires XXX diff --git a/doc/draft-riikonen-silc-pp-07.nroff b/doc/draft-riikonen-silc-pp-07.nroff new file mode 100644 index 00000000..c478b474 --- /dev/null +++ b/doc/draft-riikonen-silc-pp-07.nroff @@ -0,0 +1,2917 @@ +.pl 10.0i +.po 0 +.ll 7.2i +.lt 7.2i +.nr LL 7.2i +.nr LT 7.2i +.ds LF Riikonen +.ds RF FORMFEED[Page %] +.ds CF +.ds LH Internet Draft +.ds RH XXX +.ds CH +.na +.hy 0 +.in 0 +.nf +Network Working Group P. Riikonen +Internet-Draft +draft-riikonen-silc-pp-07.txt XXX +Expires: XXX + +.in 3 + +.ce 2 +SILC Packet Protocol + + +.ti 0 +Status of this Memo + +This document is an Internet-Draft and is in full conformance with +all provisions of Section 10 of RFC 2026. Internet-Drafts are +working documents of the Internet Engineering Task Force (IETF), its +areas, and its working groups. Note that other groups may also +distribute working documents as Internet-Drafts. + +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any +time. It is inappropriate to use Internet-Drafts as reference +material or to cite them other than as "work in progress." + +The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt + +The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html + +The distribution of this memo is unlimited. + + +.ti 0 +Abstract + +This memo describes a Packet Protocol used in the Secure Internet Live +Conferencing (SILC) protocol, specified in the Secure Internet Live +Conferencing, Protocol Specification Internet Draft [SILC1]. This +protocol describes the packet types and packet payloads which defines +the contents of the packets. The protocol provides secure binary packet +protocol that assures that the contents of the packets are secured and +authenticated. + + + + + + + + +.ti 0 +Table of Contents + +.nf +1 Introduction .................................................. 3 + 1.1 Requirements Terminology .................................. 4 +2 SILC Packet Protocol .......................................... 4 + 2.1 SILC Packet ............................................... 4 + 2.2 SILC Packet Header ........................................ 5 + 2.3 SILC Packet Types ......................................... 8 + 2.3.1 SILC Packet Payloads ................................ 15 + 2.3.2 Generic payloads .................................... 16 + 2.3.2.1 ID Payload .................................. 16 + 2.3.2.2 Argument Payload ............................ 16 + 2.3.2.3 Channel Payload ............................. 17 + 2.3.2.4 Public Key Payload .......................... 18 + 2.3.2.5 Message Payload ............................. 19 + 2.3.3 Disconnect Payload .................................. 22 + 2.3.4 Success Payload ..................................... 23 + 2.3.5 Failure Payload ..................................... 23 + 2.3.6 Reject Payload ...................................... 24 + 2.3.7 Notify Payload ...................................... 25 + 2.3.8 Error Payload ....................................... 32 + 2.3.9 Channel Message Payload ............................. 33 + 2.3.10 Channel Key Payload ................................ 34 + 2.3.11 Private Message Payload ............................ 35 + 2.3.12 Private Message Key Payload ........................ 36 + 2.3.13 Command Payload .................................... 38 + 2.3.14 Command Reply Payload .............................. 39 + 2.3.15 Connection Auth Request Payload .................... 39 + 2.3.16 New ID Payload ..................................... 40 + 2.3.17 New Client Payload ................................. 41 + 2.3.18 New Server Payload ................................. 42 + 2.3.19 New Channel Payload ................................ 43 + 2.3.20 Key Agreement Payload .............................. 43 + 2.3.21 Resume Router Payload .............................. 44 + 2.3.22 File Transfer Payload .............................. 45 + 2.3.23 Resume Client Payload .............................. 46 + 2.4 SILC ID Types ............................................. 47 + 2.5 Packet Encryption And Decryption .......................... 48 + 2.5.1 Normal Packet Encryption And Decryption ............. 48 + 2.5.2 Channel Message Encryption And Decryption ........... 49 + 2.5.3 Private Message Encryption And Decryption ........... 50 + 2.6 Packet MAC Generation ..................................... 50 + 2.7 Packet Padding Generation ................................. 51 + 2.8 Packet Compression ........................................ 52 + 2.9 Packet Sending ............................................ 52 + 2.10 Packet Reception ......................................... 52 + 2.11 Packet Routing ........................................... 53 + 2.12 Packet Broadcasting ...................................... 54 +3 Security Considerations ....................................... 55 +4 References .................................................... 55 +5 Author's Address .............................................. 56 + +.ti 0 +List of Figures + +.nf +Figure 1: Typical SILC Packet +Figure 2: SILC Packet Header +Figure 3: ID Payload +Figure 4: Argument Payload +Figure 5: Channel Payload +Figure 6: Public Key Payload +Figure 7: Message Payload +Figure 8: Disconnect Payload +Figure 9: Success Payload +Figure 10: Failure Payload +Figure 11: Reject Payload +Figure 12: Notify Payload +Figure 13: Error Payload +Figure 14: Channel Key Payload +Figure 15: Private Message Key Payload +Figure 16: Command Payload +Figure 17: Connection Auth Request Payload +Figure 18: New Client Payload +Figure 19: New Server Payload +Figure 20: Key Agreement Payload +Figure 21: Resume Router Payload +Figure 22: File Transfer Payload +Figure 23: Resume Client Payload + + +.ti 0 +1. Introduction + +This document describes a Packet Protocol used in the Secure Internet +Live Conferencing (SILC) protocol specified in the Secure Internet Live +Conferencing, Protocol Specification Internet Draft [SILC1]. This +protocol describes the packet types and packet payloads which defines +the contents of the packets. The protocol provides secure binary packet +protocol that assures that the contents of the packets are secured and +authenticated. The packet protocol is designed to be compact to avoid +unnecessary overhead as much as possible. This makes the SILC suitable +also in environment of low bandwidth requirements such as mobile networks. +All packet payloads can also be compressed to further reduce the size +of the packets. + +All packets in SILC network are always encrypted and their integrity +is assured by computed MACs. The protocol defines several packet types +and packet payloads. Each packet type usually has a specific packet +payload that actually defines the contents of the packet. Each packet +also includes a default SILC Packet Header that provides sufficient +information about the origin of the packet and destination of the +packet. + + +.ti 0 +1.1 Requirements Terminology + +The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, +MAY, and OPTIONAL, when they appear in this document, are to be +interpreted as described in [RFC2119]. + + +.ti 0 +2 SILC Packet Protocol + +.ti 0 +2.1 SILC Packet + +SILC packets deliver messages from sender to receiver securely by +encrypting important fields of the packet. The packet consists of +default SILC Packet Header, Padding, Packet Payload data, and, packet +MAC. + +The following diagram illustrates typical SILC packet. + + +.in 5 +.nf + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +| n bytes | 1 - n bytes | n bytes | n bytes +| SILC Header | Padding | Data Payload | MAC + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.in 3 + +.ce +Figure 1: Typical SILC Packet + + +SILC Header is always the first part of the packet and its purpose +is to provide information about the packet. It provides for example +the packet type, origin of the packet and the destination of the packet. +The header is variable in length. See the following section for +description of SILC Packet header. Packets without SILC header or +with malformed SILC header MUST be dropped. + +Padding follows the packet header. The purpose of the padding is to +make the packet multiple by eight (8) or by the block size of the +cipher used in the encryption, which ever is larger. The maximum +length of padding is currently 128 bytes. The padding is always +encrypted. The padding is applied always, even if the packet is +not encrypted. See the section 2.7 Padding Generation for more +detailed information. + +Data payload area follows padding and it is the actual data of the +packet. The packet data is the packet payloads defined in this +protocol. The data payload area is always encrypted. + +The last part of SILC packet is the packet MAC that assures the +integrity of the packet. See the section 2.6 Packet MAC Generation +for more information. If compression is used the compression is +always applied before encryption. + +All fields in all packet payloads are always in MSB (most significant +byte first) order. + + +.ti 0 +2.2 SILC Packet Header + +The SILC packet header is applied to all SILC packets and it is +variable in length. The purpose of SILC Packet header is to provide +detailed information about the packet. The receiver of the packet +uses the packet header to parse the packet and gain other relevant +parameters of the packet. + +The following diagram represents the SILC packet header. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload Length | Flags | Packet Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Pad Length | RESERVED | Source ID Len | Dest ID Len | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Src ID Type | | ++-+-+-+-+-+-+-+-+ + +| | +~ Source ID ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Dst ID Type | | ++-+-+-+-+-+-+-+-+ + +| | +~ Destination ID ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 2: SILC Packet Header + + +.in 6 +o Payload Length (2 bytes) - Is the length of the packet + not including the padding of the packet. + +o Flags (1 byte) - Indicates flags to be used in packet + processing. Several flags may be set by ORing the flags + together. + + The following flags are reserved for this field: + + + No flags 0x00 + + In this case the field is ignored. + + + Private Message Key 0x01 + + Indicates that the packet must include private + message that is encrypted using private key set by + client. Servers does not know anything about this + key and this causes that the private message is + not handled by the server at all, it is just + passed along. See section 2.5.3 Private Message + Encryption And Decryption for more information. + + + List 0x02 + + Indicates that the packet consists of list of + packet payloads indicated by the Packet Type field. + The payloads are added one after the other. Note that + there are packet types that must not be used as + list. Parsing of list packet is done by calculating + the length of each payload and parsing them one by + one. + + + Broadcast 0x04 + + Marks the packet to be broadcasted. Client cannot + send broadcast packet and normal server cannot send + broadcast packet. Only router server may send broadcast + packet. The router receiving of packet with this flag + set MUST send (broadcast) the packet to its primary + route. If router has several router connections the + packet may be sent only to the primary route. See + section 2.12 Packet Broadcasting for description of + packet broadcasting. + + + + Compressed 0x08 + + Marks that the payload of the packet is compressed. + The sender of the packet marks this flag when it + compresses the payload, and any server or router + en route to the recipient MUST NOT unset this flag. + See section 2.8 Packet Compression for description of + packet compressing. + +.in 3 + +o Packet Type (1 byte) - Is the type of the packet. Receiver + uses this field to parse the packet. See section 2.3 + SILC Packets for list of defined packet types. + +o Pad Length (1 byte) - Indicates the length of the padding + applied after the SILC Packet header. Maximum length for + padding is 128 bytes. + +o RESERVED (1 byte) - Reserved field and must include a + zero (0) value. + +o Source ID Length (1 byte) - Indicates the length of the + Source ID field in the header, not including this or any + other fields. + +o Destination ID Length (1 byte) - Indicates the length of the + Destination ID field in the header, not including this or + any other fields. + +o Src ID Type (1 byte) - Indicates the type of ID in the + Source ID field. See section 2.4 SILC ID Types for + defined ID types. + +o Source ID (variable length) - The actual source ID that + indicates which is the original sender of the packet. + +o Dst ID Type (1 byte) - Indicates the type of ID in the + Destination ID field. See section 2.4 SILC ID Types for + defined ID types. + +o Destination ID (variable length) - The actual destination + ID that indicates which is the end receiver of the packet. + + + + + + +.ti 0 +2.3 SILC Packet Types + +SILC packet types defines the contents of the packet and it is used by +the receiver to parse the packet. The packet type is 8 bits, as a one +byte, in length. The range for the packet types are from 0 - 255, +where 0 is never sent and 255 is currently reserved for future +extensions and MUST NOT be defined to any other purpose. Every SILC +specification compliant implementation SHOULD support all of these packet +types. + +The below list of the SILC Packet types includes reference to the packet +payload as well. Packet payloads are the actual packet data area. Each +packet type defines packet payload which usually may only be sent with +the specific packet type. + +Most of the packets are packets that must be destined directly to entity +that is connected to the sender. It is not allowed, for example, for a +router to send disconnect packet to client that is not directly connected +to the router. However, there are some special packet types that may +be destined to some entity that the sender does not have direct +connection with. These packets are for example private message packets, +channel message packets, command packets and some other packets that may +be broadcasted in the SILC network. If the packet is allowed to be sent +to indirectly connected entity it is defined separately in the packet +description below. Other packets MUST NOT be sent or accepted, if sent, +to indirectly connected entities. + +Some packets MAY be sent as lists by adding the List flag to the Packet +Header and constructing multiple packet payloads one after the other. +When this is allowed it is separately defined below. Other packets +MUST NOT be sent as list and the List flag MUST NOT be set. + + +List of SILC Packet types are defined as follows. + +.in 1 + 0 SILC_PACKET_NONE + + This type is reserved and it is never sent. + + + 1 SILC_PACKET_DISCONNECT + + This packet is sent to disconnect the remote end. Reason of + the disconnection is sent inside the packet payload. Client + usually does not send this packet. + + Payload of the packet: See section 2.3.3 Disconnect Payload + + + 2 SILC_PACKET_SUCCESS + + This packet is sent upon successful execution of some protocol. + The status of the success is sent in the packet. + + Payload of the packet: See section 2.3.4 Success Payload + + + 3 SILC_PACKET_FAILURE + + This packet is sent upon failure of some protocol. The status + of the failure is sent in the packet. + + Payload of the packet: See section 2.3.5 Failure Payload + + + 4 SILC_PACKET_REJECT + + This packet MAY be sent upon rejection of some protocol. + The status of the rejection is sent in the packet. + + Payload of the packet: See section 2.3.6 Reject Payload + + + 5 SILC_PACKET_NOTIFY + + This packet is used to send notify message. The packet is + usually sent between server and client, but also between + server and router. Client MUST NOT send this packet. Server + MAY send this packet to channel as well when the packet is + distributed to all clients on the channel. This packet MAY + be sent as list. + + Payload of the packet: See section 2.3.7 Notify Payload. + + + + 6 SILC_PACKET_ERROR + + This packet is sent when an error occurs. Server MAY + send this packet. Client MUST NOT send this packet. The + client MAY entirely ignore the packet, however, server is + most likely to take action anyway. This packet MAY be sent + to entity that is indirectly connected to the sender. + + Payload of the packet: See section 2.3.8 Error Payload. + + + 7 SILC_PACKET_CHANNEL_MESSAGE + + This packet is used to send messages to channels. The packet + includes Channel ID of the channel and the actual message to + the channel. Messages sent to the channel are always protected + by channel specific keys. Channel Keys are distributed by + SILC_PACKET_CHANNEL_KEY packet. This packet MAY be sent to + entity that is indirectly connected to the sender. + + Payload of the packet: See section 2.3.9 Channel Message + Payload + + + 8 SILC_PACKET_CHANNEL_KEY + + This packet is used to distribute new key for particular + channel. Each channel has their own independent keys that + is used to protect the traffic on the channel. Only server + may send this packet. This packet MAY be sent to entity + that is indirectly connected to the sender. + + Payload of the packet: See section 2.3.10 Channel Key Payload + + + 9 SILC_PACKET_PRIVATE_MESSAGE + + This packet is used to send private messages from client + to another client. By default, private messages are protected + by session keys established by normal key exchange protocol. + However, it is possible to use specific key to protect private + messages. See [SILC1] for private message key generation. + This packet MAY be sent to entity that is indirectly connected + to the sender. + + Payload of the packet: See section 2.3.11 Private Message + Payload + + + 10 SILC_PACKET_PRIVATE_MESSAGE_KEY + + This packet can be used to agree about a key to be used to + protect private messages between two clients. This packet + is sent inside the SILC network and protected with session + keys. There are other means of agreeing to use private message + keys as well, than sending this packet which may not be + desirable on all situations. See the [SILC1] for private + message key generation. + + Payload of the packet: See section 2.3.12 Private Message + Key Payload + + + 11 SILC_PACKET_COMMAND + + This packet is used to send commands from client to server. + Server MAY send this packet to other servers as well. All + commands are listed in their own section SILC Command Types + in [SILC4]. The contents of this packet is command specific. + This packet MAY be sent to entity that is indirectly connected + to the sender. + + Payload of the packet: See section 2.3.13 Command Payload + + + 12 SILC_PACKET_COMMAND_REPLY + + This packet is sent as reply to the SILC_PACKET_COMMAND packet. + The contents of this packet is command specific. This packet + MAY be sent to entity that is indirectly connected to the + sender. + + Payload of the packet: See section 2.3.14 Command Reply + Payload and section 2.3.13 Command + Payload + + + + + 13 SILC_PACKET_KEY_EXCHANGE + + This packet is used to start SILC Key Exchange Protocol, + described in detail in [SILC3]. + + Payload of the packet: Payload of this packet is described + in the section SILC Key Exchange + Protocol and its sub sections in + [SILC3]. + + + 14 SILC_PACKET_KEY_EXCHANGE_1 + + This packet is used as part of the SILC Key Exchange Protocol. + + Payload of the packet: Payload of this packet is described + in the section SILC Key Exchange + Protocol and its sub sections in + [SILC3]. + + + 15 SILC_PACKET_KEY_EXCHANGE_2 + + This packet is used as part of the SILC Key Exchange Protocol. + + Payload of the packet: Payload of this packet is described + in the section SILC Key Exchange + Protocol and its sub sections in + [SILC3]. + + + 16 SILC_PACKET_CONNECTION_AUTH_REQUEST + + This packet is used to request an authentication method to + be used in the SILC Connection Authentication Protocol. If + initiator of the protocol does not know the mandatory + authentication method this packet MAY be used to determine it. + The party receiving this payload SHOULD respond with the same + packet including the mandatory authentication method. + + Payload of the packet: See section 2.3.15 Connection Auth + Request Payload + + + + + 17 SILC_PACKET_CONNECTION_AUTH + + This packet is used to start and perform the SILC Connection + Authentication Protocol. This protocol is used to authenticate + the connecting party. The protocol is described in detail in + [SILC3]. + + Payload of the packet: Payload of this packet is described + in the section SILC Authentication + Protocol and it sub sections in [SILC]. + + + 18 SILC_PACKET_NEW_ID + + This packet is used to distribute new IDs from server to + router and from router to all other routers in SILC network. + This is used when for example new client is registered to + SILC network. The newly created IDs of these operations are + distributed by this packet. Only server may send this packet, + however, client MUST be able to receive this packet. This + packet MAY be sent to entity that is indirectly connected + to the sender. This packet MAY be sent as list. + + Payload of the packet: See section 2.3.16 New ID Payload + + + 19 SILC_PACKET_NEW_CLIENT + + This packet is used by client to register itself to the + SILC network. This is sent after key exchange and + authentication protocols has been completed. Client sends + various information about itself in this packet. + + Payload of the packet: See section 2.3.17 New Client Payload + + + 20 SILC_PACKET_NEW_SERVER + + This packet is used by server to register itself to the + SILC network. This is sent after key exchange and + authentication protocols has been completed. Server sends + this to the router it connected to, or, if router was + connecting, to the connected router. Server sends its + Server ID and other information in this packet. The client + MUST NOT send or receive this packet. + + Payload of the packet: See section 2.3.18 New Server Payload + + + 21 SILC_PACKET_NEW_CHANNEL + + This packet is used to notify routers about newly created + channel. Channels are always created by the router and it MUST + notify other routers about the created channel. Router sends + this packet to its primary route. Client MUST NOT send this + packet. This packet MAY be sent to entity that is indirectly + connected to the sender. This packet MAY be sent as list. + + Payload of the packet: See section 2.3.19 New Channel Payload + + + 22 SILC_PACKET_REKEY + + This packet is used to indicate that re-key must be performed + for session keys. See section Session Key Regeneration in + [SILC1] for more information. This packet does not have + a payload. + + + 23 SILC_PACKET_REKEY_DONE + + This packet is used to indicate that re-key is performed and + new keys must be used hereafter. This packet does not have a + payload. + + + 24 SILC_PACKET_HEARTBEAT + + This packet is used by clients, servers and routers to keep the + connection alive. It is RECOMMENDED that all servers implement + keepalive actions and perform it to both direction in a link. + This packet does not have a payload. + + + 25 SILC_PACKET_KEY_AGREEMENT + + This packet is used by clients to request key negotiation + between another client in the SILC network. If the negotiation + is started it is performed using the SKE protocol. The result of + the negotiation, the secret key material, can be used for + example as private message key. The server and router MUST NOT + send this packet. + + Payload of the packet: See section 2.3.20 Key Agreement Payload + + + 26 SILC_PACKET_RESUME_ROUTER + + This packet is used during backup router protocol when the + original primary router of the cell comes back online and wishes + to resume the position as being the primary router of the cell. + + Payload of the packet: See section 2.3.21 Resume Router Payload + + + 27 SILC_PACKET_FTP + + This packet is used to perform an file transfer protocol in the + SILC session with some entity in the network. The packet is + multi purpose. The packet is used to tell other entity in the + network that the sender wishes to perform an file transfer + protocol. The packet is also used to actually tunnel the + file transfer protocol stream. The file transfer protocol + stream is always protected with the SILC binary packet protocol. + + Payload of the packet: See section 2.3.22 File Transfer Payload + + + 28 SILC_PACKET_RESUME_CLIENT + + This packet is used to resume a client back to the network + after it has been detached. A client is able to detach from + the network but the client is still valid client in the network. + The client may then later resume its session back by sending + this packet to a server. Routers also use this packet to notify + other routers in the network that the detached client has resumed. + + Payload of the packet: See section 2.3.23 Resume Client Payload + + + 29 - 199 + + Currently undefined commands. + + + 200 - 254 + + These packet types are reserved for private use and they will + not be defined by this document. + + + 255 SILC_PACKET_MAX + + This type is reserved for future extensions and currently it + MUST NOT be sent. +.in 3 + + +.ti 0 +2.3.1 SILC Packet Payloads + +All payloads resides in the main data area of the SILC packet. However +all payloads MUST be at the start of the data area after the SILC +packet header and padding. All fields in the packet payload are always +encrypted, as they reside in the data area of the packet which is +always encrypted. + +Payloads described in this section are common payloads that MUST be +accepted anytime during SILC session. Most of the payloads may only +be sent with specific packet type which is defined in the description +of the payload. + +There are many other payloads in SILC as well. However, they are not +common in the sense that they could be sent at any time. These payloads +are not described in this section. These are payloads such as SILC +Key Exchange payloads and so on. These are described in [SILC1], +[SILC3] and [SILC4]. + + +.ti 0 +2.3.2 Generic payloads + +This section describes generic payloads that are not associated to any +specific packet type. They can be used for example inside some other +packet payload. + + +.ti 0 +2.3.2.1 ID Payload + +This payload can be used to send an ID. ID's are variable in length +thus this payload provides a way to send variable length ID. + +The following diagram represents the ID Payload. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| ID Type | ID Length | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ ID Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 3: ID Payload + + +.in 6 +o ID Type (2 bytes) - Indicates the type of the ID. See + section 2.4 SILC ID Types for list of defined ID types. + +o ID Length (2 bytes) - Length of the ID Data area not + including the length of any other fields in the payload. + +o ID Data (variable length) - The actual ID data. The encoding + of the ID data is defined in section 2.4 SILC ID Types. +.in 3 + + +.ti 0 +2.3.2.2 Argument Payload + +Argument Payload is used to set arguments for any packet payload that +need and support arguments, such as commands. Number of arguments +associated with a packet MUST be indicated by the packet payload which +need the arguments. Argument Payloads MUST always reside right after +the packet payload needing the arguments. Incorrect amount of argument +payloads MUST cause rejection of the packet. + +The following diagram represents the Argument Payload. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload Length | Argument Type | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Argument Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 4: Argument Payload + + +.in 6 +o Payload Length (2 bytes) - Length of the Argument Data + field not including the length of any other field in the + payload. + +o Argument Type (1 byte) - Indicates the type of the argument. + Every argument can have a specific type that MUST be defined + by the packet payload needing the argument. For example + every command specify a number for each argument that may be + associated with the command. By using this number the receiver + of the packet knows what type of argument this is. If there is + no specific argument type this field is set to zero (0) value. + +o Argument Data (variable length) - Argument data. +.in 3 + + +.ti 0 +2.3.2.3 Channel Payload + +Generic Channel Payload may be used to send information about a channel, +its name, the Channel ID and a mode. + +The following diagram represents the Channel Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Channel Name Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Channel Name ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Channel ID Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Channel ID ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Mode Mask | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 5: New Channel Payload + + +.in 6 +o Channel Name Length (2 bytes) - Length of the channel name + field. + +o Channel Name (variable length) - The name of the channel. + +o Channel ID Length (2 bytes) - Length of the Channel ID field. + +o Channel ID (variable length) - The Channel ID. + +o Mode Mask (4 bytes) - A mode. This can be the mode of the + channel but it can also be the mode of a client on the + channel. The contents of this field is dependent of the + usage of this payload. The usage is defined separately + when this payload is used. This is a 32 bit MSB first value. +.in 3 + + +.ti 0 +2.3.2.4 Public Key Payload + +Generic Public Key Payload may be used to send different type of +public keys and certificates. + +The following diagram represents the Public Key Payload. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Public Key Length | Public Key Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Public Key (or certificate) ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 6: Public Key Payload + + +.in 6 +o Public Key Length (2 bytes) - The length of the Public Key + (or certificate) field, not including any other field. + +o Public Key Type (2 bytes) - The public key (or certificate) + type. This field indicates the type of the public key in + the packet. See the [SILC3] for defined public key types. + +o Public Key (or certificate) (variable length) - The + public key or certificate data. +.in 3 + + +.ti 0 +2.3.2.5 Message Payload + +Generic Message Payload can be used to send messages in SILC. It +is used to send channel messages and private messages. + +The following diagram represents the Message Payload. + +(*) indicates that the field is not encrypted. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Message Flags | Message Length | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Message Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Padding Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Padding ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Initial Vector * ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ MAC * ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 7: Message Payload + + +.in 6 +o Message Flags (2 bytes) - Includes the Message Flags of the + message. The flags can indicate a reason or a purpose for + the message. The following Message Flags are defined: + + 0x0000 SILC_MESSAGE_FLAG_NONE + + No specific flags set. + + 0x0001 SILC_MESSAGE_FLAG_AUTOREPLY + + This message is an automatic reply to an earlier + received message. + + 0x0002 SILC_MESSAGE_FLAG_NOREPLY + + There should not be reply messages to this + message. + + 0x0004 SILC_MESSAGE_FLAG_ACTION + + The sender is performing an action and the message + is the indication of the action. + + 0x0008 SILC_MESSAGE_FLAG_NOTICE + + The message is for example an informational notice + type message. + + 0x0010 SILC_MESSAGE_FLAG_REQUEST + + This is a generic request flag to send request + messages. A separate document should define any + payloads associated to this flag. + + 0x0020 SILC_MESSAGE_FLAG_SIGNED + + This flag indicates that the message is signed + with sender's private key and thus can be verified + by the receiver using the sender's public key. A + separate document should define the detailed procedure + of the signing process and any associated payloads + for this flag. + + 0x0040 SILC_MESSAGE_FLAG_REPLY + + This is a generic reply flag to send a reply to + previously received request. A separate document + should define any payloads associated to this flag. + + 0x0080 SILC_MESSAGE_FLAG_DATA + + This is a generic data flag, indicating that the + message includes some data which can be interpreted + in a specific way. Using this flag any kind of data + can be delivered inside message payload. A separate + document should define how this flag is interpreted + and define any associated payloads. + + 0x0100 SILC_MESSAGE_FLAG_UTF8 + + This flag indicates that the message is UTF-8 encoded + textual message. When sending text messages in SILC + this flag SHOULD be used. When this flag is used the + text sent as message MUST be UTF-8 encoded. + + 0x0200 - 0x0800 RESERVED + + Reserved for future flags. + + 0x1000 - 0x8000 PRIVATE RANGE + + Private range for free use. + +o Message Length (2 bytes) - Indicates the length of the + Message Data field in the payload, not including any + other field. + +o Message Data (variable length) - The actual message data. + +o Padding Length (2 bytes) - Indicates the length of the + Padding field in the payload, not including any other + field. + +o Padding (variable length) - If this payload is used as + channel messages, the padding MUST be applied because + this payload is encrypted separately from other parts + of the packet. If this payload is used as private + messages, the padding is present only when the payload + is encrypted with private message key. If encrypted + with session keys this field MUST NOT be present and the + Padding Length field includes a zero (0) value. The + padding SHOULD be random data. + +o Initial Vector (variable length) - This field MUST be + present when this payload is used as channel messages. + The IV SHOULD be random data for each channel message. + + When encrypting private messages with session keys this + field MUST NOT be present. For private messages this + field is present only when encrypting with a static + private message key (pre-shared key). If randomly + generated key material is used this field MUST NOT be + present. Also, If Key Agreement (SKE) was used to + negotiate fresh key material for private message key + this field MUST NOT be present. See the section 4.6 + in [SILC1] for more information about IVs when + encrypting private messages. + + This field includes the initial vector used in message + encryption. It need to be used in the packet decryption + as well. Contents of this field depends on the encryption + algorithm and encryption mode. This field is not encrypted, + is not included in padding calculation and its length + equals to cipher's block size. This field is authenticated + by the message MAC. + +o MAC (variable length) - The MAC computed from the + Message Flags, Message Length, Message Data, Padding Length, + Padding and Initial Vector fields in that order. The MAC + is computed after the payload is encrypted. This is so + called Encrypt-Then-MAC order; first encrypt, then compute + MAC from ciphertext. The MAC protects the integrity of + the Message Payload. Also, when used as channel messages + it is possible to have multiple private channel keys set, + and receiver can use the MAC to verify which of the keys + must be used in decryption. This field is not encrypted. +.in 3 + + +.ti 0 +2.3.3 Disconnect Payload + +Disconnect payload is sent upon disconnection. Reason of the +disconnection is sent to the disconnected party in the payload. + +The payload may only be sent with SILC_PACKET_DISCONNECT packet. It +MUST NOT be sent in any other packet type. The following diagram +represents the Disconnect Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Status | | ++-+-+-+-+-+-+-+-+ + +| | +~ Disconnect Message ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 8: Disconnect Payload + +.in 6 +o Status (1 byte) - Indicates the Status Type, defined in [SILC3] + for the reason of disconnection. + +o Disconnect Message (variable length) - Human readable UTF-8 + encoded string indicating reason of the disconnection. This + field MAY be omitted. +.in 3 + + +.ti 0 +2.3.4 Success Payload + +Success payload is sent when some protocol execution is successfully +completed. The payload is simple; indication of the success is sent. +This may be any data, including binary or human readable data, and +it is protocol dependent. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Success Indication ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 9: Success Payload + + +.in 6 +o Success Indication (variable length) - Indication of + the success. This may be for example some flag that + indicates the protocol and the success status or human + readable success message. The true length of this + payload is available by calculating it from the SILC + Packet Header. +.in 3 + + + +.ti 0 +2.3.5 Failure Payload + +This is opposite of Success Payload. Indication of failure of +some protocol is sent in the payload. + + + + + + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Failure Indication ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 10: Failure Payload + + +.in 6 +o Failure Indication (variable length) - Indication of + the failure. This may be for example some flag that + indicates the protocol and the failure status or human + readable failure message. The true length of this + payload is available by calculating it from the SILC + Packet Header. +.in 3 + + +.ti 0 +2.3.6 Reject Payload + +This payload is sent when some protocol is rejected to be executed. +Other operations MAY send this as well that was rejected. The +indication of the rejection is sent in the payload. The indication +may be binary or human readable data and is protocol dependent. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Reject Indication ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 11: Reject Payload + + +.in 6 +o Reject Indication (variable length) - Indication of + the rejection. This maybe for example some flag that + indicates the protocol and the rejection status or human + readable rejection message. The true length of this + payload is available by calculating it from the SILC + Packet Header. +.in 3 + + + + +.ti 0 +2.3.7 Notify Payload + +Notify payload is used to send notify messages. The payload is usually +sent from server to client and from server to router. It is also used +by routers to notify other routers in the network. This payload MAY also +be sent to a channel. Client MUST NOT send this payload. If client +receives this payload it MAY ignore the contents of the payload, however, +notify message SHOULD be audited. Servers and routers MUST process +notify packets. + +The payload may only be sent with SILC_PACKET_NOTIFY packet. It MUST +not be sent in any other packet type. The following diagram represents +the Notify Payload. + + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Notify Type | Payload Length | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Argument Nums | ++-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 12: Notify Payload + + +.in 6 +o Notify Type (2 bytes) - Indicates the type of the notify + message. + +o Payload Length (2 bytes) - Length of the entire Notify Payload + including any associated Argument Payloads. + +o Argument Nums (1 byte) - Indicates the number of Argument + Payloads associated to this payload. Notify types may define + arguments to be send along the notify message. +.in 3 + +The following list of currently defined notify types. The format for +notify arguments is same as in SILC commands described in [SILC4]. +Note that all IDs sent in arguments are sent inside ID Payload. Also +note that all passphrases that may be sent inside arguments MUST be +UTF-8 [RFC2279] encoded. Also note that all public keys or certificates +sent inside arguments are actually Public Key Payloads. + + +.in 6 +0 SILC_NOTIFY_TYPE_NONE + + If no specific notify type apply for the notify message this type + MAY be used. + + Max Arguments: 1 + Arguments: (1) + + The is implementation specific free UTF-8 text string. + Receiver MAY ignore this message. + + +1 SILC_NOTIFY_TYPE_INVITE + + Sent when an client is invited to a channel. This is also sent + when the invite list of the channel is changed. This notify type + is sent between routers and if an client was invited, to the + client as well. In this case the packet is destined to the client. + + Max Arguments: 5 + Arguments: (1) (2) + (3) [] (4) [] + (5) [] + + The is the channel. The is the name + of the channel and is provided because the client which receives + this notify packet may not have a way to resolve the name of the + channel from the . The is the + Client ID which invited the client to the channel. The + 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 , if present, indicates the information to be + added to or removed from the invite list. The + format is defined in [SILC4] with SILC_COMMAND_INVITE command. + When this notify is destined to a client the and + MUST NOT be sent. + + +2 SILC_NOTIFY_TYPE_JOIN + + Sent when client has joined to a channel. The server MUST + distribute this type to the local clients on the channel and then + send it to its primary router. The router or server receiving the + packet distributes this type to the local clients on the channel + and broadcast it to the network. + + Max Arguments: 2 + Arguments: (1) [] (2) + + The is the client that joined to the channel indicated + by the . + + +3 SILC_NOTIFY_TYPE_LEAVE + + Sent when client has left a channel. The server must distribute + this type to the local clients on the channel and then send it + to its primary router. The router or server receiving the + packet distributes this type to the local clients on the channel + and broadcast it to the network. + + Max Arguments: 1 + Arguments: (1) + + The is the client which left the channel. + + +4 SILC_NOTIFY_TYPE_SIGNOFF + + Sent when client signoff from SILC network. The server MUST + distribute this type to the local clients on the channel and then + send it to its primary router. The router or server receiving + the packet distributes this type to the local clients on the + channel and broadcast it to the network. + + Max Arguments: 2 + Arguments: (1) (2) + + The is the client which left SILC network. The + is free text string indicating the reason of the signoff. + + +5 SILC_NOTIFY_TYPE_TOPIC_SET + + Sent when topic is set/changed on a channel. This type must be + sent only to the clients which are joined on the channel which + topic was set or changed. + + Max Arguments: 2 + Arguments: (1) (2) + + The is the ID of the entity who set the topic. It + usually is Client ID but it can be Server ID and Channel ID as well. + + +6 SILC_NOTIFY_TYPE_NICK_CHANGE + + Sent when client changes nick on a channel. The server MUST + distribute this type only to the local clients on the channel + and then send it to its primary router. The router or server + receiving the packet distributes this type to the local clients + on the channel and broadcast it to the network. + + Max Arguments: 3 + Arguments: (1) (2) + (3) + + The is the old ID of the client which changed + the nickname. The is the new ID generated by + the change of the nickname. The is the new nickname. + Note that it is possible to send this notify even if the nickname + has not changed, but client ID was changed. + + +7 SILC_NOTIFY_TYPE_CMODE_CHANGE + + Sent when channel mode has changed. This type MUST be sent only + to the clients which are joined on the channel which mode was + changed. + + Max Arguments: 6 + Arguments: (1) (2) + (3) [] (4) <[hmac>] + (5) [] (6) [] + + The is the ID (usually Client ID but it can be + Server ID as well when the router is enforcing channel mode + change) of the entity which changed the mode. The + is the new mode mask of the channel. The client can safely + ignore the argument since the SILC_PACKET_CHANNEL_KEY + packet will force the new channel key change anyway. The + argument is important since the client is responsible of setting + the new HMAC and the hmac key into use. The is + the passphrase of the channel, if it was now set. The argument is sent when the founder mode on the + channel was set. All routers and servers that receive the packet + MUST save the founder's public key so that the founder can + reclaim the channel founder rights back for the channel on any + server in the network. + + +8 SILC_NOTIFY_TYPE_CUMODE_CHANGE + + Sent when user mode on channel has changed. This type MUST be + sent only to the clients which are joined on the channel where + the target client is on. + + Max Arguments: 4 + Arguments: (1) (2) + (3) (4) [] + + The is the ID (usually Client ID but it can be + Server ID as well when the router is enforcing user's mode + change) of the entity which changed the mode. The + is the new mode mask of the channel. The + is the client which mode was changed. The + is the public key of the channel founder and is sent only + when first setting the channel founder mode using the + SILC_COMMAND_CUMODE command, and when sending this notify. + + +9 SILC_NOTIFY_TYPE_MOTD + + Sent when Message of the Day (motd) is sent to a client. + + Max Arguments: 1 + Arguments: (1) + + The is the Message of the Day. This notify MAY be + ignored. + + +10 SILC_NOTIFY_TYPE_CHANNEL_CHANGE + + Sent when channel's ID has changed for a reason or another. + This is sent by normal server to the client. This can also be + sent by router to other server to force the Channel ID change. + The Channel ID MUST be changed to use the new one. When sent + to clients, this type MUST be sent only to the clients which is + joined on the channel. + + Max Arguments: 2 + Arguments: (1) (2) + + The is the channel's old ID and the is the new one that MUST replace the old one. + Server which receives this from router MUST re-announce the + channel to the router by sending SILC_PACKET_NEW_CHANNEL packet + with the new Channel ID. + + +11 SILC_NOTIFY_TYPE_SERVER_SIGNOFF + + Sent when server quits SILC network. Those clients from this + server that are on channels must be removed from the channel. + + Max Arguments: 256 + Arguments: (1) (n) [] [...] + + The is the server's ID. The rest of the arguments + are the Client IDs of the clients which are coming from this + server and are thus quitting the SILC network also. If the + maximum number of arguments are reached another + SILC_NOTIFY_TYPE_SERVER_SIGNOFF notify packet MUST be sent. + When this notify packet is sent between routers the Client ID's + MAY be omitted. Server receiving the Client ID's in the payload + may use them directly to remove the client. + + +12 SILC_NOTIFY_TYPE_KICKED + + Sent when a client has been kicked from a channel. This is + sent also to the client which was kicked from the channel. + The client which was kicked from the channel MUST be removed + from the channel. The client MUST also be removed from channel's + invite list if it is explicitly added in the list. This notify + type is always destined to the channel. The router or server + receiving the packet distributes this type to the local clients + on the channel and broadcast it to the network. + + Max Arguments: 3 + Arguments: (1) (2) [] + (3) + + The is the client which was kicked from the channel. + The kicker may have set the to indicate the reason for + the kicking. The is the kicker. + + +13 SILC_NOTIFY_TYPE_KILLED + + Sent when a client has been killed from the network. This is sent + also to the client which was killed from the network. The client + which was killed from the network MUST be removed from the network. + This notify type is destined directly to the client which was + killed and to channel if the client is on any channel. The router + or server receiving the packet distributes this type to the local + clients on the channel and broadcast it to the network. The client + MUST also be removed from joined channels invite list if it is + explicitly added in the lists. + + Max Arguments: 3 + Arguments: (1) (2) [] + (3) + + The is the client which was killed from the network. + The killer may have set the to indicate the reason for + the killing. The is the killer, which may be + client but also router server. + + +14 SILC_NOTIFY_TYPE_UMODE_CHANGE + + Sent when user's mode in the SILC changes. This type is sent + only between routers as broadcast packet. + + Max Arguments: 2 + Arguments: (1) (2) + + The is the client which mode was changed. The + is the new mode mask. + + +15 SILC_NOTIFY_TYPE_BAN + + Sent when the ban list of the channel is changed. This type is + sent only between routers as broadcast packet. + + Max Arguments: 3 + Arguments: (1) (2) [] + (3) [] + + The is the channel which ban list was changed. + The 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 indicates the information to be + added to or removed from the ban list. The format + format is defined in [SILC4] with SILC_COMMAND_BAN command. + + +16 SILC_NOTIFY_TYPE_ERROR + + Sent when an error occurs during processing some SILC procedure. + This is not used when error occurs during command processing, see + [SILC4] for more information about commands and command replies. + This type is sent directly to the sender of the packet whose packet + caused the error. See [SILC1] for definition when this type + can be sent. + + Max Arguments: 256 + Arguments: (1) (n) [...] + + The is the error type defined in [SILC4]. Note that + same types are also used with command replies to indicate the + status of a command. Both commands and this notify type share + same status types. Rest of the arguments are status type + dependent and are specified with those status types that can be + sent currently inside this notify type in [SILC4]. The is size of 1 byte. + + +17 SILC_NOTIFY_TYPE_WATCH + + Sent to indicate change in a watched user. Client can set + nicknames to be watched with SILC_COMMAND_WATCH command, and + receive notifications when they login to network, signoff from + the network or their user mode is changed. This notify type + is used to deliver these notifications. The notify type is + sent directly to the watching client. + + Max Arguments: 4 + Arguments: (1) (2) [] + (3) (4) [] + + The is the user's Client ID which is being watched, + and the is its nickname. If the client just + changed the nickname, then is the new nickname, but + the is the old client ID. The is the + user's current user mode. The can be same as the + Notify Payload's Notify Type, and is 16 bit MSB first order value. + If provided it may indicate the notify that occurred for the + client. If client logged in to the network the + MUST NOT be present. +.in 3 + +Notify types starting from 16384 are reserved for private notify +message types. + +Router server which receives SILC_NOTIFY_TYPE_SIGNOFF, +SILC_NOTIFY_TYPE_SERVER_SIGNOFF, SILC_NOTIFY_TYPE_KILLED, +SILC_NOTIFY_TYPE_NICK_CHANGE and SILC_NOTIFY_TYPE_UMODE_CHANGE +MUST check whether someone in the local cell is watching the nickname +the client has, and send the SILC_NOTIFY_TYPE_WATCH notify to the +watcher, unless the client in case has the SILC_UMODE_REJECT_WATCHING +user mode set. If the watcher client and the client that was +watched is same the notify SHOULD NOT be sent. + + +.ti 0 +2.3.8 Error Payload + +Error payload is sent upon error in protocol. Error may occur in +various conditions when server sends this packet. Client MUST NOT +send this payload but MUST be able to accept it. However, client +MAY totally ignore the contents of the packet as server is going to +take action on the error anyway. However, it is recommended +that the client takes error packet seriously. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Error Message ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 13: Error Payload + + +.in 6 +o Error Message (variable length) - Human readable error + message as UTF-8 string. +.in 3 + + +.ti 0 +2.3.9 Channel Message Payload + +Channel Message Payload is used to send message to channels, a group +of users. These messages can only be sent if client has joined to +some channel. Even though this packet is very common in SILC it +is still special packet. Some special handling on sending and +reception of channel message is required. + +Padding MUST be applied into this payload since the payload is +encrypted separately from other parts of the packet with the +channel specific key. Hence the requirement of the padding. +The packet MUST be made multiple by eight (8) or by the block +size of the cipher, which ever is larger. + +The SILC header in this packet is encrypted with the session key +of the next receiver of the packet. Nothing else is encrypted +with that key. Thus, the actual packet and padding to be +encrypted with the session key is SILC Header plus padding to it +to make it multiple by eight (8) or multiple by the block size +of the cipher, which ever is larger. + +Receiver of the the channel message packet is able to determine +the channel the message is destined to by checking the destination +ID from the SILC Packet header which tells the destination channel. +The original sender of the packet is also determined by checking +the source ID from the header which tells the client which sent +the message. + +This packet use generic Message Payload as Channel Message Payload. +See section 2.3.2.5 for generic Message Payload. + + +.ti 0 +2.3.10 Channel Key Payload + +All traffic in channels are protected by channel specific keys. +Channel Key Payload is used to distribute channel keys to all +clients on the particular channel. Channel keys are sent when +the channel is created, when new user joins to the channel and +whenever a user has left a channel. Server creates the new +channel key and distributes it to the clients by encrypting this +payload with the session key shared between the server and +the client. After that, client starts using the key received +in this payload to protect the traffic on the channel. + +The client which is joining to the channel receives its key in the +SILC_COMMAND_JOIN command reply message thus it is not necessary to +send this payload to the entity which sent the SILC_COMMAND_JOIN +command. + +Channel keys are cell specific thus every router in the cell have +to create a channel key and distribute it if any client in the +cell has joined to a channel. Channel traffic between cell's +are not encrypted using channel keys, they are encrypted using +normal session keys between two routers. Inside a cell, all +channel traffic is encrypted with the specified channel key. +Channel key SHOULD expire periodically, say, in one hour, in +which case new channel key is created and distributed. + +The payload may only be sent with SILC_PACKET_CHANNEL_KEY packet. +It MUST NOT be sent in any other packet type. The following diagram +represents the Channel Key Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Channel ID Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Channel ID ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Cipher Name Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Cipher Name ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Channel Key Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Channel Key ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 14: Channel Key Payload + + + +.in 6 +o Channel ID Length (2 bytes) - Indicates the length of the + Channel ID field in the payload, not including any other + field. + +o Channel ID (variable length) - The Channel ID of the + channel this key is meant for. + +o Cipher Name Length (2 bytes) - Indicates the length of the + Cipher name field in the payload, not including any other + field. + +o Cipher Name (variable length) - Name of the cipher used + in the protection of channel traffic. This name is + initially decided by the creator of the channel but it + MAY change during the life time of the channel as well. + +o Channel Key Length (2 bytes) - Indicates the length of the + Channel Key field in the payload, not including any other + field. + +o Channel Key (variable length) - The actual channel key + material. +.in 3 + + +.ti 0 +2.3.11 Private Message Payload + +Private Message Payload is used to send private message between +two clients. The messages are sent only to the specified user +and no other user inside SILC network is able to see the message. + +The message can be protected by the session key established by the +SILC Key Exchange Protocol. However, it is also possible to agree +to use a private key to protect just the private messages. It is +for example possible to perform Key Agreement between two clients. +See section 2.3.20 Key Agreement Payload how to perform key +agreement. See also section 2.3.12 Private Message Key Payload +for another way of using private keys with private messages. See +[SILC1] section 4.6 for detailed description for private message +key generation procedure. + +If normal session key is used to protect the message, every server +between the sender client and the receiving client MUST decrypt the +packet and always re-encrypt it with the session key of the next +receiver of the packet. See section Client To Client in [SILC1]. + +When private key is used to protect the message, servers between +the sender and the receiver needs not to decrypt/re-encrypt the +packet. Section Client To Client in [SILC1] gives example of this +scheme as well. + +This packet use generic Message Payload as Private Message Payload. +See section 2.3.2.5 for generic Message Payload. + + +.ti 0 +2.3.12 Private Message Key Payload + +This payload is OPTIONAL and can be used to send private message +key between two clients in the network. The packet is secured with +normal session keys. By default private messages are encrypted +with session keys, and with this payload it is possible to set +private key for private message encryption between two clients. + +The receiver of this payload SHOULD verify for example from user +whether user want to receive private message key. Note that there +are other, more secure ways of exchanging private message keys in +the SILC network. Instead of sending this payload it is possible to +negotiate the private message key with SKE protocol using the Key +Agreement payload directly peer to peer, see section 2.3.20. + +This payload may only be sent by client to another client. Server +MUST NOT send this payload at any time. After sending this payload +the sender of private messages must set the Private Message Key +flag into SILC Packet Header. + +The payload may only be sent with SILC_PACKET_PRIVATE_MESSAGE_KEY +packet. It MUST NOT be sent in any other packet type. The following +diagram represents the Private Message Key Payload. + + + + + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Private Message Key Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Private Message Key ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Cipher Name Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Cipher Name ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| HMAC Name Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ HMAC Name ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 15: Private Message Key Payload + + + +.in 6 +o Private Message Key Length (2 bytes) - Indicates the length + of the Private Message Key field in the payload, not including + any other field. + +o Private Message Key (variable length) - The actual private + message key material. + +o Cipher Name Length (2 bytes) - Indicates the length of the + Cipher Name field in the payload, not including any other + field. + +o Cipher Name (variable length) - Name of the cipher to use + in the private message encryption. If this field does not + exist then the default cipher of the SILC protocol is used. + See the [SILC1] for defined ciphers. + +o HMAC Name Length (2 bytes) - Indicates the length of the + HMAC Name field in the payload, not including any other + field. + +o HMAC Name (variable length) - Name of the HMAC to use + in the private message MAC computation. If this field does + not exist then the default HMAC of the SILC protocol is used. + See the [SILC1] for defined HMACs. +.in 3 + + +.ti 0 +2.3.13 Command Payload + +Command Payload is used to send SILC commands from client to server. +Also server MAY send commands to other servers. The following diagram +represents the Command Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload Length | SILC Command | Arguments Num | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Command Identifier | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 16: Command Payload + + +.in 6 +o Payload Length (2 bytes) - Length of the entire command + payload including any command argument payloads associated + with this payload. + +o SILC Command (1 byte) - Indicates the SILC command. This MUST + be set to non-zero value. If zero (0) value is found in this + field the packet MUST be discarded. + +o Arguments Num (1 byte) - Indicates the number of arguments + associated with the command. If there are no arguments this + field is set to zero (0). The arguments MUST follow the + command payload. See section 2.3.2.2 for definition of the + Argument Payload. + +o Command Identifier (2 bytes) - Identifies this command at the + sender's end. The entity which replies to this command MUST + set the value found from this field into the Command Payload + used to send the reply to the sender. This way the sender + can identify which command reply belongs to which originally + sent command. What this field includes is implementation + issue but it is RECOMMENDED that wrapping counter value is + used in the field. Value zero (0) in this field means that + no specific value is set. +.in 3 + +See [SILC4] for detailed description of different SILC commands, +their arguments and their reply messages. + + + +.ti 0 +2.3.14 Command Reply Payload + +Command Reply Payload is used to send replies to the commands. The +Command Reply Payload is identical to the Command Payload thus see +the 2.3.13 section for the payload specification. + +The entity which sends the reply packet MUST set the Command Identifier +field in the reply packet's Command Payload to the value it received +in the original command packet. + +See SILC Commands in [SILC4] for detailed description of different +SILC commands, their arguments and their reply messages. + + +.ti 0 +2.3.15 Connection Auth Request Payload + +Client MAY send this payload to server to request the authentication +method that must be used in authentication protocol. If client knows +this information beforehand this payload is not necessary to be sent. +Server performing authentication with another server MAY also send +this payload to request the authentication method. If the connecting +server already knows this information this payload is not necessary +to be sent. + +Server receiving this request SHOULD reply with same payload sending +the mandatory authentication method. Algorithms that may be required +to be used by the authentication method are the ones already +established by the SILC Key Exchange protocol. See section Key +Exchange Start Payload in [SILC3] for detailed information. + +The payload may only be sent with SILC_PACKET_CONNECTION_AUTH_REQUEST +packet. It MUST NOT be sent in any other packet type. The following +diagram represents the Connection Auth Request Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Connection Type | Authentication Method | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 17: Connection Auth Request Payload + + +.in 6 +o Connection Type (2 bytes) - Indicates the type of the + connection. The following connection types are defined: + + + 1 Client connection + 2 Server connection + 3 Router connection + + If any other type is found in this field the packet MUST be + discarded and the authentication MUST be failed. + +o Authentication Method (2 bytes) - Indicates the authentication + method to be used in the authentication protocol. The following + authentication methods are defined: + + 0 NONE (mandatory) + 1 password (mandatory) + 2 public key (mandatory) + + If any other type is found in this field the packet MUST be + discarded and the authentication MUST be failed. If this + payload is sent as request to receive the mandatory + authentication method this field MUST be set to zero (0), + indicating that receiver should send the mandatory + authentication method. The receiver sending this payload + to the requesting party, MAY also set this field to zero (0) + to indicate that authentication is not required. In this + case authentication protocol still MUST be started but + server is most likely to respond with SILC_PACKET_SUCCESS + immediately. +.in 3 + + + + +.ti 0 +2.3.16 New ID Payload + +New ID Payload is a multipurpose payload. It is used to send newly +created ID's from clients and servers. When client connects to server +and registers itself to the server by sending SILC_PACKET_NEW_CLIENT +packet, server replies with this packet by sending the created ID for +the client. Server always creates the ID for the client. + +This payload is also used when server tells its router that new client +has registered to the SILC network. In this case the server sends +the Client ID of the client to the router. Similarly when router +distributes information to other routers about the client in the SILC +network this payload is used. + +Also, when server connects to router, router use this payload to inform +other routers about new server in the SILC network. However, every +server (or router) creates their own ID's thus the ID distributed by +this payload is not created by the distributor in this case. Servers +create their own ID's. Server registers itself to the network by +sending SILC_PACKET_NEW_SERVER to the router it connected to. The case +is same when router connects to another router. + +However, this payload MUST NOT be used to send information about new +channels. New channels are always distributed by sending the dedicated +SILC_PACKET_NEW_CHANNEL packet. Client MUST NOT send this payload. +Both client and server (and router) MAY receive this payload. + +The packet use generic ID Payload as New ID Payload. See section +2.3.2.1 for generic ID Payload. + + +.ti 0 +2.3.17 New Client Payload + +When client is connected to the server, keys has been exchanged and +connection has been authenticated, client MUST register itself to the +server. Client's first packet after key exchange and authentication +protocols must be SILC_PACKET_NEW_CLIENT. This payload tells server all +the relevant information about the connected user. Server creates a new +client ID for the client when received this payload and sends it to the +client in New ID Payload. + +This payload sends username and real name of the user on the remote host +which is connected to the SILC server with SILC client. The server +creates the client ID according the information sent in this payload. +The nickname of the user becomes the nickname sent in this payload. + +The payload may only be sent with SILC_PACKET_NEW_CLIENT packet. It +MUST NOT be sent in any other packet type. The following diagram +represents the New Client Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Username Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Username ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Real Name Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Real Name ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 18: New Client Payload + + +.in 6 +o Username Length (2 bytes) - Length of the Username field. + +o Username (variable length) - The username of the user on + the host where connecting to the SILC server. + +o Real Name Length (2 bytes) - Length of the Real Name field. + +o Real Name (variable length) - The real name of the user + on the host where connecting to the SILC server. +.in 3 + + +.ti 0 +2.3.18 New Server Payload + +This payload is sent by server when it has completed successfully both +key exchange and connection authentication protocols. The server +MUST register itself to the SILC Network by sending this payload. +The first packet after these key exchange and authentication protocols +is SILC_PACKET_NEW_SERVER packet. The payload includes the Server ID +of the server that it has created by itself. It also includes a +name of the server that is associated to the Server ID. + +The payload may only be sent with SILC_PACKET_NEW_SERVER packet. It +MUST NOT be sent in any other packet type. The following diagram +represents the New Server Payload. + + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Server ID Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Server ID Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Server Name Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Server Name ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 19: New Server Payload + + +.in 6 +o Server ID Length (2 bytes) - Length of the Server ID Data + field. + +o Server ID Data (variable length) - The actual Server ID + data. + +o Server Name Length (2 bytes) - Length of the server name + field. + +o Server Name (variable length) - The server name. +.in 3 + + +.ti 0 +2.3.19 New Channel Payload + +Information about newly created channel is broadcasted to all routers +in the SILC network by sending this packet payload. Channels are +created by router of the cell. Server never creates channels unless +it is a standalone server and it does not have router connection, +in this case server acts as router. Normal server send JOIN command +to the router (after it has received JOIN command from client) which +then processes the command and creates the channel. Client MUST NOT +send this packet. Server MAY send this packet to a router when it is +announcing its existing channels to the router after it has connected +to the router. + +The packet use generic Channel Payload as New Channel Payload. See +section 2.3.2.3 for generic Channel Payload. The Mode Mask field in the +Channel Payload is the mode of the channel. + + +.ti 0 +2.3.20 Key Agreement Payload + +This payload is used by clients to request key negotiation between +another client in the SILC Network. The key agreement protocol used +is the SKE protocol. The result of the protocol, the secret key +material, can be used for example as private message key between the +two clients. This significantly adds security as the key agreement +is performed outside the SILC network. The server and router MUST NOT +send this payload. + +The sender MAY tell the receiver of this payload the hostname and the +port where the SKE protocol is running in the sender's end. The +receiver MAY then initiate the SKE negotiation with the sender. The +sender MAY also optionally not to include the hostname and the port +of its SKE protocol. In this case the receiver MAY reply to the +request by sending the same payload filled with the receiver's hostname +and the port where the SKE protocol is running. The sender MAY then +initiate the SKE negotiation with the receiver. + +This payload may be sent with SILC_PACKET_KEY_AGREEMENT and +SILC_PACKET_FTP packet types. It MUST NOT be sent in any other packet +types. The following diagram represents the Key Agreement Payload. + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Hostname Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Hostname ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Port | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 20: Key Agreement Payload + + +.in 6 +o Hostname Length (2 bytes) - Indicates the length of the + Hostname field. + +o Hostname (variable length) - The hostname or IP address where + the SKE protocol is running. The sender MAY fill this field + when sending the payload. If the receiver sends this payload + as reply to the request it MUST fill this field. + +o Port (4 bytes) - The port where the SKE protocol is bound. + The sender MAY fill this field when sending the payload. If + the receiver sends this payload as reply to the request it + MUST fill this field. This is a 32 bit MSB first order value. +.in 3 + + +After the key material has been received from the SKE protocol it is +processed as the [SILC3] describes. If the key material is used as +channel private key then the Sending Encryption Key, as defined in +[SILC3] is used as the channel private key. Other key material must +be discarded. The [SILC1] in section 4.6 defines the way to use the +key material if it is intended to be used as private message keys. +Any other use for the key material is undefined. + + +.ti 0 +2.3.21 Resume Router Payload + +See the [SILC1] for Resume Router protocol where this payload is +used. The payload may only be sent with SILC_PACKET_RESUME_ROUTER +packet. It MUST NOT be sent in any other packet type. The following +diagram represents the Resume Router Payload. + + +.in 21 +.nf + 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Type | Session ID | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 21: Resume Router Payload + + +.in 6 +o Type (1 byte) - Indicates the type of the backup resume + protocol packet. The type values are defined in [SILC1]. + +o Session ID (1 bytes) - Indicates the session ID for the + backup resume protocol. The sender of the packet sets this + value and the receiver MUST set the same value in subsequent + reply packet. +.in 3 + + +.ti 0 +2.3.22 File Transfer Payload + +File Transfer Payload is used to perform file transfer protocol +between two entities in the network. The actual file transfer +protocol is always encapsulated inside the SILC Packet. The actual +data stream is also sent peer to peer outside SILC network. + +When an entity, usually a client wishes to perform file transfer +protocol with another client in the network, they perform Key Agreement +protocol as described in the section 2.3.20 Key Agreement Payload and +in [SILC3], inside File Transfer Payload. After the Key Agreement +protocol has been performed the subsequent packets in the data stream +will be protected using the new key material. The actual file transfer +protocol is also initialized in this stage. All file transfer protocol +packets are always encapsulated in the File Transfer Payload and +protected with the negotiated key material. + +The payload may only be sent with SILC_PACKET_FTP packet. It MUST NOT +be sent in any other packet type. The following diagram represents the +File Transfer Payload. + + + + + + + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Type | | ++-+-+-+-+-+-+-+-+ + +| | +~ Data ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 22: File Transfer Payload + + +.in 6 +o Type (1 byte) - Indicates the type of the file transfer + protocol. The following file transfer protocols has been + defined: + + 1 Secure File Transfer Protocol (SFTP) (mandatory) + + If zero (0) value or any unsupported file transfer protocol + type is found in this field the packet must be discarded. + The currently mandatory file transfer protocol is SFTP. + The SFTP protocol is defined in [SFTP]. + +o Data (variable length) - Arbitrary file transfer data. The + contents and encoding of this field is dependent of the usage + of this payload and the type of the file transfer protocol. + When this payload is used to perform the Key Agreement + protocol, this field include the Key Agreement Payload, + as defined in the section 2.3.20 Key Agreement Payload. + When this payload is used to send the actual file transfer + protocol data, the encoding is defined in the corresponding + file transfer protocol. +.in 3 + + +.ti 0 +2.3.23 Resume Client Payload + +This payload is used by client to resume its detached session in the +SILC Network. A client is able to detach itself from the network by +sending SILC_COMMAND_DETACH command to its server. The network +connection to the client is lost but the client remains as valid +client in the network. The client is able to resume the session back +by sending this packet and including the old Client ID, and an +Authentication Payload [SILC1] which the server use to verify with +the detached client's public key. This also implies that the +mandatory authentication method is public key authentication. + +Server or router that receives this from the client also sends this, +without the Authentication Payload, to routers in the network so that +they know the detached client has resumed. Refer to the [SILC1] for +detailed description how the detaching and resuming procedure is +performed. + +The payload may only be sent with SILC_PACKET_RESUME CLIENT packet. It +MUST NOT be sent in any other packet type. The following diagram +represents the Resume Client Payload. + +.in 5 +.nf + 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Client ID Length | | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +| | +~ Client ID ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| | +~ Authentication Payload ~ +| | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in 3 + +.ce +Figure 23: Resume Client Payload + + +.in 6 +o Client ID Length (1 byte) - The length of the Client ID + field not including any other field. + +o Client ID (variable length) - The detached client's Client + ID. The client that sends this payload must know the Client + ID. + +o Authentication Payload (variable length) - The authentication + payload that the server will verify with the detached client's + public key. If the server doesn't know the public key, it must + retrieve it for example with SILC_COMMAND_GETKEY command. +.in 3 + + + +.ti 0 +2.4 SILC ID Types + +ID's are used in the SILC network to associate different entities. +The following ID's has been defined to be used in the SILC network. + +.in 6 +0 No ID + + This is used when other ID type is available at the time. + +1 Server ID + + Server ID to associate servers. See the format of + this ID in [SILC1]. + +2 Client ID + + Client ID to associate clients. See the format of + this ID in [SILC1]. + +3 Channel ID + + Channel ID to associate channels. See the format of + this ID in [SILC1]. +.in 3 + +When encoding different IDs into the ID Payload, all fields are always +in MSB first order. The IP address, port, and/or the random number +are encoded in the MSB first order. + + +.ti 0 +2.5 Packet Encryption And Decryption + +SILC packets are encrypted almost entirely. Only the MAC at the end +of the packet is never encrypted. The SILC Packet header is the first +part of a packet to be encrypted and it is always encrypted with the +key of the next receiver of the packet. The data payload area of the +packet is always entirely encrypted and it is usually encrypted with +the next receiver's key. However, there are some special packet types +and packet payloads that require special encryption process. These +special cases are described in the next sections. First is described +the normal packet encryption process. + + +.ti 0 +2.5.1 Normal Packet Encryption And Decryption + +Normal SILC packets are encrypted with the session key of the next +receiver of the packet. The entire SILC Packet header and the packet +data payload is is encrypted with the same key. Padding of the packet +is also encrypted always with the session key, also in special cases. +Computed MAC of the packet MUST NOT be encrypted. + +Decryption process in these cases are straightforward. The receiver +of the packet MUST first decrypt the SILC Packet header, or some parts +of it, usually first 16 bytes of it. Then the receiver checks the +packet type from the decrypted part of the header and can determine +how the rest of the packet must be decrypted. If the packet type is +any of the special cases described in the following sections the packet +decryption is special. If the packet type is not among those special +packet types rest of the packet can be decrypted with the same key. + +With out a doubt, this sort of decryption processing causes some +overhead to packet decryption, but never the less, is required. + +The MAC of the packet is also verified at this point. The MAC is +computed from the ciphertext of the packet so it can be verified +at this stage. The length of the packet need to be known to be able +to verify the MAC from the ciphertext so the first 16 bytes need to +be decrypted to determine the packet length. However, the MAC MUST +be verified from the entire ciphertext. + + +.ti 0 +2.5.2 Channel Message Encryption And Decryption + +Channel Messages (Channel Message Payload) are always encrypted with +the channel specific key. However, the SILC Packet header is not +encrypted with that key. As in normal case, the header is encrypted +with the key of the next receiver of the packet, who ever that might +be. Note that in this case the encrypted data area is not touched +at all; it MUST NOT be re-encrypted with the session key. + +Receiver of a channel message, who ever that is, is REQUIRED to decrypt +the SILC Packet header to be able to recognize the packet to be as +channel message. This is same procedure as for normal SILC packets. +As the receiver founds the packet to be channel message, rest of the +packet processing is special. Rest of the SILC Packet header is +decrypted with the same session key along with the padding of the +packet. After that the packet is protected with the channel specific +key and thus can be decrypted only if the receiver is the client on +the channel. See section 2.7 Packet Padding Generation for more +information about padding on special packets. + +If the receiver of the channel message is router which is routing the +message to another router then it MUST decrypt the Channel Message +payload. Between routers (that is, between cells) channel messages +are protected with session keys shared between the routers. This +causes another special packet processing for channel messages. If +the channel message is received from another router then the entire +packet, including Channel Message payload, MUST be encrypted with the +session key shared between the routers. In this case the packet +decryption process is as with normal SILC packets. Hence, if the +router is sending channel message to another router the Channel +Message payload MUST have been decrypted and MUST be re-encrypted +with the session key shared between the another router. In this +case the packet encryption is as with any normal SILC packet. + +It must be noted that this is only when the channel messages are sent +from router to another router. In all other cases the channel +message encryption and decryption is as described above. This +different processing of channel messages with router to router +connection is because channel keys are cell specific. All cells have +their own channel keys thus the channel message traveling from one +cell to another MUST be protected as it would be any normal SILC +packet. + +If the SILC_CMODE_PRIVKEY channel mode has been set for the channel +then the router cannot decrypt the packet as it does not know the +private key. In this case the entire packet MUST be encrypted with +the session key and sent to the router. The router receiving the +packet MUST check the channel mode and decrypt the packet accordingly. + + +.ti 0 +2.5.3 Private Message Encryption And Decryption + +By default, private message in SILC are protected by session keys. +In this case the private message encryption and decryption process is +equivalent to normal packet encryption and decryption. + +However, private messages MAY be protected with private message key +which causes the packet to be special packet. The procedure in this +case is very much alike to channel packets. The actual private message +is encrypted with the private message key and other parts of the +packet is encrypted with the session key. See 2.7 Packet Padding +Generation for more information about padding on special packets. + +The difference from channel message processing is that server or router +en route never decrypts the actual private message, as it does not +have the key to do that. Thus, when sending packets between router +the processing is same as in any other case as well; the packet's header +and padding is protected by the session key and the data area is not +touched. + +The true receiver of the private message is able to decrypt the private +message as it shares the key with the sender of the message. + + +.ti 0 +2.6 Packet MAC Generation + +Data integrity of a packet is protected by including a message +authentication code (MAC) at the end of the packet. The MAC is computed +from shared secret MAC key, that is established by the SILC Key Exchange +protocol, from packet sequence number, and from the encrypted packet +data. The MAC is always computed after packet is encrypted. This is +so called Encrypt-Then-MAC order; packet is first encrypted, then MAC +is computed from the encrypted data. + +The MAC is computed from entire packet. Every bit of data in the packet, +including SILC Packet Header is used in the MAC computing. This way +the entire packet becomes authenticated. + +Hence, packet's MAC generation is as follows: + + mac = MAC(key, sequence number | Encrypted SILC packet) + +The MAC key is negotiated during the SKE protocol. The sequence number +is a 32 bit MSB first value starting from zero for first packet and +increasing for subsequent packets, finally wrapping after 2^32 packets. +The value is never reset, not even after rekey has been performed. +However, rekey MUST be performed before the sequence number wraps +and repeats from zero. Note that the sequence number is incremented only +when MAC is computed for a packet. If packet is not encrypted and MAC is +not computed then the sequence number is not incremented. Hence, the +sequence number is zero for the very first encrypted packet. + +See [SILC1] for defined and allowed MAC algorithms. + + +.ti 0 +2.7 Packet Padding Generation + +Padding is needed in the packet because the packet is encrypted. It +always MUST be multiple by eight (8) or multiple by the block size +of the cipher, which ever is larger. The padding is always encrypted. + +For normal packets the padding is added after the SILC Packet Header +and between the Data Payload area. The padding for normal packets +may be calculated as follows: + +.in 6 +padding_length = 16 - (packet_length mod block_size) +if (padding_length < 8) + padding_length += block_size +.in 3 + +The `block_size' is the block size of the cipher. The maximum padding +length is 128 bytes, and minimum is 8 bytes. For example, packets that +include a passphrase or a password for authentication purposes SHOULD +pad the packet up to the maximum padding length. The maximum padding +is calculated as follows: + +.in 6 +padding_length = 128 - (packet_length mod block_size) +.in 3 + +For special packets the padding calculation is different as special +packets may be encrypted differently. In these cases the encrypted +data area MUST already be multiple by the block size thus in this case +the padding is calculated only for SILC Packet Header, not for any +other area of the packet. The same algorithm works in this case as +well, except that the `packet length' is now the SILC Packet Header +length. + +The padding MUST be random data, preferably, generated by +cryptographically strong random number generator for each packet +separately. + + +.ti 0 +2.8 Packet Compression + +SILC Packets MAY be compressed. In this case the data payload area +is compressed and all other areas of the packet MUST remain as they +are. After compression is performed for the data area, the length +field of Packet Header MUST be set to the compressed length of the +data. + +The compression MUST always be applied before encryption. When +the packet is received and decrypted the data area MUST be decompressed. +Note that the true sender of the packet MUST apply the compression and +the true receiver of the packet MUST apply the decompression. Any +server or router en route SHOULD NOT decompress the packet. + + +.ti 0 +2.9 Packet Sending + +The sender of the packet MUST assemble the SILC Packet Header with +correct values. It MUST set the Source ID of the header as its own +ID, unless it is forwarding the packet. It MUST also set the Destination +ID of the header to the true destination. If the destination is client +it will be Client ID, if it is server it will be Server ID and if it is +channel it will be Channel ID. + +If the sender wants to compress the packet it MUST apply the +compression now. Sender MUST also compute the padding as described +in above sections. Then sender MUST encrypt the packet as has been +described in above sections according whether the packet is normal +packet or special packet. Then sender MUST compute the MAC of the +packet. The computed MAC MUST NOT be encrypted. + + +.ti 0 +2.10 Packet Reception + +On packet reception the receiver MUST check that all fields in the +SILC Packet Header are valid. It MUST check the flags of the +header and act accordingly. It MUST also check the MAC of the packet +and if it is to be failed the packet MUST be discarded. Also if the +header of the packet includes any bad fields the packet MUST be +discarded. + +See above sections on the decryption process of the received packet. + +The receiver MUST also check that the ID's in the header are valid +ID's. Unsupported ID types or malformed ID's MUST cause packet +rejection. The padding on the reception is always ignored. + +The receiver MUST also check the packet type and start parsing the +packet according to the type. However, note the above sections on +special packet types and their parsing. + + +.ti 0 +2.11 Packet Routing + +Routers are the primary entities in the SILC network that takes care +of packet routing. However, normal servers routes packets as well, for +example, when they are routing channel message to the local clients. +Routing is quite simple as every packet tells the true origin and the +true destination of the packet. + +It is still RECOMMENDED for routers that has several routing connections +to create route cache for those destinations that has faster route than +the router's primary route. This information is available for the router +when other router connects to the router. The connecting party then +sends all of its locally connected clients, servers and channels. These +informations helps to create the route cache. Also, when new channels +are created to a cell its information is broadcasted to all routers +in the network. Channel ID's are based on router's ID thus it is easy +to create route cache based on these informations. If faster route for +destination does not exist in router's route cache the packet MUST be +routed to the primary route (default route). + +However, there are some issues when routing channel messages to group +of users. Routers are responsible of routing the channel message to +other routers, local servers and local clients as well. Routers MUST +send the channel message to only one router in the network, preferably +to the shortest route to reach the channel users. The message can be +routed into either upstream or downstream. After the message is sent +to a router in the network it MUST NOT be sent to any other router in +either same route or other route. The message MUST NOT be routed to +the router it came from. + +When routing for example private messages they should be routed to the +shortest route always to reach the destination client as fast as possible. + +For server which receives a packet to be routed to its locally connected +client the server MUST check whether the particular packet type is +allowed to be routed to the client. Not all packets may be sent by +some odd entity to client that is indirectly connected to the sender. +See section 2.3 SILC Packet Types and paragraph about indirectly connected +entities and sending packets to them. The section mentions the packets +that may be sent to indirectly connected entities. It is clear that +server cannot send, for example, disconnect packet to client that is not +directly connected to the server. + +Routers form a ring in the SILC network. However, routers may have other +direct connections to other routers in the network too. This can cause +interesting routing problems in the network. Since the network is a ring, +the packets usually should be routed into clock-wise direction, or if it +cannot be used then always counter clock-wise (primary route) direction. +Problems may arise when a faster direct route exists and router is routing +a channel message. Currently channel messages must be routed either +in upstream or downstream, they cannot be routed to other direct routes. +The SILC protocol should have a shortest path discovery protocol, and some +existing routing protocol, that can handle a ring network with other +direct routes inside the ring (so called hybrid ring-mesh topology), +MAY be defined to be used with the SILC protocol. Additional +specifications MAY be written on the subject to permeate this +specification. + + +.ti 0 +2.12 Packet Broadcasting + +SILC packets MAY be broadcasted in SILC network. However, only router +server may send or receive broadcast packets. Client and normal server +MUST NOT send broadcast packets and they MUST ignore broadcast packets +if they receive them. Broadcast packets are sent by setting Broadcast +flag to the SILC packet header. + +Broadcasting packets means that the packet is sent to all routers in +the SILC network, except to the router that sent the packet. The router +receiving broadcast packet MUST send the packet to its primary route. +The fact that SILC routers may have several router connections can +cause problems, such as race conditions inside the SILC network, if +care is not taken when broadcasting packets. Router MUST NOT send +the broadcast packet to any other route except to its primary route. + +If the primary route of the router is the original sender of the packet +the packet MUST NOT be sent to the primary route. This may happen +if router has several router connections and some other router uses +the router as its primary route. + +Routers use broadcast packets to broadcast for example information +about newly registered clients, servers, channels etc. so that all the +routers may keep these informations up to date. + + +.ti 0 +3 Security Considerations + +Security is central to the design of this protocol, and these security +considerations permeate the specification. Common security considerations +such as keeping private keys truly private and using adequate lengths for +symmetric and asymmetric keys must be followed in order to maintain the +security of this protocol. + + +.ti 0 +4 References + +[SILC1] Riikonen, P., "Secure Internet Live Conferencing (SILC), + Protocol Specification", Internet Draft, May 2002. + +[SILC3] Riikonen, P., "SILC Key Exchange and Authentication + Protocols", Internet Draft, May 2002. + +[SILC4] Riikonen, P., "SILC Commands", Internet Draft, May 2002. + +[IRC] Oikarinen, J., and Reed D., "Internet Relay Chat Protocol", + RFC 1459, May 1993. + +[IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810, + April 2000. + +[IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC + 2811, April 2000. + +[IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC + 2812, April 2000. + +[IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC + 2813, April 2000. + +[SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", + Internet Draft. + +[PGP] Callas, J., et al, "OpenPGP Message Format", RFC 2440, + November 1998. + +[SPKI] Ellison C., et al, "SPKI Certificate Theory", RFC 2693, + September 1999. + +[PKIX-Part1] Housley, R., et al, "Internet X.509 Public Key + Infrastructure, Certificate and CRL Profile", RFC 2459, + January 1999. + +[Schneier] Schneier, B., "Applied Cryptography Second Edition", + John Wiley & Sons, New York, NY, 1996. + +[Menezes] Menezes, A., et al, "Handbook of Applied Cryptography", + CRC Press 1997. + +[OAKLEY] Orman, H., "The OAKLEY Key Determination Protocol", + RFC 2412, November 1998. + +[ISAKMP] Maughan D., et al, "Internet Security Association and + Key Management Protocol (ISAKMP)", RFC 2408, November + 1998. + +[IKE] Harkins D., and Carrel D., "The Internet Key Exchange + (IKE)", RFC 2409, November 1998. + +[HMAC] Krawczyk, H., "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + +[PKCS1] Kalinski, B., and Staddon, J., "PKCS #1 RSA Cryptography + Specifications, Version 2.0", RFC 2437, October 1998. + +[RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + +[SFTP] Ylonen T., and Lehtinen S., "Secure Shell File Transfer + Protocol", Internet Draft, March 2001. + +[RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", RFC 2279, January 1998. + +.ti 0 +5 Author's Address + +.nf +Pekka Riikonen +Snellmaninkatu 34 A 15 +70100 Kuopio +Finland + +EMail: priikone@iki.fi + +This Internet-Draft expires XXX diff --git a/doc/draft-riikonen-silc-spec-07.nroff b/doc/draft-riikonen-silc-spec-07.nroff index 077cda32..ac6a6dc1 100644 --- a/doc/draft-riikonen-silc-spec-07.nroff +++ b/doc/draft-riikonen-silc-spec-07.nroff @@ -16,7 +16,7 @@ .nf Network Working Group P. Riikonen Internet-Draft -draft-riikonen-silc-spec-06.txt XXX +draft-riikonen-silc-spec-07.txt XXX Expires: XXX .in 3 @@ -107,6 +107,7 @@ Table of Contents 3.10.1.2 CTR Mode .................................. 24 3.10.1.3 Randomized CBC Mode ....................... 25 3.10.2 Public Key Algorithms .............................. 26 + 3.10.2.1 Multi-Precision Integers .................. XXX 3.10.3 Hash Functions ..................................... 26 3.10.4 MAC Algorithms ..................................... 27 3.10.5 Compression Algorithms ............................. 27 @@ -1353,6 +1354,17 @@ described in [PKCS7]. When using OpenPGP certificates the signature is computed as described in [PGP]. +.ti 0 +3.10.2.1 Multi-Precision Integers + +Multi-Precision (MP) integers in SILC are encoded and decoded as defined +in PKCS #1 [PKCS1]. MP integers are unsigned, encoded with desired octet +length. This means that if the octet length is more than the actual +length of the integer one or more leading zero octets will appear at the +start of the encoding. The actual length of the integer is the bit size +of the integer not counting any leading zero bits. + + .ti 0 3.10.3 Hash Functions -- 2.43.0