INTERNET-DRAFT T. Shemsedinov RIST Expires: 21 February, 2001 M. Shemetilo NPUOU August 2001 Universal Service Protocol draft-shemsedinov-usp-02.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 except that the right to produce its updatings is not granted. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them in other cases than as "work in progress." The list of current Internet-Drafts can be accesses 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. This section will be updated with the appropriate verbiage from RFC 2223 should this document has been found ready for publication as an RFC. This document is a product of the Research Institute of System Technologies and National Polytechnic University of Ukraine. Abstract This document contains the description of a call and response packets of protocol USP. The protocol is the maximum generalized way of coding of the complex hierarchical information, in its basis the principles of object-parametrical modeling are fixed. The protocol does not assume binding to any specific service and gives only basic rules structuring of any service protocols, given for creation, however USP was developed as RPC protocol, which responses should be multipart structures on similarity MIME or XML, but with support of a multilevel enclosure and other expansions. Unfortunately, the majority of the modern protocols represent the information differently, it is caused by that they were created by the independent developers, in different time and for work in different operational systems. The reduction of the protocols to a common format of representation of the information will allow essentially to facilitate development of the new protocols and spelling new servers, will remove problems connected to any incompatibility, and will raise speed of processing of the information. I distinctly imagine to myself all complexities connected to the introduction USP, but standardization always brought more benefits, than problems. Shemsedinov RIST [Page 1] Internet-Draft USP August 2001 1. Transfer and common structure of packets The protocols of this family are intended for running dialogue between set of the clients and server, i.e. for realization of the removed call of procedures and reception of the structured results. The USP packets are divided on two groups: calls and responses. One USP packet can consist of set TCP packets. For definition of the end of USP packet, last of TCP packets comes to end by three symbols: #46#13#10. Packets are divided on three types: a calls, responses and events. The clients transfer packets containing the information, necessary for execution of function in such format: FunctionName(par1..., parN). Server should up to the expiration timeout answer each function in such format: Field1[val1] Field2[val2] ... FieldN[valN]. The responses is divided into fields, each consists of a name and value in square brackets. The fields are divided by blanks (#32) or symbols #13#10. Such structure of a packet gives very general its kind, complex packets, the files and structures of the data will be described below. In names of fields, as well as in values, the symbols possible are any from #32 up to #255 except listed: #35, #36, #37, #38, #40, #41, #44, #91, #93. Other symbols are transferred as pair of symbol #36 ("$") and the symbol with a code increased on 48. Such coding of fields values allows to get rid of all managing symbols. The large and small letters in the names of fields and functions differ. 2. Classification of response packets The response packets are of two types: simple and structural. The simple packets transfer values of the certain fields, and structural can comprise hierarchy of subpackets, arrays and files. 2.1. Packet header The first line of each packet contains header. The first field of heading is "Res", it contains a code of correctness of performance of inquiry. In case of successful execution the field has value "OK", the different code is an error code in a format "ERR_*". The second obligatory field "Model", it has two possible values: "small" and "large", this field defines, whether the packet is a simple or contains the structured data. Further go either field of a simple packet or structure of the data. Shemsedinov RIST [Page 2] Internet-Draft USP August 2001 2.2. Classification of data structures Each structure has obligatory fields, they are contained in first its line and determine a name of structure (field "Part") and type of structure (field "Type"). The type of structure can accept 5 values: "plain", "multipart", "array", "table", "file ". The end of structure considers a field "Endpart" containing a name of closed structure. 2.2.1. Plain structures The type of structure "plain" allows to store in structure a set of fields with unique names. The order of fields following has no importance. The unit of this type can be not separated on fields in general and can contain the text allowed symbols or any others symbols that must be coded as in a such a way as values of fields. 2.2.2. Multipart structures The type of structure "multipart" enables to break structure on substructures. The format of substructure corresponds to this description, and all substructures can have a multiple enclosure. 2.2.3. Arrays structures The type of structure "array" speaks that the structure stores in each line an element of array. Each element can have a similar set of fields, or they can differ. 2.2.4. Tables structures The type of structure "table" should have identical fields in each record. The names of fields are specified in header, and each record contans values of fields only. Each record is limited to pair of symbols "[]" (#91#93). The values between them are divided by "," (#44). This type differs from a type "array" by reduction of the record size. 2.2.5. Files structures The structure type "file" allows to place in packets whole binary files coded in the format Base64 (RFC 2045). However, the affiliated protocols can have the variety of coding, in such case they should add in structure definition a field that contains the coding method identifier. 2.3. Examples of response packets For the best understanding, we can see the various information representation in a formated USP packets in some examples followed. Shemsedinov RIST [Page 3] Internet-Draft USP August 2001 2.3.1. Elementary (not structured) packet In this example the packet contains one set of not repeating fields only. In particular it is the data about any user. Res[OK] Model[small] User[Vasia Pupkin] Email[vasia@pupkin.com] Usertype[extended_user] State[Connected]. 2.3.2. Packet with one array section Continuing the previous example, we admit, that we need to transfer the information about the several users. Then the packet will look as following: Res[OK] Model[large] Part[Users] Type[array] User[Vasia Pupkin] Email[vasia@pupkin.com] User[XNP] Email[xnp@zhadum.anfacom.net] User[Nut_M] Email[Nut@rulez4ever.org] Endpart[Users]. 2.3.3. Packet with table The same information, as in the previous example. Res[OK] Model[large] Part[Users] Type[table] [User,Email] [Vasia Pupkin,vasia@pupkin.com] [XNP,xnp@zhadum.anfacom.net] [Nut_M,Nut@rulez4ever.org] Endpart[Users]. 2.3.1. Structured packet with various substructures This example shows the possibility to present the information about my workstation. Res[OK] Model[large] Part[MyWorkstation] Type[multipart] Name[WS1] IP[10.18.8.51] Sysop[Shemsedinov Timur] Domain[RIST] Building[18] Room[435] Organization[Research Institute of System Technologies] Part[Display] Type[multipart] Name[Sampo] Diagonal[14] ManufDate[May.1998] Part[ModeList] Type[table] [Resolution,Color,Frq] [640x480,True,85] [800x600,True,85] [1024x768,65535,85] [1280x1024,256,85] Shemsedinov RIST [Page 4] Internet-Draft USP August 2001 [1600x1200,256,60] Endpart[ModeList] Part[Adapter] Type[plain] Chip[S3 Trio64V2] Dac[S3 SDAC] Memory[2Mb] Manuf[S3 Incorporated] Endpart[Adapter] Endpart[Display] Part[Keyboard] Type[plain] Name[FTC] ModelName[KWD-203] Alpha[Roman,Cyrillic] KeyCount[104] Endpart[Keyboard] Part[Disks] Type[array] Disk[A] Type[Floppy] Descr[3inch] Disk[C] Size[38974345] Disk[D] Size[2398459] Disk[E] Size[29038429] Disk[F] Type[CDROM] Descr[x32] Disk[G] Size[9873653] Endpart[Disks] Part[RAM] Type[plain] MemType[DIMM] Size[128] Descr[two chips] Endpart[RAM] Part[CPU] Type[plain] Name[K6-2] Manuf[AMD] Speed[300] Descr[with 3dNow] Endpart[CPU] Endpart[Computer]. 3. Events packets The events packets differ from the answers packets only by that they can be transferred by a server to any connected client at any time without a function call. It have a sens if necessary to notice the clients about events occurring on a server. The text of a event packet differ only by the first line, which contains a name of event in a format: "Event[name]". 3.1. Example of event without parameters If the event does not require transfer of the additional information except a name of event, it is possible to be limited to one line. For example, to notice of the USP server administrator about change in a configuration and necessity to re-read it such packet can be transferred: Event[cfg_changed]. 3.2. Example of a packet with structure transferred as parameter In events packets possible are all cases of the structural and enclosed packets, arrays and files, etc. For example, if there is remote administration interface in USP server is possible to notify the client-manager about new users connections, through transferring Shemsedinov RIST [Page 5] Internet-Draft USP August 2001 a event packet: Event[client_connected] Model[large] Part[c_info] Type[plain] Name[...] IP[...] TimeOfConnection[...] Port[...] SelectedService[...] UserGroup[...] Endpart[c_info]. However, the same information can be transferred with Model = "small": Event[client_connected] Model[small] Name[...] IP[...] TimeOfConnection[...] Port[...] SelectedService[...] UserGroup[...]. 4. Handshake There is a primary dialogue at connection of each client, and as a result the server identifies the client and determines in what subprotocol to transfer its inquiries. The format of handshake consists of standard USP packets with the fixed fields set. First a server sends a greeting packet, with such a fields: Res, Model, Servername, Time, Date, Owner, Services. The client decides on the basis of the received information, whether this server gives access to necessary service. If it so, client calls "SelectService" with parameters: ServiceName, UserName, Password. The server only confirms or rejects a choice of service, its accessibility to the specified user and correctness of the password. Instead of "SelectService" here may be used a pseudonym "sls". 4.1. Example of handshake Having connection established server sends a packet: Res[OK] Model[small] Servername[First USP Server] Owner[rist] Time[8:11] Date[25.Sep.2000] Services[RA,RMU,OODB,SHFS]. The client chooses the subprotocol and transfers a name and password by calling the function: SelectService(RA,asutp,asutp). Server confirms successful connection with the subprotocol: Res[OK] Model[small]. From this point all packets from this client are transformed into calls of functions from the separate module that realizes the specific subprotocol. Thus subprotocols become an usual API. However, the basic module watches functions calls and if the Shemsedinov RIST [Page 6] Internet-Draft USP August 2001 function "SelectService" is carried out repeatedly, it switches the client to other module of server. 4.2. System functions After successful end of the first handshake, except functions of the current interface and "SelectService" the two systems functions "listinterface" and "man" can be called in any time. A pseudonym for "listinterface" is "li". Function "listinterface" returns the list of accessible functions of the chosen service (is called without parameters), and the function "man" with name of function specified in its sole parameter returns a format of a call of the interface function. 5. Simplifications of packets structures In frequently occuring cases some fields of USP packets can be omitted, since their meanings are exactly defined by other fields or contanes any useful information. Also arrays can have the simplified structure: if a set of fields in each line of an array identical, there is no necessity to store names of fields in each line. Such cases will be considered in following sections. 5.1. Returning of a code of the function performance If the packet contains only field "Res", the field "Model" can contain only value "small", so it can be not specified. For example: instead of "Res[OK] Model[small]." it is possible to transfer "Res[OK].". The call of event without parameters can be reduced too, as was already shown above: "Event[Name].". 5.2. Simplicity of reading versus the size of packets We used indents in all examples of text-packets for simplicity of reading, and distinct visual separation between beginnings and ends of structures. These indents are not obligatory at all, because the structure of a packet without them is precisely determined. However, they can take place in the packets, if there is the person with Telnet compatible terminal on the client side, instead of the application. 5.3. One-dimensional arrays If it is necessary to transfer an one-dimensional array, it can be made without creating subpackets of a root packet, and simply by listing values separated by the symbol #44 (it is a special symbol for the fields values, and it was reserved for this case). 6. The subprotocol of the remote administration of USP server. This protocol is not obligatory on all USP servers but it gives set of opportunities for flexible server configuration without its Shemsedinov RIST [Page 7] Internet-Draft USP August 2001 reload. The protocol has the name "RA/USP" and the line "SelectService" in handshake should look in a following way: SelectService(RA,name,password). 6.1. The basic functions of RA/USP. Call: GetIPs(). Response: Res[OK] Model[large] Part[IPS] Type[plain] 10.18.8.54 10.18.8.52 10.18.8.3 Endpart[IPS]. Description: Receive the list of IP addresses (or masks) of clients, which can work with server (i.e. AccessList). Call: AddIP(IPAddr). Response: Res[OK]. Description: Add IP (or mask) in AccessList. Call: DelIP(IPAddr). Response: Res[OK]. Description: Remove IP (or mask) from AccessList. Call: GetLog(). Response: Res[OK] Model[large] Part[LogFile] Type[plain] 9/25/2000 20:30:38 10.18.8.51 Error #10053 9/25/2000 20:30:44 10.18.8.51 connected 9/25/2000 20:30:52 10.18.8.51 disconnected Endpart[Logfile]. Description: Receive logfile in which the date and time of some operations of the users is registered. Call: GetInfo(). Response: Description: Receive the common information about server. Call: GetUsers(). Response: Res[OK] Model[large] Part[Users] Type[array] User[Asutp] Service[OODB] IP[..] Inc[..] Out[..] Socket[..] User[Timur] Service[RA] IP[..] Inc[..] Out[..] Socket[..] User[Nps5] Service[RMU] IP[..] Inc[..] Out[..] Socket[..] Endpart[Users]. Description: Receive the information about the users and their parameters. The values of some fields are replaced in ".." for brevity. The field "Socket" contains ID of connection, this value Shemsedinov RIST [Page 8] Internet-Draft USP August 2001 can be transferred as parameter of function "CloseUser". Call: CloseUser(UserID) Response: Res[OK]. Description: Disconnect of the client. Call: GetINI(). Response: Res[OK] Model[large] Part[INIfile] Type[plain] alias=test syslogin=asutp syspass=asutp Endpart[INIfile]. Description: Receive the list and values of an environment variables. Call: SetINI(varName,varValue). Response: Res[OK]. Description: Establish value of certain variable. Call: Sleep(). Response: Res[OK]. Description: Lull the server. Call: Wake(). Response: Res[OK]. Description: Wake the server. Call: Restart(). Response: Res[OK]. Description: Gently restart of the server. Shemsedinov RIST [Page 9] Internet-Draft USP August 2001 7. References [1] Postel, J., "Transmission Control Protocol - DARPA Internet Program Protocol Specification", RFC-793, ISI, September 1981. [2] Freed,Borenstein, RFC-2045 "Multipurpose Internet Mail Extensions" Unit: "Base64 Content-Transfer-Encoding", November 1996. [3] Sun Microsystems, Inc. "RPC: Remote Procedure Call", RFC-1057, June, 1988. 8. Author's Address Timur Shemsedinov Research Institute of System Technologies Ukraine, Kiev Email: timur@niist.ntu-kpi.kiev.ua Marina Shemetilo PolySystem, Ukraine, Kiev Email: marina@cis-kiev.com Expires: 21 February, 2001 Shemsedinov RIST [Page 10]