[Docs] [txt|pdf] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 RFC 4154

Trade Working Group                                          July 2001
INTERNET-DRAFT                                         Masayuki Terada
                                                           Ko Fujimura
Expires: January 2002                                              NTT

  Voucher Trading System Application Programming Interface (VTS-API)
               <draft-ietf-trade-voucher-vtsapi-00.txt>


Status of This Document

 This document is an Internet-Draft and is in full conformance with
 all provisions of Section 10 of RFC2026.

 Internet-Drafts are working documents of the Internet Engineering
 Task Force (IETF), its areas, and its working groups.  Note that
 other groups may also distribute working documents as Internet-
 Drafts.

 Internet-Drafts are draft documents valid for a maximum of six months
 and may be updated, replaced, or obsoleted 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 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.

 Distribution of this document is unlimited. Please send comments to
 the TRADE  working group at <ietf-trade@lists.elistx.com>, which may
 be joined by sending a message with subject "subscribe" to <ietf-
 trade-request@lists.elistx.com>.

 Discussions of the TRADE working group are archived at
 http://lists.elistx.com/archives/ietf-trade.


Abstract

   This document specifies the Voucher Trading System Application
   Programming Interface (VTS-API). The VTS-API allows a wallet or other
   application to issue, transfer, and redeem vouchers in a uniform
   manner independent of the VTS implementation. The VTS is a system to
   securely transfer vouchers, e.g., coupons, tickets, loyalty points,
   and gift certificates; this process is often necessary in the course
   of payment and/or delivery transactions.







M. Terada and K. Fujimura                                       [Page 1]

INTERNET-DRAFT                     VTS-API                     July 2001

Table of Contents

   Status of this Memo  . . . . . . . . . . . . . . . . . . . . . . .  1
   Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
   1.      Introduction . . . . . . . . . . . . . . . . . . . . . . .  3
   2.      Processing Model . . . . . . . . . . . . . . . . . . . . .  3
   3.      Design Overview  . . . . . . . . . . . . . . . . . . . . .  5
   4.      Concepts . . . . . . . . . . . . . . . . . . . . . . . . .  5
   5.      Interface Definitions  . . . . . . . . . . . . . . . . . .  6
   5.1     VTSManager . . . . . . . . . . . . . . . . . . . . . . . .  6
   5.1.1   getParticipantRepository . . . . . . . . . . . . . . . . .  7
   5.1.2   getVoucherComponentRepository  . . . . . . . . . . . . . .  7
   5.2     ParticipantRepository  . . . . . . . . . . . . . . . . . .  7
   5.2.1   lookup . . . . . . . . . . . . . . . . . . . . . . . . . .  8
   5.3     Participant  . . . . . . . . . . . . . . . . . . . . . . .  8
   5.3.1   getIdentifier  . . . . . . . . . . . . . . . . . . . . . .  8
   5.3.2   getVTSAgent  . . . . . . . . . . . . . . . . . . . . . . .  8
   5.4     VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . .  8
   5.4.1   login  . . . . . . . . . . . . . . . . . . . . . . . . . .  9
   5.4.2   logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10
   5.4.3   prepare  . . . . . . . . . . . . . . . . . . . . . . . . . 10
   5.4.4   issue  . . . . . . . . . . . . . . . . . . . . . . . . . . 11
   5.4.5   transfer . . . . . . . . . . . . . . . . . . . . . . . . . 11
   5.4.6   consume  . . . . . . . . . . . . . . . . . . . . . . . . . 12
   5.4.7   present  . . . . . . . . . . . . . . . . . . . . . . . . . 13
   5.4.8   cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 13
   5.4.9   resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14
   5.4.10  getContents  . . . . . . . . . . . . . . . . . . . . . . . 14
   5.4.11  getSessions  . . . . . . . . . . . . . . . . . . . . . . . 15
   5.4.12  addReceptionListener . . . . . . . . . . . . . . . . . . . 15
   5.4.13  removeReceiptListener  . . . . . . . . . . . . . . . . . . 15
   5.5     Session  . . . . . . . . . . . . . . . . . . . . . . . . . 16
   5.5.1   getIdentifier  . . . . . . . . . . . . . . . . . . . . . . 16
   5.5.2   getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 16
   5.5.3   getSender  . . . . . . . . . . . . . . . . . . . . . . . . 16
   5.5.4   getReceiver  . . . . . . . . . . . . . . . . . . . . . . . 17
   5.5.5   isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 17
   5.5.6   isActivated  . . . . . . . . . . . . . . . . . . . . . . . 17
   5.5.7   isSuspended  . . . . . . . . . . . . . . . . . . . . . . . 17
   5.5.8   isCompleted  . . . . . . . . . . . . . . . . . . . . . . . 17
   5.6     Voucher  . . . . . . . . . . . . . . . . . . . . . . . . . 17
   5.6.1   getIssuer  . . . . . . . . . . . . . . . . . . . . . . . . 18
   5.6.2   getPromise   . . . . . . . . . . . . . . . . . . . . . . . 18
   5.6.3   getCount . . . . . . . . . . . . . . . . . . . . . . . . . 18
   5.7     VoucherComponentRepository . . . . . . . . . . . . . . . . 18
   5.7.1   regist   . . . . . . . . . . . . . . . . . . . . . . . . . 18
   5.8     VoucherComponent . . . . . . . . . . . . . . . . . . . . . 19
   5.8.1   getDocument  . . . . . . . . . . . . . . . . . . . . . . . 19
   5.9     ReceptionListener  . . . . . . . . . . . . . . . . . . . . 20
   5.9.1   arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 20
   5.10    Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 20
   6.      Example Code . . . . . . . . . . . . . . . . . . . . . . . 21
   7.      Security Considerations  . . . . . . . . . . . . . . . . . 22

