INTERNET-DRAFT T. Shemsedinov Expires: 8 April, 2003 D. Krep RIST M. Shemetilo CIS-KIEV October 2002 Universal Service Protocol : USP Version 3 draft-shemsedinov-usp-04.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 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. 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 (1999-2002). Abstract This document describes an application-level remote procedure calls protocol called the USP. This protocol is the maximally generalized way of client/server interactions in distributed systems of object- oriented, hierarchical, relational or hybrid data model. USP treats such interaction as remote procedure calls. This document contains specification of calls, responses and events of USP including the complex structures' coding needed for representation of the objects. Also URI schema of USP is considered. Shemsedinov RIST [Page 1] Internet-Draft USP October 2002 Table of contents 1. Introduction..................................................2 1.1. Tasks to be Solved..........................................3 1.2. Transport Layer.............................................4 1.3. Analogs, Differences and Benefits...........................4 2. USP Client/Server Architecture................................5 2.1. Shared RPC Interfaces.......................................5 2.2. Client Side.................................................6 3. Packet Syntax.................................................7 3.1. Packet Classification.......................................7 3.1.1. Call Packet...............................................7 3.1.2. Response Packet...........................................7 3.1.3. Event Packet..............................................8 3.2. USP ABNF Specification......................................9 3.2.1. Level-1 (Packet Separation)..............................10 3.2.2. Level-2 (Plain Parsing)..................................10 3.2.3. Level-3 (Hierarchical Parsing)...........................12 3.3. Structured Data............................................14 3.3.1. Node Classification......................................14 3.3.1.1. Objects, Folders and Members...........................14 3.3.1.2. Plain Node (Set of Fields).............................16 3.3.1.3. Multipart Node (Tree Hierarchy)........................16 3.3.1.4. Array Node.............................................17 3.3.1.5. Table Node.............................................17 3.3.1.6. File Node (Binary Data)................................18 4. Handshake....................................................18 5. System Predefined Functions..................................19 5.1. SLS (Select Interface).....................................19 5.2. LI (List Interface)........................................19 5.3. MAN (Getting Manual).......................................19 6. URL Scheme for Remote Procedure Calls via USP................20 7. Security consideration.......................................21 8. Acknowledgements.............................................22 9. Author's Address.............................................22 10. References..................................................23 A. Error Codes..................................................24 B. Character Status Table.......................................25 C. Reserved words...............................................25 1. Introduction The USP is an application-level protocol using any connection- oriented transport layer with bi-directional octet streaming possibilities and reliable data delivery. Such transport protocol is a Transmission Control Protocol [1]. The USP is not assigned to any specific service and gives only basic rules for service interfaces developing. There is a tendency to standardization of network transport, but unfortunately, the majority of today's protocols represent the information differently, it is caused by the fact that they were created by the independent Shemsedinov RIST [Page 2] Internet-Draft USP October 2002 developers, at the different time and for the different systems. The transformation of already existing protocols is a very difficult task, moreover, this task is senseless in the most cases, because old-style protocols perform their functions well and the world cannot be changed instantly. However we can see what benefits has brought the information format unification in case of MIME, URI or in sphere of markup languages (such as HTML and XML) in spite of all problems with putting those fields in order. Such initiative will remove problems connected with incompatibility, and will increase speed of information processing, but it should be supported by appropriate development and introduction of servers and end-user software. Research Institute of System Technologies is going to provide complete free-source codes and support libraries for the several programming languages. I am distinctly aware of all complexities connected with USP implementation, but standardization always brings more benefits, than problems. 1.1. Tasks to be Solved The necessity of this protocol development has been in need for a long time especially for the system integrators and distributed systems developers. Recently the object-oriented systems have received wide spreading. They gives us not only convenient information exchange facilities, but also it provides structuring of the data in the unified formats with the purposes of the maximum automated information processing. Object-oriented technologies give users possibilities of modeling their project domain classes themselves. Getting users to take part in data modeling and participation in information systems development makes this process not a conveyer, but specialized and at the same time mass production (such idea is stated by Don Tapscott [2]). The inter-module interaction of such flexible information systems requires using of many protocols, but uniting and coordinating work of the system should be performed by the remote procedure call protocol. The principle of RPC is rather ancient, it was applied from times of networks initiation. The further development of the network technologies has shown that even the local interprocess communication can be successfully realized through the network protocols. Moreover, the local systems, constructed on such principle, can be simply upgraded into distributed environment, for use in corporate and international networks. Thus the practical experience and research efforts of a numerous developers in this sphere enabled us to establish the following requirements to the present protocol: o Using the most widely spread transmit protocol (TCP), but opportunity for using other proper transport meeting the requirements of section 1.2 of this document; Shemsedinov RIST [Page 3] Internet-Draft USP October 2002 o Object data transmission and object-oriented modeling principles [6] and data modeling completeness [5] maintaining; o Open system requirements including making both the documentation and sources of protocol supporting libraries available for free; o Maximal technology versatility, absence of binding to any subject area, operational system, project or programming language, etc.; o Packet readability and compatibility with Telnet [9]. Namely, data presentation format must be readable both for the application and the user using the standard terminal client; o Modularity and maximal simplicity; o Compromise between the information redundancy and the speed of parsing; o Some other minor requirements which appears during developing, for instance, callback support, binary data coding, language identification. But the basic design of a current protocol is its application as a bases for the information systems of the hybrid data model, it means, that it should have optimal facilities of the complex data representation. Various data models (relational, hierarchical, network, object-oriented) are used nowadays, even within one system. It conveys that listed models are optimum in the certain area each. The provision of such common protocol, and quite possible, related data storage system will allow integrating the separated modules of information systems. The Research Institute of System Technologies hopes that we will submit the first hybrid database management system on the basis of the given protocol, for a public in the near future. 1.2. Transport Layer The Universal Service Protocol requires octet streaming transport- level protocol allowing transmitting of entire codepage (00-FF). The transport service should be connection-oriented reliable protocol providing bi-directional client/server data transmission. For today USP is based on TCP [1], however using of different transport is possible. 1.3. Analogs, Differences and Benefits Enumerated below technologies and some others not so well known developments have been tested and considered as an object-oriented transport: SunRPC [4], DCOM, CORBA, SOAP [11], BEEP [8], XML-RPC. But unfortunately, all developments, known to us, did not meet the mentioned above requirements. Some have a binary format, not readable for the users, others do not support operations with Shemsedinov RIST [Page 4] Internet-Draft USP October 2002 objects, such as passing object as parameter or result of RPCs. Some are simply extremely ponderous and are not fulfils open system requirements. The technologies based on SGML-family markup languages (first of all XML [12]) are undoubtedly allows to represent any data, but they are frankly superfluous for objects representation and furthermore for RPC's packing. They do not express all completeness of the data modeling theory, for instance, identifying, non-identifying, physical, logical, sub-category relationships between the objects and the classes. Markup languages have other tasks, namely, they are called to markup and outlay internal structure of the documents. Thus the distributed system technologies based on RPCs can be divided into two groups: o Internal standards mainly oriented at the corporation policy rather than openness or elegance; o Task-oriented protocols by the independent developers, created on precise purpose and absolutely incompatible with each other. Such systems have fixed set of instructions limited by areas of use. They are not pretend to any kind of universality but at the same time performing their functions well. The main idea of USP is that the protocols really should be task- oriented, i.e. have their own sets of commands and instructions etc. But there should be common protocol development rules. These rules should include unified format of the following features: o handshake (authorization and authentication mechanism); o procedure calls' format and arguments passing agreement; o responses' format; o object representation format and transmission rules; o events' format; o server's management tools. 2. USP Client/Server Architecture 2.1. Shared RPC Interfaces The distributed information system server on USP is intended for providing client access to the resources. First of all it is information resources, besides server can share computing, relaying, synchronizing, searching, batch executing etc. services. The USP service called interface is the set of the specialized functions designed for certain needs. Also interface can be represented as Shemsedinov RIST [Page 5] Internet-Draft USP October 2002 a shared API. The client application is acting in the initiating role. The server awaits connection as a listener, and when the client opens session, it gives out the list of accessible interfaces and other information on itself. The client chooses the necessary interface through handshake (authorization) and then it can evoke RPCs only in a context of chosen interface. During connection there are two styles of interaction: o The client sends RPC execution request to the server and server replies with a generated packet of response. o The Server sends the event message to the client without inquiry. The event can be formed and sent by server as a result of by other user's RPC execution or changing a server condition or any operations on the data, which can be useful to the client in a context of the selected interface, etc. The direct interaction between two clients is impossible in the scope of USP. The server acts as the coordinating mechanism, but it does not mean, that all operations will be executed at the server. The network interaction should be organized to exclude superfluous data transfer. After reception of object/data from server's storehouse to client's memory, object/data becomes separated and storage-independent. It can be changed some times on user's request, stored as a file or transformed by client application. If it is necessary to synchronize object/data with storehouse, it is enough to transfer only its changes so-called Delta. 2.2. Client Side Since USP provides synchronous RPC execution, if the client starts execution thread, it cannot start one more while current thread works. It is supposed that client application has single thread or, in case of the multithread application, each thread has individual USP connection. The client application can be specialized, i.e. designed for interaction with specified service interface or can be universal. USP provides mechanism of getting server structure information and the object-oriented data representation format allows to parse response packets of any remote procedure in the same way. The user can choose the interface and function, can get help on function and its parameters' list, then fill parameters and make a call. The representation of the response packets on the client's screen is not regulated by its syntax and can be arbitrary, however should correspond to hierarchical, tabular, plane and other node type`s classification of the source packet. Shemsedinov RIST [Page 6] Internet-Draft USP October 2002 3. Packet Syntax 3.1. Packet Classification There are three kinds of packets: Call, Response, Event, they have different purpose but similar syntax. The difference between them is only in headers (first line of any packet). Representation of the attached data structure is identical and will be discussed in section 3.3 of this document. The ABNF specification also can be found in section 3.2. 3.1.1. Call Packet The client sends a call packet to the server asking to perform the remote procedure. There are two formats of the call: function-style or command-style. The function-style format reminds a classical call of the function in the majority of the programming languages. It is an identifier after which a set of parameters divided by comma follows in brackets. As shown in the following: function = identifier "(" [ value-list ] ")" value-list = value *( "," value ) The command-style format is even easier. The parameters should be specified divided by SP character after the identifier. command = identifier [ parameters ] parameters = value *( SP value ) The attached data can follow the header optionally. The following examples show some typical call packets. OpenFlap TP015 Plap01. CloseFlap(TP004,Flap02). AppendOrder(7795) Color[dark-blue metallic] Upholstery[leather] Gear-box[automatic] Year[1999-2002] Mileage[10] Set[air-conditioner,4airbag]. 3.1.2. Response Packet The server always sends a response packet to the client as result of remote procedure execution. If a procedure finishes successfully then a response header contains "Res" field (result code) "OK". Otherwise, the result code begins on "ERR" then an error code follows. The optional fields also can be present in a header, for Shemsedinov RIST [Page 7] Internet-Draft USP October 2002 instance, field "Message" containing error description. response = "Res[" res-code "]" [ SP field-list ] res-code = "OK" / ( "ERR" value ) The system error codes are given in appendix A. The following examples show some typical response packets. Res[OK]. Res[ERR23] Message[can not execute function : syntax error]. Res[OK] Object[PT004:OilPump] Displacement[constant] Value[63] Control[automatic] Status[working] Member[FlowMeter] Substance[fluid] Recording[off] Role[master] Period[00:30] DataOutput[Parent.FT002.Verification] End[FlowMeter] Member[Outlet] Pressure[180] Status[working] Member[FailureSensors] Type[table] [Module,Indication,Status] [Seatings,none,OK] [Flap01,open,OK] [Flap02,closed,overload] [Joint,detach,OK] End[FailureSensors] End[Outlet] End[PT004]. 3.1.3. Event Packet The server sends an event to the client in case of its condition change, notifying on process of the batch task execution, in case of database actions, operations of other users or any other operations requiring notice of the client without its direct inquiry. An event can be sent both during waiting for RPC call or execution remote procedure execution. If an event arises during response packet transmission, an event gets into the queue. The developers should take into account that some event packets can stick together with each other or with a response packet. In such case they comes to the client application together. For packet dividing the trailer is used. trailer = "." CR LF An event packet should have an obligatory field "Event" containing Shemsedinov RIST [Page 8] Internet-Draft USP October 2002 name of event. The optional fields also can be present in the header of event, for instance "Message" containing event message. The following examples show some typical event packets. Event[CacheChanged] Classes[AnnualReport,AnnualBalanceSheet]. Event[DatabaseBackup] Percent[63]. Event[DeleteNotification] User[Tim] Operation[Delete] ObjectName[Root.Objects.Kpi.Rist.Shared.Info.2002.April] Time[2002-09-20T20:03:52+3:00] Status[Done]. Event[StateCritical] Object[OTS-2:OilPumpStop] Cause[pressure jump] Damage[none] Date[2001-06-24] Member[History] Type[table] [Time,Action,Pump,Parameter,ValueBefore,ValueAfter,Flap] [02:27:18,OilpumpStart,PT007,P_in,50.1,6.8,48%] [02:27:20,OilpumpStart,PT008,P_k,48.6,42.4,45%] [02:27:32,Failure,PT007,P_max,58.9,60.4,48%] [02:27:33,Stop,all,P_max,63.2,6.8,79%] End[History] Member[Committee] Type[table] [id,Name,Status,ProtectionType,Assessment] [756,I.Burack,chief,system defence,fair] [807,V.Rubanov,mechanical engineer,flaps,fair] [078,P.Dyba,electrical engineer,pressure defence,good] End[Committee] Member[Instructions] The development of the optimum running mode and check of the output pressure relay is necessary End[Instructions] End[OTS-2]. 3.2. USP ABNF Specifications The ABNF specification of USP is divided into three levels of abstraction. It is made for granting an opportunity to interfaces to override syntax of the USP if it is necessary. Usually interfaces represent the data in a format of the third level, i.e. using hierarchical syntax which enables to describe complex objects. If there is a necessity to be descend to one level down, the interface redefines the specification of the third level by its own syntax, remaining within the second level specification though. If the interface introduces additional rules and restrictions on the basis of third level, it creates the fourth level, but the packets Shemsedinov RIST [Page 9] Internet-Draft USP October 2002 should meet the requirements of a base level. The server's core should provide facilities for parsing on each of three base levels. Such multilevel specification provides complex structure of object-oriented parser. Each level of this parser should inherit parent's rules and provide additional ones. The client sends an octet stream, which forms a packet in the server's temporary buffer. The buffer can contain only visible symbols and pair CR LF dividing lines. The special symbols are used for packet forming as it described in Telnet specification [9]. The octet stream can be represented as the zero level specification. stream = *( unprintable / printable ) unprintable = %d00-31 printable = %d32-255 3.2.1. Level-1 (Packet Separation) The first level specification describes how packets should be divided from each other. When the whole packet gets into the buffer, server starts execution thread and passes the packet to the second level parser. usp-packet = data trailer data = *( printable / CR LF ) printable = %x20-FF trailer = "." CR LF 3.2.2. Level-2 (Plain Parsing) The second level specification provides facilities for packet pre-analyzing without complex objects parsing, such as extracting header and basic fields access. usp-packet = header [ CR LF structure ] trailer trailer = "." CR LF header = call / response / event call = function / command function = identifier "(" [ value-line ] ")" command = identifier [ parameters ] parameters = value *( SP value ) Shemsedinov RIST [Page 10] Internet-Draft USP October 2002 response = "Res[" res-code "]" [ SP field-list ] res-code = "OK" / ( "ERR" value ) event = "Event[" value "]" [ SP "Message[" value "]" ] [SP field-line] field-line = field *( SP field ) identifier = value structure = field *( divider [data divider] field ) field = field-name "[" value-list "]" value-list = value *( separator value ) data = value *( ( divider / separator ) value ) field-name = *(char) divider = SP / (CR LF) / reserved / unreserved separator = "," / ":" value = *( char / ( "$" char ) ) unprintable = %d00-31 printable = reserved / unreserved / char reserved = "$" / "(" / ")" / "," / ":" / "[" / "]" unreserved = "#" / "%" / "&" / "." / "/" / ";" / " char = SP / "!" / %d34 / "'" / "+" / "-" / %d48-57 / %d60-90 / %d94-255 Shemsedinov RIST [Page 11] Internet-Draft USP October 2002 3.2.3. Level-3 (Hierarchical Parsing) The third level specification completely defines USP core including multilevel recursive enclosing of the nodes and the complex object representation including properties, folders and binary data coding. Each subsequent specification includes a part of previous, but it does not mean that there are recurring operations in parser. The partially processed data should be parsed further being transferred from one level to another. usp-packet = header [ CR LF structure ] trailer trailer = "." CR LF header = call / response / event call = function / command function = identifier "(" [ value-list ] ")" command = identifier [ parameters ] parameters = value *( SP value ) response = "Res[" res-code "]" [ SP field-list ] res-code = "OK" / ( "ERR" value ) event = "Event[" value "]" [ SP "Message[" value "]" ] [ SP field-list ] identifier = value structure = large / small small = field-list field-list = field *( divider field ) field-line = field *( SP field ) large = node-header CR LF [ node-body CR LF ] node-trailer CR LF node-header = ("Part" / "Object" / "Folder" / "Member") "[" identifier ":" class "]" [ SP "Type[" node-type "]" ] [ field-line ] node-body = plain-node / table-node / array-node / file-node node-trailer = "End[" identifier "]" Shemsedinov RIST [Page 12] Internet-Draft USP October 2002 class = value node-type = "array" / "file" / "table" plain-node = field *( divider [data divider] field ) *( CR LF large ) table-node = table-header *( CR LF table-record ) table-header = "[" identifier *( "," identifier ) "]" table-record = "[" value *( "," value ) "]" array-node = array-record *( CR LF array-record ) array-record = field-line file-node = base64 base64 = hex-octet *( hex-octet ) *( CR LF hex-octet *( hex-octet ) ) [ "=" ] hex-octet = 2*( hexdig ) field = field-name "[" value-list "]" value-list = value *( separator value ) data = value *( ( divider / separator ) value ) field-name = *(char) divider = SP / (CR LF) / reserved / unreserved separator = "," / ":" value = *( ( char / unreserved ) / ( "$" char ) ) unprintable = %d00-31 printable = reserved / unreserved / char reserved = "$" / "(" / ")" / "," / ":" / "[" / "]" unreserved = "#" / "%" / "&" / "." / "/" / ";" / " digit = %d48-57 hexdig = digit / "A" / "B" / "C" / "D" / "E" / "F" upalpha = %d65-90 Shemsedinov RIST [Page 13] Internet-Draft USP October 2002 lowalpha = %d97-122 char = SP / "!" / %d34 / "'" / "+" / "-" / digit / %d60-64 / upalpha / %d94-96 / lowalpha / %d123-255 3.3. Structured Data Using reserved words for fields naming it is possible to create multilevel hierarchy in which reserved fields separates the node bodies. The list of reserved words you can find in appendix. 3.3.1. Node Classification Each node has obligatory fields in its first line (node header). These fields determines name, class and type of a node. node-header = ("Part" / "Object" / "Folder" / "Member") "[" identifier ":" class "]" [ SP "Type[" node-type "]" ] [ field-line ] The header begins on one of the following fields: "Part", "Object", "Folder" or "Member". Using of listed keywords fixes a model of a node. If keyword "Part" is used, the model is not specified, a node contains the auxiliary or temporary data or a model specification is not necessary for this node. Use of other keywords is considered in section 3.3.1.1 of this document. The field "Type" is used for definition of a node data format. It is important to understand a difference between class, type and model. The type defines a format of data structure stored in the node body, the class specifies a parent in a context of the given interface and the model (defined by keyword) specifies the relations between the given and the enclosed nodes or its container. It does not mean that all classifications should be present at each node. Only three types of five are specified obviously: node-type = "array" / "file" / "table" Others two more often used are omitted, since they can be determined by other fields. The field "End" containing the name of the closing structure marks the end of the structure. 3.3.1.1. Objects, Folders and Members The hierarchical structure of the packet can have node classification according to rules of ER-model (entity- relationship), in this case physical relationships between nodes are defined by the node models. There are there node models in the USP: "Object", "Folder" and "Member". However there is fourth Shemsedinov RIST [Page 14] Internet-Draft USP October 2002 keyword "Part". It is used if the data model of the specific task does not specify a difference of nodes, or specifies this difference in another way. Part cannot be used in the same packet with the classified nodes. The "Object" is a digital model of the entity (physical phenomenon or subject area concept, for instance "device", "organization", "contract"). The object is integral (but flexible) structure, its properties and members have no sense without object. The object can be the container for any other nodes. The "Folder" serves for association of nodes into groups. The folder is auxiliary structure and has not analogue in a subject area. Folder's properties and the "Member" nodes contained in folder stores auxiliary information as well. The folder expresses the relation shown in this example: +------------------+ +-------------+ +-------------------+ | Object | -> | Folder | -> | Object | | University "KPI" | | Departments | | Department "FICT" | +------------------+ +-------------+ +-------------------+ The "Member" is a complex property of its container. The member can have a class as well as the folder or the object, in this case the member is the typified property. The members can contain in objects, folders, and members. But the member can not be the container for the objects and folders. The fields and members are in the relation attribute-entity to its containers, as shown in following example: +----------+ | Object | +----------------| "Person" |------------+ | +----------+ | | | | | +--------+ +-----------+ +-------+ +----------+ | Field | | Member | | Field | | Field | | "Name" | | "Address" | | "Age" | | "Salary" | +--------+ +-----------+ +-------+ +----------+ | | +----------+ +---------+ | Field | | Field | | "Street" | | "House" | +----------+ +---------+ The are physical and logical relationships between nodes. Physical ones are defined by the node models and enclosing of the nodes. Logical relationships are represented in the packet structure as the fields containing references in an URI format (links). The link can point at the data of an own packet or at any external data, other objects, RPC calls, resources given by other protocols, etc. Shemsedinov RIST [Page 15] Internet-Draft USP October 2002 3.3.1.2. Plain Node (Set of Fields) If a node does not contain a field "Type" in its header and has no enclosed nodes, such node is "plain" node. The node body is separated into fields, each of which consists of a field name (identifier) and a field value (in square brackets). SP character (% d32) or CR LF pair (% d13.10) or simple text divides the fields. value = *( ( char / unreserved ) / ( "$" char ) ) unreserved = "#" / "%" / "&" / "." / "/" / ";" / " char = SP / "!" / %d34 / "'" / "+" / "-" / digit / %d60-64 / upalpha / %d94-96 / lowalpha / %d123-255 The identifier as well as value can contain all characters, except "unprintable" and "reserved". unprintable = %d00-31 reserved = "$" / "(" / ")" / "," / ":" / "[" / "]" Other characters should be coded as a pair of reserved character "$" (%d36) and a character which code is increased on %d48 from a source code. Such coding allows to get rid of all illegal characters. There is a difference between "upalpha" and "lowalpha" characters both in a value and in a field identifier. upalpha = %d65-90 lowalpha = %d97-122 Let's notice that there is no case difference in a function or interface identifier. However, applications should convert "lowalpha" letters to equivalent "upalpha" in the USP interface name. 3.3.1.3. Multipart Node (Tree Hierarchy) If a node header does not contain a field "Type" but has enclosed nodes, such node is "multipart" node. This node type is used for dividing the structure into substructures. Multipart node can also contain plain fields before enclosed nodes. A node "Animals" of the following example is "multipart" as well as "Dog", but "Resolution" is not: Folder[Animals:Images] Object[Dog:Image] Shemsedinov RIST [Page 16] Internet-Draft USP October 2002 GetURI[usp://ws.somewhere.com/UOD?GetObject(Root.Images.Dog)] Member[Resolution] Width[200] Height[200] PixelsCm[37.809] ColorBits[32] End[Resolution] End[Dog] End[Animals] 3.3.1.4. Array Node The "array" node type is used for simple representation of structure's array. The structures with different field sets can be contained in it. Each structure should be divide by CR LF and thus occupies one line. In this case the headers for each array item are not required. Part[Tools] Type[array] Name[soft-tip pen] Diameter[8mm] Color[green] Name[crayons] Colors[red,black,yellow,green,blue,white] Name[eraser] Name[ruler] Length[290mm] Part[Tools] 3.3.1.5. Table Node The type of structure "table" should have identical field set in each record. In this case, with a view of packet size reduction, the names of the fields are not specified in each record. Instead of it they are specified once in the first item as in header of the table. Each record of the table contains fields' values only. Records should be limited by a pair of characters "[]" (%d91.93). The values are separated by character "," (%d44). Part[Employees] Type[table] [ID,Name,Mailto,Birth,Profession,Gender] [1,Golikov,gol@other-end.of-world.ua,1983-04-14,programmer,male] [2,Yanko,avy@south-coast.online.com,1980-05-16,administrator,male] End[Employees] Shemsedinov RIST [Page 17] Internet-Draft USP October 2002 3.3.1.6. File Node (Binary Data) The node type "file" allows to put the Base64 [3] coded binary file into packets. However, interfaces can use the variety of coding, in such cases they should include a field that contains the coding method identifier in the node header. In this case, the data interpretation becomes a task of the specialized client. Part[Cat:gif] Type[file] R0lGODdhZABQAIAAAAAAAP///ywAAAAAZABQAAAC/4yPqcvtD6OcEoBwLbb36X5wIEUu H4Y2mZONoWtqJSmuiHjDELeVdXrb6FSynXD2QgIjNgbPp4xKe4ri1DC8aqnY7IxXtG6r LSZ2jPqEl+NyyIxOn1MdrxL0rKDr83e8rMYWB1Q3IsMnSNFyQtU06II3B+n4FbRUmGan 2IeIaDllGClnpaknKsflVRrThbm2OnHqduonZnpWaON6FdbZ14OHkwmHexQICyX5C0aZ 4ObU6iwEuVfrF53Igoo7y0m4tQYcygsTeVh1Xen9nUQeTJp7ma0n3eiMbNQu7xmoxSiG jx4LQ8MKpjPz454tUOWA1apB6wi0YkP6/UH3AsdCJ/8bDyr81WaSQotd5uXRZ2JawE1B AI47SSTYwGKDPknMYRNkTFU1PRBcpDMisYyY5oWkxu7TypQljV6c6SjqUjI9VSjl13TS VKdVW+qy1BFmha1RCCbS5YlMR4xd4aTNyFXnxLZEmpbUuJZtXasePI6t55fG3oEJiebd KwyUX7EcLUK8kxMyHXOkfCZmVPZpqMewzikrS5bpyR/4LpN9Bq4xl2RPq1F1OFSmv5ou JQXUCC70X6FMEpOjOw1wrEe6d4CRC5wp3X6Hgy9rnpwwSFXCeqEWXKn0Z76PVcYlzjjG 9Ya7o6sJr5amNqenO7d6uzMp36rNAR3q7Cs6R0WzoL/v8VzcF/hFg95+8OmHnGG5+Gbc Td/9YceCDhWY3j0IIlcdREUh0Yx+5YSToV00eJbgRUgBdl53/IkS4FAiJneccLRhhFc4 uUXU4mtG8LEghdIdVJEUAF3YEkoy9qUjQjlaVdmReqVE3kj+gdakXqtc19uD7qCDDFrr qcZcjP5Qwtt/hPBE1YaUgQdNiCcGOZ8xPE7ZG4AsFebkamoBldl7zLABn4YaNkjUew4K KE6N9k0mKGdGfimPgJwxw5yZC1HoY5yC9VjZCp6SNoyYjZ1QSnFzNgoPHRNq+d8ipLI6 Iql4OrjkXDAW9SeCtRKJRgEAOw== End[Cat] 4. Handshake The USP server in the listening role accepts the clients initiating connections. When a connection is established a client waits for the greeting message from a server. This greeting message is an USP packet contained an essential information of a server, which is necessary for the client before selecting the interface. The first field of a greeting is "Res". If it contains "OK" then a session proceeds, in an opposite case it contains the error code explaining to the user a reason of server's inaccessibility. Required fields of the greeting message are the following: "Res", "ServerName", "Owner", "Interfaces", "Version". It is desirable to put a field "Time" into the greeting as a timestamp [7] of the connection establishment moment. Besides, the server can put into the greeting any additional fields, depending on necessities of a specific task. The order of fields does not play a part, but it is recommended to order fields according to their importance, or at least, put the fields described in this document first. Next step is a choice of the interface and authorization, for that the user calls a function "sls" described in section 5.1. The server confirms or rejects a choice according to the server's security settings and user's rights. Shemsedinov RIST [Page 18] Internet-Draft USP October 2002 S: C: S: Res[OK] Servername[ws_timur] Owner[RIST] Time[2002-09-24T16:52+03:00] Services[RA,UOD,SHFS] Version[USP-3]. C: sls(UOD,nobody,test). S: Res[OK]. After the successful handshake passing all packets from this client are transmitted into interface, except system calls (next section). 5. System Predefined Functions In addition to the functions of the current interface, the system functions "SelectInterface", "ListInterface" and "Manual" can be called. 5.1. SLS (Select Interface) The function is for a interface selection or a switching between interfaces. This function is a part of handshake, but it can be called repeatedly. In the repeated call the password and UserName can be omitted and the server will use already confirmed account for attempt to associate a connection with next interface. It is supposed that the client can re-send the "UserName" and the "Password" several times to change access rights during a connection. The "lowalpha" and "upalpha" characters, as already noted, is equivalent in interface name but not in UserName or Password. So, the variants are possible: "SLS", "sls", "Sls", etc. Besides, the client can use an alias of this function: "SelectInterface". The ABNF of a call is the following: sls = "SelectInterface" "(" Interface [ "," UserName "," Password ] ")" trailer 5.2. LI (List Interface) The system function "ListInterface" returns the list of accessible functions of the chosen service interface including short description and calls' format (it is called without parameters). An alias of "ListInterface" is "li". 5.3. MAN (Getting Manual) The system function "man" with the function identifier in its single parameter returns a detailed user manual and a format of a call. Shemsedinov RIST [Page 19] Internet-Draft USP October 2002 6. URL Scheme for Remote Procedure Calls via USP It is very comfortable for the user to represent the references to the USP interfaces or RPCs in URI syntax. Thus RPC ceases to be only interprocess or inter-application communication mechanism. It becomes the tool for the end user. Through the URI, the user can get the information about the USP server and its services and resources, available through the shared interfaces. The user also can get the manual and call format of the RPCs. In RFC-2396 the complete BNF of an URI specification is included. Therefore, there are only those rules, in this document, which are concerns the USP scheme specific. In following ABNF the rule names determined in the appendix A of RFC-2396 [15] are used: usp-reference = scheme ":" authority "/" interface [ "?" query [ "#" fragment ] ] scheme = "usp" interface = *uric query = identifier [ "(" [ parameters ] ")" ] identifier = *uric parameters = value *( "," value ) value = *uric According to RFC-2718 [13] and RFC-2717 [14] the explanation of USP URI scheme use are given below. An only operation, which can be performed on an USP URI is "call". It is very GET-like operation. The identifier and parameters of the remote procedure can be specified in URI, otherwise application should map URI to the following system calls of the protocol: o If there is no name of the interface in URI, the application should establish USP session or use a parameters of already established session, and show to the user the information received during handshake including the list of shared interfaces. o If there is no remote procedure identifier in URI, the application should call a function "ListInterface". o If the remote procedure identifier is given without brackets "()" and parameters, the application should call a function "Manual" and pass the RPC identifier as a parameter of a call. o If there is no parameter of the remote procedure but the brackets "()" are present, the application should call a specified function without parameters. Shemsedinov RIST [Page 20] Internet-Draft USP October 2002 Aside from RPC's parameters included in URI, the user can attach to the call any information packed in an USP syntax (i.e. object). Use of USP URI scheme does not require any modification of the Proxy or the client browser. But it would be useful if the applications will run the USP browser from any document containing the USP reference in an URI syntax. It is quite easy without code changing, since the modern operational systems and applications allow to register the new scheme associated with the application. As USP is the protocol with session establishment, the first URI within the scope of one application should establish the session, and subsequent URIs should be processed within of the current connection. 7. Security consideration Concerning security, the USP defines only authorization mechanism and requirement to the USP server and the client realization. This document does not contain explanations of data loose protection during its transmission over the transport channel or special traffic coding against the grabbing. These tasks are duty of the transport layer protocols using by USP. The following rules are given as a security measures for USP URI scheme: o The USP URI cannot contain system function calls such as authorization. Thus URI should not contain the username or password even encoded. If URI requires a session establishment and user authorization, the client application should provide the user dialogue for getting this information. o Any data, distribution of which is undesirable, should be located in a packet attached to a call, but not in URI itself. o The parameters of a call should be encoded using "%" syntax of URI, instead of "$" syntax of USP preventing of wrong interpretation. The following rules should be taken in attention by the server's developers: o There should be a way to control access through the accesslist. System tools (for instance at the Unix-like systems) may implement it, but the developers using other operational systems, which are not having such tools, should take care of this requirement; o The history of authorization operations should be logged; o The server should reply with error ERR05 "connection aborted" and Shemsedinov RIST [Page 21] Internet-Draft USP October 2002 break a connection after three unsuccessful authorizations; o Before the successful authorization, the user can transfer only single-line packets, otherwise the server should reply with error ERR05 and break a connection; The developers of the client applications should think of caching necessity and its storing security on the local computer. In any case, the password should not be cached, even encoded. 8. Acknowledgements The authors gratefully acknowledges the contributions of: George O. Timoshin, Vladimir G. Galagan, Valery M. Vlasenko, Victor Ostashevsky, Pasha Nikulin, and Alexander Kostiuchenko. Den Motuzenko was helpful in developing this project, he provided valuable suggestions and corrections. 9. Author's Address Timur Shemsedinov Research Institute of System Technologies Ukraine, Kiev EMail: Timur@niist.ntu-kpi.kiev.ua Marina Shemetilo Computer Inter Service - PolySystem Ukraine, Kiev EMail: Marina@cis-kiev.com Denis Krep Research Institute of System Technologies Ukraine, Kiev EMail: Daywer@niist.ntu-kpi.kiev.ua Shemsedinov RIST [Page 22] Internet-Draft USP October 2002 10. References [1] Postel, J., "Transmission Control Protocol - DARPA Internet Program Protocol Specification", RFC-793, ISI, September 1981. [2] Don Tapscott "The Digital Economy. Promise and Peril in the Age of Networked Intelligence", 1996. [3] Freed, Borenstein, RFC-2045 "Multipurpose Internet Mail Extensions" Unit: "Base64 Content-Transfer-Encoding", November 1996. [4] Sun Microsystems, Inc. "RPC: Remote Procedure Call", RFC-1057, June 1988. [5] Tsichritzis D, Lochovsky F., "Data Models", Prentice-Hall, 1982. [6] Grady Booch, "Object-Oriented Design", Rational, 1991. [7] G. Klyne, C. Newman, "Date and Time on the Internet: Timestamps" RFC-3339, July 2002. [8] M. Rose, "The Blocks Extensible Exchange Protocol Core", RFC-3080, March 2001, Invisible Worlds, Inc. [9] J. Postel, J. Reynolds, "Telnet Protocol Specification", ISI, RFC-0854, May 1983. [10] T. Berners-Lee MIT/LCS, R. Fielding, U.C. Irvine, L. Masinter Xerox Corporation, "Uniform Resource Identifiers (URI): Generic Syntax" RFC-2396, August 1998. [11] E. O'Tuathail Clipcode.com, M. Rose Dover Beach Consulting, Inc. "Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)", RFC-3288, June 2002. [12] J. Boyer, PureEdge Solutions Inc., "Canonical XML Version 1.0", RFC-3076, March 2001. [13] L. Masinter, H. Alvestrand, D. Zigmond, R. Petke, "Guidelines for new URL Schemes", RFC-2718, November 1999. [14] R. Petke, I. King, "Registration Procedures for URL Scheme Names" RFC-2717, BCP-35, November 1999. [15] D. Crocker, P. Overell, "Augmented BNF Syntax Specifications: ABNF" RFC-2234, November 1997. Shemsedinov RIST [Page 23] Internet-Draft USP October 2002 Appendix A. Error Codes ---------------------------------------------------------- code meaning ---------------------------------------------------------- 00-19 general errors 01 not in access list 02 interface not selected 03 handshake failure 04 access denied 05 connection aborted 18 protocol internal error 19 unknown error 20-39 can not execute function 20 function not found 21 function syntax error 22 one or more parameters are invalid 23 syntax error in attached data 24 operation now in progress 25 shutdown in progress 38 parser internal error 39 unknown error 40-59 execution terminated 40 access violation 41 invalid file operation 42 sharing violation 43 operation timeout 44 out of memory 45 disk full 46 thread deadlock 58 interface internal error 59 unknown error 60-79 object DBMS errors 60 access violation 61 object not fount 62 object locked 63 invalid path 64 invalid object 65 invalid child 66 invalid class 67 invalid property 68 invalid index 69 database corrupt 70 database does not exist 78 DBMS internal error 79 unknown error 100-999 interface defined errors ---------------------------------------------------------- Shemsedinov RIST [Page 24] Internet-Draft USP October 2002 Appendix B. Character Status Table ---------------------------------------------------------- decimal hex symbols status ---------------------------------------------------------- 000-031 00-1F .......................... unprintable 032-034 20-22 SP ! " .......................... char 035 23 # ......................... unreserved 036 24 $ ........................... reserved 037-038 25-26 %& ........................ unreserved 039 27 ' ............................... char 040-041 28-29 () .......................... reserved 042-043 2A-2B *+ .............................. char 044 2C , ........................... reserved 045 2D - ............................... char 046-047 2E-2F ./ ........................ unreserved 048-057 30-39 0123456789 ...................... char 058 3A : ........................... reserved 059 3B ; ......................... unreserved 060-090 3C-5A <=>?@ABCDEPQRSTUVWXYZ ........... char 091 5B [ ........................... reserved 092 5C ......................... unreserved 093 5D ] ........................... reserved 094-255 5E-FF ................................. char ---------------------------------------------------------- Appendix C. Reserved words -------+--------------+----------------+------------------ Word | in Node Body | in Node Header | in Packet Header -------+--------------+----------------+------------------ Object | reserved | reserved | Member | reserved | reserved | Folder | reserved | reserved | Part | reserved | reserved | End | reserved | reserved | reserved Type | | reserved | Res | | | reserved Event | | | reserved -------+--------------+----------------+------------------ Expires: 8 April, 2003 Shemsedinov RIST [Page 25]