idnits 2.17.1 draft-ietf-trade-voucher-vtsapi-01.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 == The page length should not exceed 58 lines per page, but there was 15 longer pages, the longest (page 10) being 588 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 25 pages 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: ---------------------------------------------------------------------------- == Line 189 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 (January 2002) is 8136 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 156, but not defined == Unused Reference: 'DOMHash' is defined on line 1263, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 1286, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DOM' ** Downref: Normative reference to an Informational RFC: RFC 2803 (ref. 'DOMHash') == Outdated reference: A later version (-13) exists of draft-ietf-trade-ecml2-spec-02 -- Possible downref: Non-RFC (?) normative reference: ref. 'GPSF' == Outdated reference: A later version (-07) exists of draft-ietf-trade-voucher-lang-02 ** Downref: Normative reference to an Informational draft: draft-ietf-trade-voucher-lang (ref. 'GVL') == Outdated reference: A later version (-04) exists of draft-ietf-trade-drt-requirements-03 ** Downref: Normative reference to an Informational draft: draft-ietf-trade-drt-requirements (ref. 'VTS') ** Downref: Normative reference to an Informational RFC: RFC 2801 (ref. 'IOTP') -- Possible downref: Non-RFC (?) normative reference: ref. 'JCC' Summary: 8 errors (**), 0 flaws (~~), 12 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Trade Working Group January 2002 2 INTERNET-DRAFT Masayuki Terada 3 Ko Fujimura 4 Expires: July 2002 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 M. Terada and K. Fujimura [Page 1] 49 Table of Contents 51 Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1 52 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Processing Model . . . . . . . . . . . . . . . . . . . . . 3 55 3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 56 4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 5. Interface Definitions . . . . . . . . . . . . . . . . . . 6 58 5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 6 59 5.1.1 getParticipantRepository . . . . . . . . . . . . . . . . . 7 60 5.1.2 getVoucherComponentRepository . . . . . . . . . . . . . . 7 61 5.2 ParticipantRepository . . . . . . . . . . . . . . . . . . 7 62 5.2.1 lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 5.3 Participant . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.3.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 8 65 5.3.2 getVTSAgent . . . . . . . . . . . . . . . . . . . . . . . 8 66 5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14 76 5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 15 79 5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 15 80 5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 16 82 5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 16 83 5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 17 84 5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 17 85 5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 17 86 5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 17 87 5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 18 88 5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 18 89 5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 18 90 5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 18 91 5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 18 92 5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 19 93 5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 19 94 5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 19 95 5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 19 96 5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 19 97 5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 20 98 5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 20 99 5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 20 100 5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 21 101 5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 21 103 M. Terada and K. Fujimura [Page 2] 104 5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 21 105 5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 22 106 6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 23 107 7. Security Considerations . . . . . . . . . . . . . . . . . 24 108 8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . 24 109 9. References . . . . . . . . . . . . . . . . . . . . . . . . 24 110 10. Author's Address . . . . . . . . . . . . . . . . . . . . . 25 112 1. Introduction 114 This document specifies the Voucher Trading System Application 115 Programming Interface (VTS-API). The motivation and background of the 116 Voucher Trading System (VTS) are described in Requirements for 117 Generic Voucher Trading [VTS]. 119 A voucher is a logical entity that represents a certain right and is 120 logically managed by the VTS. A voucher is generated by the issuer, 121 traded among users, and finally collected using VTS. The terminology 122 and model of the VTS are also described in [VTS]. 124 The VTS-API allows a caller application to issue, transfer, and 125 redeem vouchers in a uniform manner independent of the VTS 126 implementation. Several attempts have been made at providing a 127 generic payment API. Java Commerce Client [JCC] and Generic Payment 128 Service Framework [GPSF], for example, introduce a modular wallet 129 architecture that permits diverse types of payment modules to be 130 added as plug-ins and supports both check-like/cash-like payment 131 models. This document is inspired by these approaches but the scope 132 of this document is limited to the VTS model, in which cash-like 133 payment model is assumed and vouchers are directly or indirectly 134 transferred between sender (transferor) and receiver (transferee) via 135 the VTS. This document is not intended to support API for SET, 136 e-check or other payment schemes that do not fit the VTS model. 138 Unlike the APIs provided in JCC and GPSF, which are designed to 139 transfer only monetary values, this API enables the transfer of a 140 wide-range of values through the use of XML-based Generic Voucher 141 Language [GVL]. The monetary meaning of the voucher is interpreted by 142 the upper application layer using the information described in the 143 language. This approach makes it possible to provide a simpler API in 144 the voucher-transfer layer and enhances runtime efficiency. 146 The API specification in this document is described in the Java 147 language syntax. Bindings for other programming languages may be 148 completed in a future version of this document or separate related 149 specifications. [Editor's note: Language independent interface 150 definitions, e.g., CORBA IDL, can be used if needed, but we are not 151 sure if they are really language independent.] 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 155 this document are to be interpreted as described in [RFC 2119] 157 M. Terada and K. Fujimura [Page 3] 158 2. Processing Model 160 This section provides the processing model in which the VTS-API is 161 used. Most of the text in this section has been taken from the 162 Generic Voucher Language specification [GVL]. 164 There are several ways of implementing VTS. For discount coupons or 165 event tickets, for example, the smart-card-based decentralized 166 offline VTS is often preferred, whereas for bonds or securities, 167 the centralized online VTS is preferred. It is impractical to 168 define standard protocols for issuing, transferring, or redeeming 169 vouchers at this moment. 171 To provide implementation flexibility, this document assumes a 172 modular wallet architecture that allows multiple VTS to be added as 173 plug-ins. In this architecture, instead of specifying a standard 174 voucher transfer protocol, two specifications, i.e., Voucher 175 Component and VTS-API specifications, are standardized (Figure 1). 177 Sender wallet/Issuing system Receiver wallet/Collecting system 178 +---------------------------+ +---------------------------+ 179 | | | | 180 | | Voucher Component | | 181 | | (Specifies Issuer, Promise, Holder, and VTS Provider) | | 182 | |-------------------------------------------------------->| | 183 | | | | | | 184 | | Intention to receive and payment (option) | | 185 | |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 186 | | | | | | 187 | | | | | | 188 | | Issue/transfer/ VTS | | VTS Register | | 189 | | redeem request plug-in | plug-in Listener(*1)| | 190 | |------------------>| | | |<------------------| | 191 | | (VTS API) |<- - - - - - - ->| (VTS API) | | 192 | | | VTS-specific | | | 193 | | | protocol if VTS | | | 194 | | | is distributed | | | 195 | | Result |<- - - - - - - ->| Notify(*2) | | 196 | |<------------------| | | |------------------>| | 197 +---------------------------+ +---------------------------+ 198 (*1) Registration is optional. Note also that the VTS plug-ins are 199 usually pre-registered when the wallet or collecting system 200 is started. 201 (*2) If a listener is registered. 203 Figure 1. Wallet architecture with VTS plug-ins 205 After sender and receiver agree on what vouchers are to be traded and 206 which VTS is to be used, the issuing system or wallet system requests 207 the corresponding VTS plug-in to permit the issue, transfer, or 208 redeem transactions to be performed via the VTS-API. The VTS then 209 rewrites the ownership of the vouchers using the VTS-specific 210 protocol. Finally, a completion event is sent to the wallet systems 212 M. Terada and K. Fujimura [Page 4] 213 or issuing/collecting systems. 215 This document describes the VTS-API specification. See [GVL] for the 216 Voucher Component specification. 218 3. Design Overview 220 We have adopted the following approach to specify the VTS-API. 222 1) Provide an abstract and uniform API that encapsulates the VTS 223 implementation. For example, a common API is provided for both 224 centralized and decentralized VTS. It brings more freedom of VTS 225 selection for issuers and application developers. 227 2) To provide an abstract and uniform API, this document introduces 228 an interface called VTSAgent that is associated with a holder and 229 provides methods to manipulate vouchers held by its holder. 230 Vouchers are accessed through the methods provided by the 231 VTSAgent. 233 3) Use existing standards for the VTS branding mechanism 234 (negotiation). This document assumes that the VTS to be used for 235 sending a voucher has settled before calling the VTS-APIs. 236 Negotiation can be done within the upper application layer using 237 other standards, e.g., [IOTP] or [ECML], if necessary. 239 4) Support only push-type voucher transfer interface in which voucher 240 transfer session is initiated by the transferor side. Pull-type 241 voucher transfer interface can be implemented on top of the 242 push-type VTS interface at application level. 244 4. Concepts 246 The VTS-API consists of the following interfaces. A VTS is required 247 to implement all of the interfaces except ReceptionLister, which is 248 intended to be implemented by wallets or other applications that 249 use VTS. 251 VTSManager 253 Provides the starting point to use a VTS plug-in. All of the 254 objects needed to manipulate vouchers can be directly or indirectly 255 acquired via the VTSManager. A VTSManager maintains the two 256 repositories; a ParticipantRepository and a 257 VoucherComponentRepository described below. 259 ParticipantRepository 261 Provides the access points of Participants, which are to be trading 262 partners. A ParticipantRepository maintains Participants and acts as 263 an "address book" of trading partners. 265 Participant 267 M. Terada and K. Fujimura [Page 5] 268 Represents a participant (such as issuers, holders, and 269 collectors). A Participant knows how to obtain the corresponding 270 VTSAgent described below. 272 VTSAgent (extends Participant) 274 Provides the access point of vouchers in Valid Voucher Set (VVS) 275 that is logically managed by VTS. A VTSAgent provides a means of 276 manipulating vouchers held by its holder; basic trading methods, 277 i.e., issue, transfer, consume, and present. Before calling trading 278 methods, the application must create a Session which is described 279 below. 281 Session 283 Represents the logical connection established by the trade. A 284 Session has references to two Participants, i.e., the sender and the 285 receiver. After trading methods are called using a Session, the 286 Session holds a reference to the Vouchers to be traded. 288 Voucher 290 Represents one or more vouchers of which all of the issuer part and 291 promise part of vouchers are the same. A Voucher holds references to 292 the Participant (issuer) who issued the voucher and a 293 VoucherComponent (promise) which is described below. 295 VoucherComponent 297 Represents a Voucher Component described in [GVL]. It defines the 298 promise part of the voucher. 300 VoucherComponentRepository 302 Provides the access points of VoucherComponents. A 303 VoucherComponentRepository maintains VoucherComponents and acts as a 304 "voucher type book" managed by the VTS. This document assumes that a 305 set of VoucherComponents has been acquired and stored in this 306 repository. Delivery of VoucherComponents is beyond the scope of this 307 document. It may be delivered within the VTS from the trading 308 partners or manually acquired from a trusted third party (See Section 309 3 of [GVL]). 311 ReceptionListener 313 Provides a listener function with regard to the receipt of a voucher 314 by VTSAgent to wallets or other applications that implement this 315 interface. (This interface may not be implemented as part of VTS) 317 5. Interface Definitions 319 The interfaces defined in this document reside in the package named 321 M. Terada and K. Fujimura [Page 6] 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 Classes that implement this interface should have a public default 337 constructor (a constructor without any parameters) to make the VTS 338 pluggable. 340 5.1.1 getParticipantRepository 342 public ParticipantRepository getParticipantRepository() 344 Returns a repository that maintains Participants. 346 Returns: 348 the ParticipantRepository of the VTS, or null if no 349 ParticipantRepository is available. 351 5.1.2 getVoucherComponentRepository 353 public VoucherComponentRepository getVoucherComponentRepository() 355 Returns a repository that maintains VoucherComponents. 357 Returns: 359 the VoucherComponentRepository of the VTS, or null if no 360 VoucherComponentRepository is available. 362 5.2 ParticipantRepository 364 public interface ParticipantRepository 366 Provides the access points of Participants. A ParticipantRepository 367 maintains Participants and acts as an "address book" of trading 368 partners. 370 The object implementing this interface maintains Participants (or 371 holds a reference to an object maintaining Participants), which are 372 to be trading partners. 374 The implementation of ParticipantRepository may be either (an adaptor 376 M. Terada and K. Fujimura [Page 7] 377 to) "yellow pages" which is a network-wide directory service like 378 LDAP, or "pocket address book" which maintains only personal 379 acquaintances. 381 5.2.1 lookup 383 public Participant lookup(String id) 385 Retrieves the participant that has the specified id. 387 Returns: 389 the participant associated with the specified id or null if the id 390 is null or the corresponding participant cannot be found. 392 5.3 Participant 394 public interface Participant 396 Represents the participants (such as issuers, holders, and 397 collectors). 399 This interface is used as representation of the trade partners and 400 issuers of vouchers. Anyone can retrieve objects implementing 401 Participant from the participant repository. 403 5.3.1 getIdentifier 405 public String getIdentifier() 407 Returns the identifier of the participant. Each participant must 408 have a unique identifier. 410 The identifier can be used for looking up and retrieving the 411 participant via the ParticipantRepository. 413 The format of the identifier is implementation-specific. 415 Returns: 417 the identifier string of the participant. 419 5.3.2 getVTSAgent 421 VTSAgent getVTSAgent() 423 Returns a VTSAgent, whose identifier is the same as the identifier of 424 the participant. 426 Returns: 428 an object implementing VTSAgent. 430 M. Terada and K. Fujimura [Page 8] 431 5.4 VTSAgent 433 public interface VTSAgent extends Participant 435 Represents contact points to access vouchers in Valid Voucher Set 436 (VVS) that is managed by the VTS. 438 Each VTSAgent is associated with a holder and provides a means for 439 managing vouchers owned by the holder. The holder must be 440 authenticated using the login() method before being called by any 441 other method, or VTSSecurityException will be issue. 443 Before calling any trading method, i.e., issue(), transfer(), 444 consume(), and present(), the application must establish a session by 445 the prepare() method. 447 Sessions may often be suspended due to network failure when the 448 voucher is sent via a network. The suspended sessions can be 449 restarted by the resume() method. Details on the state management of 450 a session are described in Section 5.5. 452 5.4.1 login 454 public void login(String passphrase) 455 throws VTSException 457 Authenticates the VTSAgent. The passphrase is specified if the VTS 458 requires it for authentication, otherwise it must be null. Nothing is 459 performed if the VTSAgent has already been logged-in. The 460 authentication scheme is implementation-specific. Examples of the 461 implementation are as follows: 463 1) Vouchers are managed on a remote centralized server (central VVS), 464 and the server requires a password to login. In this case, the 465 application may prompt the user to input the password and can be 466 given to the VTSAgent through this method. 468 2) Vouchers are managed on a remote centralized server (central VVS); 469 they require challenge-and-response authentication using 470 smartcards held by users. In this case, the passphrase may be null 471 since access to the smartcard can be done without contacting the 472 application or user, i.e., the VTSAgent receives the challenge 473 from the server, sends the challenge to the smartcard (within the 474 VTS), and returns the response from the smartcard to the server. 475 Note that a PIN to unlock the smartcard may be given through this 476 method depending on the implementation. 478 3) Each user holds their own smartcard in which their own vouchers 479 are stored (decentralized VVS). In this case, the passphrase may 480 be null since no authentication is required. Note that a PIN to 481 unlock the smartcard may be given through this depends on the 482 implementation. 484 M. Terada and K. Fujimura [Page 9] 485 Throws: 487 VTSSecurityException - if authentication fails. 489 5.4.2 logout 491 public void logout() 492 throws VTSException 494 Voids the authentication performed by the login() method. 496 After calling this method, calling any other method (except 497 login()) will cause VTSSecurityException. 499 The VTSAgent can login again by the login() method. 501 Throws: 503 VTSSecurityException - if the VTSAgent is not authenticated 504 correctly. 506 5.4.3 prepare 508 public Session prepare(Participant receiver) 509 throws VTSException 511 Establishes a session that is required for trading vouchers. The 512 trading partner who receives the vouchers is specified as receiver. 513 The vouchers to be traded will be specified later (when a trading 514 method is called). 516 The establishment of a session is implementation-specific. An 517 implementation that has a central VVS may start a transaction, while 518 other implementations that have decentralized VVS may get, from the 519 receiver, the challenge needed to authenticate the sender during the 520 establishment of the session. 522 If the VTSAgent has no ability to establish a session with the 523 specified receiver (permanent error), the VTSAgent throws an 524 InvalidParticipantExeption. If the VTSAgent can not establish a 525 session due to network failure (transient error), the VTSAgent throws 526 a CannotProceedException. 528 Parameters: 530 receiver - the trading partner who receives vouchers. 532 Returns: 534 an established session whose state is "prepared" (see Section 5.5). 536 Throws: 538 VTSSecurityException - if the VTSAgent cannot be authenticated 539 correctly. 540 InvalidParticipantException - if the specified participant is 541 invalid. 542 CannotProceedException - if the preparation of the session is 543 aborted (e.g. network failures). 545 5.4.4 issue 547 public void issue(Session session, 548 VoucherComponent promise, 549 java.lang.Number num) 550 throws VTSException 552 Issues vouchers. This method creates the specified number of 553 vouchers and adds them to the VVS. Note 554 that receiver is specified when the prepare() method is 555 called. Nothing is performed if the specified number is 0. 557 The session MUST be "prepared" when calling this method. The state 558 of the session will be "activated" when the vouchers are created, and 559 it will be "completed" when the transaction is successfully completed 560 or "suspended" if the transaction is interrupted abnormally (e.g., 561 network failures). 563 Parameters: 565 session - the session used by the issue transaction. 566 promise - the promise part of the voucher. 567 num - the number of vouchers to be issued. 569 Throws: 571 VTSSecurityException - if the VTSAgent cannot be authenticated 572 correctly. 573 InvalidStateException - if the session is not "prepared". 574 CannotProceedException - if the transaction cannot be successfully 575 completed. 577 5.4.5 transfer 579 public void transfer(Session session, 580 Participant issuer, 581 VoucherComponent promise, 582 java.lang.Number num) 583 throws VTSException 585 Transfers vouchers. This method rewrites the specified number of 586 vouchers to in 587 the VVS. Note that receiver is specified when the prepare() method is 588 called. The VTSAgent must have sufficient vouchers in the VVS. 589 Nothing is performed if the specified number is 0. 591 The session MUST be "prepared" when calling this method. The state 592 of the session will be "activated" when the voucher are retrieved 593 from the sender, and it will be "completed" when the transaction is 594 successfully completed or "suspended" if the transaction is 595 interrupted abnormally (e.g., network failures). 597 If null is specified for the issuer parameter, it indicates "any 598 issuer". This method selects vouchers to be transferred from the set 599 of vouchers returned by the getContents(null, promise). 601 Parameters: 603 session - the session used by the transfer transaction. 604 issuer - the issuer part of the voucher, or null. 605 promise - the promise part of the voucher. 606 num - the number of vouchers to be transferred. 608 Throws: 610 VTSSecurityException - if the VTSAgent cannot be authenticated 611 correctly. 612 InsufficientVoucherException - if the VTSAgent doesn't have a 613 sufficient number of vouchers to transfer. 614 InvalidStateException - if the session is not "prepared". 615 CannotProceedException - if the transaction cannot be successfully 616 completed. 618 5.4.6 consume 620 public void consume(Session session, 621 Participant issuer, 622 VoucherComponent promise, 623 java.lang.Number num) 624 throws VTSException 626 Consumes vouchers. This method deletes the specified number of 627 specified vouchers from the VVS. The VTSAgent 628 must have sufficient vouchers in the VVS. Nothing is performed if 629 the specified number is 0. 631 The session MUST be "prepared" when calling this method. The state 632 of the session will be "activated" when the vouchers are deleted, and 633 it will be "completed" when the transaction is successfully completed 634 or "suspended" if the transaction is interrupted abnormally (e.g., 635 network failures). 637 If null is specified for the issuer parameter, it indicates "any 638 issuer". This method selects vouchers to be consumed from the set of 639 vouchers returned by the getContents(null, promise). 641 Parameters: 643 session - the session used by the consume transaction. 645 issuer - the issuer part of the voucher, or null. 646 promise - the promise part of the voucher. 647 num - the number of vouchers to be consumed. 649 Throws: 651 VTSSecurityException - if the VTSAgent cannot be authenticated 652 correctly. 653 InsufficientVoucherException - if the VTSAgent doesn't have a 654 sufficient number of vouchers to consume. 655 InvalidStateException - if the session is not "prepared". 656 CannotProceedException - if the transaction cannot be successfully 657 completed. 659 5.4.7 present 661 public void present(Session session, 662 Participant issuer, 663 VoucherComponent promise, 664 java.lang.Number num) 665 throws VTSException 667 Presents vouchers. This method shows that the sender has the 668 specified number of vouchers in the VVS to 669 the receiver of the session; No modification is performed to the 670 VVS. The VTSAgent must have a sufficient vouchers in the VVS. Nothing 671 is performed if the specified number is 0. 673 The session MUST be "prepared" when calling this method. The state 674 of the session will be "activated" when the vouchers are retrieved, 675 and it will be "completed" when the transaction is successfully 676 completed or "suspended" if the transaction is interrupted abnormally 677 (e.g., by network failures). 679 If null is specified for the issuer parameter, it indicates "any 680 issuer". This method selects vouchers to be presented from the set 681 of vouchers returned by the getContents(null, promise). 683 Parameters: 685 session - the session used by the present transaction. 686 issuer - the issuer part of the voucher, or null. 687 promise - the promise part of the voucher. 688 num - the number of the voucher to be presented. 690 Throws: 692 VTSSecurityException - if the VTSAgent cannot be authenticated 693 correctly. 694 InsufficientVoucherException - if the VTSAgent doesn't have a 695 sufficient number of vouchers to present. 696 InvalidStateException - if the session is not "prepared". 697 CannotProceedException - if the transaction cannot be successfully 698 completed. 700 5.4.8 cancel 702 public void cancel(Session session) 703 throws VTSException 705 Releases the session. "Prepared" sessions MUST be canceled. An 706 implementation MAY be permitted to cancel "activated" or "suspended" 707 sessions. 709 Throws: 711 VTSSecurityException - if the VTSAgent cannot be authenticated 712 correctly. 713 InvalidStateException - if the state of the session isn't 714 cancelable. 716 5.4.9 resume 718 public void resume(Session session) 719 throws VTSException 721 Restarts the session. Only "suspended" sessions can be resumed. 723 The state of the session will be re-"activated" immediately, and it 724 will be "completed" when the transaction is successfully completed or 725 "suspended" again if the transaction is interrupted abnormally (e.g., 726 network failures). 728 Throws: 730 VTSSecurityException - if the VTSAgent cannot be authenticated 731 correctly. 732 InvalidStateException - if the session is not "suspended". 733 CannotProceedException - if the transaction cannot be successfully 734 completed. 736 5.4.10 create 738 public void create(VoucherComponent promise, java.lang.Number num) 739 throws VTSException 741 Creates vouchers where the issuer is the VTSAgent itself. This 742 method creates the specified number of vouchers and adds them to the VVS. Nothing is performed if the 744 specified number is 0. 746 Throws: 748 VTSSecurityException - if the VTSAgent cannot be authenticated 749 correctly. 751 5.4.11 delete 753 public void delete(Participant issuer, 754 VoucherComponent promise, 755 java.lang.Number num) 756 throws VTSException 758 Deletes vouchers. This method deletes the specified number of 759 vouchers from the VVS. The VTSAgent must 760 have sufficient vouchers in the VVS. Nothing is performed if the 761 specified number is 0. 763 Throws: 765 VTSSecurityException - if the VTSAgent cannot be authenticated 766 correctly. 767 InsufficientVoucherException - if the VTSAgent doesn't have 768 sufficient number of vouchers to delete. 770 5.4.12 getContents 772 public java.util.Set getContents(Participant issuer, 773 VoucherComponent promise) 774 throws VTSException 776 Returns the set of vouchers whose issuer and promise both match the 777 issuer and promise specified in the parameters. 779 If null is specified for the issuer or promise parameter, it 780 indicates "any issuer" or "any promise", respectively. If null is 781 specified for both parameters, this method selects all vouchers owned 782 by the holder from the VVS. 784 Returns: 786 the set of vouchers held by the holder of the VTSAgent. 788 Throws: 790 VTSSecurityException - if the VTSAgent cannot be authenticated 791 correctly. 793 5.4.13 getSessions 795 public java.lang.Set getSessions() 796 throws VTSException 798 Returns a set of not-completed sessions prepared by the VTSAgent. 800 Returns: 802 the set of sessions prepared by the VTSAgent and not yet completed. 804 Throws: 806 VTSSecurityException - if the VTSAgent cannot be authenticated 807 correctly. 809 5.4.14 getLog 811 public java.lang.Set getLog() 812 throws VTSException 814 Returns a set of completed sessions prepared or received by the 815 VTSAgent. This set represents the trading log of the VTSAgent. A 816 VTS may delete an old log eventually, so that the entire log may 817 not be returned; the amount of the log kept by the VTSAgent is 818 implementation-specific. 820 Returns: 822 the set of completed sessions prepared or received by the VTSAgent. 824 Throws: 826 VTSSecurityException - if the VTSAgent cannot be authenticated 827 correctly. 829 5.4.15 addReceptionListener 831 public void addReceptionListener(ReceptionListener l) 832 throws VTSException 834 Adds a ReceptionListener to the listener list. 836 After a ReceptionListener l is registered by this method, l.arrive() 837 will be called whenever the VTSAgent receives a voucher. 839 Nothing is performed if the specified listener is null. 841 Throws: 843 VTSSecurityException - if the VTSAgent cannot be authenticated 844 correctly. 846 5.4.16 removeReceptionListener 848 public void removeReceptionListener(ReceptionListener l) 849 throws VTSException 851 Removes a ReceptionListener from the listener list. 853 Nothing is performed when the specified listener is null or not 854 registered. 856 Throws: 858 VTSSecurityException - if the VTSAgent cannot be authenticated 859 correctly. 861 5.5 Session 863 public interface Session 865 Represents the logical connection established by the trade. Sessions 866 are established by VTSAgent#prepare(). 868 A session has four states: prepared, activated, suspended, and 869 completed. The initial state of a session is "prepared", and the 870 session will be "activated" immediately when any of the trading 871 methods of VTSAgent is called. The "activated" session will be 872 "completed" after the trading method is successfully completed. If 873 the trading method is transiently failed (e.g. network failure), the 874 session will be "suspended". Suspended sessions can be re-"activated" 875 and restarted by calling VTSAgent#resume(). 877 A completed session may disappear from the VTSAgent; the session 878 will be collected by the GC unless other objects keep its reference. 880 5.5.1 getIdentifier 882 public String getIdentifier() 884 Returns the identifier of the session. The generation scheme of the 885 identifier is implementation-specific. An implementation may use a 886 transaction ID as the identifier of the session. 888 Returns: 890 the string of the identifier of the session. 892 5.5.2 getVoucher 894 public Voucher getVoucher() 896 Returns the voucher to be traded using the session, or returns null 897 if the session has not been activated. 899 Returns: 901 the voucher to be traded or null if the state of the session is 902 "prepared". 904 5.5.3 getSender 906 public Participant getSender() 908 Returns the sender of the session, i.e., the creator who prepared the 909 session. 911 Returns: 913 the sender of the session. 915 5.5.4 getReceiver 917 public Participant getReceiver() 919 Returns the receiver of the session, i.e., the participant specified 920 when preparing the session (by the VTSAgent#prepare() method). 922 Returns: 924 the receiver of the session. 926 5.5.5 isPrepared 928 public boolean isPrepared() 930 Verifies if the session is "prepared". 932 Returns: 934 true if the session is in "prepared" state, or false. 936 5.5.6 isActivated 938 public boolean isActivated() 940 Verifies if the session is "activated". 942 Returns: 944 true if the session is in "activated" state, or false. 946 5.5.7 isSuspended 948 public boolean isSuspended() 950 Verifies if the session is "suspended". 952 Returns: 954 true if the session is in "suspended" state, or false. 956 5.5.8 isCompleted 958 public boolean isCompleted() 960 Verifies if the session is "completed". 962 Returns: 964 true if the session is in "completed" state, or false. 966 5.6 Voucher 968 public interface Voucher 970 Represents voucher(s) described in [VTS]. An object implementing 971 this interface can represent more than one voucher if all of the 972 issuer part and the promise part of the vouchers are the same. 974 5.6.1 getIssuer 976 public Participant getIssuer() 978 Returns the issuer part of the voucher(s). 980 Returns: 982 the participant who issued the voucher(s). 984 5.6.2 getPromise 986 public VoucherComponent getPromise() 988 Returns the promise part of the voucher(s). 990 Returns: 992 the voucher component that defines the promise of the voucher. 994 5.6.3 getCount 996 public java.lang.Number getCount() 998 Returns the number of the voucher(s). 1000 Returns: 1002 the positive (>0) number of the voucher(s). 1004 5.7 VoucherComponentRepository 1006 public interface VoucherComponentRepository 1008 Maintains VoucherComponents. 1010 An object implementing VoucherComponentRepository provides a means of 1011 retrieving the voucher components that are the promises of vouchers 1012 in the VVS. 1014 Before issuing a voucher, the promise of the voucher must be 1015 registered with this repository. The repository can be implemented 1016 as either a network-wide directory service or personal storage like 1017 the ParticipantRepository. 1019 5.7.1 register 1021 public VoucherComponent register(org.w3c.dom.Document document) 1023 Creates a voucher component associated with the specified DOM object 1024 and registers the voucher component with the repository. 1026 A voucher component of the voucher to be issued must be registered 1027 using this method. 1029 Nothing is performed (and the method returns null) if the specified 1030 document is null or the syntax of the document does not conform to 1031 the VTS. 1033 Returns: 1035 a registered voucher component associated with the 1036 specified document, or null if the document is null or has wrong 1037 syntax. 1039 5.8 VoucherComponent 1041 public interface VoucherComponent 1043 Represents the voucher component that defines the promise of the 1044 voucher. 1046 Each VoucherComponent object has its own unique identifier, and it is 1047 associated with an XML document that describes the promise made by 1048 the issuer of the voucher, e.g., the goods or services can be claimed 1049 in exchange for redeeming the voucher. 1051 This interface can be implemented as sort of a "smart pointer" to the 1052 XML document. An implementation may have a reference to a voucher 1053 component repository instead of the voucher component and retrieve 1054 the document dynamically from the repository when the getDocument() 1055 method is called. 1057 5.8.1 getIdentifier 1059 public String getIdentifier() 1061 Returns the identifier of the voucher component. Each voucher 1062 component must have a unique identifier. The identifier may be 1063 used to check for equivalence of voucher components. 1065 The format of the identifier is implementation-specific. 1067 Returns: 1069 The identifier string of the voucher component. 1071 5.8.2 getDocument 1073 public org.w3c.dom.Document getDocument() 1075 Returns a Document Object Model [DOM] representation of the document 1076 associated with the voucher component by the 1077 VoucherComponentRepository#register() method. 1079 The DOM object to be returned may be retrieved from a 1080 VoucherComponentRepository on demand, instead of the VoucherComponent 1081 always keeping a reference to the DOM object. 1083 Returns: 1085 a DOM representation of the document associated with the voucher 1086 component. 1088 Throws: 1090 DocumentNotFoundException - if the associated DOM object cannot be 1091 retrieved. 1093 5.9 ReceptionListener 1095 public interface ReceptionListener extends java.util.EventListener 1097 Provides a listener interface that provides notification that a 1098 VTSAgent has been received a voucher. 1100 When a voucher arrives at VTSAgent, the VTSAgent invokes arrive() 1101 method of each registered ReceptionListener. ReceptionListeners can 1102 obtain a Session object, which contains information about the 1103 received voucher and the sender of the voucher. 1105 This interface is intended to provide a means of notifying a wallet 1106 that "You have new vouchers", so that this interface may be 1107 implemented by wallets or other applications using VTS. 1109 5.9.1 arrive 1111 public void arrive(Session session) 1113 Provides notification of the arrival of a voucher. 1115 After the listener is registered to a VTSAgent (by the 1116 VTSAgent#addReceptionListener() method), the VTSAgent invokes this 1117 method whenever it receives a voucher. 1119 The specified session is equivalent to the session used by the sender 1120 to trade the voucher. The state of the session is "completed" when 1121 this method is called. 1123 5.10 Exceptions 1125 java.lang.Exception 1126 +-- VTSException 1127 +-- CannotProceedException 1128 +-- DocumentNotFoundException 1129 +-- InsufficientVoucherException 1130 +-- InvalidParticipantException 1131 +-- InvalidStateException 1132 +-- VTSSecurityException 1134 VTSException 1136 This is the superclass of all exceptions thrown by the methods in the 1137 interfaces constructs the VTS-API. 1139 CannotProceedException 1141 This exception is thrown when a trading is interrupted due to 1142 network failures or other errors. 1144 DocumentNotFoundException 1146 This exception is thrown when the document associated with a voucher 1147 component cannot be found. 1149 InsufficientVoucherException 1151 This exception is thrown when the number of the voucher is less than 1152 the number specified to trade. 1154 InvalidParticipantException 1156 This exception is thrown when the specified participant cannot be 1157 located. 1159 InvalidStateException 1161 This exception is thrown when the state of the session is invalid to 1162 proceed the operation. 1164 VTSSecurityException 1166 This exception is thrown when authentication fails or a method 1167 which requires authentication in advance is called without 1168 authentication. 1170 6. Example Code 1172 // Issue a voucher 1174 VTSManager vts = new FooVTSManager(); 1175 ParticipantRepository addrBook = vts.getParticipantRepository(); 1176 VoucherComponentRepository vcr = vts.getVoucherComponentRepository(); 1178 Participant you = addrBook.lookup("http://foo.bar/baz"); 1179 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1181 VoucherComponent promise = vcr.register(anXMLVoucherDocument); 1183 try { 1184 me.login(); 1185 s = me.prepare(you); 1186 me.issue(s, promise, 1); 1187 me.logout(); 1188 } catch (VTSException e) { 1189 System.err.println("Sorry!"); 1190 e.printStackTrace(); 1191 } 1193 // Transfer all my vouchers 1195 VTSManager vts = new FooVTSManager(); 1196 ParticipantRepository addrBook = vts.getParticipantRepository(); 1198 Participant you = addrBook.lookup("http://foo.bar/baz"); 1199 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1201 try { 1202 me.login(); 1203 Iterator i = me.getContents(null, null).iterator(); 1205 while (i.hasNext) { 1206 Voucher v = (Voucher) i.next(); 1207 s = me.prepare(you); 1208 me.transfer(s, v.getIssuer(), v.getPromise(), v.getCount()); 1209 } 1211 me.logout(); 1212 } catch (VTSException e) { 1213 System.err.println("Sorry!"); 1214 e.printStackTrace(); 1215 } 1217 // Register an incoming voucher notifier (biff) 1219 VTSManager vts = new FooVTSManager(); 1221 ParticipantRepository addrBook = vts.getParticipantRepository(); 1222 VTSAgent me = addrBook.lookup("myName").getVTSAgent(); 1223 ReceptionListener listener = new ReceptionListener() { 1224 public void arrive(Session s) { 1225 System.out.println("You got a new voucher."); 1226 } 1227 }; 1229 try { 1230 me.login(); 1231 me.addReceptionListener(listener); 1232 me.logout(); 1233 } catch (VTSException e) { 1234 System.err.println("Sorry!"); 1235 e.printStackTrace(); 1236 } 1238 7. Security Considerations 1240 This document assumes that the VTS plug-in is trusted. The caller 1241 application of a VTS should authenticate the VTS plug-in and bind it 1242 securely using the VTS Provider information specified in the Voucher 1243 Component. This document, however, does not specify any application 1244 authentication scheme and it is assumed to be specified by other 1245 related standards. [Editor's note: References are for further 1246 study. Until various VTS systems are deployed, it may be enough to 1247 manually check and install VTS plug-ins like other download 1248 applications.] 1250 To protect vouchers from being stolen, the VTSAgent must be 1251 authenticated securely. This document introduced a login/logout 1252 facility for this purpose (see Section 5.4). 1254 8. Acknowledgement 1256 (tbs) 1258 9. References 1260 [DOM] "Document Object Model (DOM), Level 1 Specification", October 1261 ,1998. 1263 [DOMHash] H. Maruyama, K. Tamura, and N. Uramoto, "Digest Values 1264 for DOM (DOMHASH)", RFC 2803, 2000. 1266 [ECML] J. W. Parsons, "Electronic Commerce Modeling Language (ECML) 1267 Version 2 Specification", draft-ietf-trade-ecml2-spec-02.txt, 1268 2001. 1270 [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.), 1271 "SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854, 1272 Springer-Verlag, 2000. 1274 [GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher 1275 Language", draft-ietf-trade-voucher-lang-02.txt, 2001. 1277 [VTS] K. Fujimura, "Requirements and Design for Voucher Trading 1278 System (VTS)", draft-ietf-trade-drt-requirements-03.txt, 2002. 1280 [IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version 1281 1.0", RFC 2801, 2000. 1283 [JCC] Sun Microsystems Inc., "Java Commerce Client", 1284 . 1286 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1287 Requirement Levels", BCP 14, RFC 2119, 1997. 1289 10. Author's Address 1291 Masayuki Terada and Ko Fujimura 1292 NTT Corporation 1293 1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN 1294 Phone: +81-(0)468-59-3814 1295 Fax: +81-(0)468-59-2241 1296 Email: terada@isl.ntt.co.jp, fujimura@isl.ntt.co.jp