M. Terada and K. Fujimura                                       [Page 2]

INTERNET-DRAFT                     VTS-API                     July 2001

   8.      Acknowledgement  . . . . . . . . . . . . . . . . . . . . . 23
   9.      References . . . . . . . . . . . . . . . . . . . . . . . . 23
   10.     Author's Address . . . . . . . . . . . . . . . . . . . . . 23

1. Introduction

   This document specifies the Voucher Trading System Application
   Programming Interface (VTS-API). The motivation and background of the
   Voucher Trading System (VTS) are described in Requirements for
   Generic Voucher Trading [GVT].

   A voucher is a logical entity that represents a certain right and is
   logically managed by the VTS. A voucher is generated by the issuer,
   traded among users, and finally collected using VTS. The terminology
   and model of the VTS are also described in [GVT].

   The VTS-API allows a caller application to issue, transfer, and
   redeem vouchers in a uniform manner independent of the VTS
   implementation.  Several attempts have been made at providing a
   generic payment API. Java Commerce Client [JCC] and Generic Payment
   Service Framework [GPSF], for example, introduce a modular wallet
   architecture that permits diverse types of payment modules to be
   added as plug-ins and supports both check-like/cash-like payment
   models. This document is inspired by these approaches but the scope
   of this document is limited to the VTS model, in which cash-like
   payment model is assumed and vouchers are directly or indirectly
   transferred between sender (transferor) and receiver (transferee) via
   the VTS. This document is not intended to support API for SET,
   e-check or other payment schemes that do not fit the VTS model.

   Unlike the APIs provided in JCC and GPSF, which are designed to
   transfer only monetary values, this API enables the transfer of a
   wide-range of values through the use of XML-based Generic Voucher
   Language [GVL]. The monetary meaning of the voucher is interpreted by
   the upper application layer using the information described in the
   language. This approach makes it possible to provide a simpler API in
   the voucher-transfer layer and enhances runtime efficiency.

   The API specification in this document is described in the Java
   language syntax. Bindings for other programming languages are to be
   completed in a future version of this document or separate related
   specifications.  [Editor's note: Language independent interface
   definitions, e.g., CORBA IDL, can be used if needed, but we are not
   sure if they atr really language independent.]

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
   this document are to be interpreted as described in [RFC 2119]

2. Processing Model

   This section provides the processing model in which the VTS-API is
   used.  Most of the text in this section has been taken from the

M. Terada and K. Fujimura                                       [Page 3]

INTERNET-DRAFT                     VTS-API                     July 2001

   Generic Voucher Language specification [GVL].

   There are several ways of implementing VTS. For discount coupons or
   event tickets, for example, the smart-card-based decentralized
   offline VTS is often preferred, whereas for bonds or securities,
   the centralized online VTS is preferred. It is impractical to
   define standard protocols for issuing, transferring, or redeeming
   vouchers at this moment.

   To provide implementation flexibility, this document assumes a
   modular wallet architecture that allows multiple VTS to be added as
   plug-ins.  In this architecture, instead of specifying a standard
   voucher transfer protocol, two specifications, i.e., Voucher
   Component and VTS-API specifications, are standardized (Figure 1).

   Sender wallet/Issuing system      Receiver wallet/Collecting system
   +---------------------------+       +---------------------------+
   |                           |       |                           |
   |  |                    Voucher Component                    |  |
   |  |  (Specifies Issuer, Promise, Holder, and VTS Provider)  |  |
   |  |-------------------------------------------------------->|  |
   |  |                        |       |                        |  |
   |  |         Intention to receive and payment (option)       |  |
   |  |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - |  |
   |  |                        |       |                        |  |
   |  |                        |       |                        |  |
   |  | Issue/transfer/  VTS   |       |   VTS      Register    |  |
   |  | redeem request   plug-in       |   plug-in  Listener(*1)|  |
   |  |------------------>|    |       |    |<------------------|  |
   |  | (VTS API)         |<- - - - - - - ->|         (VTS API) |  |
   |  |                   | VTS-specific    |                   |  |
   |  |                   | protocol if VTS |                   |  |
   |  |                   | is distributed  |                   |  |
   |  |  Result           |<- - - - - - - ->|       Notify(*2)  |  |
   |  |<------------------|    |       |    |------------------>|  |
   +---------------------------+       +---------------------------+
   (*1) Registration is optional. Note also that the VTS plug-ins are
        usually pre-registered when the wallet or collecting system
        is started.
   (*2) If a listener is registered.

           Figure 1. Wallet architecture with VTS plug-ins

   After sender and receiver agree on what vouchers are to be traded and
   which VTS is to be used, the issuing system or wallet system requests
   the corresponding VTS plug-in to permit the issue, transfer, or
   redeem transactions to be performed via the VTS-API. The VTS then
   rewrites the ownership of the vouchers using the VTS-specific
   protocol. Finally, a completion event is sent to the wallet systems
   or issuing/collecting systems.

   This document describes the VTS-API specification. See [GVL] for the
   Voucher Component specification.

