





Internet Engineering Task Force                                  S.Dwyer
INTERNET DRAFT                                            PenguinFriends
Category: Informational                                    19 April 2001


               Vendor Machine Simulation Protocol (VMSP)

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited. Security considerations are a natural part of this
   memo if secure administration is required, but is, for the moment,
   implementation-specific. Its purpose is educational, and does not
   purport to be of any serious use otherwise.

Copyright Notice

   $Revision: 1.7 $
   Copyright (C) Sean Dwyer (2001).  All Rights Reserved.

Abstract

   This memo describes a protocol which supports a networked
   client-server model for vending machine simulations. Authentication
   models are discussed, as are likely administrative and simple
   commands between the vending machine simulation and clients. It is
   expected that this protocol will develop as more complex simulation
   needs are discovered.

Table of Contents

   1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . .  2
   2. Why a Protocol? . . . . . . . . . . . . . . . . . . . . . . .  2
   3. Useful Protocol Models. . . . . . . . . . . . . . . . . . . .  3
   4. Authentication Models . . . . . . . . . . . . . . . . . . . .  4
   5. Client/Server States. . . . . . . . . . . . . . . . . . . . .  4
    5.1 Server States . . . . . . . . . . . . . . . . . . . . . . .  4
    5.2 Client States . . . . . . . . . . . . . . . . . . . . . . .  5
   6. Client/Server Interaction . . . . . . . . . . . . . . . . . .  5
    6.1. Client Requests  . . . . . . . . . . . . . . . . . . . . .  6
    6.2. Server Responses . . . . . . . . . . . . . . . . . . . . .  8
   7. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 13
   8. Security Considerations . . . . . . . . . . . . . . . . . . . 13
   9. Acknowlegements . . . . . . . . . . . . . . . . . . . . . . . 13
   10. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
   11. Author's Address . . . . . . . . . . . . . . . . . . . . . . 14




Dwyer                        PenguinFriends                     [Page 1]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


1. Introduction

   The protocol exists between a vendor machine client (VC) and a vendor
   machine server (VS). It must be flexible and simple. It must satisfy
   the needs of clients, servers and administrators. An administrator is
   defined as a client with privileged access to the server, an ordinary
   client has only regular access.

   Because we are talking about simulators, real-world considerations
   may not be relevant; equally, there may be artificial situations
   invented for simulations that only exist in relation to such a
   protocol.  Perhaps it should be called an Imaginary Vendor Machine
   Protocol instead :)

   This protocol has been developed for interest only: it was written
   because the programming language I used at the time (python) had the
   necessary tools to make implementation worthwhile.

2. Why a Protocol?

   Historically, networked vendor simulations have only been useful for
   one reason: to check the current status of a vending machine. This
   does not allow for actual USE of the machine, for which there are a
   number of desirable transactions (with server/client applications):

      - To get status of a product (VS/VC).
      - To obtain a product (VC).
      - To get useful usage statistics (VS).
      - To manage the machine (VS).

   Naturally, this depends on the complexity of the simulation, but it
   can easily be shown that a connection-based model with a well-defined
   protocol makes some complexities possible:

   - Authentication: normally, the only authentication a vending machine
     requires is the correct cost of an item and an item choice.
     However, if security or useful statistics are desired, some more
     detailed form of authentication is needed.

   - Administration: like the benefits of authentication, useful
     administration becomes possible: logs, statistics, restocking,
     revenue management. Unlike the real world, networked services are
     only really useful if they produce information for the
     administrator, rather than the administrator gathering information
     herself (e.g. by physically opening and restocking a machine).

   These, and probably more, are good reasons to have a well-defined
   protocol between VC's and VS's.



Dwyer                        PenguinFriends                     [Page 2]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


