idnits 2.17.1 draft-ietf-trade-voucher-vtsapi-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 3 instances of lines with control characters in the document. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 193 has weird spacing: '...request plug...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 2003) is 7741 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC 2119' is mentioned on line 161, but not defined == Unused Reference: 'RFC2119' is defined on line 1314, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DOM' == Outdated reference: A later version (-13) exists of draft-ietf-trade-ecml2-spec-08 -- Possible downref: Non-RFC (?) normative reference: ref. 'EXC-C14N' -- Possible downref: Non-RFC (?) normative reference: ref. 'GPSF' == Outdated reference: A later version (-07) exists of draft-ietf-trade-voucher-lang-04 ** Downref: Normative reference to an Informational draft: draft-ietf-trade-voucher-lang (ref. 'GVL') ** Downref: Normative reference to an Informational RFC: RFC 2801 (ref. 'IOTP') -- Possible downref: Non-RFC (?) normative reference: ref. 'JCC' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA-1' ** Downref: Normative reference to an Informational draft: draft-ietf-trade-drt-requirements (ref. 'VTS') Summary: 7 errors (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Trade Working Group February 2003 2 INTERNET-DRAFT Masayuki Terada 3 Ko Fujimura 4 Expires: August 2003 NTT 6 Voucher Trading System Application Programming Interface (VTS-API) 7 9 Status of This Document 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Distribution of this document is unlimited. Please send comments to 31 the TRADE working group at , which may 32 be joined by sending a message with subject "subscribe" to . 35 Discussions of the TRADE working group are archived at 36 http://lists.elistx.com/archives/ietf-trade. 38 Abstract 40 This document specifies the Voucher Trading System Application 41 Programming Interface (VTS-API). The VTS-API allows a wallet or other 42 application to issue, transfer, and redeem vouchers in a uniform 43 manner independent of the VTS implementation. The VTS is a system to 44 securely transfer vouchers, e.g., coupons, tickets, loyalty points, 45 and gift certificates; this process is often necessary in the course 46 of payment and/or delivery transactions. 48 Acknowledgements 50 The following persons, in alphabetic order, contributed substantially 51 to the material herein: 53 Donald Eastlake 3rd 54 Iguchi Makoto 55 Yoshitaka Nakamura 56 Ryuji Shoda 58 Table of Contents 60 Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1 61 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 62 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Processing Model . . . . . . . . . . . . . . . . . . . . . 4 65 3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 66 4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 5. Interface Definitions . . . . . . . . . . . . . . . . . . 7 68 5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 7 69 5.1.1 getParticipantRepository . . . . . . . . . . . . . . . . . 7 70 5.1.2 getVoucherComponentRepository . . . . . . . . . . . . . . 7 71 5.2 ParticipantRepository . . . . . . . . . . . . . . . . . . 8 72 5.2.1 lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 5.3 Participant . . . . . . . . . . . . . . . . . . . . . . . 8 74 5.3.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 8 75 5.3.2 getVTSAgent . . . . . . . . . . . . . . . . . . . . . . . 9 76 5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 12 82 5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12 83 5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13 84 5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 14 85 5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14 86 5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 15 88 5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 15 89 5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 16 90 5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 91 5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 17 92 5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 17 93 5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 17 94 5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 18 95 5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 18 96 5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 18 97 5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 18 98 5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 18 99 5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 19 100 5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 19 101 5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 19 102 5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 19 103 5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 19 104 5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 19 105 5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 20 106 5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 20 107 5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 20 108 5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 21 109 5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 21 110 5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 21 111 5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 22 112 5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 22 113 5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 22 114 6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 23 115 7. Security Considerations . . . . . . . . . . . . . . . . . 25 116 8. References . . . . . . . . . . . . . . . . . . . . . . . . 25 117 9. Author's Address . . . . . . . . . . . . . . . . . . . . . 26 118 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 26 120 1. Introduction 122 This document specifies the Voucher Trading System Application 123 Programming Interface (VTS-API). The motivation and background of the 124 Voucher Trading System (VTS) are described in Requirements for 125 Generic Voucher Trading [VTS]. 127 A voucher is a logical entity that represents a certain right and is 128 logically managed by the VTS. A voucher is generated by the issuer, 129 traded among users, and finally collected using VTS. The terminology 130 and model of the VTS are also described in [VTS]. 132 The VTS-API allows a caller application to issue, transfer, and 133 redeem vouchers in a uniform manner independent of the VTS 134 implementation. Several attempts have been made at providing a 135 generic payment API. Java Commerce Client [JCC] and Generic Payment 136 Service Framework [GPSF], for example, introduce a modular wallet 137 architecture that permits diverse types of payment modules to be 138 added as plug-ins and supports both check-like/cash-like payment 139 models. This document is inspired by these approaches but the scope 140 of this document is limited to the VTS model, in which cash-like 141 payment model is assumed and vouchers are directly or indirectly 142 transferred between sender (transferor) and receiver (transferee) via 143 the VTS. This document is not intended to support API for SET, 144 e-check or other payment schemes that do not fit the VTS model. 146 Unlike the APIs provided in JCC and GPSF, which are designed to 147 transfer only monetary values, this API enables the transfer of a 148 wide-range of values through the use of XML-based Generic Voucher 149 Language [GVL]. The monetary meaning of the voucher is interpreted by 150 the upper application layer using the information described in the 151 language. This approach makes it possible to provide a simpler API in 152 the voucher-transfer layer and enhances runtime efficiency. 153 The API specification in this document is described in the Java 154 language syntax. Bindings for other programming languages may be 155 completed in a future version of this document or separate related 156 specifications. 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 160 this document are to be interpreted as described in [RFC 2119] 162 2. Processing Model 164 This section provides the processing model in which the VTS-API is 165 used. Most of the text in this section has been taken from the 166 Generic Voucher Language specification [GVL]. 168 There are several ways of implementing VTS. For discount coupons or 169 event tickets, for example, the smart-card-based decentralized 170 offline VTS is often preferred, whereas for bonds or securities, 171 the centralized online VTS is preferred. It is impractical to 172 define standard protocols for issuing, transferring, or redeeming 173 vouchers at this moment. 175 To provide implementation flexibility, this document assumes a 176 modular wallet architecture that allows multiple VTS to be added as 177 plug-ins. In this architecture, instead of specifying a standard 178 voucher transfer protocol, two specifications, i.e., Voucher 179 Component and VTS-API specifications, are standardized (Figure 1). 181 Sender wallet/Issuing system Receiver wallet/Collecting system 182 +---------------------------+ +---------------------------+ 183 | | | | 184 | | Voucher Component | | 185 | | (Specifies Issuer, Promise, Holder, and VTS Provider) | | 186 | |-------------------------------------------------------->| | 187 | | | | | | 188 | | Intention to receive and payment (option) | | 189 | |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 190 | | | | | | 191 | | | | | | 192 | | Issue/transfer/ VTS | | VTS Register | | 193 | | redeem request plug-in | plug-in Listener(*1)| | 194 | |------------------>| | | |<------------------| | 195 | | (VTS API) |<- - - - - - - ->| (VTS API) | | 196 | | | VTS-specific | | | 197 | | | protocol if VTS | | | 198 | | | is distributed | | | 199 | | Result |<- - - - - - - ->| Notify(*2) | | 200 | |<------------------| | | |------------------>| | 201 +---------------------------+ +---------------------------+ 202 (*1) Registration is optional. Note also that the VTS plug-ins are 203 usually pre-registered when the wallet or collecting system 204 is started. 206 (*2) If a listener is registered. 208 Figure 1. Wallet architecture with VTS plug-ins 210 After sender and receiver agree on what vouchers are to be traded and 211 which VTS is to be used, the issuing system or wallet system requests 212 the corresponding VTS plug-in to permit the issue, transfer, or 213 redeem transactions to be performed via the VTS-API. The VTS then 214 rewrites the ownership of the vouchers using the VTS-specific 215 protocol. Finally, a completion event is sent to the wallet systems 216 or issuing/collecting systems. 218 This document describes the VTS-API specification. See [GVL] for the 219 Voucher Component specification. 221 3. Design Overview 223 We have adopted the following approach to specify the VTS-API. 225 1) Provide an abstract and uniform API that encapsulates the VTS 226 implementation. For example, a common API is provided for both 227 centralized and decentralized VTS. It brings more freedom of VTS 228 selection for issuers and application developers. 230 2) To provide an abstract and uniform API, this document introduces 231 an interface called VTSAgent that is associated with a holder and 232 provides methods to manipulate vouchers held by its holder. 233 Vouchers are accessed through the methods provided by the 234 VTSAgent. 236 3) Use existing standards for the VTS branding mechanism 237 (negotiation). This document assumes that the VTS to be used for 238 sending a voucher has settled before calling the VTS-APIs. 239 Negotiation can be done within the upper application layer using 240 other standards, e.g., [IOTP] or [ECML], if necessary. 242 4) Support only push-type voucher transfer interface in which voucher 243 transfer session is initiated by the transferor side. Pull-type 244 voucher transfer interface can be implemented on top of the 245 push-type VTS interface at application level. 247 4. Concepts 249 The VTS-API consists of the following interfaces. A VTS is required 250 to implement all of the interfaces except ReceptionLister, which is 251 intended to be implemented by wallets or other applications that 252 use VTS. 254 VTSManager 256 Provides the starting point to use a VTS plug-in. All of the 257 objects needed to manipulate vouchers can be directly or indirectly 258 acquired via the VTSManager. A VTSManager maintains the two 259 repositories; a ParticipantRepository and a 260 VoucherComponentRepository described below. 262 ParticipantRepository 264 Provides the access points of Participants, which are to be trading 265 partners. A ParticipantRepository maintains Participants and acts as 266 an "address book" of trading partners. 268 Participant 270 Represents a participant (such as issuers, holders, and 271 collectors). A Participant knows how to obtain the corresponding 272 VTSAgent described below. 274 VTSAgent (extends Participant) 276 Provides the access point of vouchers in Valid Voucher Set (VVS) 277 that is logically managed by VTS. A VTSAgent provides a means of 278 manipulating vouchers held by its holder; basic trading methods, 279 i.e., issue, transfer, consume, and present. Before calling trading 280 methods, the application must create a Session which is described 281 below. 283 Session 285 Represents the logical connection established by the trade. A 286 Session has references to two Participants, i.e., the sender and the 287 receiver. After trading methods are called using a Session, the 288 Session holds a reference to the Vouchers to be traded. 290 Voucher 292 Represents one or more vouchers of which all of the issuer part and 293 promise part of vouchers are the same. A Voucher holds references to 294 the Participant (issuer) who issued the voucher and a 295 VoucherComponent (promise) which is described below. 297 VoucherComponent 299 Represents a Voucher Component described in [GVL]. It defines the 300 promise part of the voucher. 302 VoucherComponentRepository 304 Provides the access points of VoucherComponents. A 305 VoucherComponentRepository maintains VoucherComponents and acts as a 306 "voucher type book" managed by the VTS. This document assumes that a 307 set of VoucherComponents has been acquired and stored in this 308 repository. Delivery of VoucherComponents is beyond the scope of this 309 document. It may be delivered within the VTS from the trading 310 partners or manually acquired from a trusted third party (See Section 311 3 of [GVL]). 313 ReceptionListener 315 Provides a listener function with regard to the receipt of a voucher 316 by VTSAgent to wallets or other applications that implement this 317 interface. (This interface may not be implemented as part of VTS) 319 5. Interface Definitions 321 The interfaces defined in this document reside in the package named 322 "org.ietf.vts". Wallets or other applications that use this 323 API,should import this package as "import org.ietf.vts.*;". 325 5.1 VTSManager 327 public interface VTSManager 329 Provides the starting point to use a VTS plug-in. 331 All of the objects needed to manipulate vouchers can be directly or 332 indirectly acquired via a VTSManager, so that wallets or other 333 applications can make the VTS available by instantiating an object 334 implementing this interface. 336 A class that implements the VTSManager interface must have a public 337 default constructor (a constructor without any parameters). The VTS 338 provides a name for such constructor so that the implementation class 339 can bootstrap the interface. 341 5.1.1 getParticipantRepository 343 public ParticipantRepository getParticipantRepository() 345 Returns a repository that maintains Participants. 347 Returns: 349 the ParticipantRepository of the VTS, or null if no 350 ParticipantRepository is available. 352 5.1.2 getVoucherComponentRepository 354 public VoucherComponentRepository getVoucherComponentRepository() 356 Returns a repository that maintains VoucherComponents. 358 Returns: 360 the VoucherComponentRepository of the VTS, or null if no 361 VoucherComponentRepository is available. 363 5.2 ParticipantRepository 365 public interface ParticipantRepository 367 Provides the access points of Participants. A ParticipantRepository 368 maintains Participants and acts as an "address book" of trading 369 partners. 371 The object implementing this interface maintains Participants (or 372 holds a reference to an object maintaining Participants), which are 373 to be trading partners. 375 The implementation of ParticipantRepository may be either (an adaptor 376 to) "yellow pages" which is a network-wide directory service like 377 LDAP, or "pocket address book" which maintains only personal 378 acquaintances. 380 5.2.1 lookup 382 public Participant lookup(String id) 384 Retrieves the participant that has the specified id. 386 Returns: 388 the participant associated with the specified id or null if the id 389 is null or the corresponding participant cannot be found. 391 5.3 Participant 393 public interface Participant 395 Represents the participants (such as issuers, holders, and 396 collectors). 398 This interface is used as representation of the trade partners and 399 issuers of vouchers. Anyone can retrieve objects implementing 400 Participant from the participant repository. 402 5.3.1 getIdentifier 404 public String getIdentifier() 406 Returns the identifier of the participant. Each participant must 407 have a unique identifier. 409 The identifier can be used for looking up and retrieving the 410 participant via the ParticipantRepository. 412 The format of the identifier is implementation-specific. 414 Returns: 416 the identifier string of the participant. 418 5.3.2 getVTSAgent 420 VTSAgent getVTSAgent() 422 Returns a VTSAgent, whose identifier is the same as the identifier of 423 the participant. 425 Returns: 427 an object implementing VTSAgent. 429 5.4 VTSAgent 431 public interface VTSAgent extends Participant 433 Represents contact points to access vouchers in Valid Voucher Set 434 (VVS) that is managed by the VTS. 436 Each VTSAgent is associated with a holder and provides a means for 437 managing vouchers owned by the holder. The holder must be 438 authenticated using the login() method before being called by any 439 other method, or VTSSecurityException will be issue. 441 Before calling any trading method, i.e., issue(), transfer(), 442 consume(), and present(), the application must establish a session by 443 the prepare() method. 445 Sessions may often be suspended due to network failure when the 446 voucher is sent via a network. The suspended sessions can be 447 restarted by the resume() method. Details on the state management of 448 a session are described in Section 5.5. 450 Some VTSAgents may not have all of the trading methods; a voucher 451 collecting system doesn't require its VTSAgent to provide method for 452 issuing or creating vouchers. A VTSAgent returns 453 FeatureNotAvailableException when an unsupported method is invoked. 455 5.4.1 login 457 public void login(String passphrase) 458 throws VTSException 460 Authenticates the VTSAgent. The passphrase is specified if the VTS 461 requires it for authentication, otherwise it must be null. Nothing is 462 performed if the VTSAgent has already been logged-in. The 463 authentication scheme is implementation-specific. Examples of the 464 implementation are as follows: 466 1) Vouchers are managed on a remote centralized server (central VVS), 467 and the server requires a password to login. In this case, the 468 application may prompt the user to input the password and can be 469 given to the VTSAgent through this method. 471 2) Vouchers are managed on a remote centralized server (central VVS); 472 they require challenge-and-response authentication using 473 smartcards held by users. In this case, the passphrase may be null 474 since access to the smartcard can be done without contacting the 475 application or user, i.e., the VTSAgent receives the challenge 476 from the server, sends the challenge to the smartcard (within the 477 VTS), and returns the response from the smartcard to the server. 478 Note that a PIN to unlock the smartcard may be given through this 479 method depending on the implementation. 481 3) Each user holds their own smartcard in which their own vouchers 482 are stored (decentralized VVS). In this case, the passphrase may 483 be null since no authentication is required. Note that a PIN to 484 unlock the smartcard may be given through this depends on the 485 implementation. 487 Throws: 489 VTSSecurityException - if authentication fails. 491 5.4.2 logout 493 public void logout() 494 throws VTSException 496 Voids the authentication performed by the login() method. 498 After calling this method, calling any other method (except 499 login()) will cause VTSSecurityException. 501 The VTSAgent can login again by the login() method. 503 Throws: 505 VTSSecurityException - if the VTSAgent is not authenticated 506 correctly. 508 5.4.3 prepare 510 public Session prepare(Participant receiver) 511 throws VTSException 513 Establishes a session that is required for trading vouchers. The 514 trading partner who receives the vouchers is specified as receiver. 515 The vouchers to be traded will be specified later (when a trading 516 method is called). 518 The establishment of a session is implementation-specific. An 519 implementation that has a central VVS may start a transaction, while 520 other implementations that have decentralized VVS may get, from the 521 receiver, the challenge needed to authenticate the sender during the 522 establishment of the session. 524 If the VTSAgent has no ability to establish a session with the 525 specified receiver (permanent error), the VTSAgent throws an 526 InvalidParticipantExeption. If the VTSAgent can not establish a 527 session due to network failure (transient error), the VTSAgent throws 528 a CannotProceedException. 530 Parameters: 532 receiver - the trading partner who receives vouchers. 534 Returns: 536 an established session whose state is "prepared" (see Section 5.5). 538 Throws: 540 CannotProceedException - if the preparation of the session is 541 aborted (e.g. network failures). 542 FeatureNotAvailableException - if the VTSAgent does not provide 543 any trading methods. 544 InvalidParticipantException - if the specified participant is 545 invalid. 546 VTSSecurityException - if the VTSAgent cannot be authenticated 547 correctly. 549 5.4.4 issue 551 public void issue(Session session, 552 VoucherComponent promise, 553 java.lang.Number num) 554 throws VTSException 556 Issues vouchers. This method creates the specified number of 557 vouchers and adds them to the VVS. Note 558 that receiver is specified when the prepare() method is 559 called. Nothing is performed if the specified number is 0. 561 The session MUST be "prepared" when calling this method. The state 562 of the session will be "activated" when the vouchers are created, and 563 it will be "completed" when the transaction is successfully completed 564 or "suspended" if the transaction is interrupted abnormally (e.g., 565 network failures). 567 Parameters: 569 session - the session used by the issue transaction. 570 promise - the promise part of the voucher. 571 num - the number of vouchers to be issued. 573 Throws: 575 CannotProceedException - if the transaction cannot be successfully 576 completed. 577 FeatureNotAvailableException - if the VTSAgent does not provide 578 a means of issuing vouchers. 579 InvalidStateException - if the session is not "prepared". 580 VTSSecurityException - if the VTSAgent cannot be authenticated 581 correctly. 583 5.4.5 transfer 585 public void transfer(Session session, 586 Participant issuer, 587 VoucherComponent promise, 588 java.lang.Number num) 589 throws VTSException 591 Transfers vouchers. This method rewrites the specified number of 592 vouchers to in 593 the VVS. Note that receiver is specified when the prepare() method is 594 called. The VTSAgent must have sufficient vouchers in the VVS. 595 Nothing is performed if the specified number is 0. 597 The session MUST be "prepared" when calling this method. The state 598 of the session will be "activated" when the voucher are retrieved 599 from the sender, and it will be "completed" when the transaction is 600 successfully completed or "suspended" if the transaction is 601 interrupted abnormally (e.g., network failures). 603 If null is specified for the issuer parameter, it indicates "any 604 issuer". This method selects vouchers to be transferred from the set 605 of vouchers returned by the getContents(null, promise). 607 Parameters: 609 session - the session used by the transfer transaction. 610 issuer - the issuer part of the voucher, or null. 611 promise - the promise part of the voucher. 612 num - the number of vouchers to be transferred. 614 Throws: 616 CannotProceedException - if the transaction cannot be successfully 617 completed. 618 FeatureNotAvailableException - if the VTSAgent does not provide 619 a means of transferring vouchers. 620 InsufficientVoucherException - if the VTSAgent doesn't have a 621 sufficient number of vouchers to transfer. 622 InvalidStateException - if the session is not "prepared". 623 VTSSecurityException - if the VTSAgent cannot be authenticated 624 correctly. 626 5.4.6 consume 627 public void consume(Session session, 628 Participant issuer, 629 VoucherComponent promise, 630 java.lang.Number num) 631 throws VTSException 633 Consumes vouchers. This method deletes the specified number of 634 specified vouchers from the VVS. The VTSAgent 635 must have sufficient vouchers in the VVS. Nothing is performed if 636 the specified number is 0. 638 The session MUST be "prepared" when calling this method. The state 639 of the session will be "activated" when the vouchers are deleted, and 640 it will be "completed" when the transaction is successfully completed 641 or "suspended" if the transaction is interrupted abnormally (e.g., 642 network failures). 644 If null is specified for the issuer parameter, it indicates "any 645 issuer". This method selects vouchers to be consumed from the set of 646 vouchers returned by the getContents(null, promise). 648 Parameters: 650 session - the session used by the consume transaction. 651 issuer - the issuer part of the voucher, or null. 652 promise - the promise part of the voucher. 653 num - the number of vouchers to be consumed. 655 Throws: 657 CannotProceedException - if the transaction cannot be successfully 658 completed. 659 FeatureNotAvailableException - if the VTSAgent does not provide 660 a means of consuming vouchers. 661 InsufficientVoucherException - if the VTSAgent doesn't have a 662 sufficient number of vouchers to consume. 663 InvalidStateException - if the session is not "prepared". 664 VTSSecurityException - if the VTSAgent cannot be authenticated 665 correctly. 667 5.4.7 present 669 public void present(Session session, 670 Participant issuer, 671 VoucherComponent promise, 672 java.lang.Number num) 673 throws VTSException 675 Presents vouchers. This method shows that the sender has the 676 specified number of vouchers in the VVS to 677 the receiver of the session; No modification is performed to the 678 VVS. The VTSAgent must have a sufficient vouchers in the VVS. Nothing 679 is performed if the specified number is 0. 681 The session MUST be "prepared" when calling this method. The state 682 of the session will be "activated" when the vouchers are retrieved, 683 and it will be "completed" when the transaction is successfully 684 completed or "suspended" if the transaction is interrupted abnormally 685 (e.g., by network failures). 687 If null is specified for the issuer parameter, it indicates "any 688 issuer". This method selects vouchers to be presented from the set 689 of vouchers returned by the getContents(null, promise). 691 Parameters: 693 session - the session used by the present transaction. 694 issuer - the issuer part of the voucher, or null. 695 promise - the promise part of the voucher. 696 num - the number of the voucher to be presented. 698 Throws: 700 CannotProceedException - if the transaction cannot be successfully 701 completed. 702 InsufficientVoucherException - if the VTSAgent doesn't have a 703 sufficient number of vouchers to present. 704 InvalidStateException - if the session is not "prepared". 705 FeatureNotAvailableException - if the VTSAgent does not provide 706 a means of presenting vouchers. 707 VTSSecurityException - if the VTSAgent cannot be authenticated 708 correctly. 710 5.4.8 cancel 712 public void cancel(Session session) 713 throws VTSException 715 Releases the session. "Prepared" sessions MUST be canceled. An 716 implementation MAY be permitted to cancel "activated" or "suspended" 717 sessions. 719 Throws: 721 InvalidStateException - if the state of the session isn't 722 cancelable. 723 VTSSecurityException - if the VTSAgent cannot be authenticated 724 correctly. 726 5.4.9 resume 728 public void resume(Session session) 729 throws VTSException 731 Restarts the session. Only "suspended" sessions can be resumed. 733 The state of the session will be re-"activated" immediately, and it 734 will be "completed" when the transaction is successfully completed or 735 "suspended" again if the transaction is interrupted abnormally (e.g., 736 network failures). 738 Throws: 740 CannotProceedException - if the transaction cannot be successfully 741 completed. 742 InvalidStateException - if the session is not "suspended". 743 VTSSecurityException - if the VTSAgent cannot be authenticated 744 correctly. 746 5.4.10 create 748 public void create(VoucherComponent promise, java.lang.Number num) 749 throws VTSException 751 Creates vouchers where the issuer is the VTSAgent itself. This 752 method creates the specified number of vouchers and adds them to the VVS. Nothing is performed if the 754 specified number is 0. 756 Throws: 758 FeatureNotAvailableException - if the VTSAgent does not provide 759 a means of creating vouchers. 760 VTSSecurityException - if the VTSAgent cannot be authenticated 761 correctly. 763 5.4.11 delete 765 public void delete(Participant issuer, 766 VoucherComponent promise, 767 java.lang.Number num) 768 throws VTSException 770 Deletes vouchers. This method deletes the specified number of 771 vouchers from the VVS. The VTSAgent must 772 have sufficient vouchers in the VVS. Nothing is performed if the 773 specified number is 0. 775 Throws: 777 InsufficientVoucherException - if the VTSAgent doesn't have 778 sufficient number of vouchers to delete. 779 VTSSecurityException - if the VTSAgent cannot be authenticated 780 correctly. 782 5.4.12 getContents 784 public java.util.Set getContents(Participant issuer, 785 VoucherComponent promise) 787 throws VTSException 789 Returns the set of vouchers whose issuer and promise both match the 790 issuer and promise specified in the parameters. 792 If null is specified for the issuer or promise parameter, it 793 indicates "any issuer" or "any promise", respectively. If null is 794 specified for both parameters, this method selects all vouchers owned 795 by the holder from the VVS. 797 Returns: 799 the set of vouchers held by the holder of the VTSAgent. 801 Throws: 803 VTSSecurityException - if the VTSAgent cannot be authenticated 804 correctly. 806 5.4.13 getSessions 808 public java.lang.Set getSessions() 809 throws VTSException 811 Returns a set of not-completed sessions prepared by the VTSAgent. 813 Returns: 815 the set of sessions prepared by the VTSAgent and not yet completed. 817 Throws: 819 VTSSecurityException - if the VTSAgent cannot be authenticated 820 correctly. 822 5.4.14 getLog 824 public java.lang.Set getLog() 825 throws VTSException 827 Returns a set of completed sessions prepared or received by the 828 VTSAgent. This set represents the trading log of the VTSAgent. A 829 VTS may delete an old log eventually, so that the entire log may 830 not be returned; the amount of the log kept by the VTSAgent is 831 implementation-specific. 833 Returns: 835 the set of completed sessions prepared or received by the VTSAgent. 837 Throws: 839 VTSSecurityException - if the VTSAgent cannot be authenticated 840 correctly. 842 5.4.15 addReceptionListener 844 public void addReceptionListener(ReceptionListener l) 845 throws VTSException 847 Adds a ReceptionListener to the listener list. 849 After a ReceptionListener l is registered by this method, l.arrive() 850 will be called whenever the VTSAgent receives a voucher. 852 Nothing is performed if the specified listener is null. 854 Throws: 856 VTSSecurityException - if the VTSAgent cannot be authenticated 857 correctly. 859 5.4.16 removeReceptionListener 861 public void removeReceptionListener(ReceptionListener l) 862 throws VTSException 864 Removes a ReceptionListener from the listener list. 866 Nothing is performed when the specified listener is null or not 867 registered. 869 Throws: 871 VTSSecurityException - if the VTSAgent cannot be authenticated 872 correctly. 874 5.5 Session 876 public interface Session 878 Represents the logical connection established by the trade. Sessions 879 are established by VTSAgent#prepare(). 881 A session has four states: prepared, activated, suspended, and 882 completed. The initial state of a session is "prepared", and the 883 session will be "activated" immediately when any of the trading 884 methods of VTSAgent is called. The "activated" session will be 885 "completed" after the trading method is successfully completed. If 886 the trading method is transiently failed (e.g. network failure), the 887 session will be "suspended". Suspended sessions can be re-"activated" 888 and restarted by calling VTSAgent#resume(). 890 A completed session may disappear from the VTSAgent; the session 891 will be collected by the GC unless other objects keep its reference. 893 5.5.1 getIdentifier 895 public String getIdentifier() 897 Returns the identifier of the session. The generation scheme of the 898 identifier is implementation-specific. An implementation may use a 899 transaction ID as the identifier of the session. 901 Returns: 903 the string of the identifier of the session. 905 5.5.2 getVoucher 907 public Voucher getVoucher() 909 Returns the voucher to be traded using the session, or returns null 910 if the session has not been activated. 912 Returns: 914 the voucher to be traded or null if the state of the session is 915 "prepared". 917 5.5.3 getSender 919 public Participant getSender() 921 Returns the sender of the session, i.e., the creator who prepared the 922 session. 924 Returns: 926 the sender of the session. 928 5.5.4 getReceiver 930 public Participant getReceiver() 932 Returns the receiver of the session, i.e., the participant specified 933 when preparing the session (by the VTSAgent#prepare() method). 935 Returns: 937 the receiver of the session. 939 5.5.5 isPrepared 941 public boolean isPrepared() 943 Verifies if the session is "prepared". 945 Returns: 947 true if the session is in "prepared" state, or false. 949 5.5.6 isActivated 951 public boolean isActivated() 953 Verifies if the session is "activated". 955 Returns: 957 true if the session is in "activated" state, or false. 959 5.5.7 isSuspended 961 public boolean isSuspended() 963 Verifies if the session is "suspended". 965 Returns: 967 true if the session is in "suspended" state, or false. 969 5.5.8 isCompleted 971 public boolean isCompleted() 973 Verifies if the session is "completed". 975 Returns: 977 true if the session is in "completed" state, or false. 979 5.6 Voucher 981 public interface Voucher 983 Represents voucher(s) described in [VTS]. An object implementing 984 this interface can represent more than one voucher if all of the 985 issuer part and the promise part of the vouchers are the same. 987 5.6.1 getIssuer 989 public Participant getIssuer() 991 Returns the issuer part of the voucher(s). 993 Returns: 995 the participant who issued the voucher(s). 997 5.6.2 getPromise 998 public VoucherComponent getPromise() 1000 Returns the promise part of the voucher(s). 1002 Returns: 1004 the voucher component that defines the promise of the voucher. 1006 5.6.3 getCount 1008 public java.lang.Number getCount() 1010 Returns the number of the voucher(s). 1012 Returns: 1014 the positive (>0) number of the voucher(s). 1016 5.7 VoucherComponentRepository 1018 public interface VoucherComponentRepository 1020 Maintains VoucherComponents. 1022 An object implementing VoucherComponentRepository provides a means of 1023 retrieving the voucher components that are the promises of vouchers 1024 in the VVS. 1026 Before issuing a voucher, the promise of the voucher must be 1027 registered with this repository. The repository can be implemented 1028 as either a network-wide directory service or personal storage like 1029 the ParticipantRepository. 1031 5.7.1 register 1033 public VoucherComponent register(org.w3c.dom.Document document) 1035 Creates a voucher component associated with the specified DOM object 1036 and registers the voucher component with the repository. 1038 A voucher component of the voucher to be issued must be registered 1039 using this method. 1041 Nothing is performed (and the method returns null) if the specified 1042 document is null or the syntax of the document does not conform to 1043 the VTS. 1045 The method returns the registered voucher component if the specified 1046 DOM object has been already registered. (No new voucher component is 1047 created in this case). 1049 Returns: 1051 a registered voucher component associated with the 1052 specified document, or null if the document is null or has wrong 1053 syntax. 1055 5.8 VoucherComponent 1057 public interface VoucherComponent 1059 Represents the voucher component that defines the promise of the 1060 voucher. 1062 Each VoucherComponent object has its own unique identifier, and it is 1063 associated with an XML document that describes the promise made by 1064 the issuer of the voucher, e.g., the goods or services can be claimed 1065 in exchange for redeeming the voucher. 1067 This interface can be implemented as sort of a "smart pointer" to the 1068 XML document. An implementation may have a reference to a voucher 1069 component repository instead of the voucher component and retrieve 1070 the document dynamically from the repository when the getDocument() 1071 method is called. 1073 5.8.1 getIdentifier 1075 public String getIdentifier() 1077 Returns the identifier of the voucher component. Each voucher 1078 component must have a unique identifier. The identifier may be 1079 used to check for equivalence of voucher components. 1081 The format of the identifier is implementation-specific, however, it 1082 is RECOMMENDED to include the hash value of the voucher component in 1083 the identifier to assure its uniqueness. For generating the hash 1084 value, it is desirble to use a secure hash function, e.g., [SHA-1], 1085 and to apply a canonicalization function, e.g., [EXC-C14N], before 1086 applying the hash function to minimize the impact of insignificant 1087 format changes to the voucher component, e.g., line breaks or 1088 character encoding. 1090 Returns: 1092 The identifier string of the voucher component. 1094 5.8.2 getDocument 1096 public org.w3c.dom.Document getDocument() 1098 Returns a Document Object Model [DOM] representation of the document 1099 associated with the voucher component by the 1100 VoucherComponentRepository#register() method. 1102 The DOM object to be returned may be retrieved from a 1103 VoucherComponentRepository on demand, instead of the VoucherComponent 1104 always keeping a reference to the DOM object. 1106 The VTS must guarantee that the getDocument method will eventually 1107 return the DOM object provided that the voucher associated with the 1108 corresponding voucher component exists in the VVS. 1110 Returns: 1112 a DOM representation of the document associated with the voucher 1113 component. 1115 Throws: 1117 DocumentNotFoundException - if the associated DOM object cannot be 1118 retrieved. 1120 5.9 ReceptionListener 1122 public interface ReceptionListener extends java.util.EventListener 1124 Provides a listener interface that provides notification that a 1125 VTSAgent has been received a voucher. 1127 When a voucher arrives at VTSAgent, the VTSAgent invokes arrive() 1128 method of each registered ReceptionListener. ReceptionListeners can 1129 obtain a Session object, which contains information about the 1130 received voucher and the sender of the voucher. 1132 This interface is intended to provide a means of notifying a wallet 1133 that "You have new vouchers", so that this interface may be 1134 implemented by wallets or other applications using VTS. 1136 5.9.1 arrive 1138 public void arrive(Session session) 1140 Provides notification of the arrival of a voucher. 1142 After the listener is registered to a VTSAgent (by the 1143 VTSAgent#addReceptionListener() method), the VTSAgent invokes this 1144 method whenever it receives a voucher. 1146 The specified session is equivalent to the session used by the sender 1147 to trade the voucher. The state of the session is "completed" when 1148 this method is called. 1150 5.10 Exceptions 1152 java.lang.Exception 1153 +-- VTSException 1154 +-- CannotProceedException 1155 +-- DocumentNotFoundException 1156 +-- FeatureNotAvailableException 1157 +-- InsufficientVoucherException 1158 +-- InvalidParticipantException 1159 +-- InvalidStateException 1160 +-- VTSSecurityException 1162 VTSException 1164 This is the superclass of all exceptions thrown by the methods in the 1165 interfaces constructs the VTS-API. 1167 CannotProceedException 1169 This exception is thrown when a trading is interrupted due to 1170 network failures or other errors. 1172 DocumentNotFoundException 1174 This exception is thrown when the document associated with a voucher 1175 component cannot be found. 1177 FeatureNotAvailableException 1179 This exception is thrown when the invoked method is not supported. 1181 InsufficientVoucherException 1183 This exception is thrown when the number of the voucher is less than 1184 the number specified to trade. 1186 InvalidParticipantException 1188 This exception is thrown when the specified participant cannot be 1189 located. 1191 InvalidStateException 1193 This exception is thrown when the state of the session is invalid to 1194 proceed the operation. 1196 VTSSecurityException 1198 This exception is thrown when authentication fails or a method 1199 which requires authentication in advance is called without 1200 authentication. 1202 6. Example Code 1204 // Issue a voucher 1206 VTSManager vts = new FooVTSManager(); 1207 ParticipantRepository addrBook = vts.getParticipantRepository(); 1208 VoucherComponentRepository vcr = vts.getVoucherComponentRepository(); 1209 Participant you = addrBook.lookup("http://foo.bar/baz"); 1210 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1212 VoucherComponent promise = vcr.register(anXMLVoucherDocument); 1214 try { 1215 me.login(); 1216 s = me.prepare(you); 1217 me.issue(s, promise, 1); 1218 me.logout(); 1219 } catch (VTSException e) { 1220 System.err.println("Sorry!"); 1221 e.printStackTrace(); 1222 } 1224 // Transfer all my vouchers 1226 VTSManager vts = new FooVTSManager(); 1227 ParticipantRepository addrBook = vts.getParticipantRepository(); 1229 Participant you = addrBook.lookup("http://foo.bar/baz"); 1230 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1232 try { 1233 me.login(); 1234 Iterator i = me.getContents(null, null).iterator(); 1236 while (i.hasNext) { 1237 Voucher v = (Voucher) i.next(); 1238 s = me.prepare(you); 1239 me.transfer(s, v.getIssuer(), v.getPromise(), v.getCount()); 1240 } 1242 me.logout(); 1243 } catch (VTSException e) { 1244 System.err.println("Sorry!"); 1245 e.printStackTrace(); 1246 } 1248 // Register an incoming voucher notifier (biff) 1250 VTSManager vts = new FooVTSManager(); 1252 ParticipantRepository addrBook = vts.getParticipantRepository(); 1253 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1255 ReceptionListener listener = new ReceptionListener() { 1256 public void arrive(Session s) { 1257 System.out.println("You got a new voucher."); 1258 } 1259 }; 1261 try { 1262 me.login(); 1263 me.addReceptionListener(listener); 1264 me.logout(); 1265 } catch (VTSException e) { 1266 System.err.println("Sorry!"); 1267 e.printStackTrace(); 1268 } 1270 7. Security Considerations 1272 This document assumes that the VTS plug-in is trusted. The caller 1273 application of a VTS should authenticate the VTS plug-in and bind it 1274 securely using the VTS Provider information specified in the Voucher 1275 Component. This document, however, does not specify any application 1276 authentication scheme and it is assumed to be specified by other 1277 related standards. Until various VTS systems are deployed, it is 1278 enough to manually check and install VTS plug-ins like other download 1279 applications. 1281 To protect vouchers from being stolen, the VTSAgent must be 1282 authenticated securely. This document introduced a login/logout 1283 facility for this purpose (see Section 5.4). 1285 8. References 1287 [DOM] V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs, A. Le 1288 Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, and L. Wood. 1289 "Document Object Model (DOM) Level 1 Specification", W3C 1290 Recommendation, October 1998, 1291 1293 [ECML] J. W. Parsons and D. Eastlake "Electronic Commerce Modeling 1294 Language (ECML) Version 2 Specification", 1295 draft-ietf-trade-ecml2-spec-08.txt, 2003. 1297 [EXC-C14N] J. Boyer, D. Eastlake, and J. Reagle, "Exclusive XML 1298 Canonicalization Version 1.0", W3C Recommendation, July 2002, 1299 1301 [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.), 1302 "SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854, 1303 Springer-Verlag, 2000. 1305 [GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher 1306 Language", draft-ietf-trade-voucher-lang-04.txt, 2002. 1308 [IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version 1309 1.0", RFC 2801, 2000. 1311 [JCC] Sun Microsystems Inc., "Java Commerce Client", 1312 . 1314 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1315 Requirement Levels", BCP 14, RFC 2119, 1997. 1317 [SHA-1] Department of Commerce/National Institute of Standards and 1318 Technology, "FIPS PUB 180-1. Secure Hash Standard. U.S.", 1319 1321 [VTS] K. Fujimura, "Requirements and Design for Voucher Trading 1322 System (VTS)", draft-ietf-trade-drt-requirements-04.txt, 2002. 1323 In RFC Editor queue. 1325 9. Author's Address 1327 Masayuki Terada and Ko Fujimura 1328 NTT Corporation 1329 1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN 1330 Phone: +81-(0)46-859-3814 1331 Fax: +81-(0)46-859-8329 1332 Email: terada@isl.ntt.co.jp, fujimura@isl.ntt.co.jp 1334 Full Copyright Statement 1336 Copyright (C) The Internet Society (2003). All Rights Reserved. 1338 This document and translations of it may be copied and furnished to 1339 others, and derivative works that comment on or otherwise explain it 1340 or assist in its implementation may be prepared, copied, published 1341 and distributed, in whole or in part, without restriction of any 1342 kind, provided that the above copyright notice and this paragraph are 1343 included on all such copies and derivative works. However, this 1344 document itself may not be modified in any way, such as by removing 1345 the copyright notice or references to the Internet Society or other 1346 Internet organizations, except as needed for the purpose of 1347 developing Internet standards in which case the procedures for 1348 copyrights defined in the Internet Standards process must be 1349 followed, or as required to translate it into languages other than 1350 English. 1352 The limited permissions granted above are perpetual and will not be 1353 revoked by the Internet Society or its successors or assigns. 1355 This document and the information contained herein is provided on an 1356 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1357 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1358 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1359 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1360 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.