M. Terada and K. Fujimura                                       [Page 4]

INTERNET-DRAFT                     VTS-API                     July 2001


3. Design Overview

   We have adopted the following approach to specify the VTS-API.

   1) Provide an abstract and uniform API that encapsulates the VTS
      implementation. For example, a common API is provided for both
      centralized and decentralized VTS. It brings more freedom of VTS
      selection for issuers and application developers.

   2) To provide an abstract and uniform API, this document introduces
      an interface called VTSAgent that is associated with a holder and
      provides methods to manipulate vouchers held by its holder.
      Vouchers are accessed through the methods provided by the
      VTSAgent.

   3) Use existing standards for the VTS branding mechanism
      (negotiation).  This document assumes that the VTS to be used for
      sending a voucher has settled before calling the VTS-APIs.
      Negotiation can be done within the upper application layer using
      other standards, e.g., [IOTP] or [ECML], if necessary.

   4) Support only push-type voucher transfer interface in which voucher
      transfer session is initiated by the transferor side. Pull-type
      voucher transfer interface can be implemented on top of the
      push-type VTS interface at application level.

4. Concepts

   The VTS-API consists of the following interfaces. A VTS is required
   to implement all of the interfaces except ReceiptionLister, which
   is intended to be implemented by wallets or other applications that
   use VTS.

  VTSManager

   Provides the starting point to use a VTS plug-in.  All of the
   objects needed to manipulate vouchers can be directly or indirectly
   acquired via the VTSManager.  A VTSManager maintains the two
   repositories; a ParticipantRepository and a
   VoucherComponentRepository described below.

  ParticipantRepository

   Provides the access points of Participants, which are to be trading
   partners. A ParticipantRepository maintains Participants and acts as
   an "address book" of trading partners.

  Participant

   Represents a participant (such as issuers, holders, and
   collectors). A Participant knows how to obtain the corresponding
   VTSAgent described below.

M. Terada and K. Fujimura                                       [Page 5]

INTERNET-DRAFT                     VTS-API                     July 2001


  VTSAgent (extends Participant)

   Provides the access point of vouchers in Valid Voucher Set (VVS)
   that is logically managed by VTS.  A VTSAgent provides a means of
   manipulating vouchers held by its holder; basic trading methods,
   i.e., issue, transfer, consume, and present. Before calling trading
   methods, the application must create a Session which is described
   below.

  Session

   Represents the logical connection established by the trade.  A
   Session has references to two Participants, i.e., the sender and the
   receiver.  After trading methods are called using a Session, the
   Session holds a reference to the Vouchers to be traded.

  Voucher

   Represents one or more vouchers of which all of the issuer part and
   promise part of vouchers are the same. A Voucher holds references to
   the Participant (issuer) who issued the voucher and a
   VoucherComponent (promise) which is described below.

  VoucherComponent

   Represents a Voucher Component described in [GVL]. It defines the
   promise part of the voucher.

  VoucherComponentRepository

   Provides the access points of VoucherComponents. A
   VoucherComponentRepository maintains VoucherComponents and acts as a
   "voucher type book" managed by the VTS. This document assumes that a
   set of VoucherComponents has been acquired and stored in this
   repository. Delivery of VoucherComponents is beyond the scope of this
   document. It may be delivered within the VTS from the trading
   partners or manually acquired from a trusted third party (See Section
   3 of [GVL]).

  ReceptionListener

   Provides a listener function with regard to the receipt of a voucher
   by VTSAgent to wallets or other applications that implement this
   interface.  (This interface may not be implemented as part of VTS)

5. Interface Definitions

   The interfaces defined in this document reside in the package named
   "org.ietf.vts".  Wallets or other applications that use this
   API,should import this package as "import org.ietf.vts.*;".

5.1 VTSManager

M. Terada and K. Fujimura                                       [Page 6]

INTERNET-DRAFT                     VTS-API                     July 2001


  public interface VTSManager

   Provides the starting point to use a VTS plug-in.

   All of the objects needed to manipulate vouchers can be directly or
   indirectly acquired via a VTSManager, so that wallets or other
   applications can make the VTS available by instantiating an object
   implementing this interface.

   Classes that implement this interface should have a public default
   constructor (a constructor without any parameters) to make the VTS
   pluggable.