3. Useful Protocol Models

   Let's look at the needs of the three participants in this protocol.
   Necessarily, clients and administrators are on the client side, and
   are different uses of possibly the same client process.

   Client:

      - requires a service
      - requires a list (non-)available services
      - requires a receipt of service, e.g. change, or the actual (virtual)
        item.

   To do this, the Server may

      - require authentication from a client
      - require some form of payment from a client
      - require acknowlegement from a client

   And an administrator may

      - require current status of a server
      - require management of server components (float, items, stocks)
      - require management of server, e.g. restricted access or daemon
        management.

   The simplest set of client commands could thus be:

      HELO/EHLO
      LIST
      GET <item>
      AUTH <authentication-mechanism>
      HELP
      QUIT
      <optional administrative commands based on successful AUTH>

   The corresponding server responses:

      <server startup message >
      Ok
      ERROR
      FAIL < in response to an auth >
      BYE

   This is very similar to the [SMTP] protocol, in fact similar enough
   to make use of ESMTP (and other desired extensions to SMTP) as a
   basis for a simple connection-based protocol. We can use an
   HMAC-based MD5 challenge-response to provide authentication, and mix



Dwyer                        PenguinFriends                     [Page 3]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   it with standard SMTP-type commands, codes and responses.

4. Authentication Models

   Authentication in this protocol is achieved in two senses:
   transport-security, and data-security. We want to protect our access
   to the data, and the data itself. The [SASL] protocol is generally
   used in [SMTP AUTH]: we display authentication mechanisms we support,
   and ask the client to choose an authentication mechanism. VMSP so far
   supports the [CRAM-MD5] authentication model, which requires that the
   server prepares a unique string, and hashes it with a secret shared
   between it and the client according to the [HMAC] protocol.

   This is a challenge-response procedure. The client takes the
   challenge string, hashes it with the shared secret and returns it to
   the server. The server compares the hash to its copy, and if it
   matches, administrative commands and access are granted. Only for the
   life of the desired transactions, should this authentication hold.

   In addition, we can make use of [IDENT] authentication as a adjunct
   to HELO/EHLO, much like sendmail. Ident status MUST not affect
   full-blown authentication, however.

5. Client/Server States

   Client and Server states follow SMTP conventions for COMMAND, READY,
   DATA, and AUTH. By this convention, there is no "UNREADY" state,
   readiness is dependent on connection. Server states are
   Client-driven, with the exception of the results of asynchronous
   operations within certain states, which may force changes of state
   regardless of Client requests.

   See section 6. for indications of state during specific requests and
   responses.

5.1 Server States

   When a Client connects, the Server moves into the READY state. The
   Server must indicate this state by announcing a "ready" code and
   message to the client. The READY state indicates that the server is
   capable of servicing Client requests. If the Server is unable to do
   so (too many connections, for example), it must indicate this by the
   appropriate error code and an optional message. The Server can then
   terminate the connection. In this case the Server must not enter the
   COMMAND state.

   When a Client makes a request, the Server moves into the COMMAND
   state. In this state, the Server may process requests by the Client.



Dwyer                        PenguinFriends                     [Page 4]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   If there are no more requests, the Server may move back into the
   READY state while the Client is connected.

   If the Client has data to process by the Server, the Server moves
   within the AUTH state to the DATA state. While in this state, the
   Server can perform asynchronous operations on the data given or
   requested. The Server moves back to the READY state when DATA state
   operations are complete. A DATA state is really only viable within an
   AUTH state, as it's currently the only way the client is allowed to
   request an explicit alteration of the Server's data file.

   Finally, the AUTH state is very similar to the DATA state. From
   COMMAND state, the Server moves into the AUTH state, performing any
   necessary operations before falling back to READY state.

   In the DATA and AUTH states, errors force a change of state. If an
   authorization request fails, for example, that signals the end of
   AUTH state and the Server returns to READY state. The Client must
   begin the authorization procedure again. If the response to an
   authentication challenge fails however, no new AUTH requests should
   be allowed from the client.

5.2 Client States

   The Client changes state when the Server makes a request in response
   to a DATA or AUTH request. During a DATA or AUTH transaction, both Client
   and Server are effectively in the same state until successfully
   completed or an error occurs.

   These are states that the Client initiates; either Client or Server
   may discontinue the transaction and revert to COMMAND or READY mode.

   (put an example transaction here)

