idnits 2.17.1 draft-ietf-trade-voucher-vtsapi-05.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.) ** 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 196 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 7742 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 164, but not defined == Unused Reference: 'RFC2119' is defined on line 1299, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DOM' == Outdated reference: A later version (-07) exists of draft-ietf-trade-voucher-lang-05 ** Downref: Normative reference to an Informational draft: draft-ietf-trade-voucher-lang (ref. 'GVL') == Outdated reference: A later version (-13) exists of draft-ietf-trade-ecml2-spec-08 Summary: 4 errors (**), 0 flaws (~~), 9 warnings (==), 3 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 Copyright (C) The Internet Society (2003). All Rights Reserved. 50 Acknowledgements 52 The following persons, in alphabetic order, contributed substantially 53 to the material herein: 55 Donald Eastlake 3rd 56 Iguchi Makoto 57 Yoshitaka Nakamura 58 Ryuji Shoda 60 Table of Contents 62 Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1 63 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 64 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 2 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Processing Model . . . . . . . . . . . . . . . . . . . . . 4 67 3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 68 4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 5. Interface Definitions . . . . . . . . . . . . . . . . . . 7 70 5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 7 71 5.1.1 getParticipantRepository . . . . . . . . . . . . . . . . . 7 72 5.1.2 getVoucherComponentRepository . . . . . . . . . . . . . . 7 73 5.2 ParticipantRepository . . . . . . . . . . . . . . . . . . 8 74 5.2.1 lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 5.3 Participant . . . . . . . . . . . . . . . . . . . . . . . 8 76 5.3.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 8 77 5.3.2 getVTSAgent . . . . . . . . . . . . . . . . . . . . . . . 9 78 5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 9 79 5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10 82 5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11 83 5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 12 84 5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 14 87 5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14 88 5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 15 89 5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 15 90 5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 15 91 5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 16 92 5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 93 5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 17 94 5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 17 95 5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 17 96 5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 18 97 5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 18 98 5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 18 99 5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 18 100 5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 18 101 5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 19 102 5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 19 103 5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 19 104 5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 19 105 5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 19 106 5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 19 107 5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 20 108 5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 20 109 5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 20 110 5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 21 111 5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 21 112 5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 21 113 5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 22 114 5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 22 115 5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 22 116 6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 23 117 7. Security Considerations . . . . . . . . . . . . . . . . . 25 118 8. Normative References . . . . . . . . . . . . . . . . . . . 25 119 9. Informative References . . . . . . . . . . . . . . . . . . 25 120 10. Author's Address . . . . . . . . . . . . . . . . . . . . . 26 121 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 26 123 1. Introduction 125 This document specifies the Voucher Trading System Application 126 Programming Interface (VTS-API). The motivation and background of the 127 Voucher Trading System (VTS) are described in Requirements for 128 Generic Voucher Trading [VTS]. 130 A voucher is a logical entity that represents a certain right and is 131 logically managed by the VTS. A voucher is generated by the issuer, 132 traded among users, and finally collected using VTS. The terminology 133 and model of the VTS are also described in [VTS]. 135 The VTS-API allows a caller application to issue, transfer, and 136 redeem vouchers in a uniform manner independent of the VTS 137 implementation. Several attempts have been made at providing a 138 generic payment API. Java Commerce Client [JCC] and Generic Payment 139 Service Framework [GPSF], for example, introduce a modular wallet 140 architecture that permits diverse types of payment modules to be 141 added as plug-ins and supports both check-like/cash-like payment 142 models. This document is inspired by these approaches but the scope 143 of this document is limited to the VTS model, in which cash-like 144 payment model is assumed and vouchers are directly or indirectly 145 transferred between sender (transferor) and receiver (transferee) via 146 the VTS. This document is not intended to support API for SET, 147 e-check or other payment schemes that do not fit the VTS model. 149 Unlike the APIs provided in JCC and GPSF, which are designed to 150 transfer only monetary values, this API enables the transfer of a 151 wide-range of values through the use of XML-based Generic Voucher 152 Language [GVL]. The monetary meaning of the voucher is interpreted by 153 the upper application layer using the information described in the 154 language. This approach makes it possible to provide a simpler API in 155 the voucher-transfer layer and enhances runtime efficiency. 156 The API specification in this document is described in the Java 157 language syntax. Bindings for other programming languages may be 158 completed in a future version of this document or separate related 159 specifications. 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 163 this document are to be interpreted as described in [RFC 2119] 165 2. Processing Model 167 This section provides the processing model in which the VTS-API is 168 used. Most of the text in this section has been taken from the 169 Generic Voucher Language specification [GVL]. 171 There are several ways of implementing VTS. For discount coupons or 172 event tickets, for example, the smart-card-based decentralized 173 offline VTS is often preferred, whereas for bonds or securities, 174 the centralized online VTS is preferred. It is impractical to 175 define standard protocols for issuing, transferring, or redeeming 176 vouchers at this moment. 178 To provide implementation flexibility, this document assumes a 179 modular wallet architecture that allows multiple VTS to be added as 180 plug-ins. In this architecture, instead of specifying a standard 181 voucher transfer protocol, two specifications, i.e., Voucher 182 Component and VTS-API specifications, are standardized (Figure 1). 184 Sender wallet/Issuing system Receiver wallet/Collecting system 185 +---------------------------+ +---------------------------+ 186 | | | | 187 | | Voucher Component | | 188 | | (Specifies Issuer, Promise, Holder, and VTS Provider) | | 189 | |-------------------------------------------------------->| | 190 | | | | | | 191 | | Intention to receive and payment (option) | | 192 | |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 193 | | | | | | 194 | | | | | | 195 | | Issue/transfer/ VTS | | VTS Register | | 196 | | redeem request plug-in | plug-in Listener(*1)| | 197 | |------------------>| | | |<------------------| | 198 | | (VTS API) |<- - - - - - - ->| (VTS API) | | 199 | | | VTS-specific | | | 200 | | | protocol if VTS | | | 201 | | | is distributed | | | 202 | | Result |<- - - - - - - ->| Notify(*2) | | 203 | |<------------------| | | |------------------>| | 204 +---------------------------+ +---------------------------+ 205 (*1) Registration is optional. Note also that the VTS plug-ins are 206 usually pre-registered when the wallet or collecting system 207 is started. 209 (*2) If a listener is registered. 211 Figure 1. Wallet architecture with VTS plug-ins 213 After sender and receiver agree on what vouchers are to be traded and 214 which VTS is to be used, the issuing system or wallet system requests 215 the corresponding VTS plug-in to permit the issue, transfer, or 216 redeem transactions to be performed via the VTS-API. The VTS then 217 rewrites the ownership of the vouchers using the VTS-specific 218 protocol. Finally, a completion event is sent to the wallet systems 219 or issuing/collecting systems. 221 This document describes the VTS-API specification. See [GVL] for the 222 Voucher Component specification. 224 3. Design Overview 226 We have adopted the following approach to specify the VTS-API. 228 1) Provide an abstract and uniform API that encapsulates the VTS 229 implementation. For example, a common API is provided for both 230 centralized and decentralized VTS. It brings more freedom of VTS 231 selection for issuers and application developers. 233 2) To provide an abstract and uniform API, this document introduces 234 an interface called VTSAgent that is associated with a holder and 235 provides methods to manipulate vouchers held by its holder. 236 Vouchers are accessed through the methods provided by the 237 VTSAgent. 239 3) Use existing standards for the VTS branding mechanism 240 (negotiation). This document assumes that the VTS to be used for 241 sending a voucher has settled before calling the VTS-APIs. 242 Negotiation can be done within the upper application layer using 243 other standards, e.g., [IOTP] or [ECML], if necessary. 245 4) Support only push-type voucher transfer interface in which voucher 246 transfer session is initiated by the transferor side. Pull-type 247 voucher transfer interface can be implemented on top of the 248 push-type VTS interface at application level. 250 4. Concepts 252 The VTS-API consists of the following interfaces. A VTS is required 253 to implement all of the interfaces except ReceptionLister, which is 254 intended to be implemented by wallets or other applications that 255 use VTS. 257 VTSManager 259 Provides the starting point to use a VTS plug-in. All of the 260 objects needed to manipulate vouchers can be directly or indirectly 261 acquired via the VTSManager. A VTSManager maintains the two 262 repositories; a ParticipantRepository and a 263 VoucherComponentRepository described below. 265 ParticipantRepository 267 Provides the access points of Participants, which are to be trading 268 partners. A ParticipantRepository maintains Participants and acts as 269 an "address book" of trading partners. 271 Participant 273 Represents a participant (such as issuers, holders, and 274 collectors). A Participant knows how to obtain the corresponding 275 VTSAgent described below. 277 VTSAgent (extends Participant) 279 Provides the access point of vouchers in Valid Voucher Set (VVS) 280 that is logically managed by VTS. A VTSAgent provides a means of 281 manipulating vouchers held by its holder; basic trading methods, 282 i.e., issue, transfer, consume, and present. Before calling trading 283 methods, the application must create a Session which is described 284 below. 286 Session 288 Represents the logical connection established by the trade. A 289 Session has references to two Participants, i.e., the sender and the 290 receiver. After trading methods are called using a Session, the 291 Session holds a reference to the Vouchers to be traded. 293 Voucher 295 Represents one or more vouchers of which all of the issuer part and 296 promise part of vouchers are the same. A Voucher holds references to 297 the Participant (issuer) who issued the voucher and a 298 VoucherComponent (promise) which is described below. 300 VoucherComponent 302 Represents a Voucher Component described in [GVL]. It defines the 303 promise part of the voucher. 305 VoucherComponentRepository 307 Provides the access points of VoucherComponents. A 308 VoucherComponentRepository maintains VoucherComponents and acts as a 309 "voucher type book" managed by the VTS. This document assumes that a 310 set of VoucherComponents has been acquired and stored in this 311 repository. Delivery of VoucherComponents is beyond the scope of this 312 document. It may be delivered within the VTS from the trading 313 partners or manually acquired from a trusted third party (See Section 314 3 of [GVL]). 316 ReceptionListener 318 Provides a listener function with regard to the receipt of a voucher 319 by VTSAgent to wallets or other applications that implement this 320 interface. (This interface may not be implemented as part of VTS) 322 5. Interface Definitions 324 The interfaces defined in this document reside in the package named 325 "org.ietf.vts". Wallets or other applications that use this 326 API,should import this package as "import org.ietf.vts.*;". 328 5.1 VTSManager 330 public interface VTSManager 332 Provides the starting point to use a VTS plug-in. 334 All of the objects needed to manipulate vouchers can be directly or 335 indirectly acquired via a VTSManager, so that wallets or other 336 applications can make the VTS available by instantiating an object 337 implementing this interface. 339 A class that implements the VTSManager interface must have a public 340 default constructor (a constructor without any parameters). The VTS 341 provides a name for such constructor so that the implementation class 342 can bootstrap the interface. 344 5.1.1 getParticipantRepository 346 public ParticipantRepository getParticipantRepository() 348 Returns a repository that maintains Participants. 350 Returns: 352 the ParticipantRepository of the VTS, or null if no 353 ParticipantRepository is available. 355 5.1.2 getVoucherComponentRepository 357 public VoucherComponentRepository getVoucherComponentRepository() 359 Returns a repository that maintains VoucherComponents. 361 Returns: 363 the VoucherComponentRepository of the VTS, or null if no 364 VoucherComponentRepository is available. 366 5.2 ParticipantRepository 368 public interface ParticipantRepository 370 Provides the access points of Participants. A ParticipantRepository 371 maintains Participants and acts as an "address book" of trading 372 partners. 374 The object implementing this interface maintains Participants (or 375 holds a reference to an object maintaining Participants), which are 376 to be trading partners. 378 The implementation of ParticipantRepository may be either (an adaptor 379 to) "yellow pages" which is a network-wide directory service like 380 LDAP, or "pocket address book" which maintains only personal 381 acquaintances. 383 5.2.1 lookup 385 public Participant lookup(String id) 387 Retrieves the participant that has the specified id. 389 Returns: 391 the participant associated with the specified id or null if the id 392 is null or the corresponding participant cannot be found. 394 5.3 Participant 396 public interface Participant 398 Represents the participants (such as issuers, holders, and 399 collectors). 401 This interface is used as representation of the trade partners and 402 issuers of vouchers. Anyone can retrieve objects implementing 403 Participant from the participant repository. 405 5.3.1 getIdentifier 407 public String getIdentifier() 409 Returns the identifier of the participant. Each participant must 410 have a unique identifier. 412 The identifier can be used for looking up and retrieving the 413 participant via the ParticipantRepository. 415 The format of the identifier is implementation-specific. 417 Returns: 419 the identifier string of the participant. 421 5.3.2 getVTSAgent 423 VTSAgent getVTSAgent() 425 Returns a VTSAgent, whose identifier is the same as the identifier of 426 the participant. 428 Returns: 430 an object implementing VTSAgent. 432 5.4 VTSAgent 434 public interface VTSAgent extends Participant 436 Represents contact points to access vouchers in Valid Voucher Set 437 (VVS) that is managed by the VTS. 439 Each VTSAgent is associated with a holder and provides a means for 440 managing vouchers owned by the holder. The holder must be 441 authenticated using the login() method before being called by any 442 other method, or VTSSecurityException will be issue. 444 Before calling any trading method, i.e., issue(), transfer(), 445 consume(), and present(), the application must establish a session by 446 the prepare() method. 448 Sessions may often be suspended due to network failure when the 449 voucher is sent via a network. The suspended sessions can be 450 restarted by the resume() method. Details on the state management of 451 a session are described in Section 5.5. 453 Some VTSAgents may not have all of the trading methods; a voucher 454 collecting system doesn't require its VTSAgent to provide method for 455 issuing or creating vouchers. A VTSAgent returns 456 FeatureNotAvailableException when an unsupported method is invoked. 458 5.4.1 login 460 public void login(String passphrase) 461 throws VTSException 463 Authenticates the VTSAgent. The passphrase is specified if the VTS 464 requires it for authentication, otherwise it must be null. Nothing is 465 performed if the VTSAgent has already been logged-in. The 466 authentication scheme is implementation-specific. Examples of the 467 implementation are as follows: 469 1) Vouchers are managed on a remote centralized server (central VVS), 470 and the server requires a password to login. In this case, the 471 application may prompt the user to input the password and can be 472 given to the VTSAgent through this method. 474 2) Vouchers are managed on a remote centralized server (central VVS); 475 they require challenge-and-response authentication using 476 smartcards held by users. In this case, the passphrase may be null 477 since access to the smartcard can be done without contacting the 478 application or user, i.e., the VTSAgent receives the challenge 479 from the server, sends the challenge to the smartcard (within the 480 VTS), and returns the response from the smartcard to the server. 481 Note that a PIN to unlock the smartcard may be given through this 482 method depending on the implementation. 484 3) Each user holds their own smartcard in which their own vouchers 485 are stored (decentralized VVS). In this case, the passphrase may 486 be null since no authentication is required. Note that a PIN to 487 unlock the smartcard may be given through this depends on the 488 implementation. 490 Throws: 492 VTSSecurityException - if authentication fails. 494 5.4.2 logout 496 public void logout() 497 throws VTSException 499 Voids the authentication performed by the login() method. 501 After calling this method, calling any other method (except 502 login()) will cause VTSSecurityException. 504 The VTSAgent can login again by the login() method. 506 Throws: 508 VTSSecurityException - if the VTSAgent is not authenticated 509 correctly. 511 5.4.3 prepare 513 public Session prepare(Participant receiver) 514 throws VTSException 516 Establishes a session that is required for trading vouchers. The 517 trading partner who receives the vouchers is specified as receiver. 518 The vouchers to be traded will be specified later (when a trading 519 method is called). 521 The establishment of a session is implementation-specific. An 522 implementation that has a central VVS may start a transaction, while 523 other implementations that have decentralized VVS may get, from the 524 receiver, the challenge needed to authenticate the sender during the 525 establishment of the session. 527 If the VTSAgent has no ability to establish a session with the 528 specified receiver (permanent error), the VTSAgent throws an 529 InvalidParticipantExeption. If the VTSAgent can not establish a 530 session due to network failure (transient error), the VTSAgent throws 531 a CannotProceedException. 533 Parameters: 535 receiver - the trading partner who receives vouchers. 537 Returns: 539 an established session whose state is "prepared" (see Section 5.5). 541 Throws: 543 CannotProceedException - if the preparation of the session is 544 aborted (e.g. network failures). 545 FeatureNotAvailableException - if the VTSAgent does not provide 546 any trading methods. 547 InvalidParticipantException - if the specified participant is 548 invalid. 549 VTSSecurityException - if the VTSAgent cannot be authenticated 550 correctly. 552 5.4.4 issue 554 public void issue(Session session, 555 VoucherComponent promise, 556 java.lang.Number num) 557 throws VTSException 559 Issues vouchers. This method creates the specified number of 560 vouchers and adds them to the VVS. Note 561 that receiver is specified when the prepare() method is 562 called. Nothing is performed if the specified number is 0. 564 The session MUST be "prepared" when calling this method. The state 565 of the session will be "activated" when the vouchers are created, and 566 it will be "completed" when the transaction is successfully completed 567 or "suspended" if the transaction is interrupted abnormally (e.g., 568 network failures). 570 Parameters: 572 session - the session used by the issue transaction. 573 promise - the promise part of the voucher. 574 num - the number of vouchers to be issued. 576 Throws: 578 CannotProceedException - if the transaction cannot be successfully 579 completed. 580 FeatureNotAvailableException - if the VTSAgent does not provide 581 a means of issuing vouchers. 582 InvalidStateException - if the session is not "prepared". 583 VTSSecurityException - if the VTSAgent cannot be authenticated 584 correctly. 586 5.4.5 transfer 588 public void transfer(Session session, 589 Participant issuer, 590 VoucherComponent promise, 591 java.lang.Number num) 592 throws VTSException 594 Transfers vouchers. This method rewrites the specified number of 595 vouchers to in 596 the VVS. Note that receiver is specified when the prepare() method is 597 called. The VTSAgent must have sufficient vouchers in the VVS. 598 Nothing is performed if the specified number is 0. 600 The session MUST be "prepared" when calling this method. The state 601 of the session will be "activated" when the voucher are retrieved 602 from the sender, and it will be "completed" when the transaction is 603 successfully completed or "suspended" if the transaction is 604 interrupted abnormally (e.g., network failures). 606 If null is specified for the issuer parameter, it indicates "any 607 issuer". This method selects vouchers to be transferred from the set 608 of vouchers returned by the getContents(null, promise). 610 Parameters: 612 session - the session used by the transfer transaction. 613 issuer - the issuer part of the voucher, or null. 614 promise - the promise part of the voucher. 615 num - the number of vouchers to be transferred. 617 Throws: 619 CannotProceedException - if the transaction cannot be successfully 620 completed. 621 FeatureNotAvailableException - if the VTSAgent does not provide 622 a means of transferring vouchers. 623 InsufficientVoucherException - if the VTSAgent doesn't have a 624 sufficient number of vouchers to transfer. 625 InvalidStateException - if the session is not "prepared". 626 VTSSecurityException - if the VTSAgent cannot be authenticated 627 correctly. 629 5.4.6 consume 630 public void consume(Session session, 631 Participant issuer, 632 VoucherComponent promise, 633 java.lang.Number num) 634 throws VTSException 636 Consumes vouchers. This method deletes the specified number of 637 specified vouchers from the VVS. The VTSAgent 638 must have sufficient vouchers in the VVS. Nothing is performed if 639 the specified number is 0. 641 The session MUST be "prepared" when calling this method. The state 642 of the session will be "activated" when the vouchers are deleted, and 643 it will be "completed" when the transaction is successfully completed 644 or "suspended" if the transaction is interrupted abnormally (e.g., 645 network failures). 647 If null is specified for the issuer parameter, it indicates "any 648 issuer". This method selects vouchers to be consumed from the set of 649 vouchers returned by the getContents(null, promise). 651 Parameters: 653 session - the session used by the consume transaction. 654 issuer - the issuer part of the voucher, or null. 655 promise - the promise part of the voucher. 656 num - the number of vouchers to be consumed. 658 Throws: 660 CannotProceedException - if the transaction cannot be successfully 661 completed. 662 FeatureNotAvailableException - if the VTSAgent does not provide 663 a means of consuming vouchers. 664 InsufficientVoucherException - if the VTSAgent doesn't have a 665 sufficient number of vouchers to consume. 666 InvalidStateException - if the session is not "prepared". 667 VTSSecurityException - if the VTSAgent cannot be authenticated 668 correctly. 670 5.4.7 present 672 public void present(Session session, 673 Participant issuer, 674 VoucherComponent promise, 675 java.lang.Number num) 676 throws VTSException 678 Presents vouchers. This method shows that the sender has the 679 specified number of vouchers in the VVS to 680 the receiver of the session; No modification is performed to the 681 VVS. The VTSAgent must have a sufficient vouchers in the VVS. Nothing 682 is performed if the specified number is 0. 684 The session MUST be "prepared" when calling this method. The state 685 of the session will be "activated" when the vouchers are retrieved, 686 and it will be "completed" when the transaction is successfully 687 completed or "suspended" if the transaction is interrupted abnormally 688 (e.g., by network failures). 690 If null is specified for the issuer parameter, it indicates "any 691 issuer". This method selects vouchers to be presented from the set 692 of vouchers returned by the getContents(null, promise). 694 Parameters: 696 session - the session used by the present transaction. 697 issuer - the issuer part of the voucher, or null. 698 promise - the promise part of the voucher. 699 num - the number of the voucher to be presented. 701 Throws: 703 CannotProceedException - if the transaction cannot be successfully 704 completed. 705 InsufficientVoucherException - if the VTSAgent doesn't have a 706 sufficient number of vouchers to present. 707 InvalidStateException - if the session is not "prepared". 708 FeatureNotAvailableException - if the VTSAgent does not provide 709 a means of presenting vouchers. 710 VTSSecurityException - if the VTSAgent cannot be authenticated 711 correctly. 713 5.4.8 cancel 715 public void cancel(Session session) 716 throws VTSException 718 Releases the session. "Prepared" sessions MUST be canceled. An 719 implementation MAY be permitted to cancel "activated" or "suspended" 720 sessions. 722 Throws: 724 InvalidStateException - if the state of the session isn't 725 cancelable. 726 VTSSecurityException - if the VTSAgent cannot be authenticated 727 correctly. 729 5.4.9 resume 731 public void resume(Session session) 732 throws VTSException 734 Restarts the session. Only "suspended" sessions can be resumed. 736 The state of the session will be re-"activated" immediately, and it 737 will be "completed" when the transaction is successfully completed or 738 "suspended" again if the transaction is interrupted abnormally (e.g., 739 network failures). 741 Throws: 743 CannotProceedException - if the transaction cannot be successfully 744 completed. 745 InvalidStateException - if the session is not "suspended". 746 VTSSecurityException - if the VTSAgent cannot be authenticated 747 correctly. 749 5.4.10 create 751 public void create(VoucherComponent promise, java.lang.Number num) 752 throws VTSException 754 Creates vouchers where the issuer is the VTSAgent itself. This 755 method creates the specified number of vouchers and adds them to the VVS. Nothing is performed if the 757 specified number is 0. 759 Throws: 761 FeatureNotAvailableException - if the VTSAgent does not provide 762 a means of creating vouchers. 763 VTSSecurityException - if the VTSAgent cannot be authenticated 764 correctly. 766 5.4.11 delete 768 public void delete(Participant issuer, 769 VoucherComponent promise, 770 java.lang.Number num) 771 throws VTSException 773 Deletes vouchers. This method deletes the specified number of 774 vouchers from the VVS. The VTSAgent must 775 have sufficient vouchers in the VVS. Nothing is performed if the 776 specified number is 0. 778 Throws: 780 InsufficientVoucherException - if the VTSAgent doesn't have 781 sufficient number of vouchers to delete. 782 VTSSecurityException - if the VTSAgent cannot be authenticated 783 correctly. 785 5.4.12 getContents 787 public java.util.Set getContents(Participant issuer, 788 VoucherComponent promise) 790 throws VTSException 792 Returns the set of vouchers whose issuer and promise both match the 793 issuer and promise specified in the parameters. 795 If null is specified for the issuer or promise parameter, it 796 indicates "any issuer" or "any promise", respectively. If null is 797 specified for both parameters, this method selects all vouchers owned 798 by the holder from the VVS. 800 Returns: 802 the set of vouchers held by the holder of the VTSAgent. 804 Throws: 806 VTSSecurityException - if the VTSAgent cannot be authenticated 807 correctly. 809 5.4.13 getSessions 811 public java.lang.Set getSessions() 812 throws VTSException 814 Returns a set of not-completed sessions prepared by the VTSAgent. 816 Returns: 818 the set of sessions prepared by the VTSAgent and not yet completed. 820 Throws: 822 VTSSecurityException - if the VTSAgent cannot be authenticated 823 correctly. 825 5.4.14 getLog 827 public java.lang.Set getLog() 828 throws VTSException 830 Returns a set of completed sessions prepared or received by the 831 VTSAgent. This set represents the trading log of the VTSAgent. A 832 VTS may delete an old log eventually, so that the entire log may 833 not be returned; the amount of the log kept by the VTSAgent is 834 implementation-specific. 836 Returns: 838 the set of completed sessions prepared or received by the VTSAgent. 840 Throws: 842 VTSSecurityException - if the VTSAgent cannot be authenticated 843 correctly. 845 5.4.15 addReceptionListener 847 public void addReceptionListener(ReceptionListener l) 848 throws VTSException 850 Adds a ReceptionListener to the listener list. 852 After a ReceptionListener l is registered by this method, l.arrive() 853 will be called whenever the VTSAgent receives a voucher. 855 Nothing is performed if the specified listener is null. 857 Throws: 859 VTSSecurityException - if the VTSAgent cannot be authenticated 860 correctly. 862 5.4.16 removeReceptionListener 864 public void removeReceptionListener(ReceptionListener l) 865 throws VTSException 867 Removes a ReceptionListener from the listener list. 869 Nothing is performed when the specified listener is null or not 870 registered. 872 Throws: 874 VTSSecurityException - if the VTSAgent cannot be authenticated 875 correctly. 877 5.5 Session 879 public interface Session 881 Represents the logical connection established by the trade. Sessions 882 are established by VTSAgent#prepare(). 884 A session has four states: prepared, activated, suspended, and 885 completed. The initial state of a session is "prepared", and the 886 session will be "activated" immediately when any of the trading 887 methods of VTSAgent is called. The "activated" session will be 888 "completed" after the trading method is successfully completed. If 889 the trading method is transiently failed (e.g. network failure), the 890 session will be "suspended". Suspended sessions can be re-"activated" 891 and restarted by calling VTSAgent#resume(). 893 A completed session may disappear from the VTSAgent; the session 894 will be collected by the GC unless other objects keep its reference. 896 5.5.1 getIdentifier 898 public String getIdentifier() 900 Returns the identifier of the session. The generation scheme of the 901 identifier is implementation-specific. An implementation may use a 902 transaction ID as the identifier of the session. 904 Returns: 906 the string of the identifier of the session. 908 5.5.2 getVoucher 910 public Voucher getVoucher() 912 Returns the voucher to be traded using the session, or returns null 913 if the session has not been activated. 915 Returns: 917 the voucher to be traded or null if the state of the session is 918 "prepared". 920 5.5.3 getSender 922 public Participant getSender() 924 Returns the sender of the session, i.e., the creator who prepared the 925 session. 927 Returns: 929 the sender of the session. 931 5.5.4 getReceiver 933 public Participant getReceiver() 935 Returns the receiver of the session, i.e., the participant specified 936 when preparing the session (by the VTSAgent#prepare() method). 938 Returns: 940 the receiver of the session. 942 5.5.5 isPrepared 944 public boolean isPrepared() 946 Verifies if the session is "prepared". 948 Returns: 950 true if the session is in "prepared" state, or false. 952 5.5.6 isActivated 954 public boolean isActivated() 956 Verifies if the session is "activated". 958 Returns: 960 true if the session is in "activated" state, or false. 962 5.5.7 isSuspended 964 public boolean isSuspended() 966 Verifies if the session is "suspended". 968 Returns: 970 true if the session is in "suspended" state, or false. 972 5.5.8 isCompleted 974 public boolean isCompleted() 976 Verifies if the session is "completed". 978 Returns: 980 true if the session is in "completed" state, or false. 982 5.6 Voucher 984 public interface Voucher 986 Represents voucher(s) described in [VTS]. An object implementing 987 this interface can represent more than one voucher if all of the 988 issuer part and the promise part of the vouchers are the same. 990 5.6.1 getIssuer 992 public Participant getIssuer() 994 Returns the issuer part of the voucher(s). 996 Returns: 998 the participant who issued the voucher(s). 1000 5.6.2 getPromise 1001 public VoucherComponent getPromise() 1003 Returns the promise part of the voucher(s). 1005 Returns: 1007 the voucher component that defines the promise of the voucher. 1009 5.6.3 getCount 1011 public java.lang.Number getCount() 1013 Returns the number of the voucher(s). 1015 Returns: 1017 the positive (>0) number of the voucher(s). 1019 5.7 VoucherComponentRepository 1021 public interface VoucherComponentRepository 1023 Maintains VoucherComponents. 1025 An object implementing VoucherComponentRepository provides a means of 1026 retrieving the voucher components that are the promises of vouchers 1027 in the VVS. 1029 Before issuing a voucher, the promise of the voucher must be 1030 registered with this repository. The repository can be implemented 1031 as either a network-wide directory service or personal storage like 1032 the ParticipantRepository. 1034 5.7.1 register 1036 public VoucherComponent register(org.w3c.dom.Document document) 1038 Creates a voucher component associated with the specified DOM object 1039 and registers the voucher component with the repository. 1041 A voucher component of the voucher to be issued must be registered 1042 using this method. 1044 Nothing is performed (and the method returns null) if the specified 1045 document is null or the syntax of the document does not conform to 1046 the VTS. 1048 The method returns the registered voucher component if the specified 1049 DOM object has been already registered. (No new voucher component is 1050 created in this case). 1052 Returns: 1054 a registered voucher component associated with the 1055 specified document, or null if the document is null or has wrong 1056 syntax. 1058 5.8 VoucherComponent 1060 public interface VoucherComponent 1062 Represents the voucher component that defines the promise of the 1063 voucher. 1065 Each VoucherComponent object has its own unique identifier, and it is 1066 associated with an XML document that describes the promise made by 1067 the issuer of the voucher, e.g., the goods or services can be claimed 1068 in exchange for redeeming the voucher. 1070 This interface can be implemented as sort of a "smart pointer" to the 1071 XML document. An implementation may have a reference to a voucher 1072 component repository instead of the voucher component and retrieve 1073 the document dynamically from the repository when the getDocument() 1074 method is called. 1076 5.8.1 getIdentifier 1078 public String getIdentifier() 1080 Returns the identifier of the voucher component. Each voucher 1081 component must have a unique identifier. The identifier may be 1082 used to check for equivalence of voucher components. 1084 The format of the identifier is implementation-specific, however, it 1085 is RECOMMENDED to include the hash value of the voucher component in 1086 the identifier to assure its uniqueness. For generating the hash 1087 value, it is desirble to use a secure hash function, e.g., [SHA-1], 1088 and to apply a canonicalization function, e.g., [EXC-C14N], before 1089 applying the hash function to minimize the impact of insignificant 1090 format changes to the voucher component, e.g., line breaks or 1091 character encoding. 1093 Returns: 1095 The identifier string of the voucher component. 1097 5.8.2 getDocument 1099 public org.w3c.dom.Document getDocument() 1101 Returns a Document Object Model [DOM] representation of the document 1102 associated with the voucher component by the 1103 VoucherComponentRepository#register() method. 1105 The DOM object to be returned may be retrieved from a 1106 VoucherComponentRepository on demand, instead of the VoucherComponent 1107 always keeping a reference to the DOM object. 1109 The VTS must guarantee that the getDocument method will eventually 1110 return the DOM object provided that the voucher associated with the 1111 corresponding voucher component exists in the VVS. 1113 Returns: 1115 a DOM representation of the document associated with the voucher 1116 component. 1118 Throws: 1120 DocumentNotFoundException - if the associated DOM object cannot be 1121 retrieved. 1123 5.9 ReceptionListener 1125 public interface ReceptionListener extends java.util.EventListener 1127 Provides a listener interface that provides notification that a 1128 VTSAgent has been received a voucher. 1130 When a voucher arrives at VTSAgent, the VTSAgent invokes arrive() 1131 method of each registered ReceptionListener. ReceptionListeners can 1132 obtain a Session object, which contains information about the 1133 received voucher and the sender of the voucher. 1135 This interface is intended to provide a means of notifying a wallet 1136 that "You have new vouchers", so that this interface may be 1137 implemented by wallets or other applications using VTS. 1139 5.9.1 arrive 1141 public void arrive(Session session) 1143 Provides notification of the arrival of a voucher. 1145 After the listener is registered to a VTSAgent (by the 1146 VTSAgent#addReceptionListener() method), the VTSAgent invokes this 1147 method whenever it receives a voucher. 1149 The specified session is equivalent to the session used by the sender 1150 to trade the voucher. The state of the session is "completed" when 1151 this method is called. 1153 5.10 Exceptions 1155 java.lang.Exception 1156 +-- VTSException 1157 +-- CannotProceedException 1158 +-- DocumentNotFoundException 1159 +-- FeatureNotAvailableException 1160 +-- InsufficientVoucherException 1161 +-- InvalidParticipantException 1162 +-- InvalidStateException 1163 +-- VTSSecurityException 1165 VTSException 1167 This is the superclass of all exceptions thrown by the methods in the 1168 interfaces constructs the VTS-API. 1170 CannotProceedException 1172 This exception is thrown when a trading is interrupted due to 1173 network failures or other errors. 1175 DocumentNotFoundException 1177 This exception is thrown when the document associated with a voucher 1178 component cannot be found. 1180 FeatureNotAvailableException 1182 This exception is thrown when the invoked method is not supported. 1184 InsufficientVoucherException 1186 This exception is thrown when the number of the voucher is less than 1187 the number specified to trade. 1189 InvalidParticipantException 1191 This exception is thrown when the specified participant cannot be 1192 located. 1194 InvalidStateException 1196 This exception is thrown when the state of the session is invalid to 1197 proceed the operation. 1199 VTSSecurityException 1201 This exception is thrown when authentication fails or a method 1202 which requires authentication in advance is called without 1203 authentication. 1205 6. Example Code 1207 // Issue a voucher 1209 VTSManager vts = new FooVTSManager(); 1210 ParticipantRepository addrBook = vts.getParticipantRepository(); 1211 VoucherComponentRepository vcr = vts.getVoucherComponentRepository(); 1212 Participant you = addrBook.lookup("http://foo.bar/baz"); 1213 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1215 VoucherComponent promise = vcr.register(anXMLVoucherDocument); 1217 try { 1218 me.login(); 1219 s = me.prepare(you); 1220 me.issue(s, promise, 1); 1221 me.logout(); 1222 } catch (VTSException e) { 1223 System.err.println("Sorry!"); 1224 e.printStackTrace(); 1225 } 1227 // Transfer all my vouchers 1229 VTSManager vts = new FooVTSManager(); 1230 ParticipantRepository addrBook = vts.getParticipantRepository(); 1232 Participant you = addrBook.lookup("http://foo.bar/baz"); 1233 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1235 try { 1236 me.login(); 1237 Iterator i = me.getContents(null, null).iterator(); 1239 while (i.hasNext) { 1240 Voucher v = (Voucher) i.next(); 1241 s = me.prepare(you); 1242 me.transfer(s, v.getIssuer(), v.getPromise(), v.getCount()); 1243 } 1245 me.logout(); 1246 } catch (VTSException e) { 1247 System.err.println("Sorry!"); 1248 e.printStackTrace(); 1249 } 1251 // Register an incoming voucher notifier (biff) 1253 VTSManager vts = new FooVTSManager(); 1255 ParticipantRepository addrBook = vts.getParticipantRepository(); 1256 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1258 ReceptionListener listener = new ReceptionListener() { 1259 public void arrive(Session s) { 1260 System.out.println("You got a new voucher."); 1261 } 1262 }; 1264 try { 1265 me.login(); 1266 me.addReceptionListener(listener); 1267 me.logout(); 1268 } catch (VTSException e) { 1269 System.err.println("Sorry!"); 1270 e.printStackTrace(); 1271 } 1273 7. Security Considerations 1275 This document assumes that the VTS plug-in is trusted. The caller 1276 application of a VTS should authenticate the VTS plug-in and bind it 1277 securely using the VTS Provider information specified in the Voucher 1278 Component. This document, however, does not specify any application 1279 authentication scheme and it is assumed to be specified by other 1280 related standards. Until various VTS systems are deployed, it is 1281 enough to manually check and install VTS plug-ins like other download 1282 applications. 1284 To protect vouchers from being stolen, the VTSAgent must be 1285 authenticated securely. This document introduced a login/logout 1286 facility for this purpose (see Section 5.4). 1288 8. Normative References 1290 [DOM] V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs, A. Le 1291 Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, and L. Wood. 1292 "Document Object Model (DOM) Level 1 Specification", W3C 1293 Recommendation, October 1998, 1294 1296 [GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher 1297 Language", draft-ietf-trade-voucher-lang-05.txt, 2003. 1299 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1300 Requirement Levels", BCP 14, RFC 2119, 1997. 1302 9. Informative References 1304 [ECML] J. W. Parsons and D. Eastlake "Electronic Commerce Modeling 1305 Language (ECML) Version 2 Specification", 1306 draft-ietf-trade-ecml2-spec-08.txt, 2003. 1308 [EXC-C14N] J. Boyer, D. Eastlake, and J. Reagle, "Exclusive XML 1309 Canonicalization Version 1.0", W3C Recommendation, July 2002, 1310 1312 [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.), 1313 "SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854, 1314 Springer-Verlag, 2000. 1316 [IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version 1317 1.0", RFC 2801, 2000. 1319 [JCC] Sun Microsystems Inc., "Java Commerce Client", 1320 . 1322 [SHA-1] Department of Commerce/National Institute of Standards and 1323 Technology, "FIPS PUB 180-1. Secure Hash Standard. U.S.", 1324 1326 [VTS] K. Fujimura, "Requirements and Design for Voucher Trading 1327 System (VTS)", draft-ietf-trade-drt-requirements-04.txt, 2002. 1328 In RFC Editor queue. 1330 10. Author's Address 1332 Masayuki Terada and Ko Fujimura 1333 NTT Corporation 1334 1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN 1335 Phone: +81-(0)46-859-3814 1336 Fax: +81-(0)46-859-8329 1337 Email: terada@isl.ntt.co.jp, fujimura@isl.ntt.co.jp 1339 Full Copyright Statement 1341 Copyright (C) The Internet Society (2003). All Rights Reserved. 1343 This document and translations of it may be copied and furnished to 1344 others, and derivative works that comment on or otherwise explain it 1345 or assist in its implementation may be prepared, copied, published 1346 and distributed, in whole or in part, without restriction of any 1347 kind, provided that the above copyright notice and this paragraph are 1348 included on all such copies and derivative works. However, this 1349 document itself may not be modified in any way, such as by removing 1350 the copyright notice or references to the Internet Society or other 1351 Internet organizations, except as needed for the purpose of 1352 developing Internet standards in which case the procedures for 1353 copyrights defined in the Internet Standards process must be 1354 followed, or as required to translate it into languages other than 1355 English. 1357 The limited permissions granted above are perpetual and will not be 1358 revoked by the Internet Society or its successors or assigns. 1360 This document and the information contained herein is provided on an 1361 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1362 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1363 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1364 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1365 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.