5.1.1 getParticipantRepository

  public ParticipantRepository getParticipantRepository()

   Returns a repository that maintains Participants.

  Returns:

   the ParticipantRepository of the VTS, or null if no
   ParticipantRepository is available.

5.1.2 getVoucherComponentRepository

  public VoucherComponentRepository getVoucherComponentRepository()

   Returns a repository that maintains VoucherComponents.

  Returns:

   the VoucherComponentRepository of the VTS, or null if no
   VoucherComponentRepository is available.

5.2 ParticipantRepository

  public interface ParticipantRepository

   Provides the access points of Participants. A ParticipantRepository
   maintains Participants and acts as an "address book" of trading
   partners.

   The object implementing this interface maintains Participants (or
   holds a reference to an object maintaining Participants), which are
   to be trading partners.

   The implementation of ParticipantRepository may be either (an adaptor
   to) "yellow pages" which is a network-wide directory service like
   LDAP, or "pocket address book" which maintains only personal
   acquaintances.


M. Terada and K. Fujimura                                       [Page 7]

INTERNET-DRAFT                     VTS-API                     July 2001

5.2.1 lookup

  public Participant lookup(String id)

   Retrieves the participant that has the specified id.

  Returns:

   the participant associated with the specified id or null if the id
   is null or the corresponding participant cannot be found.

5.3 Participant

  public interface Participant

   Represents the participants (such as issuers, holders, and
   collectors).

   This interface is used as representation of the trade partners and
   issuers of vouchers.  Anyone can retrieve objects implementing
   Participant from the participant repository.

5.3.1 getIdentifier

  public String getIdentifier()

   Returns the identifier of the participant.  Each participant must
   have a unique identifier.

   The identifier can be used for looking up and retrieving the
   participant via the ParticipantRepository.

   The format of the identifier is implementation-specific.

  Returns:

   the identifier string of the participant.

5.3.2 getVTSAgent

  VTSAgent getVTSAgent()

   Returns a VTSAgent, whose identifier is the same as the identifier of
   the participant.

  Returns:

   an object implementing VTSAgent.

5.4 VTSAgent

  public interface VTSAgent extends Participant


M. Terada and K. Fujimura                                       [Page 8]

INTERNET-DRAFT                     VTS-API                     July 2001

   Represents contact points to access vouchers in Valid Voucher Set
   (VVS) that is managed by the VTS.

   Each VTSAgent is associated with a holder and provides a means for
   managing vouchers owned by the holder.  The holder must be
   authenticated using login() method before be called by any other
   method, or VTSSecurityException will be issue.

   Before calling any trading method, i.e., issue(), transfer(),
   consume(), and present(), the application must establish a session by
   the prepare() method.

   Sessions may often be suspended due to network failure when the
   voucher is sent via a network.  The suspended sessions can be
   restarted by the resume() method. Details on the state management of
   a session are described in Section 5.5.

5.4.1 login

  public void login(String passphrase)
         throws VTSException

   Authenticates the VTSAgent.  The passphrase is specified if the VTS
   requires it for authentication, otherwise it must be null. Nothing is
   performed if the VTSAgent has already been logged-in. The
   authentication scheme is implementation-specific. Examples of the
   implementation are as follows:

   1) Vouchers are managed on a remote centralized server (central VVS),
      and the server requires a password to login. In this case, the
      application may prompt the user to input the password and can be
      given to the VTSAgent through this method.

   2) Vouchers are managed on a remote centralized server (central VVS);
      they require challenge-and-response authentication using
      smartcards held by users. In this case, the passphrase may be null
      since access to the smartcard can be done without contacting the
      application or user, i.e., the VTSAgent receives the challenge
      from the server, sends the challenge to the smartcard (within the
      VTS), and returns the response from the smartcard to the server.
      Note that a PIN to unlock the smartcard may be given through this
      method depending on the implementation.

   3) Each user holds their own smartcard in which their own vouchers
      are stored (decentralized VVS). In this case, the passphrase may
      be null since no authentication is required. Note that a PIN to
      unlock the smartcard may be given through this depends on the
      implementation.

  Throws:

   VTSSecurityException - if authentication fails.


M. Terada and K. Fujimura                                       [Page 9]

INTERNET-DRAFT                     VTS-API                     July 2001

5.4.2 logout

  public void logout()
         throws VTSException

   Voids the authentication performed by the login() method.

   After calling this method, calling any other method (except
   login()) will cause VTSSecurityException.

   The VTSAgent can login again by the login() method.

  Throws:

   VTSSecurityException - if the VTSAgent is not authenticated
     correctly.