6. Client/Server Interaction.

   Certain commands and states are dependent on specific Client
   requests. For instance, a Server should deny a LIST or GET request if
   a Client has not said HELO/EHLO. Clients should expect clear
   responses and explainatory error messages from a Server.

   Note that you may wish to have more complex commands in your VMSP
   implementation: the following commands are the reference VMSP
   protocol elements, and extensions (EVMSP) should be made available to
   clients requesting them by an EHLO command, the same as ESMTP.
   Although the AUTH command belongs in that list of extended commands
   it is NOT an extension to VMSP, but is a DEFAULT.




Dwyer                        PenguinFriends                     [Page 5]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   Client requests that explicitly alter server data may require the
   server to protect the transaction from other clients.

   In the following sections, a WORD is a command, a <word>
   is an mandatory parameter and a [word] is an optional parameter,
   although missing [words] may still result in an error.

6.1 Client Requests.

   Standard client requests:

   HELO <hostname>
   EHLO <hostname>

   Status: Required
   Effect: Logging, Authentication, Protocol Extensions.
   Description: Begins the protocol between a VC and a VS.

   These introductory requests are required in any case for auditing
   purposes, but clients may need to take note of specific extensions.
   EHLO is mandatory for clients wishing to authenticate. The ident
   protocol is used to identify the client, but the server is under no
   obligation to trust the resulting information. The hostname parameter
   is mandatory.


   LIST

   Status: Optional
   Effect: Logging, Informational
   Description: Requests a list of items and costs from a server.

   There is no requirement for a VMSP server to have a standard
   compliment of items, therefore, although optional, clients are very
   likely to need to list the server's wares to make an informed
   decision.


   GET <item>

   Status: Optional
   Effect: Logging, Internal Data alteration
   Description: Requests a specific item from the server.

   In the existing implementation, if the server has the item requested,
   it will "give" the item to the client and alter the amount of items
   and the internal bank balance. The item parameter is mandatory.




Dwyer                        PenguinFriends                     [Page 6]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   AUTH <authentication-mechanism>

   Status: Required for explicit data alteration.
   Effect: Logging, Administration
   Description: Requests an authentication protocol transaction.

   Although [CRAM-MD5] is used, CRAM-SHA1, or another hash algorithm can
   be listed. Other authentication mechanisms are also possible, but
   should be applicable within the [SASL] protocol for ease of
   implementation in both clients and servers.


   HELP [topic]

   Status: Optional
   Effect: Logging, Informational
   Description: Requests available commands; optional information on a
                specific command.

   QUIT

   Status: Required
   Effect: Logging, end of transaction
   Description: ends the client/server connection.

   Mandatory for finishing the protocol transaction. Clients that do not
   QUIT in a regular manner are Bad Clients(tm) and may need to be
   barred.


   Authenticated client requests:
   These are suggestions only. In many cases, it is likely that the
   variety of server implementations will exclude these or include many
   more. Suggestions welcome.


   STATUS

   Status: Optional
   Effect: Logging, Administration
   Description: Request server status and statistics

   STATUS should return useful statistics to the client, such as uptime,
   items in need of replenishment, hourly/daily/monthly usage, how much
   (virtual?) money has been made on specific items, etc. This is
   particularly helpful to remote administrators who may not otherwise
   have access to the server logs.




