draft-ietf-trade-voucher-vtsapi-01.txt   draft-ietf-trade-voucher-vtsapi-02.txt 
Trade Working Group January 2002
Trade Working Group June 2002
INTERNET-DRAFT Masayuki Terada INTERNET-DRAFT Masayuki Terada
Ko Fujimura Ko Fujimura
Expires: July 2002 NTT Expires: December 2002 NTT
Voucher Trading System Application Programming Interface (VTS-API) Voucher Trading System Application Programming Interface (VTS-API)
<draft-ietf-trade-voucher-vtsapi-01.txt> <draft-ietf-trade-voucher-vtsapi-02.txt>
Status of This Document Status of This Document
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 10, line ? skipping to change at page 2, line 5
Abstract Abstract
This document specifies the Voucher Trading System Application This document specifies the Voucher Trading System Application
Programming Interface (VTS-API). The VTS-API allows a wallet or other Programming Interface (VTS-API). The VTS-API allows a wallet or other
application to issue, transfer, and redeem vouchers in a uniform application to issue, transfer, and redeem vouchers in a uniform
manner independent of the VTS implementation. The VTS is a system to manner independent of the VTS implementation. The VTS is a system to
securely transfer vouchers, e.g., coupons, tickets, loyalty points, securely transfer vouchers, e.g., coupons, tickets, loyalty points,
and gift certificates; this process is often necessary in the course and gift certificates; this process is often necessary in the course
of payment and/or delivery transactions. of payment and/or delivery transactions.
M. Terada and K. Fujimura [Page 1] Acknowledgements
The following persons, in alphabetic order, contributed substantially
to the material herein:
Donald Eastlake 3rd
Iguchi Makoto
Yoshitaka Nakamura
Ryuji Shoda
Table of Contents Table of Contents
Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1 Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 2
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
2. Processing Model . . . . . . . . . . . . . . . . . . . . . 3 2. Processing Model . . . . . . . . . . . . . . . . . . . . . 4
3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5
4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Interface Definitions . . . . . . . . . . . . . . . . . . 6 5. Interface Definitions . . . . . . . . . . . . . . . . . . 7
5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1.1 getParticipantRepository . . . . . . . . . . . . . . . . . 7 5.1.1 getParticipantRepository . . . . . . . . . . . . . . . . . 7
5.1.2 getVoucherComponentRepository . . . . . . . . . . . . . . 7 5.1.2 getVoucherComponentRepository . . . . . . . . . . . . . . 7
5.2 ParticipantRepository . . . . . . . . . . . . . . . . . . 7 5.2 ParticipantRepository . . . . . . . . . . . . . . . . . . 7
5.2.1 lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.2.1 lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.3 Participant . . . . . . . . . . . . . . . . . . . . . . . 8 5.3 Participant . . . . . . . . . . . . . . . . . . . . . . . 8
5.3.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 8 5.3.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 8
5.3.2 getVTSAgent . . . . . . . . . . . . . . . . . . . . . . . 8 5.3.2 getVTSAgent . . . . . . . . . . . . . . . . . . . . . . . 9
5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 15 5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 15
5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 15 5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 16
5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 16 5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 17
5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 16 5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 17
5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 17 5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 17
5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 18
5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 19
5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 19
5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 19
5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 19 5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 19
5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 19 5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 19
5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 19 5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 20
5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 20 5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 21
5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 20 5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 21
5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 21 5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 21
5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 21 5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 22
5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 22
M. Terada and K. Fujimura [Page 2]
5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 22 5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 22
6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 23 6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 23
7. Security Considerations . . . . . . . . . . . . . . . . . 24 7. Security Considerations . . . . . . . . . . . . . . . . . 24
8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . 24 8. References . . . . . . . . . . . . . . . . . . . . . . . . 25
9. References . . . . . . . . . . . . . . . . . . . . . . . . 24 9. Author's Address . . . . . . . . . . . . . . . . . . . . . 25
10. Author's Address . . . . . . . . . . . . . . . . . . . . . 25 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 26
1. Introduction 1. Introduction
This document specifies the Voucher Trading System Application This document specifies the Voucher Trading System Application
Programming Interface (VTS-API). The motivation and background of the Programming Interface (VTS-API). The motivation and background of the
Voucher Trading System (VTS) are described in Requirements for Voucher Trading System (VTS) are described in Requirements for
Generic Voucher Trading [VTS]. Generic Voucher Trading [VTS].
A voucher is a logical entity that represents a certain right and is 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, logically managed by the VTS. A voucher is generated by the issuer,
skipping to change at page 10, line ? skipping to change at page 4, line 8
transfer only monetary values, this API enables the transfer of a transfer only monetary values, this API enables the transfer of a
wide-range of values through the use of XML-based Generic Voucher wide-range of values through the use of XML-based Generic Voucher
Language [GVL]. The monetary meaning of the voucher is interpreted by Language [GVL]. The monetary meaning of the voucher is interpreted by
the upper application layer using the information described in the the upper application layer using the information described in the
language. This approach makes it possible to provide a simpler API in language. This approach makes it possible to provide a simpler API in
the voucher-transfer layer and enhances runtime efficiency. the voucher-transfer layer and enhances runtime efficiency.
The API specification in this document is described in the Java The API specification in this document is described in the Java
language syntax. Bindings for other programming languages may be language syntax. Bindings for other programming languages may be
completed in a future version of this document or separate related completed in a future version of this document or separate related
specifications. [Editor's note: Language independent interface specifications.
definitions, e.g., CORBA IDL, can be used if needed, but we are not
sure if they are really language independent.]
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in [RFC 2119] this document are to be interpreted as described in [RFC 2119]
M. Terada and K. Fujimura [Page 3]
2. Processing Model 2. Processing Model
This section provides the processing model in which the VTS-API is 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 used. Most of the text in this section has been taken from the
Generic Voucher Language specification [GVL]. Generic Voucher Language specification [GVL].
There are several ways of implementing VTS. For discount coupons or There are several ways of implementing VTS. For discount coupons or
event tickets, for example, the smart-card-based decentralized event tickets, for example, the smart-card-based decentralized
offline VTS is often preferred, whereas for bonds or securities, offline VTS is often preferred, whereas for bonds or securities,
the centralized online VTS is preferred. It is impractical to the centralized online VTS is preferred. It is impractical to
skipping to change at page 10, line ? skipping to change at page 5, line 15
(*2) If a listener is registered. (*2) If a listener is registered.
Figure 1. Wallet architecture with VTS plug-ins Figure 1. Wallet architecture with VTS plug-ins
After sender and receiver agree on what vouchers are to be traded and 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 which VTS is to be used, the issuing system or wallet system requests
the corresponding VTS plug-in to permit the issue, transfer, or the corresponding VTS plug-in to permit the issue, transfer, or
redeem transactions to be performed via the VTS-API. The VTS then redeem transactions to be performed via the VTS-API. The VTS then
rewrites the ownership of the vouchers using the VTS-specific rewrites the ownership of the vouchers using the VTS-specific
protocol. Finally, a completion event is sent to the wallet systems protocol. Finally, a completion event is sent to the wallet systems
M. Terada and K. Fujimura [Page 4]
or issuing/collecting systems. or issuing/collecting systems.
This document describes the VTS-API specification. See [GVL] for the This document describes the VTS-API specification. See [GVL] for the
Voucher Component specification. Voucher Component specification.
3. Design Overview 3. Design Overview
We have adopted the following approach to specify the VTS-API. We have adopted the following approach to specify the VTS-API.
1) Provide an abstract and uniform API that encapsulates the VTS 1) Provide an abstract and uniform API that encapsulates the VTS
skipping to change at page 10, line ? skipping to change at page 6, line 15
VoucherComponentRepository described below. VoucherComponentRepository described below.
ParticipantRepository ParticipantRepository
Provides the access points of Participants, which are to be trading Provides the access points of Participants, which are to be trading
partners. A ParticipantRepository maintains Participants and acts as partners. A ParticipantRepository maintains Participants and acts as
an "address book" of trading partners. an "address book" of trading partners.
Participant Participant
M. Terada and K. Fujimura [Page 5]
Represents a participant (such as issuers, holders, and Represents a participant (such as issuers, holders, and
collectors). A Participant knows how to obtain the corresponding collectors). A Participant knows how to obtain the corresponding
VTSAgent described below. VTSAgent described below.
VTSAgent (extends Participant) VTSAgent (extends Participant)
Provides the access point of vouchers in Valid Voucher Set (VVS) Provides the access point of vouchers in Valid Voucher Set (VVS)
that is logically managed by VTS. A VTSAgent provides a means of that is logically managed by VTS. A VTSAgent provides a means of
manipulating vouchers held by its holder; basic trading methods, manipulating vouchers held by its holder; basic trading methods,
i.e., issue, transfer, consume, and present. Before calling trading i.e., issue, transfer, consume, and present. Before calling trading
skipping to change at page 10, line ? skipping to change at page 7, line 14
ReceptionListener ReceptionListener
Provides a listener function with regard to the receipt of a voucher Provides a listener function with regard to the receipt of a voucher
by VTSAgent to wallets or other applications that implement this by VTSAgent to wallets or other applications that implement this
interface. (This interface may not be implemented as part of VTS) interface. (This interface may not be implemented as part of VTS)
5. Interface Definitions 5. Interface Definitions
The interfaces defined in this document reside in the package named The interfaces defined in this document reside in the package named
M. Terada and K. Fujimura [Page 6]
"org.ietf.vts". Wallets or other applications that use this "org.ietf.vts". Wallets or other applications that use this
API,should import this package as "import org.ietf.vts.*;". API,should import this package as "import org.ietf.vts.*;".
5.1 VTSManager 5.1 VTSManager
public interface VTSManager public interface VTSManager
Provides the starting point to use a VTS plug-in. Provides the starting point to use a VTS plug-in.
All of the objects needed to manipulate vouchers can be directly or All of the objects needed to manipulate vouchers can be directly or
indirectly acquired via a VTSManager, so that wallets or other indirectly acquired via a VTSManager, so that wallets or other
applications can make the VTS available by instantiating an object applications can make the VTS available by instantiating an object
implementing this interface. implementing this interface.
Classes that implement this interface should have a public default A class that implements the VTSManager interface must have a public
constructor (a constructor without any parameters) to make the VTS default constructor (a constructor without any parameters). The VTS
pluggable. provides a name for such constructor so that the implementation class
can bootstrap the interface.
5.1.1 getParticipantRepository 5.1.1 getParticipantRepository
public ParticipantRepository getParticipantRepository() public ParticipantRepository getParticipantRepository()
Returns a repository that maintains Participants. Returns a repository that maintains Participants.
Returns: Returns:
the ParticipantRepository of the VTS, or null if no the ParticipantRepository of the VTS, or null if no
skipping to change at page 10, line ? skipping to change at page 8, line 15
Provides the access points of Participants. A ParticipantRepository Provides the access points of Participants. A ParticipantRepository
maintains Participants and acts as an "address book" of trading maintains Participants and acts as an "address book" of trading
partners. partners.
The object implementing this interface maintains Participants (or The object implementing this interface maintains Participants (or
holds a reference to an object maintaining Participants), which are holds a reference to an object maintaining Participants), which are
to be trading partners. to be trading partners.
The implementation of ParticipantRepository may be either (an adaptor The implementation of ParticipantRepository may be either (an adaptor
M. Terada and K. Fujimura [Page 7]
to) "yellow pages" which is a network-wide directory service like to) "yellow pages" which is a network-wide directory service like
LDAP, or "pocket address book" which maintains only personal LDAP, or "pocket address book" which maintains only personal
acquaintances. acquaintances.
5.2.1 lookup 5.2.1 lookup
public Participant lookup(String id) public Participant lookup(String id)
Retrieves the participant that has the specified id. Retrieves the participant that has the specified id.
skipping to change at page 10, line ? skipping to change at page 9, line 16
VTSAgent getVTSAgent() VTSAgent getVTSAgent()
Returns a VTSAgent, whose identifier is the same as the identifier of Returns a VTSAgent, whose identifier is the same as the identifier of
the participant. the participant.
Returns: Returns:
an object implementing VTSAgent. an object implementing VTSAgent.
M. Terada and K. Fujimura [Page 8]
5.4 VTSAgent 5.4 VTSAgent
public interface VTSAgent extends Participant public interface VTSAgent extends Participant
Represents contact points to access vouchers in Valid Voucher Set Represents contact points to access vouchers in Valid Voucher Set
(VVS) that is managed by the VTS. (VVS) that is managed by the VTS.
Each VTSAgent is associated with a holder and provides a means for Each VTSAgent is associated with a holder and provides a means for
managing vouchers owned by the holder. The holder must be managing vouchers owned by the holder. The holder must be
authenticated using the login() method before being called by any authenticated using the login() method before being called by any
skipping to change at page 10, line ? skipping to change at page 9, line 37
Before calling any trading method, i.e., issue(), transfer(), Before calling any trading method, i.e., issue(), transfer(),
consume(), and present(), the application must establish a session by consume(), and present(), the application must establish a session by
the prepare() method. the prepare() method.
Sessions may often be suspended due to network failure when the Sessions may often be suspended due to network failure when the
voucher is sent via a network. The suspended sessions can be voucher is sent via a network. The suspended sessions can be
restarted by the resume() method. Details on the state management of restarted by the resume() method. Details on the state management of
a session are described in Section 5.5. a session are described in Section 5.5.
Some VTSAgents may not have all of the trading methods; a voucher
collecting system doesn't require its VTSAgent to provide method for
issuing or creating vouchers. A VTSAgent returns
FeatureNotAvailableException when an unsupported method is invoked.
5.4.1 login 5.4.1 login
public void login(String passphrase) public void login(String passphrase)
throws VTSException throws VTSException
Authenticates the VTSAgent. The passphrase is specified if the VTS Authenticates the VTSAgent. The passphrase is specified if the VTS
requires it for authentication, otherwise it must be null. Nothing is requires it for authentication, otherwise it must be null. Nothing is
performed if the VTSAgent has already been logged-in. The performed if the VTSAgent has already been logged-in. The
authentication scheme is implementation-specific. Examples of the authentication scheme is implementation-specific. Examples of the
implementation are as follows: implementation are as follows:
skipping to change at page 10, line ? skipping to change at page 10, line 21
VTS), and returns the response from the smartcard to the server. VTS), and returns the response from the smartcard to the server.
Note that a PIN to unlock the smartcard may be given through this Note that a PIN to unlock the smartcard may be given through this
method depending on the implementation. method depending on the implementation.
3) Each user holds their own smartcard in which their own vouchers 3) Each user holds their own smartcard in which their own vouchers
are stored (decentralized VVS). In this case, the passphrase may are stored (decentralized VVS). In this case, the passphrase may
be null since no authentication is required. Note that a PIN to be null since no authentication is required. Note that a PIN to
unlock the smartcard may be given through this depends on the unlock the smartcard may be given through this depends on the
implementation. implementation.
M. Terada and K. Fujimura [Page 9]
Throws: Throws:
VTSSecurityException - if authentication fails. VTSSecurityException - if authentication fails.
5.4.2 logout 5.4.2 logout
public void logout() public void logout()
throws VTSException throws VTSException
Voids the authentication performed by the login() method. Voids the authentication performed by the login() method.
skipping to change at page 11, line 5 skipping to change at page 11, line 21
Parameters: Parameters:
receiver - the trading partner who receives vouchers. receiver - the trading partner who receives vouchers.
Returns: Returns:
an established session whose state is "prepared" (see Section 5.5). an established session whose state is "prepared" (see Section 5.5).
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InvalidParticipantException - if the specified participant is
invalid.
CannotProceedException - if the preparation of the session is CannotProceedException - if the preparation of the session is
aborted (e.g. network failures). aborted (e.g. network failures).
FeatureNotAvailableException - if the VTSAgent does not provide
any trading methods.
InvalidParticipantException - if the specified participant is
invalid.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.4 issue 5.4.4 issue
public void issue(Session session, public void issue(Session session,
VoucherComponent promise, VoucherComponent promise,
java.lang.Number num) java.lang.Number num)
throws VTSException throws VTSException
Issues vouchers. This method creates the specified number of Issues vouchers. This method creates the specified number of
vouchers <this, promise, receiver> and adds them to the VVS. Note vouchers <this, promise, receiver> and adds them to the VVS. Note
skipping to change at page 11, line 38 skipping to change at page 11, line 56
network failures). network failures).
Parameters: Parameters:
session - the session used by the issue transaction. session - the session used by the issue transaction.
promise - the promise part of the voucher. promise - the promise part of the voucher.
num - the number of vouchers to be issued. num - the number of vouchers to be issued.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InvalidStateException - if the session is not "prepared".
CannotProceedException - if the transaction cannot be successfully CannotProceedException - if the transaction cannot be successfully
completed. completed.
FeatureNotAvailableException - if the VTSAgent does not provide
a means of issuing vouchers.
InvalidStateException - if the session is not "prepared".
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.5 transfer 5.4.5 transfer
public void transfer(Session session, public void transfer(Session session,
Participant issuer, Participant issuer,
VoucherComponent promise, VoucherComponent promise,
java.lang.Number num) java.lang.Number num)
throws VTSException throws VTSException
Transfers vouchers. This method rewrites the specified number of Transfers vouchers. This method rewrites the specified number of
vouchers <issuer, promise, this> to <issuer, promise, receiver> in vouchers <issuer, promise, this> to <issuer, promise, receiver> in
skipping to change at page 12, line 24 skipping to change at page 12, line 44
Parameters: Parameters:
session - the session used by the transfer transaction. session - the session used by the transfer transaction.
issuer - the issuer part of the voucher, or null. issuer - the issuer part of the voucher, or null.
promise - the promise part of the voucher. promise - the promise part of the voucher.
num - the number of vouchers to be transferred. num - the number of vouchers to be transferred.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated CannotProceedException - if the transaction cannot be successfully
correctly. completed.
FeatureNotAvailableException - if the VTSAgent does not provide
a means of transferring vouchers.
InsufficientVoucherException - if the VTSAgent doesn't have a InsufficientVoucherException - if the VTSAgent doesn't have a
sufficient number of vouchers to transfer. sufficient number of vouchers to transfer.
InvalidStateException - if the session is not "prepared". InvalidStateException - if the session is not "prepared".
CannotProceedException - if the transaction cannot be successfully VTSSecurityException - if the VTSAgent cannot be authenticated
completed. correctly.
5.4.6 consume 5.4.6 consume
public void consume(Session session, public void consume(Session session,
Participant issuer, Participant issuer,
VoucherComponent promise, VoucherComponent promise,
java.lang.Number num) java.lang.Number num)
throws VTSException throws VTSException
Consumes vouchers. This method deletes the specified number of Consumes vouchers. This method deletes the specified number of
skipping to change at page 13, line 4 skipping to change at page 13, line 26
or "suspended" if the transaction is interrupted abnormally (e.g., or "suspended" if the transaction is interrupted abnormally (e.g.,
network failures). network failures).
If null is specified for the issuer parameter, it indicates "any If null is specified for the issuer parameter, it indicates "any
issuer". This method selects vouchers to be consumed from the set of issuer". This method selects vouchers to be consumed from the set of
vouchers returned by the getContents(null, promise). vouchers returned by the getContents(null, promise).
Parameters: Parameters:
session - the session used by the consume transaction. session - the session used by the consume transaction.
issuer - the issuer part of the voucher, or null. issuer - the issuer part of the voucher, or null.
promise - the promise part of the voucher. promise - the promise part of the voucher.
num - the number of vouchers to be consumed. num - the number of vouchers to be consumed.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated CannotProceedException - if the transaction cannot be successfully
correctly. completed.
FeatureNotAvailableException - if the VTSAgent does not provide
a means of consuming vouchers.
InsufficientVoucherException - if the VTSAgent doesn't have a InsufficientVoucherException - if the VTSAgent doesn't have a
sufficient number of vouchers to consume. sufficient number of vouchers to consume.
InvalidStateException - if the session is not "prepared". InvalidStateException - if the session is not "prepared".
CannotProceedException - if the transaction cannot be successfully VTSSecurityException - if the VTSAgent cannot be authenticated
completed. correctly.
5.4.7 present 5.4.7 present
public void present(Session session, public void present(Session session,
Participant issuer, Participant issuer,
VoucherComponent promise, VoucherComponent promise,
java.lang.Number num) java.lang.Number num)
throws VTSException throws VTSException
Presents vouchers. This method shows that the sender has the Presents vouchers. This method shows that the sender has the
skipping to change at page 13, line 52 skipping to change at page 14, line 22
Parameters: Parameters:
session - the session used by the present transaction. session - the session used by the present transaction.
issuer - the issuer part of the voucher, or null. issuer - the issuer part of the voucher, or null.
promise - the promise part of the voucher. promise - the promise part of the voucher.
num - the number of the voucher to be presented. num - the number of the voucher to be presented.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated CannotProceedException - if the transaction cannot be successfully
correctly. completed.
InsufficientVoucherException - if the VTSAgent doesn't have a InsufficientVoucherException - if the VTSAgent doesn't have a
sufficient number of vouchers to present. sufficient number of vouchers to present.
InvalidStateException - if the session is not "prepared". InvalidStateException - if the session is not "prepared".
CannotProceedException - if the transaction cannot be successfully FeatureNotAvailableException - if the VTSAgent does not provide
completed. a means of presenting vouchers.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.8 cancel 5.4.8 cancel
public void cancel(Session session) public void cancel(Session session)
throws VTSException throws VTSException
Releases the session. "Prepared" sessions MUST be canceled. An Releases the session. "Prepared" sessions MUST be canceled. An
implementation MAY be permitted to cancel "activated" or "suspended" implementation MAY be permitted to cancel "activated" or "suspended"
sessions. sessions.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InvalidStateException - if the state of the session isn't InvalidStateException - if the state of the session isn't
cancelable. cancelable.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.9 resume 5.4.9 resume
public void resume(Session session) public void resume(Session session)
throws VTSException throws VTSException
Restarts the session. Only "suspended" sessions can be resumed. Restarts the session. Only "suspended" sessions can be resumed.
The state of the session will be re-"activated" immediately, and it The state of the session will be re-"activated" immediately, and it
will be "completed" when the transaction is successfully completed or will be "completed" when the transaction is successfully completed or
"suspended" again if the transaction is interrupted abnormally (e.g., "suspended" again if the transaction is interrupted abnormally (e.g.,
network failures). network failures).
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InvalidStateException - if the session is not "suspended".
CannotProceedException - if the transaction cannot be successfully CannotProceedException - if the transaction cannot be successfully
completed. completed.
InvalidStateException - if the session is not "suspended".
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.10 create 5.4.10 create
public void create(VoucherComponent promise, java.lang.Number num) public void create(VoucherComponent promise, java.lang.Number num)
throws VTSException throws VTSException
Creates vouchers where the issuer is the VTSAgent itself. This Creates vouchers where the issuer is the VTSAgent itself. This
method creates the specified number of vouchers <this, promise, method creates the specified number of vouchers <this, promise,
this> and adds them to the VVS. Nothing is performed if the this> and adds them to the VVS. Nothing is performed if the
specified number is 0. specified number is 0.
Throws: Throws:
FeatureNotAvailableException - if the VTSAgent does not provide
a means of creating vouchers.
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
5.4.11 delete 5.4.11 delete
public void delete(Participant issuer, public void delete(Participant issuer,
VoucherComponent promise, VoucherComponent promise,
java.lang.Number num) java.lang.Number num)
throws VTSException throws VTSException
Deletes vouchers. This method deletes the specified number of Deletes vouchers. This method deletes the specified number of
vouchers <issuer, promise, this> from the VVS. The VTSAgent must vouchers <issuer, promise, this> from the VVS. The VTSAgent must
have sufficient vouchers in the VVS. Nothing is performed if the have sufficient vouchers in the VVS. Nothing is performed if the
specified number is 0. specified number is 0.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InsufficientVoucherException - if the VTSAgent doesn't have InsufficientVoucherException - if the VTSAgent doesn't have
sufficient number of vouchers to delete. sufficient number of vouchers to delete.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.12 getContents 5.4.12 getContents
public java.util.Set getContents(Participant issuer, public java.util.Set getContents(Participant issuer,
VoucherComponent promise) VoucherComponent promise)
throws VTSException throws VTSException
Returns the set of vouchers whose issuer and promise both match the Returns the set of vouchers whose issuer and promise both match the
issuer and promise specified in the parameters. issuer and promise specified in the parameters.
If null is specified for the issuer or promise parameter, it If null is specified for the issuer or promise parameter, it
indicates "any issuer" or "any promise", respectively. If null is indicates "any issuer" or "any promise", respectively. If null is
specified for both parameters, this method selects all vouchers owned specified for both parameters, this method selects all vouchers owned
by the holder from the VVS. by the holder from the VVS.
Returns: Returns:
skipping to change at page 20, line 22 skipping to change at page 20, line 49
Creates a voucher component associated with the specified DOM object Creates a voucher component associated with the specified DOM object
and registers the voucher component with the repository. and registers the voucher component with the repository.
A voucher component of the voucher to be issued must be registered A voucher component of the voucher to be issued must be registered
using this method. using this method.
Nothing is performed (and the method returns null) if the specified Nothing is performed (and the method returns null) if the specified
document is null or the syntax of the document does not conform to document is null or the syntax of the document does not conform to
the VTS. the VTS.
The method returns the registered voucher component if the specified
DOM object has been already registered. (No new voucher component is
created in this case).
Returns: Returns:
a registered voucher component associated with the a registered voucher component associated with the
specified document, or null if the document is null or has wrong specified document, or null if the document is null or has wrong
syntax. syntax.
5.8 VoucherComponent 5.8 VoucherComponent
public interface VoucherComponent public interface VoucherComponent
skipping to change at page 21, line 21 skipping to change at page 21, line 50
public org.w3c.dom.Document getDocument() public org.w3c.dom.Document getDocument()
Returns a Document Object Model [DOM] representation of the document Returns a Document Object Model [DOM] representation of the document
associated with the voucher component by the associated with the voucher component by the
VoucherComponentRepository#register() method. VoucherComponentRepository#register() method.
The DOM object to be returned may be retrieved from a The DOM object to be returned may be retrieved from a
VoucherComponentRepository on demand, instead of the VoucherComponent VoucherComponentRepository on demand, instead of the VoucherComponent
always keeping a reference to the DOM object. always keeping a reference to the DOM object.
The VTS must guarantee that the getDocument method will eventually
return the DOM object provided that the voucher associated with the
corresponding voucher component exists in the VVS.
Returns: Returns:
a DOM representation of the document associated with the voucher a DOM representation of the document associated with the voucher
component. component.
Throws: Throws:
DocumentNotFoundException - if the associated DOM object cannot be DocumentNotFoundException - if the associated DOM object cannot be
retrieved. retrieved.
skipping to change at page 22, line 13 skipping to change at page 22, line 47
The specified session is equivalent to the session used by the sender The specified session is equivalent to the session used by the sender
to trade the voucher. The state of the session is "completed" when to trade the voucher. The state of the session is "completed" when
this method is called. this method is called.
5.10 Exceptions 5.10 Exceptions
java.lang.Exception java.lang.Exception
+-- VTSException +-- VTSException
+-- CannotProceedException +-- CannotProceedException
+-- DocumentNotFoundException +-- DocumentNotFoundException
+-- FeatureNotAvailableException
+-- InsufficientVoucherException +-- InsufficientVoucherException
+-- InvalidParticipantException +-- InvalidParticipantException
+-- InvalidStateException +-- InvalidStateException
+-- VTSSecurityException +-- VTSSecurityException
VTSException VTSException
This is the superclass of all exceptions thrown by the methods in the This is the superclass of all exceptions thrown by the methods in the
interfaces constructs the VTS-API. interfaces constructs the VTS-API.
CannotProceedException CannotProceedException
This exception is thrown when a trading is interrupted due to This exception is thrown when a trading is interrupted due to
network failures or other errors. network failures or other errors.
DocumentNotFoundException DocumentNotFoundException
This exception is thrown when the document associated with a voucher This exception is thrown when the document associated with a voucher
component cannot be found. component cannot be found.
FeatureNotAvailableException
This exception is thrown when the invoked method is not supported.
InsufficientVoucherException InsufficientVoucherException
This exception is thrown when the number of the voucher is less than This exception is thrown when the number of the voucher is less than
the number specified to trade. the number specified to trade.
InvalidParticipantException InvalidParticipantException
This exception is thrown when the specified participant cannot be This exception is thrown when the specified participant cannot be
located. located.
skipping to change at page 24, line 20 skipping to change at page 25, line 4
try { try {
me.login(); me.login();
me.addReceptionListener(listener); me.addReceptionListener(listener);
me.logout(); me.logout();
} catch (VTSException e) { } catch (VTSException e) {
System.err.println("Sorry!"); System.err.println("Sorry!");
e.printStackTrace(); e.printStackTrace();
} }
7. Security Considerations 7. Security Considerations
This document assumes that the VTS plug-in is trusted. The caller 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 application of a VTS should authenticate the VTS plug-in and bind it
securely using the VTS Provider information specified in the Voucher securely using the VTS Provider information specified in the Voucher
Component. This document, however, does not specify any application Component. This document, however, does not specify any application
authentication scheme and it is assumed to be specified by other authentication scheme and it is assumed to be specified by other
related standards. [Editor's note: References are for further related standards. Until various VTS systems are deployed, it is
study. Until various VTS systems are deployed, it may be enough to enough to manually check and install VTS plug-ins like other download
manually check and install VTS plug-ins like other download applications.
applications.]
To protect vouchers from being stolen, the VTSAgent must be To protect vouchers from being stolen, the VTSAgent must be
authenticated securely. This document introduced a login/logout authenticated securely. This document introduced a login/logout
facility for this purpose (see Section 5.4). facility for this purpose (see Section 5.4).
8. Acknowledgement 8. References
(tbs)
9. References
[DOM] "Document Object Model (DOM), Level 1 Specification", October [DOM] "Document Object Model (DOM), Level 1 Specification", October
<http://www.w3.org/TR/REC-DOM-Level-1/>,1998. <http://www.w3.org/TR/REC-DOM-Level-1/>,1998.
[DOMHash] H. Maruyama, K. Tamura, and N. Uramoto, "Digest Values [DOMHash] H. Maruyama, K. Tamura, and N. Uramoto, "Digest Values
for DOM (DOMHASH)", RFC 2803, 2000. for DOM (DOMHASH)", RFC 2803, 2000.
[ECML] J. W. Parsons, "Electronic Commerce Modeling Language (ECML) [ECML] J. W. Parsons and D. Eastlake "Electronic Commerce Modeling
Version 2 Specification", draft-ietf-trade-ecml2-spec-02.txt, Language (ECML) Version 2 Specification",
2001. draft-ietf-trade-ecml2-spec-03.txt, 2002.
[GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.), [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.),
"SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854, "SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854,
Springer-Verlag, 2000. Springer-Verlag, 2000.
[GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher [GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher
Language", draft-ietf-trade-voucher-lang-02.txt, 2001. Language", draft-ietf-trade-voucher-lang-03.txt, 2002.
[VTS] K. Fujimura, "Requirements and Design for Voucher Trading [VTS] K. Fujimura, "Requirements and Design for Voucher Trading
System (VTS)", draft-ietf-trade-drt-requirements-03.txt, 2002. System (VTS)", draft-ietf-trade-drt-requirements-03.txt, 2002.
[IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version [IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version
1.0", RFC 2801, 2000. 1.0", RFC 2801, 2000.
[JCC] Sun Microsystems Inc., "Java Commerce Client", [JCC] Sun Microsystems Inc., "Java Commerce Client",
<http://java.sun.com/products/commerce/>. <http://java.sun.com/products/commerce/>.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, 1997. Requirement Levels", BCP 14, RFC 2119, 1997.
10. Author's Address 9. Author's Address
Masayuki Terada and Ko Fujimura Masayuki Terada and Ko Fujimura
NTT Corporation NTT Corporation
1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN 1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN
Phone: +81-(0)468-59-3814 Phone: +81-(0)468-59-3814
Fax: +81-(0)468-59-2241 Fax: +81-(0)468-59-8329
Email: terada@isl.ntt.co.jp, fujimura@isl.ntt.co.jp Email: terada@isl.ntt.co.jp, fujimura@isl.ntt.co.jp
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 End of changes. 

This html diff was produced by rfcdiff 1.25, available from http://www.levkowetz.com/ietf/tools/rfcdiff/