5.4.3 prepare

  public Session prepare(Participant receiver)
         throws VTSException

   Establishes a session that is required for trading vouchers. The
   trading partner who receives the vouchers is specified as receiver.
   The vouchers to be traded will be specified later (when a trading
   method is called).

   The establishment of a session is implementation-specific. An
   implementation that has a central VVS may start a transaction, while
   other implementations that have decentralized VVS may get, from the
   receiver, the challenge needed to authenticate the sender during the
   establishment of the session.

   If the VTSAgent has no ability to establish a session with the
   specified receiver (permanent error), the VTSAgent throws an
   InvalidParticipantExeption. If the VTSAgent can not establish a
   session due to network failure (transient error), the VTSAgent throws
   a CannotProceedException.

  Parameters:

   receiver - the trading partner who receives vouchers.

  Returns:

   an established session whose state is "prepared" (see Section 5.5).

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.
   InvalidParticipantException - if the specified participant is
     invalid.

M. Terada and K. Fujimura                                      [Page 10]

INTERNET-DRAFT                     VTS-API                     July 2001

   CannotProceedException - if the preparation of the session is
     aborted (e.g. network failures).

5.4.4 issue

  public void issue(Session session,
                    VoucherComponent promise,
                    java.lang.Number num)
         throws VTSException

   Issues vouchers.  This method creates the specified number of
   vouchers <this, promise, receiver> and adds them to the VVS.  Note
   that receiver is specified when the prepare() method is
   called. Nothing is performed if the specified number is 0.

   The session MUST be "prepared" when calling this method.  The state
   of the session will be "activated" when the vouchers are created, and
   it will be "completed" when the transaction is successfully completed
   or "suspended" if the transaction is interrupted abnormally (e.g.,
   network failures).

  Parameters:

   session - the session used by the issue transaction.
   promise - the promise part of the voucher.
   num - the number of vouchers to be issued.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
    correctly.
   InvalidStateException - if the session is not "prepared".
   CannotProceedException - if the transaction cannot be successfully
     completed.

5.4.5 transfer

  public void transfer(Session session,
                       Participant issuer,
                       VoucherComponent promise,
                       java.lang.Number num)
         throws VTSException

   Transfers vouchers.  This method rewrites the specified number of
   vouchers <issuer, promise, this> to <issuer, promise, receiver> in
   the VVS. Note that receiver is specified when the prepare() method is
   called. The VTSAgent must have sufficient vouchers in the VVS.
   Nothing is performed if the specified number is 0.

   The session MUST be "prepared" when calling this method.  The state
   of the session will be "activated" when the voucher are retrieved
   from the sender, and it will be "completed" when the transaction is
   successfully completed or "suspended" if the transaction is

M. Terada and K. Fujimura                                      [Page 11]

INTERNET-DRAFT                     VTS-API                     July 2001

   interrupted abnormally (e.g., network failures).

   If null is specified for the issuer parameter, it indicates "any
   issuer".  This method selects vouchers to be transferred from the set
   of vouchers returned by the getContents(null, promise).

  Parameters:

   session - the session used by the transfer transaction.
   issuer - the issuer part of the voucher, or null.
   promise - the promise part of the voucher.
   num - the number of vouchers to be transferred.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.
   InsufficientVoucherException - if the VTSAgent doesn't have a
     sufficient number of vouchers to transfer.
   InvalidStateException - if the session is not "prepared".
   CannotProceedException - if the transaction cannot be successfully
     completed.

5.4.6 consume

  public void consume(Session session,
                      Participant issuer,
                      VoucherComponent promise,
                      java.lang.Number num)
         throws VTSException

   Consumes vouchers.  This method deletes the specified number of
   specified vouchers <issuer, promise, this> from the VVS. The VTSAgent
   must have sufficient vouchers in the VVS.  Nothing is performed if
   the specified number is 0.

   The session MUST be "prepared" when calling this method.  The state
   of the session will be "activated" when the vouchers are deleted, and
   it will be "completed" when the transaction is successfully completed
   or "suspended" if the transaction is interrupted abnormally (e.g.,
   network failures).

   If null is specified for the issuer parameter, it indicates "any
   issuer".  This method selects vouchers to be consumed from the set of
   vouchers returned by the getContents(null, promise).

  Parameters:

   session - the session used by the consume transaction.
   issuer - the issuer part of the voucher, or null.
   promise - the promise part of the voucher.
   num - the number of vouchers to be consumed.


M. Terada and K. Fujimura                                      [Page 12]

INTERNET-DRAFT                     VTS-API                     July 2001

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.
   InsufficientVoucherException - if the VTSAgent doesn't have a
     sufficient number of vouchers to consume.
   InvalidStateException - if the session is not "prepared".
   CannotProceedException - if the transaction cannot be successfully
     completed.