Dwyer                        PenguinFriends                     [Page 7]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   ADD <item> <cost> <amount>

   Status: Optional
   Effect: Logging, explicit data alteration.
   Description: Requests addition of a new item.

   VMSP servers have no limit on the number of items, or types of items
   they may wish to offer, except as limited by data file format. In the
   reference implementation, items may not have whitespace within their
   names, for example, but there is no effective limit on the number of
   items. The item, cost and amount parameters are mandatory.


   DEL <item>

   Status: Optional
   Effect: Logging, explicit data alteration.
   Description: Requests removal of a specific item

   When deleting an item, deleting its associated data (cost and amount)
   is assumed by the server. The item parameter is mandatory.


   ROB <+/- amount>

   Status: Optional
   Effect: Logging, explicit data alteration.
   Description: Requests an alteration of the current bank total.

   ROB should allow a client to add or subtract from the current bank
   total. A negative total is an error, and the server should maintain a
   zero total in such cases. Bad Clients should not be allowed NEAR this
   command. The amount parameter is mandatory.


   ALTER <item> [name] [+/- cost] [+/- amount]

   Status: Optional
   Effect: Logging, explicit data alteration
   Description: Change an item in the server's database.

   Optionally alter an item in place, by changing its name, cost or
   amount. The item for which change is requested is a mandatory
   parameter.


6.2 Server Responses.




Dwyer                        PenguinFriends                     [Page 8]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   The following are the recommended server response codes for the
   current protocol version of VMSP:

   220 [FQDN] VMSP server [version] ready

   Returned: on successful client connection
   Parameters: server must include its fully qualified domain name and
   version.

   AUTH

   501 Syntax: AUTH authentication-type

   Returned: to a bad authentication request argument.

   501 Incomplete authorization.

   Returned: to client returning a "*" to challenge string, indicating
   discontinuation of the protocol.

   501 Authorization data error.

   Returned: on a bad client challenge response.

   503 Duplicate AUTH.

   Returned: to a client attempting to authenticate again within the
   same session.

   504 No AUTH without EHLO.

   Returned: to a client attempting to authenticate without extended
   introduction (EHLO).

   505 Bad AUTH type.

   Returned: to a client attempting to use a non-existent
   authentication-type.

   535 Authentication failed.

   Returned: to a client challenge response which fails authentication.

   334 <challenge string>

   Returned: to a successful AUTH request.
   Parameters: a base64-encoded challenge as documented in [SASL]




Dwyer                        PenguinFriends                     [Page 9]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   235 Authentication successful.

   Returned: to a succesfully authenticated client.

   EHLO

   501 Syntax: EHLO hostname

   Returned: to a bad EHLO request argument.

   503 Duplicate EHLO
   503 Duplicate HELO

   Returned: if client already introduced via HELO/EHLO

   250-[FQDN] Hello unknown user
   250-...[available extended commands]
   250 HELP

   Returned: successful, but not identified via ident request.
   Parameters: server must supply fully-qualified domain name, and a
   list of available extended client commands.
   Note: this does NOT preclude successful client AUTH requests, but
   merely indicates that the ident request failed.

   250-[FQDN] Hello [userid]@[remote fqdn], pleased to meet you.
   250-...[available extended commands]
   250 HELP

   Returned: successful and identified via ident request.
   Parameters: server must supply fully-qualified domain name, the
   userid as returned from the ident request and the fully-qualified
   domain name of the remote host.

   GET

   501 Syntax: GET item

   Returned: to a bad GET request argument.

   421 No <item> left

   Returned: when the machine is out of <item>
   Parameters: the item which has run out.

   423 No such <item>

   Returned: when the machine doesn't have the item requested.



Dwyer                        PenguinFriends                    [Page 10]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   Parameters: the item unsuccessfully requested.

   256 Enjoy your <item>

   Returned: on successful request of an item
   Parameters: the item successfully requested.

   HELO

   501 Syntax: HELO hostname

   Returned: to a bad HELO request argument.

   503 Duplicate HELO
   503 Duplicate EHLO

   Returned: if client already introduced via HELO/EHLO

   250 [FQDN] Hello unknown user

   Returned: successful, but not identified via ident request.
   Parameters: server must include fully-qualified domain name.
   Note: this response does NOT preclude a successful AUTH request,
   merely that the ident request failed.

   250 [FQDN] Hello [userid]@[remote fqdn], pleased to meet you

   Returned: successful, and identified via ident request.
   Parameters: server must include fully-qualified domain name, the
   userid returned from the ident request and the fully-qualified domain
   name of the remote host.

   HELP

   214-This is [server version]
   214-Topics:
   214- ....[help commands]
   214 End of HELP info

   Returned: on non-argument version of client help request.
   Parameters: server must supply server version and a list of available
   client commands.

   214-[topic]
   214- ...[topic information]
   214 End of HELP info

   Returned: on successful argument form of client help request.



