INTERNET-DRAFT                                            T. Shemsedinov
Expires: 25 March, 2001                                             RIST
                                                          September 2000

                       Universal Service Protocol
                            draft-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.

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.

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.  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

    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.1.  Structured packet with various substructures

    This example shows, how e-mail message as USP packet can be
    submitted.

        Res[OK] Model[large]
        Part[Mail] Type[multipart] Count[3]
          From[Timur Shemsedinov, Timur@niist.ntu-kpi.kiev.ua]
          To[Tamagochi, dt@zhadum.alfacom.net] Subject[Test message]
          Date[4.Sep.2000] Time[2:41]
          Part[msg] Type[plain]
            The test message
            with the attached file.
          Endpart[msg]
          Part[Attaced_file.ext] Type[file]
            DDWShXSZLDC285CipoJD5ig0niPrA6w/rMkm9xkrD0FKhSE4YRwkc9vWCvDv
            70KN/a+DdIEjQKRC8QIJSoEswDhWmEXovWAwN4HH/z+ph+fBwJj1XdQzO7AP
            LH8sSjks11We6JwELndDdFDqRsZJ7QshPkU1kwrd+snIqsfo+gKkL3whWMy6
            yOeGgzwkXGulI6AMBujHA5lZvNg3SBD0yVxhdP==
          Endpart[Attaced_file.ext]
        Endpart[Mail].

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
    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 and 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.

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
    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.

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.  The simplified representation of static fields arrays

    Such simplification was required for reduction of volumes of
    transmitted packets and prevention of transfer of the superfluous
    information (names of fields) in each element of an array.   But on
    today it is not supported by any known realization of USP.

    Instead of transfer of the following packet:

        Res[OK] Model[large]
        Part[files] Type[array] Count[3]
          File[usp.exe] Size[370176] Descr[USP service for NT4]
          File[valid_ip.lst] Size[73] Descr[accesslist]
          File[accounts.ini] Size[378] Descr[users_groups_accounts]
        Endpart[files].

    Its simplification is possible:

        Res[OK] Model[large]
        Part[files] Type[array] Count[3]
          [File,Size,Descr]
          [usp.exe,370176,USP service for NT4]
          [valid_ip.lst,73,accesslist]
          [accounts.ini,378,users_groups_accounts]
        Endpart[files].

    If you have looked at these two packets and there are of opportunity
    of transfer in the second case of string values of any parameter
    which in meet points or others means, read once again unit 1.

5.4.  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.

    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
    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.

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
    National Polytechnic University of Ukraine
    Ukraine, Kiev
    Email: <sth_xnp@yahoo.com>
           <timur@niist.ntu-kpi.kiev.ua>
    Fido: 2:463/482.88


Expires: 25 March, 2001
