INTERNET-DRAFT T. Shemsedinov RIST Expires: 19 September, 2001 M. Shemetilo NPUOU March 2001 Universal Service Protocol draft-shemsedinov-usp-01.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 other 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, 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 May 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 an 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 from #32 up to #255 except listed are possible: #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", differently code of a mistake in a format "ERR_*". The second obligatory field "Model", it has two possible values: "small" and "large", this field defines, whether the packet simple is or contains the structured data. Further go either field of a s imple packet or structure of the data. Shemsedinov RIST [Page 2] Internet-Draft USP May 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"), type of structure (field "Type"), and in number of elements in structure (field "Count"). The type of structure can accept 4 values: "plain", "multipart", "array", "file ". The field "Count" is underlined, only if the field "Type" has values "multipart" or "array". 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 following of fields has not importance. The unit of this type can in general be not broken on fields and to contain the text allowed symbols and coding inadmissible in this case same as well as values of fields. 2.2.2. Multipart structures The type of structure "multipart" enables to break structure on specified in a field "Count" substructures. The format of substructure is corresponds to this description, and all substructures can have a multiple enclosure. 2.2.3. Array 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, but can differ. 2.2.4. Table structures The type of structure "table" should have identical fields in each record. The names of fields are specified in header, and values of each record without the names of fields. Each record is limited to pair of symbols "[]" (#91,#93). The values are between them and are divided by "," (#44). This type differs from a type "array" by reduction of the size of record. 2.2.5. File structures The type of structure "file" allows to place in packets whole binary files coded in the format Base64 (RFC 2045). However, the affiliated protocols can have the receptions of coding, in such case they should add in definition of structure a field containing the identifier of a method of coding. 2.3. Examples of response packets Shemsedinov RIST [Page 3] Internet-Draft USP May 2001 For the best understanding, we shall result some examples of representation of the various information in a format USP packets. 2.3.1. Elementary (not structured) packet The packet contains in this example only one set of not repeating fields. For example, care of some information on one user can serve packet of such contents: 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 on the several users. Then the packet will look so: Res[OK] Model[large] Part[Users] Type[array] Count[3] 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] Count[3] [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, how it is possible to present the information on my workstation. Res[OK] Model[large] Part[MyWorkstation] Type[multipart] Count[5] 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] Count[2] Name[Sampo] Diagonal[14] ManufDate[May.1998] Part[ModeList] Type[table] Count[5] [Resolution,Color,Frq] [640x480,True,85] Shemsedinov RIST [Page 4] Internet-Draft USP May 2001 [800x600,True,85] [1024x768,65535,85] [1280x1024,256,85] [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] Count[6] 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. Packets of Events The packets of events differ from packets of the answers only by that they can be transferred by a server to any connected client at any time without a call of function. It is necessary for the notice of the clients on events occurring on a server. In the text of a packet of event differ only by first line, which is contained 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, for the notice of the USP server administrator about change of 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 packets of events all cases of the structural and enclosed Shemsedinov RIST [Page 5] Internet-Draft USP May 2001 packets, arrays and files, etc. are possible. For example, the existence in service of the USP server remote administration of an opportunity is possible to notify the client-manager on connection of the new users, transferring a packet-event: 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 With connection of each client there is a primary dialogue, as a result of which the server finds out the client and determines on what subprotocol to transfer its inquiries. The format of handshake consists of standard USP packets with the fixed fields. First sends a packet-greeting a server, it specifies in it fields: Res, Model, Servername, Time, Date, Owner, Services. On the basis of the received information the client decides, 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, entrance in it under the specified user and correctness of the password. Instead of "SelectServic"e is admitted to use a pseudonym "sls". 4.1. Example of handshake After an establishment of connection server sends a packet: Res[OK] Model[small] Servername[First USP Server] Owner[niist] Time[8:11] Date[25.Sep.2000] Services[RA,RMU,OODB,SHFS]. The client chooses the subprotocol and transfers a name and password by call of function: SelectService(RA,asutp,asutp). Server confirms successful connection with the subprotocol: Res[OK] Model[small]. From this moment all packets from this client are transformed to calls of functions in the separate module realizing the specific Shemsedinov RIST [Page 6] Internet-Draft USP May 2001 subprotocol. Thus subprotocols turn in usual API. However, the basic module watches calls of functions and if the 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 interface and "SelectService" in any time the systems functions "listinterface" and "man" can be called. A pseudonym for "listinterface" are "li". Function "listinterface" returns the list of accessible functions of the chosen service (is called without parameters), and the function "man" returns a format of a call of the function of the interface, specified in its sole parameter. 5. Simplifications of packets structures In frequently meeting cases some fields USP of packets can be omitted, since their meanings are unequivocally defined by other fields or do not carry the 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 this unit. 5.1. Return of a code of performance of function. 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 too can be reduced, as was already shown above: "Event[Name].". 5.2. Convenience of reading against the size of packets In all examples of packets we used blanks from a beginning of a line for convenience of reading both distinction of a beginning and end of structures. These blanks are not obligatory at all, the structure of a packet without them is precisely determined, however can be present at packets, if on the party of the client, instead of the application, the person with Telnet compatible terminal works. 5.3. One-dimensional arrays If it is necessary to transfer an one-dimensional array, it can be made not creating subpackets of a root packet, and simply by listing values in through a symbol #44 (this symbol is special in values of fields, it was reserved for this case). 6. The subprotocol of the remote administration of USP server. Shemsedinov RIST [Page 7] Internet-Draft USP May 2001 This protocol is not obligatory on all USP servers but it gives set of opportunities on flexible setup of server without its rerload. The protocol has the name "RA/USP" and the line "SelectService" in hand shake should look so: 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] Count[3] 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 on the users and their Shemsedinov RIST [Page 8] Internet-Draft USP May 2001 parameters. The values of some fields are replaced on ".." for brevity. The field "Socket" contains ID of connection, this value 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 a variable environment. 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: Soft sestart of the server. Shemsedinov RIST [Page 9] Internet-Draft USP May 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 National Polytechnic University of Ukraine Ukraine, Kiev Email: ms@zhadum.alfacom.net Expires: 19 September, 2001 Shemsedinov RIST [Page 10]