Dwyer                        PenguinFriends                    [Page 11]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   Parameters: the help topic, and the topic information.

   504 topic [item] unknown

   Returned: on failed argument to client help request.
   Parameters: server must supply failed argument.

   LIST

   501 Syntax: LIST

   Returned: on client attempt to give arguments to LIST

   504 No client LIST without HELO
   504 No admin LIST without EHLO

   Returned: on client attempt to LIST without HELO/EHLO having
   successfully completed.

   252-LIST
   252- Bank [amount]
   252- [machine items, item costs, item amounts]
   252 End of LIST

   Returned: on successful admin LIST request.
   Parameters: current bank amount, and a list of items, their costs,
   and their respective amounts.

   254-LIST
   254- [items, costs]
   254 End of LIST

   Returned: on successful client LIST request.
   Parameters: current items, and their costs.
   Note: this version of the protocol does not supply the respective
   amounts of each item. This is meant to be a surprise when the client
   attempts to get them.

   NOOP

   501 Syntax: NOOP

   Returned: on client attempt to give arguments to NOOP

   250 Ok

   Returned: on successful NOOP request.




Dwyer                        PenguinFriends                    [Page 12]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   QUIT

   221 [FQDN] closing connection

   Returned: on successful client disconnection
   Parameters: the fully-qualified domain name of server

7. Conclusions

   The general framework of SMTP/ESMTP has been useful for development
   of this protocol, but there are a number of outstanding issues:

      - number of, and implementation of acceptable authentication
        mechanisms.
      - variety in implementation of administration commands.
      - actual payment mechanisms for vendor machine items.
      - no server chaining: e.g. getting an item via a server request to
        another server.
      - internationalisation (including [RFC1893] codes)

   The reference implementation of client and server for this protocol
   was written for Python v2.0, which provided a fast prototyping
   environment.

8. Security Considerations.

   Security is only a consideration if you desire anything other than
   simple client-server interaction. Security only becomes desireable
   when administration does. The HMAC scheme suggested in this protocol
   is by no means the only one that could be adopted; in particular, it
   still has the IMAP4 AUTH scheme failing of requiring a login + hash
   shared secret to be stored by both client and server.

9. Acknowlegements

   Barry Warsaw <bwarsaw@beopen.com> for his interesting Python
   implementation of an smtp proxy server which gave me the idea for a
   VMSP implementation. Rob <rob@jam.rr.com> for supporting a VMSP
   specification at all.

10. References.

   [IDENT]     St. Johns, M., "Identification Protocol", RFC 1413,
               February 1993.

   [CRAM-MD5]  Klensin, J., Catoe, R. and P. Krumviede "IMAP/POP
               AUTHorize Extension for Simple Challenge/Response", RFC
               2195,September 1997.



Dwyer                        PenguinFriends                    [Page 13]

Internet-Draft  Vendor Machine Simulation Protocol (VMSP)  19 April 2001


   [HMAC]      Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for
               Message Authentication", RFC 2104, February 1997.

   [RFC1893]   Vaudreuil, G., "Enhanced Mail System Status Codes", RFC
               1893, January 1996.

   [SASL]      Myers, J., "Simple Authentication and Security Layer
               (SASL)", RFC 2222, October 1997.

   [SMTP]      Postel, J., "Simple Mail Transfer Protoocl", STD 10, RFC
               821, USC/Information Sciences Institute, August 1982.

   [SMTP AUTH] Myers, J., "SMTP Service Extension for Authentication",
               RFC 2554, March 1999.

11. Author's Address

   Sean Dwyer
   PenguinFriends
   105 McIvor Rd
   Bendigo, VIC AUSTRALIA 3550

   EMail: ewe2@can.org.au




























Dwyer                        PenguinFriends                    [Page 14]