5.4.7 present

  public void present(Session session,
                      Participant issuer,
                      VoucherComponent promise,
                      java.lang.Number num)
         throws VTSException

   Presents vouchers.  This method shows that the sender has the
   specified number of vouchers <issuer, promise, this> in the VVS to
   the receiver of the session; No modification is performed to the
   VVS. The VTSAgent must have a sufficient vouchers in the VVS. Nothing
   is performed if the specified number is 0.

   The session MUST be "prepared" when calling this method.  The state
   of the session will be "activated" when the vouchers are retrieved,
   and it will be "completed" when the transaction is successfully
   completed or "suspended" if the transaction is interrupted abnormally
   (e.g., by network failures).

   If null is specified for the issuer parameter, it indicates "any
   issuer".  This method selects vouchers to be presented from the set
   of vouchers returned by the getContents(null, promise).

  Parameters:

   session - the session used by the present transaction.
   issuer - the issuer part of the voucher, or null.
   promise - the promise part of the voucher.
   num - the number of the voucher to be presented.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.
   InsufficientVoucherException - if the VTSAgent doesn't have a
     sufficient number of vouchers to present.
   InvalidStateException - if the session is not "prepared".
   CannotProceedException - if the transaction cannot be successfully
     completed.

5.4.8 cancel


M. Terada and K. Fujimura                                      [Page 13]

INTERNET-DRAFT                     VTS-API                     July 2001

  public void cancel(Session session)
         throws VTSException

   Releases the session.  "Prepared" sessions MUST be cancelled.  An
   implementation MAY be permitted to cancel "activated" or "suspended"
   sessions.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.
   InvalidStateException - if the state of the session isn't
     cancellable.

5.4.9 resume

  public void resume(Session session)
         throws VTSException

   Restarts the session. Only "suspended" sessions can be resumed.

   The state of the session will be re-"activated" immediately, and it
   will be "completed" when the transaction is successfully completed or
   "suspended" again if the transaction is interrupted abnormally (e.g.,
   network failures).

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.
   InvalidStateException - if the session is not "suspended".
   CannotProceedException - if the transaction cannot be successfully
     completed.

5.4.10 getContents

  public java.util.Set getContents(Participant issuer,
                                   VoucherComponent promise)
         throws VTSException

   Returns the set of vouchers whose issuer and promise both match the
   issuer and promise specified in the parameters.

   If null is specified for the issuer or promise parameter, it
   indicates "any issuer" or "any promise", respectively.  If null is
   specified for both parameters, this method selects all vouchers owned
   by the holder from the VVS.

  Returns:

   the set of vouchers held by the holder of the VTSAgent.

  Throws:

M. Terada and K. Fujimura                                      [Page 14]

INTERNET-DRAFT                     VTS-API                     July 2001


   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.

5.4.11 getSessions

  public java.lang.Set getSessions()
         throws VTSException

  Returns a set of not-completed sessions prepared by the VTSAgent.

  Returns:

   the set of sessions prepared by the VTSAgent and not
   yet completed.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.

5.4.12 addReceptionListener

  public void addReceiptListener(ReceiptListener l)
         throws VTSException

  Adds a ReceiptListener to the listener list.

   After a ReceiptListener l is registered by this method, l.arrive()
   will be called whenever the VTSAgent receives a voucher.

  Nothing is performed if the specified listener is null.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.

5.4.13 removeReceiptListener

  public void removeReceiptListener(ReceiptListener l)
         throws VTSException

   Removes a ReceiptListener from the listener list.

   Nothing is performed when the specified listener is null or not
   registered.

  Throws:

   VTSSecurityException - if the VTSAgent cannot be authenticated
     correctly.


M. Terada and K. Fujimura                                      [Page 15]

INTERNET-DRAFT                     VTS-API                     July 2001

5.5 Session

  public interface Session

   Represents the logical connection established by the trade. Sessions
   are established by VTSAgent#prepare().

   A session has four states: prepared, activated, suspended, and
   completed.  The initial state of a session is "prepared", and the
   session will be "activated" immediately when any of the trading
   methods of VTSAgent is called.  The "activated" session will be
   "completed" after the trading method is successfully completed. If
   the trading method is transiently failed (e.g. network failure), the
   session will be "suspended". Suspended sessions can be re-"activated"
   and restarted by calling VTSAgent#resume().

   A completed session may be disapeared from the VTSAgent; the session
   will be collected by the GC unless other objects keep its reference.

5.5.1 getIdentifier

  public String getIdentifier()

   Returns the identifier of the session.  The generation scheme of the
   identifier is implementation-specific. An implementation may use a
   transaction ID as the identifier of the session.

  Returns:

   the string of the identifier of the session.

5.5.2 getVoucher

  public Voucher getVoucher()

   Returns the voucher to be traded using the session, or returns null
   if the session has not been activated.

  Returns:

   the voucher to be traded or null if the state of the session is
   "prepared".

5.5.3 getSender

  public Participant getSender()

   Returns the sender of the session, i.e., the creator who prepared the
   session.

  Returns:

   the sender of the session.

M. Terada and K. Fujimura                                      [Page 16]

INTERNET-DRAFT                     VTS-API                     July 2001


