draft-ietf-trade-voucher-vtsapi-06.txt   rfc4154.txt 
Trade Working Group February 2004 Network Working Group M. Terada
INTERNET-DRAFT Masayuki Terada Request for Comments: 4154 NTT DoCoMo
NTT DoCoMo Category: Informational K. Fujimura
Expires: August 2004 Ko Fujimura NTT
NTT September 2005
Voucher Trading System Application Programming Interface (VTS-API) Voucher Trading System Application Programming Interface (VTS-API)
<draft-ietf-trade-voucher-vtsapi-06.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 Status of This Memo
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 This memo provides information for the Internet community. It does
and may be updated, replaced, or obsoleted by other documents at any not specify an Internet standard of any kind. Distribution of this
time. It is inappropriate to use Internet-Drafts as reference memo is unlimited.
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at Copyright Notice
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at Copyright (C) The Internet Society (2005).
http://www.ietf.org/shadow.html.
Distribution of this document is unlimited. Please send comments to IESG Note
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 This document is not a candidate for any level of Internet Standard.
http://lists.elistx.com/archives/ietf-trade. This document specifies the Voucher Trading System Application
Programming Interface (VTS-API), which assumes that the VTS plug-in
is trusted by its user. The application making calls to VTS-API
ought to authenticate the VTS plug-in and securely bind the plug-in
with the VTS provider information specified in the Voucher Component.
However, this document does not specify an approach to application
authentication. The VTS-API should not be used without being
augmented by an application authentication mechanism.
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 Programming Interface (VTS-API). The VTS-API allows a wallet or
other application to issue, transfer, and redeem vouchers in a other application to issue, transfer, and redeem vouchers in a
uniform manner independent of the VTS implementation. The VTS is a uniform manner independent of the VTS implementation. The VTS is a
system to securely transfer vouchers, e.g., coupons, tickets, loyalty system for securely transferring vouchers; e.g., coupons, tickets,
points, and gift certificates; this process is often necessary in the loyalty points, and gift certificates. This process is often
course of payment and/or delivery transactions. necessary in the course of payment and/or delivery transactions.
Copyright (C) The Internet Society (2004). All Rights Reserved.
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 1. Introduction ................................................. 3
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2. Processing Model ............................................. 4
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 1 3. Design Overview .............................................. 6
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 4. Concepts ..................................................... 6
2. Processing Model . . . . . . . . . . . . . . . . . . . . . 4 5. Interface Definitions ........................................ 8
3. Design Overview . . . . . . . . . . . . . . . . . . . . . 6 5.1. VTSManager .............................................. 8
4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1.1. getParticipantRepository ......................... 8
5. Interface Definitions . . . . . . . . . . . . . . . . . . 7 5.1.2. getVoucherComponentRepository .................... 8
5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 8 5.2. ParticipantRepository ................................... 9
5.1.1 getParticipantRepository . . . . . . . . . . . . . . . . . 8 5.2.1. lookup ........................................... 9
5.1.2 getVoucherComponentRepository . . . . . . . . . . . . . . 8 5.3. Participant ............................................. 9
5.2 ParticipantRepository . . . . . . . . . . . . . . . . . . 8 5.3.1. getIdentifier .................................... 10
5.2.1 lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.3.2. getVTSAgent ...................................... 10
5.3 Participant . . . . . . . . . . . . . . . . . . . . . . . 9 5.4. VTSAgent ................................................ 10
5.3.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 9 5.4.1. login ............................................ 11
5.3.2 getVTSAgent . . . . . . . . . . . . . . . . . . . . . . . 9 5.4.2. logout ........................................... 12
5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.3. prepare .......................................... 12
5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.4. issue ............................................ 13
5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.5. transfer ......................................... 14
5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.6. consume .......................................... 15
5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.4.7. present .......................................... 16
5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4.8. cancel ........................................... 17
5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.4.9. resume ........................................... 18
5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.4.10. create .......................................... 18
5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.4.11. delete .......................................... 19
5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4.12. getContents ..................................... 19
5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4.13. getSessions ..................................... 19
5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4.14. getLog .......................................... 20
5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 17 5.4.15. addReceptionListener ............................ 20
5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 17 5.4.16. removeReceptionListener ......................... 21
5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.5. Session ................................................. 21
5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 18 5.5.1. getIdentifier .................................... 21
5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 18 5.5.2. getVoucher ....................................... 22
5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.5.3. getSender ........................................ 22
5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 19 5.5.4. getReceiver ...................................... 22
5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 19 5.5.5. isPrepared ....................................... 22
5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 19 5.5.6. isActivated ...................................... 23
5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 20 5.5.7. isSuspended ...................................... 23
5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 20 5.5.8. isCompleted ...................................... 23
5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 20 5.6. Voucher ................................................. 23
5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 20 5.6.1. getIssuer ........................................ 23
5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 20 5.6.2. getPromise ....................................... 24
5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.6.3. getCount ......................................... 24
5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 21 5.7. VoucherComponentRepository .............................. 24
5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 21 5.7.1. register ......................................... 24
5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.8. VoucherComponent ........................................ 25
5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 21 5.8.1. getIdentifier .................................... 25
5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.8.2. getDocument ...................................... 26
5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 22 5.9. ReceptionListener ....................................... 26
5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 22 5.9.1. arrive ........................................... 26
5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 23 5.10. Exceptions ............................................. 27
5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 23 6. Example Code ................................................. 28
5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 24 7. Security Considerations ...................................... 29
5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 24 8. Acknowledgements ............................................. 30
6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 25 9. Normative References ......................................... 30
7. Security Considerations . . . . . . . . . . . . . . . . . 26 10. Informative References ....................................... 30
8. Normative References . . . . . . . . . . . . . . . . . . . 27
9. Informative References . . . . . . . . . . . . . . . . . . 27
10. Author's Address . . . . . . . . . . . . . . . . . . . . . 28
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 28
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 Programming Interface (VTS-API). The motivation and background of
the Voucher Trading System (VTS) are described in Requirements for the 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 it
logically managed by the VTS. A voucher is generated by the issuer, is logically managed by the VTS. A voucher is generated by the
traded among users, and finally collected using VTS. The terminology issuer, traded among users, and finally collected using VTS. The
and model of the VTS are also described in [VTS]. terminology and model of the VTS are also described in [VTS].
While VTSs can be implemented in different ways such as a centralized VTSes can be implemented in different ways, such as a centralized
VTS, which uses a centralized online server to store and manage all VTS, which uses a centralized online server to store and manage all
vouchers, or a distributed VTS, which uses per-user smartcards to vouchers, or a distributed VTS, which uses per-user smartcards to
maintain the vouchers owned by each user, the VTS-API allows a caller maintain the vouchers owned by each user. However, the VTS-API
application to issue, transfer, and redeem vouchers in a uniform allows a caller application to issue, transfer, and redeem vouchers
manner independent of the VTS implementation. Several attempts have in a uniform manner independent of the VTS implementation. Several
been made at providing a generic payment API. Java Commerce Client attempts have been made to provide a generic payment API. Java
[JCC] and Generic Payment Service Framework [GPSF], for example, Commerce Client [JCC] and Generic Payment Service Framework [GPSF],
introduce a modular wallet architecture that permits diverse types of for example, introduce a modular wallet architecture that permits
payment modules to be added as plug-ins and supports both check- diverse types of payment modules to be added as plug-ins and supports
like/cash-like payment models. This document is inspired by these both check-like/cash-like payment models. This document is inspired
approaches but the scope of this document is limited to the VTS by these approaches but its scope is limited to the VTS model, in
model, in which cash-like payment model is assumed and vouchers are which the cash-like payment model is assumed and vouchers are
directly or indirectly transferred between sender (transferor) and directly or indirectly transferred between the sender (transferor)
receiver (transferee) via the VTS. This document is not intended to and receiver (transferee) via the VTS. This document is not intended
support API for SET, e-check or other payment schemes that do not fit to support API for SET, e-check, or other payment schemes that do not
the VTS model. fit the VTS model.
Unlike the APIs provided in JCC and GPSF, which are designed to Unlike the APIs provided in JCC and GPSF, which are designed to
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 Language [GVL]. The monetary meaning of the voucher is interpreted
by the upper application layer using the information described in the by the upper application layer using the information described in the
language. This approach makes it possible to provide a simpler API language. This approach makes it possible to provide a simpler API
in the voucher-transfer layer and enhances runtime efficiency. The in the voucher-transfer layer and enhances runtime efficiency. The
API specification in this document is described in the Java language API specification in this document is described in the Java language
syntax. Bindings for other programming languages may be completed in syntax. Bindings for other programming languages may be completed in
a future version of this document or separate related specifications. a future version of this document or in separate related
specifications.
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 this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119] document are to be interpreted as described in [RFC2119]
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. A part of the text in this section has been taken from the used. A part 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 to implement VTS. For discount coupons or
event tickets, for example, a smartcard-based distributed offline VTS event tickets, for example, a smartcard-based distributed offline VTS
is often preferred, whereas for bonds or securities, a centralized is often preferred, whereas for bonds or securities, a centralized
online VTS is preferred. While distributed VTSs would utilize public online VTS is preferred. While distributed VTSes would utilize
(asymmetric) key-based or shared (symmetric) key-based cryptographic public (asymmetric) key-based or shared (symmetric) key-based
challenge-and-response protocols to trade vouchers securely, cryptographic challenge-and-response protocols to trade vouchers
centralized VTSs would utilize transactions that rewrite ownerships securely, centralized VTSes would utilize transactions that rewrite
of vouchers upon their database. It is therefore impractical to ownerships of vouchers on their database. Therefore, it is
define standard protocols for issuing, transferring, or redeeming impractical to define standard protocols for issuing, transferring,
vouchers at this moment. or redeeming vouchers at this time.
To provide implementation flexibility, this document assumes a To provide implementation flexibility, this document assumes a
modular wallet architecture that allows multiple VTS to be added as modular wallet architecture that allows multiple VTSes to be added as
plug-ins. In this architecture, instead of specifying a standard plug-ins. In this architecture, instead of specifying a standard
voucher transfer protocol, two specifications, i.e., Voucher voucher transfer protocol, two specifications, Voucher Component and
Component and VTS-API specifications, are standardized (Figure 1). VTS-API, are standardized (Figure 1).
Sender wallet/Issuing system Receiver wallet/Collecting system Sender wallet/Issuing system Receiver wallet/Collecting system
+---------------------------+ +---------------------------+ +---------------------------+ +---------------------------+
| | | | | | | |
| | Voucher Component | | | | Voucher Component | |
| | (Specifies VTS Provider and Promise) | | | | (Specifies VTS Provider and Promise) | |
| |-------------------------------------------------------->| | | |-------------------------------------------------------->| |
| | | | | | | | | | | |
| | Intention to receive and payment (option) | | | | Intention to receive and payment (option) | |
| |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - | | | |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | Issue/transfer/ VTS | | VTS Register | | | | Issue/transfer/ VTS | | VTS Register | |
| | redeem request plug-in | plug-in Listener(*1)| | | | redeem request plug-in | plug-in Listener(*1)| |
| |------------------>| | | |<------------------| | | |------------------>| | | |<------------------| |
| | (VTS API) |<- - - - - - - ->| (VTS API) | | | | (VTS API) |<- - - - - - - ->| (VTS API) | |
| | | VTS-specific | | | | | | VTS-specific | | |
| | | protocol if VTS | | | | | | protocol if VTS | | |
| | | is distributed | | | | | | is distributed | | |
| | Result |<- - - - - - - ->| Notify(*2) | | | | 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 (*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
In this architecture, a VTS provides a logical view of vouchers In this architecture, a VTS provides a logical view of vouchers
called Valid Voucher Set (VVS), which is a set that includes the called a Valid Voucher Set (VVS), which is a set that includes the
vouchers <I,P,H> managed by the VTS [VTS]. A user's wallet can vouchers <I,P,H> managed by the VTS [VTS]. A user's wallet can
access (e.g. view, transfer and redeem) the subset of VVS that access (e.g., view, transfer, and redeem) the subset of the VVS that
includes a set of vouchers owned by the user, by interacting with the includes a set of vouchers owned by the user by interacting with the
VTS plug-in via the VTS-API. Likewise, an issuing system can issue a VTS plug-in via the VTS-API. Likewise, an issuing system can issue a
voucher and add it to the VVS and a collecting system can be notified voucher and add it to the VVS, and a collecting system can be
of the redemption of vouchers via the VTS-API. notified of the redemption of vouchers via the VTS-API.
After a sender and a receiver agree on what vouchers are to be traded After a sender and a receiver agree on what vouchers are to be traded
and which VTS is to be used, the issuing system or wallet system and which VTS is to be used, the issuing system or wallet system
requests the corresponding VTS plug-in to permit the issue, transfer, requests the corresponding VTS plug-in to permit the issue, transfer,
or redeem transactions to be performed via the VTS-API. The VTS then or redemption transactions to be performed via the VTS-API. The VTS
logically rewrites the ownership of the vouchers on the VVS using the then logically rewrites the ownership of the vouchers on the VVS
VTS-specific protocol. Since the VTS is responsible for preventing using the VTS-specific protocol. Since the VTS is responsible for
illegal acts on vouchers like forgery or reproduction as required in preventing illegal acts on vouchers like forgery or reproduction, as
[VTS], the protocol would include a cryptographic challenge-and- required in [VTS], the protocol would include a cryptographic
response (in a distributed VTS) or a transactional database manipula- challenge-and-response (in a distributed VTS) or a transactional
tion with adequate access controls (in a centralized VTS). Finally, database manipulation with adequate access controls (in a centralized
a completion event is sent to the wallet systems or issuing/collect- VTS). Finally, a completion event is sent to the wallet systems or
ing systems. 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 that gives the syntax and semantics Voucher Component specification that gives the syntax and semantics
for describing and interpreting meaning of vouchers. for describing and interpreting the meaning of vouchers.
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
implementation. For example, a common API is provided for implementation. For example, a common API is provided for both
both centralized and distributed VTS. It brings more freedom centralized and distributed VTSes. Issuers and application
of VTS selection for issuers and application developers. developers have more freedom in VTS selection.
2) To provide an abstract and uniform API, this document intro- 2) To provide an abstract and uniform API, this document
duces an interface called VTSAgent that is associated with a introduces an interface called VTSAgent that is associated with
holder and provides methods to manipulate vouchers held by its a holder and provides methods to manipulate vouchers held by
holder. Vouchers are accessed through the methods provided by its holder. Vouchers are accessed through the methods provided
the VTSAgent. by the VTSAgent.
3) Use existing standards for the VTS branding mechanism (negoti- 3) Use existing standards for the VTS branding mechanism
ation). This document assumes that the VTS to be used for (negotiation). This document assumes that the VTS to be used
sending a voucher has settled before calling the VTS-APIs. for sending a voucher has settled the VTS-APIs are called.
Negotiation can be done within the upper application layer Negotiation can be done within the upper application layer
using other standards, e.g., [IOTP] or [ECML], if necessary. using other standards (e.g., [IOTP] or [ECML]), if necessary.
4) Support only push-type voucher transfer interface in which 4) Support only the push-type voucher transfer interface, in which
voucher transfer session is initiated by the transferor side. the voucher transfer session is initiated by the transferor
Pull-type voucher transfer interface can be implemented on top side. A pull-type voucher transfer interface can be
of the push-type VTS interface at application level. implemented on top of the push-type VTS interface at the
application level.
4. Concepts 4. Concepts
The VTS-API consists of the following interfaces. A VTS is required The VTS-API consists of the following interfaces. A VTS is required
to implement all of the interfaces except ReceptionListener, which is to implement all of the interfaces except ReceptionListener, which is
intended to be implemented by wallets or other applications that use intended to be implemented by wallets or other applications that use
VTS. VTS.
VTSManager VTSManager
Provides the starting point to use a VTS plug-in. All of the Provides the starting point for using a VTS plug-in. All of
objects needed to manipulate vouchers can be directly or indi- the objects needed to manipulate vouchers can be directly or
rectly acquired via the VTSManager. A VTSManager maintains indirectly acquired via the VTSManager. A VTSManager maintains
the two repositories; a ParticipantRepository and a Voucher- the two repositories: a ParticipantRepository and a
ComponentRepository described below. VoucherComponentRepository, both of which are described below.
ParticipantRepository ParticipantRepository
Provides the access points of Participants, which are to be Provides the access points of participants that are to be
trading partners. A ParticipantRepository maintains Partici- trading partners. A ParticipantRepository maintains
pants and acts as an "address book" of trading partners. Participants and acts as an "address book" of trading partners.
Participant Participant
Represents a participant (such as issuers, holders, and Represents a participant (such as an issuer, a holder, or a
collectors). A Participant knows how to obtain the corre- collector). A Participant interface knows how to obtain the
sponding VTSAgent described below. corresponding VTSAgent described below.
VTSAgent (extends Participant) VTSAgent (extends Participant)
Provides the access point of vouchers in Valid Voucher Set Provides the access point of vouchers in the Valid Voucher Set
(VVS) that is logically managed by VTS. A VTSAgent provides a (VVS) that is logically managed by the VTS. A VTSAgent
means of manipulating vouchers held by its holder; basic trad- provides a means of manipulating vouchers held by its holder
ing methods, i.e., issue, transfer, consume, and present. according to basic trading methods; i.e., issue, transfer,
Before calling trading methods, the application must create a consume, and present. Before calling trading methods, the
Session which is described below. application must create a Session, which is described below.
Session Session
Represents the logical connection established by the trade. A Represents the logical connection established by the trade. A
Session has references to two Participants, i.e., the sender Session has references to two Participant interfaces; i.e.,
and the receiver. After trading methods are called using a those of the sender and the receiver. After trading methods
Session, the Session holds a reference to the Vouchers to be are called using a Session, the Session holds a reference to
traded. the Vouchers to be traded.
Voucher Voucher
Represents one or more vouchers of which all of the issuer Represents one or more vouchers in which all of the issuer and
part and promise part of vouchers are the same. A Voucher promise parts of the vouchers are the same. A Voucher holds
holds references to the Participant (issuer) who issued the references to the Participant interface who issued the voucher
voucher and a VoucherComponent (promise) which is described (issuer) and to a VoucherComponent (promise), which is
below. described below.
VoucherComponent VoucherComponent
Represents a Voucher Component described in [GVL]. It defines Represents a Voucher Component, described in [GVL]. It defines
the promise part of the voucher. the promise part of the voucher.
VoucherComponentRepository VoucherComponentRepository
Provides the access points of VoucherComponents. A Voucher- Provides the access points of VoucherComponents. A
ComponentRepository maintains VoucherComponents and acts as a VoucherComponentRepository maintains VoucherComponents and acts
"voucher type book" managed by the VTS. This document assumes as a "voucher type book" managed by the VTS. This document
that a set of VoucherComponents has been acquired and stored assumes that a set of VoucherComponents has been acquired and
in this repository. Delivery of VoucherComponents is beyond stored in this repository. Delivery of VoucherComponents is
the scope of this document. It may be delivered within the beyond the scope of this document. It may be delivered within
VTS from the trading partners or manually acquired from a the VTS from the trading partners or manually acquired from a
trusted third party (See Section 3 of [GVL]). trusted third party (see Section 3 of [GVL]).
ReceptionListener ReceptionListener
Provides a listener function with regard to the receipt of a Provides a listener function with regard to the receipt of a
voucher by VTSAgent to wallets or other applications that voucher by a VTSAgent to wallets or other applications that
implement this interface. (This interface may not be imple- implement this interface. (This interface may not be
mented as part of VTS) implemented as part of the 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
"org.ietf.vts". Wallets or other applications that use this "org.ietf.vts". Wallets or other applications that use this API,
API,should import this package as "import org.ietf.vts.*;". 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 for using 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
indirectly acquired via a VTSManager, so that wallets or other or 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.
A class that implements the VTSManager interface must have a public A class that implements the VTSManager interface must have a
default constructor (a constructor without any parameters). The public default constructor (a constructor without any parameters).
VTS provides a name for such constructor so that the implementation The VTS provides a name for such a constructor so that the
class can bootstrap the interface. 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
ParticipantRepository is available. ParticipantRepository is available.
5.1.2 getVoucherComponentRepository 5.1.2. getVoucherComponentRepository
public VoucherComponentRepository getVoucherComponentRepository() public VoucherComponentRepository getVoucherComponentRepository()
Returns a repository that maintains VoucherComponents. Returns a repository that maintains VoucherComponents.
Returns: Returns:
the VoucherComponentRepository of the VTS, or null if no the VoucherComponentRepository of the VTS, or null if no
VoucherComponentRepository is available. VoucherComponentRepository is available.
5.2 ParticipantRepository 5.2. ParticipantRepository
public interface ParticipantRepository public interface ParticipantRepository
Provides the access points of Participants. A ParticipantRepository Provides the access points of Participants. A
maintains Participants and acts as an "address book" of trading ParticipantRepository maintains Participants and acts as an
partners. "address book" of trading 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
to be trading partners. are to be trading partners.
The implementation of ParticipantRepository may be either (an The implementation of a ParticipantRepository may be either (an
adaptor to) "yellow pages" which is a network-wide directory adaptor to) "yellow pages", which is a network-wide directory
service like LDAP, or "pocket address book" which maintains only service like LDAP, or "pocket address book", which maintains only
personal acquaintances. personal 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.
Returns: Returns:
the participant associated with the specified id or null if the id the participant associated with the specified id, or null if the
is null or the corresponding participant cannot be found. id is null or the corresponding participant cannot be found.
5.3 Participant 5.3. Participant
public interface Participant public interface Participant
Represents the participants (such as issuers, holders, and Represents the participants (such as issuers, holders, and
collectors). collectors).
This interface is used as representation of the trade partners and This interface is used as a representation of the trade partners
issuers of vouchers. Anyone can retrieve objects implementing and issuers of vouchers. Anyone can retrieve objects that
Participant from the participant repository. implement Participants from the participant repository.
5.3.1 getIdentifier 5.3.1. getIdentifier
public String getIdentifier() public String getIdentifier()
Returns the identifier of the participant. Each participant must Returns the identifier of the participant. Each participant must
have a unique identifier. have a unique identifier.
The identifier can be used for looking up and retrieving the The identifier can be used for looking up and retrieving the
participant via the ParticipantRepository. participant via the ParticipantRepository.
The format of the identifier is implementation-specific. The format of the identifier is implementation-specific.
Returns: Returns:
the identifier string of the participant. the identifier string of the participant.
5.3.2 getVTSAgent 5.3.2. getVTSAgent
VTSAgent getVTSAgent() VTSAgent getVTSAgent()
Returns a VTSAgent, whose identifier is the same as the identifier Returns a VTSAgent, whose identifier is the same as the identifier
of the participant. of the participant.
Returns: Returns:
an object implementing VTSAgent. an object that implements the VTSAgent.
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 a Valid Voucher
(VVS) that is managed by the VTS. Set (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
other method, or VTSSecurityException will be issue. other method, otherwise, a VTSSecurityException will be issued.
Before calling any trading method, i.e., issue(), transfer(), Before any trading method is called, e.g., issue(), transfer(),
consume(), and present(), the application must establish a session consume(), and present(), the application must establish a session
by the prepare() method. by the prepare() method.
Sessions may often be suspended due to network failure when the Due to network failure, sessions may often be suspended 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 restarted by the resume() method. Details on the state management
of a session are described in Section 5.5. of a session are described in Section 5.5.
Some VTSAgents may not have all of the trading methods; a voucher Some VTSAgents may not have all of the trading methods; a voucher
collecting system doesn't require its VTSAgent to provide method collecting system doesn't require its VTSAgent to provide a method
for issuing or creating vouchers. A VTSAgent returns for issuing or creating vouchers. A VTSAgent returns a
FeatureNotAvailableException when an unsupported method is invoked. 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
requires it for authentication, otherwise it must be null. Nothing VTS requires it for authentication, otherwise it must be null.
is performed if the VTSAgent has already been logged-in. The Nothing is performed if the VTSAgent has already been logged-in.
authentication scheme is implementation-specific. Examples of the The authentication scheme is implementation-specific. Examples of
implementation are as follows: the implementation are as follows:
1) Vouchers are managed on a remote centralized server (centralized 1) Vouchers are managed on a remote centralized server
VTS), which requires a password to login. In this case, the (centralized VTS), which requires a password to login. In this
application may prompt the user to input the password and can be case, the application may prompt the user to input the password
given to the VTSAgent through this method. See Implementation and the password can be given to the VTSAgent through this
Notes below. method. For further information, see the Implementation Notes
below.
2) Vouchers are managed on a remote centralized server (centralized 2) Vouchers are managed on a remote centralized server
VTS), which requires challenge-and-response authentication using (centralized VTS), which requires challenge-and-response
smartcards held by users. In this case, the passphrase may be authentication using smartcards held by users. In this case,
null since access to the smartcard can be done without the passphrase may be null because access to the smartcard can
contacting the application or user, i.e., the VTSAgent receives be done without contacting the application or user (i.e., the
the challenge from the server, sends the challenge to the VTSAgent receives the challenge from the server, sends the
smartcard (within the VTS), and returns the response from the challenge to the smartcard (within the VTS), and returns the
smartcard to the server. Note that a PIN to unlock the response from the smartcard to the server). Note that a PIN to
smartcard may be given through this method depending on the unlock the smartcard may be given through this method,
implementation. 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 (distributed VTS). In this case, the passphrase may are stored (distributed VTS). In this case, the passphrase may
be null since no authentication is required. Note that a PIN to be null because no authentication is required. Note that a PIN
unlock the smartcard may be given through this depends on the to unlock the smartcard may be given, though this depends on
implementation. the implementation.
Implementation Notes: Implementation Notes:
A VTS is responsible for providing secure ways for users to A VTS is responsible for providing secure ways for users to
login(); it is strongly recommended to utilize secure login(). It is strongly recommended that secure communication
communication channels such as [TLS] if secret or privacy channels such as [TLS] be used if secret or private information
information is sent via networks. Fake server attacks including is sent via networks. Fake server attacks, including the so-
so-called MITM (man-in-the-middle) must be considered as well. called MITM (man-in-the-middle), must be considered as well.
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.
After calling this method, calling any other method (except After this method is called, calling any other method (except
login()) will cause VTSSecurityException. login()) will cause a VTSSecurityException.
The VTSAgent can login again by the login() method. The VTSAgent can login again by the login() method.
Throws: Throws:
VTSSecurityException - if the VTSAgent is not authenticated VTSSecurityException - if the VTSAgent is not authenticated
correctly. correctly.
5.4.3 prepare 5.4.3. prepare
public Session prepare(Participant receiver) public Session prepare(Participant receiver)
throws VTSException throws VTSException
Establishes a session that is required for trading vouchers. The Establishes a session that is required for trading vouchers. The
trading partner who receives the vouchers is specified as receiver. trading partner who receives the vouchers is specified as the
The vouchers to be traded will be specified later (when a trading receiver. The vouchers to be traded will be specified later (when
method is called). a trading method is called).
The establishment of a session is implementation-specific. A The establishment of a session is implementation-specific. A
centralized VTS implementation may start a transaction, while a centralized VTS implementation may start a transaction, while a
distributed VTS implementation may get, from the receiver, the distributed VTS implementation may get the challenge needed to
challenge needed to create an authentic response in the create an authentic response from the receiver in the following
following trading method. trading method.
If the VTSAgent has no ability to establish a session with the If the VTSAgent does not have the ability to establish a session
specified receiver (permanent error), the VTSAgent throws an with the specified receiver (permanent error), the VTSAgent throws
InvalidParticipantExeption. If the VTSAgent can not establish a an InvalidParticipantExeption. If the VTSAgent cannot establish a
session due to network failure (transient error), the VTSAgent session due to network failure (transient error), the VTSAgent
throws a CannotProceedException. throws a CannotProceedException.
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:
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 FeatureNotAvailableException - if the VTSAgent does not provide
any trading methods.
public void issue(Session session, InvalidParticipantException - if the specified participant is
VoucherComponent promise, invalid.
java.lang.Number num)
throws VTSException
Issues vouchers. This method creates the specified number of VTSSecurityException - if the VTSAgent cannot be authenticated
vouchers <this, promise, receiver> and adds them to the VVS. If correctly.
the VTS is distributed, this method would create a "response"
corresponding to the challenge received in the prepare() method and
send it to the receiver. Note that the receiver is specified when
prepare() is called. Nothing is performed if the specified
number is 0.
The session MUST be "prepared" when calling this method. The state 5.4.4. issue
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: public void issue(Session session,
VoucherComponent promise,
java.lang.Number num)
throws VTSException
session - the session used by the issue transaction. Issues vouchers. This method creates the specified number of
promise - the promise part of the voucher. vouchers <this, promise, receiver> and adds them to the VVS. If
num - the number of vouchers to be issued. the VTS is distributed, this method would create a "response" that
corresponds to the challenge received in the prepare() method and
send it to the receiver. Note that the receiver is specified when
prepare() is called. Nothing is performed if the specified number
is 0.
Throws: 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).
CannotProceedException - if the transaction cannot be successfully Parameters:
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 session - the session used by the issue transaction.
public void transfer(Session session, promise - the promise part of the voucher.
num - the number of vouchers to be issued.
Throws:
CannotProceedException - if the transaction cannot be successfully
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
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; i.e., deletes the vouchers from the sender and stores
them for the receiver. Similar to issue(), this method would
create and send the response to the receiver if the VTS is
distributed. 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 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:
CannotProceedException - if the transaction cannot be successfully
completed.
FeatureNotAvailableException - if the VTSAgent does not provide a
means of transferring vouchers.
InsufficientVoucherException - if the VTSAgent does not have a
sufficient number of vouchers to transfer.
InvalidStateException - if the session is not "prepared".
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.6. consume
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
Transfers vouchers. This method rewrites the specified number of Consumes vouchers. This method deletes the specified number of
vouchers <issuer, promise, this> to <issuer, promise, receiver> in vouchers <issuer, promise, this> from the VVS and notifies the
the VVS; i.e. deletes the vouchers from the sender and stores them receiver of the deletion. Similar to issue() and transfer(), the
for the receiver. Similar to issue(), this method would create response would be created and sent to the receiver if the VTS is
and send the response to the receiver if the VTS is distributed. distributed so that the receiver can obtain proof of the deletion.
The VTSAgent must have sufficient vouchers in the VVS. Nothing is The VTSAgent must have a sufficient number of vouchers in the VVS.
performed if the specified number is 0. Nothing is performed if the specified number is 0.
The session MUST be "prepared" when calling this method. The state The session MUST be "prepared" when this method is called. The
of the session will be "activated" when the voucher are retrieved state of the session will be "activated" when the vouchers are
from the sender, and it will be "completed" when the transaction is deleted, and it will be "completed" when the transaction is
successfully completed or "suspended" if the transaction is successfully completed or "suspended" if the transaction is
interrupted abnormally (e.g., network failures). interrupted abnormally (e.g., 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 transferred from the set issuer". This method selects vouchers to be consumed from the set
of vouchers returned by the getContents(null, promise). of vouchers returned by the getContents(null, promise).
Parameters: Parameters:
session - the session used by the transfer transaction. 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 transferred.
Throws: issuer - the issuer part of the voucher, or null.
CannotProceedException - if the transaction cannot be successfully promise - the promise part of the voucher.
completed.
FeatureNotAvailableException - if the VTSAgent does not provide
a means of transferring vouchers.
InsufficientVoucherException - if the VTSAgent doesn't have a
sufficient number of vouchers to transfer.
InvalidStateException - if the session is not "prepared".
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.6 consume num - the number of vouchers to be consumed.
public void consume(Session session, Throws:
Participant issuer,
VoucherComponent promise,
java.lang.Number num)
throws VTSException
Consumes vouchers. This method deletes the specified number of CannotProceedException - if the transaction cannot be successfully
vouchers <issuer, promise, this> from the VVS and notifies the completed.
deletion to the receiver. Similar to issue() and transfer(), the
response would be created and sent to the receiver if the VTS is
distributed so that the receiver can obtain proof of the deletion.
The VTSAgent must have a sufficient number of vouchers in the VVS.
Nothing is performed if the specified number is 0.
The session MUST be "prepared" when calling this method. The state FeatureNotAvailableException - if the VTSAgent does not provide a
of the session will be "activated" when the vouchers are deleted, means of consuming vouchers.
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 InsufficientVoucherException - if the VTSAgent does not have a
issuer". This method selects vouchers to be consumed from the set sufficient number of vouchers to consume.
of vouchers returned by the getContents(null, promise).
Parameters: InvalidStateException - if the session is not "prepared".
session - the session used by the consume transaction. VTSSecurityException - if the VTSAgent cannot be authenticated
issuer - the issuer part of the voucher, or null. correctly.
promise - the promise part of the voucher.
num - the number of vouchers to be consumed.
Throws: 5.4.7. present
CannotProceedException - if the transaction cannot be successfully public void present(Session session,
completed. Participant issuer,
FeatureNotAvailableException - if the VTSAgent does not provide VoucherComponent promise,
a means of consuming vouchers. java.lang.Number num)
InsufficientVoucherException - if the VTSAgent doesn't have a throws VTSException
sufficient number of vouchers to consume.
InvalidStateException - if the session is not "prepared". Presents vouchers. This method shows that the sender has the
VTSSecurityException - if the VTSAgent cannot be authenticated specified number of vouchers <issuer, promise, this> in the VVS to
correctly. the receiver of the session; no modification is performed to the
VVS. However, the response would be sent to the receiver as well
as consume() in order to prove that the VTS has been distributed.
The VTSAgent must have a sufficient number of vouchers in the VVS.
Nothing is performed if the specified number is 0.
5.4.7 present The session MUST be "prepared" when this method is called. 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).
public void present(Session session, If null is specified for the issuer parameter, it indicates "any
Participant issuer, issuer". This method selects vouchers to be presented from the
VoucherComponent promise, set of vouchers returned by the getContents(null, promise).
java.lang.Number num)
throws VTSException
Presents vouchers. This method shows that the sender has the Parameters:
specified number of vouchers <issuer, promise, this> in the VVS to
the receiver of the session; No modification is performed to the
VVS. However, the response would be sent in order to give the
proof to the receiver as well as consume() if the VTS is
distributed. The VTSAgent must have a sufficient number of
vouchers in the VVS. Nothing is performed if the specified number
is 0.
The session MUST be "prepared" when calling this method. The state session - the session used by the present transaction.
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 - the issuer part of the voucher, or null.
issuer". This method selects vouchers to be presented from the set
of vouchers returned by the getContents(null, promise).
Parameters: promise - the promise part of the voucher.
session - the session used by the present transaction. num - the number of the voucher to be presented.
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: Throws:
CannotProceedException - if the transaction cannot be successfully CannotProceedException - if the transaction cannot be successfully
completed. completed.
InsufficientVoucherException - if the VTSAgent doesn't have a
sufficient number of vouchers to present.
InvalidStateException - if the session is not "prepared".
FeatureNotAvailableException - if the VTSAgent does not provide
a means of presenting vouchers.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.8 cancel InsufficientVoucherException - if the VTSAgent does not have a
public void cancel(Session session) sufficient number of vouchers to present.
throws VTSException
Releases the session. "Prepared" sessions MUST be canceled. An InvalidStateException - if the session is not "prepared".
implementation MAY be permitted to cancel "activated" or
"suspended" sessions.
Throws: FeatureNotAvailableException - if the VTSAgent does not provide a
means of presenting vouchers.
InvalidStateException - if the state of the session isn't VTSSecurityException - if the VTSAgent cannot be authenticated
cancelable. correctly.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.9 resume 5.4.8. cancel
public void resume(Session session) public void cancel(Session session)
throws VTSException throws VTSException
Restarts the session. Only "suspended" sessions can be resumed. Releases the session. "Prepared" sessions MUST be canceled. An
The state of the session will be re-"activated" immediately, and it implementation MAY be permitted to cancel "activated" or
will be "completed" when the transaction is successfully completed "suspended" sessions.
or "suspended" again if the transaction is interrupted abnormally
(e.g., network failures).
Throws: Throws:
CannotProceedException - if the transaction cannot be successfully InvalidStateException - if the state of the session cannot be
completed. canceled.
InvalidStateException - if the session is not "suspended".
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.10 create VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
public void create(VoucherComponent promise, java.lang.Number num) 5.4.9. resume
throws VTSException
Creates vouchers where the issuer is the VTSAgent itself. This public void resume(Session session)
method creates the specified number of vouchers <this, promise, throws VTSException
this> and adds them to the VVS. Nothing is performed if the
specified number is 0.
Throws: 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).
FeatureNotAvailableException - if the VTSAgent does not provide Throws:
a means of creating vouchers.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.11 delete CannotProceedException - if the transaction cannot be successfully
public void delete(Participant issuer, VoucherComponent completed.
promise, java.lang.Number num)
throws VTSException
Deletes vouchers. This method deletes the specified number of InvalidStateException - if the session is not "suspended".
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.
Throws: VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InsufficientVoucherException - if the VTSAgent doesn't have 5.4.10. create
sufficient number of vouchers to delete.
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.12 getContents public void create(VoucherComponent promise, java.lang.Number num)
throws VTSException
public java.util.Set getContents(Participant issuer, Creates vouchers where the issuer is the VTSAgent itself. This
VoucherComponent promise) method creates the specified number of vouchers <this, promise,
throws VTSException this> and adds them to the VVS. Nothing is performed if the
specified number is 0.
Returns the set of vouchers whose issuer and promise both match the Throws:
issuer and promise specified in the parameters.
If null is specified for the issuer or promise parameter, it FeatureNotAvailableException - if the VTSAgent does not provide a
indicates "any issuer" or "any promise", respectively. If null is means of creating vouchers.
specified for both parameters, this method selects all vouchers
owned by the holder from the VVS.
Returns: VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
the set of vouchers held by the holder of the VTSAgent. 5.4.11. delete
Throws: public void delete(Participant issuer, VoucherComponent promise,
java.lang.Number num)
throws VTSException
VTSSecurityException - if the VTSAgent cannot be authenticated Deletes vouchers. This method deletes the specified number of
correctly. 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.
5.4.13 getSessions Throws:
public java.lang.Set getSessions() InsufficientVoucherException - if the VTSAgent does not have a
throws VTSException sufficient number of vouchers to delete.
Returns a set of not-completed sessions prepared by the VTSAgent. VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
Returns: 5.4.12. getContents
the set of sessions prepared by the VTSAgent and not yet completed. public java.util.Set getContents(Participant issuer,
VoucherComponent promise)
throws VTSException
Throws: Returns the set of vouchers whose issuer and promise both match
the issuer and promise specified in the parameters.
VTSSecurityException - if the VTSAgent cannot be authenticated If null is specified for the issuer or promise parameter, it
correctly. 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.
5.4.14 getLog Returns:
public java.lang.Set getLog() the set of vouchers held by the holder of the VTSAgent.
throws VTSException
Returns a set of completed sessions prepared or received by the Throws:
VTSAgent. This set represents the trading log of the VTSAgent. A
VTS may delete an old log eventually, so that the entire log may
not be returned; the amount of the log kept by the VTSAgent is
implementation-specific.
Returns: VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
the set of completed sessions prepared or received by the VTSAgent. 5.4.13. getSessions
Throws: public java.util.Set getSessions()
throws VTSException
VTSSecurityException - if the VTSAgent cannot be authenticated Returns a set of incomplete sessions prepared by the VTSAgent.
correctly.
5.4.15 addReceptionListener Returns:
public void addReceptionListener(ReceptionListener l) the set of sessions prepared by the VTSAgent that are not yet
throws VTSException completed.
Adds a ReceptionListener to the listener list. Throws:
After a ReceptionListener l is registered by this method, l.arrive() VTSSecurityException - if the VTSAgent cannot be authenticated
will be called whenever the VTSAgent receives a voucher. correctly.
Nothing is performed if the specified listener is null. 5.4.14. getLog
Throws: public java.util.Set getLog()
throws VTSException
VTSSecurityException - if the VTSAgent cannot be authenticated Returns a set of completed sessions prepared or received by the
correctly. VTSAgent. This set represents the trading log of the VTSAgent. A
VTS may delete an old log eventually, so that the entire log may
not be returned; the amount of the log kept by the VTSAgent is
implementation-specific.
5.4.16 removeReceptionListener Returns:
public void removeReceptionListener(ReceptionListener l) the set of completed sessions prepared or received by the
throws VTSException VTSAgent.
Removes a ReceptionListener from the listener list. Throws:
Nothing is performed when the specified listener is null or not VTSSecurityException - if the VTSAgent cannot be authenticated
registered. correctly.
Throws: 5.4.15. addReceptionListener
VTSSecurityException - if the VTSAgent cannot be authenticated public void addReceptionListener(ReceptionListener l)
correctly. throws VTSException
5.5 Session Adds a ReceptionListener to the listener list.
public interface Session After a ReceptionListener l is registered by this method,
l.arrive() will be called whenever the VTSAgent receives a
voucher.
Represents the logical connection established by the trade. Nothing is performed if the specified listener is null.
Sessions are established by VTSAgent#prepare().
A session has four states: prepared, activated, suspended, and Throws:
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 disappear from the VTSAgent; the session VTSSecurityException - if the VTSAgent cannot be authenticated
will be collected by the GC unless other objects keep its correctly.
reference.
5.5.1 getIdentifier 5.4.16. removeReceptionListener
public String getIdentifier() public void removeReceptionListener(ReceptionListener l)
throws VTSException
Returns the identifier of the session. The generation scheme of Removes a ReceptionListener from the listener list.
the identifier is implementation-specific. An implementation may
use a transaction ID as the identifier of the session.
Returns: Nothing is performed when the specified listener is null or not
registered.
the string of the identifier of the session. Throws:
5.5.2 getVoucher VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
public Voucher getVoucher() 5.5. Session
Returns the voucher to be traded using the session, or returns null public interface Session
if the session has not been activated.
Returns: Represents the logical connection established by the trade.
Sessions are established by VTSAgent#prepare().
the voucher to be traded or null if the state of the session is A session has four states: prepared, activated, suspended, and
"prepared". 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 fails transiently (e.g., network failure),
the session will be "suspended". Suspended sessions can be re-
"activated" and restarted by calling VTSAgent#resume().
5.5.3 getSender A completed session may disappear from the VTSAgent; the session
will be collected by the GC unless other objects keep its
reference.
public Participant getSender() 5.5.1. getIdentifier
Returns the sender of the session, i.e., the creator who prepared
the session.
Returns: public String getIdentifier()
the sender of the session. 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.
5.5.4 getReceiver Returns:
public Participant getReceiver() the string of the identifier of the session.
Returns the receiver of the session, i.e., the participant 5.5.2. getVoucher
specified when preparing the session (by the VTSAgent#prepare()
method).
Returns: public Voucher getVoucher()
the receiver of the session. Returns the voucher to be traded using the session, or returns
null if the session has not been activated.
5.5.5 isPrepared Returns:
public boolean isPrepared() the voucher to be traded, or null if the state of the session is
"prepared".
Verifies if the session is "prepared". 5.5.3. getSender
Returns: public Participant getSender()
true if the session is in "prepared" state, or false. Returns the sender of the session (i.e., the creator who prepared
the session).
5.5.6 isActivated Returns:
public boolean isActivated() the sender of the session.
Verifies if the session is "activated". 5.5.4. getReceiver
Returns: public Participant getReceiver()
true if the session is in "activated" state, or false. Returns the receiver of the session (i.e., the participant
specified when preparing the session (by the VTSAgent#prepare()
method)).
5.5.7 isSuspended Returns:
public boolean isSuspended() the receiver of the session.
Verifies if the session is "suspended". 5.5.5. isPrepared
Returns: public boolean isPrepared()
true if the session is in "suspended" state, or false. Verifies if the session is "prepared".
5.5.8 isCompleted Returns:
public boolean isCompleted()
Verifies if the session is "completed". true if the session is in the "prepared" state, otherwise, false.
Returns: 5.5.6. isActivated
true if the session is in "completed" state, or false. public boolean isActivated()
5.6 Voucher Verifies if the session is "activated".
public interface Voucher Returns:
Represents voucher(s) described in [VTS]. An object implementing true if the session is in the "activated" state, otherwise, false.
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 5.5.7. isSuspended
public Participant getIssuer() public boolean isSuspended()
Returns the issuer part of the voucher(s). Verifies if the session is "suspended".
Returns: Returns:
the participant who issued the voucher(s). true if the session is in the "suspended" state, otherwise, false.
5.6.2 getPromise 5.5.8. isCompleted
public VoucherComponent getPromise() public boolean isCompleted()
Returns the promise part of the voucher(s). Verifies if the session is "completed".
Returns: Returns:
the voucher component that defines the promise of the voucher. true if the session is in the "completed" state, otherwise, false.
5.6.3 getCount 5.6. Voucher
public java.lang.Number getCount() public interface Voucher
Returns the number of the voucher(s). Represents voucher(s) described in [VTS]. 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.
Returns: 5.6.1. getIssuer
the positive (>0) number of the voucher(s). public Participant getIssuer()
5.7 VoucherComponentRepository Returns the issuer part of the voucher(s).
public interface VoucherComponentRepository Returns:
Maintains VoucherComponents. the participant who issued the voucher(s).
An object implementing VoucherComponentRepository provides a means 5.6.2. getPromise
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 public VoucherComponent getPromise()
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 register Returns the promise part of the voucher(s).
public VoucherComponent register(org.w3c.dom.Document document) Returns:
Creates a voucher component associated with the specified DOM the voucher component that defines the promise of the voucher.
object and registers the voucher component with the repository.
A voucher component of the voucher to be issued must be registered 5.6.3. getCount
using this method.
Nothing is performed (and the method returns null) if the specified public java.lang.Number getCount()
document is null or the syntax of the document does not conform to
the VTS.
The method returns the registered voucher component if the Returns the number of the voucher(s).
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 specified the positive (>0) number of the voucher(s).
document, or null if the document is null or has wrong syntax.
5.8 VoucherComponent 5.7. VoucherComponentRepository
public interface VoucherComponent public interface VoucherComponentRepository
Represents the voucher component that defines the promise of the Maintains VoucherComponents.
voucher.
Each VoucherComponent object has its own unique identifier, and it An object implementing VoucherComponentRepository provides a means
is associated with an XML document that describes the promise made of retrieving the voucher components that are the promises of
by the issuer of the voucher, e.g., the goods or services can be vouchers in the VVS.
claimed in exchange for redeeming the voucher.
This interface can be implemented as sort of a "smart pointer" to Before issuing a voucher, the promise of the voucher must be
the XML document. An implementation may have a reference to a registered with this repository. The repository can be
voucher component repository instead of the voucher component and implemented as either a network-wide directory service or personal
retrieve the document dynamically from the repository when the storage like the ParticipantRepository.
getDocument() method is called.
5.8.1 getIdentifier 5.7.1. register
public String getIdentifier()
Returns the identifier of the voucher component. Each voucher public VoucherComponent register(org.w3c.dom.Document document)
component must have a unique identifier. The identifier may be
used to check for equivalence of voucher components.
The format of the identifier is implementation-specific, however, Creates a voucher component associated with the specified DOM
it is RECOMMENDED to include the hash value of the voucher object and registers the voucher component with the repository.
component in the identifier to assure its uniqueness. For
generating the hash value, it is desirable to use a secure hash
function, e.g., [SHA-1], and to apply a canonicalization function,
e.g., [EXC-C14N], before applying the hash function to minimize the
impact of insignificant format changes to the voucher component,
e.g., line breaks or character encoding.
Returns: A voucher component of the voucher to be issued must be registered
using this method.
The identifier string of the voucher component. 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.
5.8.2 getDocument 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).
public org.w3c.dom.Document getDocument() Returns:
Returns a Document Object Model [DOM] representation of the a registered voucher component associated with the specified
document associated with the voucher component by the document, or null if the document is null or has wrong syntax.
VoucherComponentRepository#register() method.
The DOM object to be returned may be retrieved from a 5.8. VoucherComponent
VoucherComponentRepository on demand, instead of the
VoucherComponent always keeping a reference to the DOM object.
The VTS must guarantee that the getDocument method will eventually public interface VoucherComponent
return the DOM object provided that the voucher associated with the
corresponding voucher component exists in the VVS.
Returns: Represents the voucher component that defines the promise of the
voucher.
a DOM representation of the document associated with the voucher Each VoucherComponent object has its own unique identifier and is
component. associated with an XML document that describes the promise made by
the issuer of the voucher (e.g., goods or services can be claimed
in exchange for redeeming the voucher).
Throws: 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
it may retrieve the document dynamically from the repository when
the getDocument() method is called.
DocumentNotFoundException - if the associated DOM object cannot be 5.8.1. getIdentifier
retrieved.
5.9 ReceptionListener public String getIdentifier()
public interface ReceptionListener extends java.util.EventListener Returns the identifier of the voucher component. Each voucher
component must have a unique identifier. The identifier may be
used to check for equivalence of voucher components.
Provides a listener interface that provides notification that a The format of the identifier is implementation-specific, however,
VTSAgent has been received a voucher. it is RECOMMENDED that the hash value of the voucher component in
the identifier be included to assure uniqueness. For generating
the hash value, it is desirable to use a secure hash function
(e.g., [SHA-1]) and to apply a canonicalization function (e.g.,
[EXC-C14N]) before applying the hash function to minimize the
impact of insignificant format changes to the voucher component,
(e.g., line breaks or character encoding).
When a voucher arrives at VTSAgent, the VTSAgent invokes arrive() Returns:
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 the identifier string of the voucher component.
that "You have new vouchers", so that this interface may be
implemented by wallets or other applications using VTS.
5.9.1 arrive 5.8.2. getDocument
public void arrive(Session session) public org.w3c.dom.Document getDocument()
Provides notification of the arrival of a voucher. Returns a Document Object Model [DOM] representation of the
document associated with the voucher component by the
VoucherComponentRepository#register() method.
After the listener is registered to a VTSAgent (by the The DOM object to be returned may be retrieved from a
VTSAgent#addReceptionListener() method), the VTSAgent invokes this VoucherComponentRepository on demand, instead of the
method whenever it receives a voucher. VoucherComponent always keeping a reference to the DOM object.
The specified session is equivalent to the session used by the The VTS must guarantee that the getDocument method will eventually
sender to trade the voucher. The state of the session is return the DOM object, provided that the voucher associated with
"completed" when this method is called. the corresponding voucher component exists in the VVS.
5.10 Exceptions Returns:
java.lang.Exception a DOM representation of the document associated with the voucher
+-- VTSException component.
+-- CannotProceedException
+-- DocumentNotFoundException
+-- FeatureNotAvailableException
+-- InsufficientVoucherException
+-- InvalidParticipantException
+-- InvalidStateException
+-- VTSSecurityException
VTSException Throws:
This is the superclass of all exceptions thrown by the methods
in the interfaces constructs the VTS-API.
CannotProceedException DocumentNotFoundException - if the associated DOM object cannot be
This exception is thrown when a trading is interrupted due to retrieved.
network failures or other errors.
DocumentNotFoundException 5.9. ReceptionListener
This exception is thrown when the document associated with a
voucher component cannot be found.
FeatureNotAvailableException public interface ReceptionListener extends java.util.EventListener
This exception is thrown when the invoked method is not sup-
ported.
InsufficientVoucherException Provides a listener interface with a notification that a VTSAgent
This exception is thrown when the number of the voucher is has received a voucher.
less than the number specified to trade.
InvalidParticipantException When a voucher arrives at the VTSAgent, the VTSAgent invokes the
This exception is thrown when the specified participant cannot arrive() method of each registered ReceptionListener.
be located. ReceptionListeners can obtain a Session object, which contains
information about the received voucher and the sender of the
voucher.
InvalidStateException This interface is intended to provide a means of notifying a
This exception is thrown when the state of the session is wallet that "You have new vouchers", so that this interface may be
invalid to proceed the operation. implemented by wallets or other applications that use VTS.
VTSSecurityException 5.9.1. arrive
This exception is thrown when authentication fails or a method
which requires authentication in advance is called without
authentication.
6. Example Code public void arrive(Session session)
Provides notification of the arrival of a voucher.
After the listener is registered to a VTSAgent (by the
VTSAgent#addReceptionListener() 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
+-- FeatureNotAvailableException
+-- InsufficientVoucherException
+-- InvalidParticipantException
+-- InvalidStateException
+-- VTSSecurityException
VTSException
This is the superclass of all exceptions thrown by the methods in
the interfaces that construct the VTS-API.
CannotProceedException
This exception is thrown when a trading is interrupted by network
failures or other errors.
DocumentNotFoundException
This exception is thrown when the document associated with a
voucher component cannot be found.
FeatureNotAvailableException
This exception is thrown when the invoked method is not supported.
InsufficientVoucherException
This exception is thrown when the number of the voucher is less
than the number specified for trading.
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
and the operation cannot proceed.
VTSSecurityException
This exception is thrown when authentication fails, or when a
method that requires authentication in advance is called without
authentication.
6. Example Code
// Issue a voucher // Issue a voucher
VTSManager vts = new FooVTSManager(); VTSManager vts = new FooVTSManager();
ParticipantRepository addrBook = vts.getParticipantRepository(); ParticipantRepository addrBook = vts.getParticipantRepository();
VoucherComponentRepository vcr = vts.getVoucherComponentRepository(); VoucherComponentRepository vcr = vts.getVoucherComponentRepository();
Participant you = addrBook.lookup("http://example.org/foo"); Participant you = addrBook.lookup("http://example.org/foo");
// looks up a trading partner identified as "http://example.org/foo". // looks up a trading partner identified as
// "http://example.org/foo".
VTSAgent me = addrBook.lookup("myName").getVTSAgent(); VTSAgent me = addrBook.lookup("myName").getVTSAgent();
// a short-cut name may be used if VTS implementation allows. // a short-cut name may be used if VTS implementation allows.
VoucherComponent promise = vcr.register(anXMLVoucherDocument); VoucherComponent promise = vcr.register(anXMLVoucherDocument);
// registers a voucher component corresponding to the voucher to // registers a voucher component that corresponds to the voucher
// be issued. // to be issued.
try { try {
me.login(); me.login();
// sets up the issuer's smartcard (assuming distributed VTS). // sets up the issuer's smartcard (assuming distributed VTS).
s = me.prepare(you); s = me.prepare(you);
// receives a challenge from the partner. // receives a challenge from the partner.
me.issue(s, promise, 1); me.issue(s, promise, 1);
// sends a voucher using the received challenge. // sends a voucher using the received challenge.
me.logout(); me.logout();
} catch (VTSException e) { } catch (VTSException e) {
// if an error (e.g. a network trouble) occurs... // if an error (e.g., a network trouble) occurs...
System.err.println("Sorry."); System.err.println("Sorry.");
e.printStackTrace(); e.printStackTrace();
// this example simply prints a stack trace, but a real wallet // this example simply prints a stack trace, but a real wallet
// may prompt the user to retry (or cancel). // may prompt the user to retry (or cancel).
} }
// Transfer all my vouchers // Transfer all my vouchers
VTSManager vts = new FooVTSManager(); VTSManager vts = new FooVTSManager();
ParticipantRepository addrBook = vts.getParticipantRepository(); ParticipantRepository addrBook = vts.getParticipantRepository();
Participant you = addrBook.lookup("8f42 5aab ffff cafe babe..."); Participant you = addrBook.lookup("8f42 5aab ffff cafe babe...");
// some VTS implementations would use a hash value of a public key // some VTS implementations would use a hash value of a public key
// (aka fingerprint) as an identifier of a participant. // (aka fingerprint) as an identifier of a participant.
VTSAgent me = addrBook.lookup("myName").getVTSAgent(); VTSAgent me = addrBook.lookup("myName").getVTSAgent();
try { try {
me.login(); me.login();
Iterator i = me.getContents(null, null).iterator(); Iterator i = me.getContents(null, null).iterator();
while (i.hasNext()) { while (i.hasNext()) {
Voucher v = (Voucher) i.next(); Voucher v = (Voucher) i.next();
s = me.prepare(you); s = me.prepare(you);
me.transfer(s, v.getIssuer(), v.getPromise(), v.getCount()); me.transfer(s, v.getIssuer(), v.getPromise(), v.getCount());
} }
skipping to change at page 26, line 52 skipping to change at page 29, line 42
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
Security is very important for trading vouchers. VTS implementations Security is very important for trading vouchers. VTS implementations
are responsible for preventing illegal acts upon vouchers as are responsible for preventing illegal acts upon vouchers (as
described in [VTS], as well as preventing malicious accesses from described in [VTS]), as well as preventing malicious access from
invalid users and fake server attacks including man-in-the-middle invalid users and fake server attacks, including man-in-the-middle
attacks. attacks.
The means to achieve the above requirements are not specified in this The means to achieve the above requirements are not specified in this
document since it depends on VTS implementation, however, securing document because they depend on VTS implementation. However,
communication channels (e.g. using TLS) between client VTS plug-ins securing communication channels (e.g., using TLS) between client VTS
and the central server in a centralized VTS (as described in 5.4.1 plug-ins and the central server in a centralized VTS (as described in
login()) and applying cryptographic challenge-and-response techniques 5.4.1 login()), and applying cryptographic challenge-and-response
in a distributed VTS are likely helpful and strongly recommended to techniques in a distributed VTS are likely to be helpful and are
implement a secure VTS. strongly recommended to implement a secure VTS.
This document assumes that the VTS plug-in is trusted by its user. This document assumes that the VTS plug-in is trusted by its user.
The caller application of a VTS should authenticate the VTS plug-in The caller application of a VTS should authenticate the VTS plug-in
and bind it securely using the VTS Provider information specified in and bind it securely using the VTS Provider information specified in
the Voucher Component. This document, however, does not specify any the Voucher Component. This document, however, does not specify any
application authentication scheme and it is assumed to be specified application authentication scheme and it is assumed to be specified
by other related standards. Until various VTS systems are deployed, by other related standards. Until various VTS systems are deployed,
it is enough to manually check and install VTS plug-ins like other it is enough to manually check and install VTS plug-ins like other
download applications. download applications.
8. Normative References 8. Acknowledgements
[DOM] V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs, A. Le The following persons, in alphabetic order, contributed substantially
Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, and L. Wood. "Docu- to the material herein:
ment Object Model (DOM) Level 1 Specification", W3C Recommendation,
October 1998, <http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/>
[GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher Lan- Donald Eastlake 3rd
guage", draft-ietf-trade-voucher-lang-06.txt, 2004. Iguchi Makoto
Yoshitaka Nakamura
Ryuji Shoda
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Require- 9. Normative References
ment Levels", BCP 14, RFC 2119, 1997.
9. Informative References [DOM] V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs,
A. Le Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, and
L. Wood. "Document Object Model (DOM) Level 1
Specification", W3C Recommendation, October 1998,
<http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/>
[ECML] J. W. Parsons and D. Eastlake "Electronic Commerce Modeling [GVL] Fujimura, K. and M. Terada, "XML Voucher: Generic Voucher
Language (ECML) Version 2 Specification", draft-ietf-trade- Language", RFC 4153, September 2005.
ecml2-spec-09.txt, 2004.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
10. Informative References
[ECML] Eastlake 3rd, D., "Electronic Commerce Modeling Language
(ECML) Version 2 Specification", RFC 4112, June 2005.
[EXC-C14N] J. Boyer, D. Eastlake, and J. Reagle, "Exclusive XML [EXC-C14N] J. Boyer, D. Eastlake, and J. Reagle, "Exclusive XML
Canonicalization Version 1.0", W3C Recommendation, July 2002, Canonicalization Version 1.0", W3C Recommendation, July
<http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/> 2002, <http://www.w3.org/TR/2002/REC-xml-exc-c14n-
20020718/>
[GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.), [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner
"SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854, (Eds.), "SEMPER - Secure Electronic Marketplace for
Springer-Verlag, 2000. Europe," LNCS 1854, Springer-Verlag, 2000.
[IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version [IOTP] Burdett, D., "Internet Open Trading Protocol - IOTP
1.0", RFC 2801, 2000. Version 1.0", RFC 2801, April 2000.
[JCC] T. Goldstein, "The Gateway Security Model in the Java Elec- [JCC] T. Goldstein, "The Gateway Security Model in the Java
tronic Commerce Framework", Proc. of Financial Cryptography '97, Electronic Commerce Framework", Proc. of Financial
1997. Cryptography '97, 1997.
[SHA-1] Department of Commerce/National Institute of Standards and [SHA-1] Department of Commerce/National Institute of Standards and
Technology, "FIPS PUB 180-1. Secure Hash Standard. U.S.", Technology, "FIPS PUB 180-1. Secure Hash Standard. U.S.",
<http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt> <http://csrc.nist.gov/publications/fips/fips180-2/
fips180-2withchangenotice.pdf>
[VTS] K. Fujimura and D. Eastlake, "Requirements and Design for [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
Voucher Trading System (VTS)", RFC3506, 2003. RFC 2246, January 1999.
10. Author's Address [VTS] Fujimura, K. and D. Eastlake, "Requirements and Design for
Voucher Trading System (VTS)", RFC 3506, March 2003.
Authors' Addresses
Masayuki Terada Masayuki Terada
NTT DoCoMo, Inc. NTT DoCoMo, Inc.
3-5 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN 3-5 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-8536 JAPAN
Phone: +81-(0)46-840-3809 Phone: +81-(0)46-840-3809
Fax: +81-(0)46-840-3364 Fax: +81-(0)46-840-3705
Email: te@mml.yrp.nttdocomo.co.jp EMail: te@rex.yrp.nttdocomo.co.jp
Ko Fujimura 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)46-859-3814
Fax: +81-(0)46-859-8329 Phone: +81-(0)46-859-3053
Email: fujimura@isl.ntt.co.jp Fax: +81-(0)46-859-1730
EMail: fujimura.ko@lab.ntt.co.jp
Full Copyright Statement Full Copyright Statement
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2005).
This document and translations of it may be copied and furnished to This document is subject to the rights, licenses and restrictions
others, and derivative works that comment on or otherwise explain it contained in BCP 78, and except as set forth therein, the authors
or assist in its implementation may be prepared, copied, published retain all their rights.
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 doc-
ument 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 develop-
ing 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 This document and the information contained herein are provided on an
revoked by the Internet Society or its successors or assigns. "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM 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.
This document and the information contained herein is provided on an Intellectual Property
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING The IETF takes no position regarding the validity or scope of any
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Intellectual Property Rights or other rights that might be claimed to
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MER- pertain to the implementation or use of the technology described in
CHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at ietf-
ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
 End of changes. 353 change blocks. 
923 lines changed or deleted 962 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/