5.5.4 getReceiver

  public Participant getReceiver()

   Returns the receiver of the session, i.e., the participant specified
   when preparing the session (by the VTSAgent#prepare() method).

  Returns:

   the receiver of the session.

5.5.5 isPrepared

  public boolean isPrepared()

   Verifies if the session is "prepared".

  Returns:

   true if the session is in "prepared" state, or false.

5.5.6 isActivated

  public boolean isActivated()

   Verifies if the session is "activated".

  Returns:

   true if the session is in "activated" state, or false.

5.5.7 isSuspended

  public boolean isSuspended()

   Verifies if the session is "suspended".

  Returns:

   true if the session is in "suspended" state, or false.

5.5.8 isCompleted

  public boolean isCompleted()

   Verifies if the session is "completed".

  Returns:

   true if the session is in "completed" state, or false.

5.6 Voucher

M. Terada and K. Fujimura                                      [Page 17]

INTERNET-DRAFT                     VTS-API                     July 2001


  public interface Voucher

   Represents voucher(s) described in [GVT].  An object implementing
   this interface can represent more than one voucher if all of the
   issuer part and the promise part of the vouchers are the same.

5.6.1 getIssuer

  public Participant getIssuer()

   Returns the issuer part of the voucher(s).

  Returns:

   the participant who issued the voucher(s).

5.6.2 getPromise

  public VoucherComponent getPromise()

   Returns the promise part of the voucher(s).

  Returns:

   the voucher component that defines the promise of the voucher.

5.6.3 getCount

  public java.lang.Number getCount()

   Returns the number of the voucher(s).

  Returns:

   the positive (>0) number of the voucher(s).

5.7 VoucherComponentRepository

  public interface VoucherComponentRepository

   Maintains VoucherComponents.

   An object implementing VoucherComponentRepository provides a means of
   retrieving the voucher components that are the promises of vouchers
   in the VVS.

   Before issuing a voucher, the promise of the voucher must be
   registered with this repository.  The repository can be implemented
   as either a network-wide directory service or personal storage like
   the ParticipantRepository.

5.7.1 regist

M. Terada and K. Fujimura                                      [Page 18]

INTERNET-DRAFT                     VTS-API                     July 2001


  public VoucherComponent regist(org.w3c.dom.Document document)

   Creates a voucher component associated with the specified DOM object
   and registers the voucher component with the repository.

   A voucher component of the voucher to be issued must be registered
   using this method.

   Nothing is performed (and the method returns null) if the specified
   document is null or the syntax of the document does not conform to
   the VTS.

  Returns:

   a registered voucher component associated with the
   specified document, or null if the document is null or has wrong
   syntax.

5.8 VoucherComponent

  public interface VoucherComponent

   Represents the voucher component that defines the promise of the
   voucher.

   Each VoucherComponent object has its own unique identifier, and it is
   associated with an XML document that describes the promise made by
   the issuer of the voucher, e.g., the goods or services can be claimed
   in exchange for redeeming the voucher.

   This interface can be implemented as sort of a "smart pointer" to the
   XML document.  An implementation may have a reference to a voucher
   component repository instead of the voucher component and retrieve
   the document dynamically from the repository when the getDocument()
   method is called.

5.8.1 getDocument

  public org.w3c.dom.Document getDocument()

   Returns a Document Object Model [DOM] representation of the document
   associated with the voucher component by the
   VoucherComponentRepository#regist() method.

   The DOM object to be returned may be retrieved from a
   VoucherComponentRepository on demand, instead of the VoucherComponent
   always keeping a reference to the DOM object.

  Returns:

   a DOM representation of the document assoiated with the voucher
   component.

M. Terada and K. Fujimura                                      [Page 19]

INTERNET-DRAFT                     VTS-API                     July 2001


  Throws:

   DocumentNotFoundException - if the associated DOM object cannot be
     retrieved.

5.9 ReceptionListener

  public interface ReceptionListener extends java.util.EventListener

   Provides a listener interface that provides notification that a
   VTSAgent has been received a voucher.

   When a voucher arrives at VTSAgent, the VTSAgent invokes arrive()
   method of each registered ReceptionListener.  ReceptionListeners can
   obtain a Session object, which contains information about the
   received voucher and the sender of the voucher.

   This interface is intended to provide a means of notifying a wallet
   that "You have new vouchers", so that this interface may be
   implemented by wallets or other applications using VTS.

5.9.1 arrive

  public void arrive(Session session)

   Provides notification of the arrival of a voucher.

   After the listener is registered to a VTSAgent (by the
   VTSAgent#addReceiptionListener() method), the VTSAgent invokes this
   method whenever it receives a voucher.

   The specified session is equivalent to the session used by the sender
   to trade the voucher.  The state of the session is "completed" when
   this method is called.

5.10 Exceptions

java.lang.Exception
  +-- VTSException
      +-- CannotProceedException
      +-- DocumentNotFoundException
      +-- InsufficientVoucherException
      +-- InvalidParticipantException
      +-- InvalidStateException
      +-- VTSSecurityException

  VTSException

   This is the superclass of all exceptions thrown by the methods in the
   interfaces constructs the VTS-API.

  CannotProceedException

M. Terada and K. Fujimura                                      [Page 20]

INTERNET-DRAFT                     VTS-API                     July 2001


   This exception is thrown when a trading is interrupted due to
   network failures or other errors.

  DocumentNotFoundException

   This exception is thrown when the document associated with a voucher
   component cannot be found.

  InsufficientVoucherException

   This exception is thrown when the number of the voucher is less than
   the number specified to trade.

  InvalidParticipantException

   This exception is thrown when the specified participant cannot be
   located.

  InvalidStateException

   This exception is thrown when the state of the session is invalid to
   proceed the operation.

  VTSSecurityException

   This exception is thrown when authentication fails or a method
   which requires authentication in advance is called without
   authentication.

6. Example Code

  // Issue a voucher

  VTSManager vts = new FooVTSManager();
  ParticipantRepository addrBook = vts.getParticipantRepository();
  VoucherComponentRepository vcr = vts.getVoucherComponentRepository();

  Participant you = addrBook.lookup("http://foo.bar/baz");
  VTSAgent me = addrBook.lookup("myName").getVTSAgent();

  VoucherComponent promise = vcr.regist(anXMLVoucherDocument);

  try {
    me.login();
    s = me.prepare(you);
    me.issue(s, promise, 1);
    me.logout();
  } catch (VTSException e) {
    System.err.println("Sorry!");
    e.printStackTrace();
  }


M. Terada and K. Fujimura                                      [Page 21]

INTERNET-DRAFT                     VTS-API                     July 2001

  // Transfer all my vouchers

  VTSManager vts = new FooVTSManager();
  ParticipantRepository addrBook = vts.getParticipantRepository();

  Participant you = addrBook.lookup("http://foo.bar/baz");
  VTSAgent me = addrBook.lookup("myName").getVTSAgent();

  try {
    me.login();
    Iterator i = me.getContents(null, null).iterator();

    while (i.hasNext) {
      Voucher v = (Voucher) i.next();
      s = me.prepare(you);
      me.transfer(s, v.getIssuer(), v.getPromise(), v.getCount());
    }

    me.logout();
  } catch (VTSException e) {
    System.err.println("Sorry!");
    e.printStackTrace();
  }

  // Register an incoming voucher notifier (biff)

  VTSManager vts = new FooVTSManager();

  ParticipantRepository addrBook = vts.getParticipantRepository();
  VTSAgent me = addrBook.lookup("myName").getVTSAgent();

  ReceiptionListener listener = new ReceiptionListener() {
    public void arrive(Session s) {
      System.out.println("You got a new voucher.");
    }
  };

  try {
    me.login();
    me.addReceiptionListener(listener);
    me.logout();
  } catch (VTSException e) {
    System.err.println("Sorry!");
    e.printStackTrace();
  }

7. Security Considerations

   This document assumes that the VTS plug-in is trusted. The caller
   application of a VTS should authenticate the VTS plug-in and bind it
   securely using the VTS Provider information specified in the Voucher
   Component. This document, however, does not specify any application
   authentication scheme and it is assumed to be specified by other

M. Terada and K. Fujimura                                      [Page 22]

INTERNET-DRAFT                     VTS-API                     July 2001

   related standards. [Editor's note: References are for further
   study. Until various VTS systems are deployed, it may be enough to
   manually check and install VTS plug-ins like other download
   applications.]

   To protect vouchers from being stolen, the VTSAgent must be
   authenticated securely. This document introduced a login/logout
   facility for this purpose (see Section 5.4).

8. Acknowledgement

   (tbs)

9. References

   [DOM] "Document Object Model (DOM), Level 1 Specification", October
   <http://www.w3.org/TR/REC-DOM-Level-1/>,1998.

   [DOMHash] H. Maruyama, K. Tamura, and N. Uramoto, "Digest Values
   for DOM (DOMHASH)", RFC 2803, 2000.

   [ECML] J. W. Parsons, "Electronic Commerce Modeling Language (ECML)
   Version 2 Specification", draft-ietf-trade-ecml2-spec-00.txt,
   2001.

   [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.),
   "SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854,
   Springer-Verlag, 2000.

   [GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher
   Language", draft-ietf-trade-voucher-lang-01.txt, 2001.

   [GVT] K. Fujimura, "Requirements for Generic Voucher Trading",
   draft-ietf-trade-drt-requirements-02.txt, 2001.

   [IOTP] D.  Burdett, "Internet Open Trading Protocol - IOTP Version
   1.0", RFC 2801, 2000.

   [JCC] Sun Microsystems Inc., "Java Commerce Client",
   <http://java.sun.com/products/commerce/>.

   [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
   Requirement Levels", BCP 14, RFC 2119, 1997.

10. Author's Address

   Masayuki Terada and Ko Fujimura
   NTT Corporation
   1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN
   Phone: +81-(0)468-59-3814
   Fax:   +81-(0)468-59-2241
   Email: terada@isl.ntt.co.jp, fujimura@isl.ntt.co.jp


M. Terada and K. Fujimura                                      [Page 23]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/