1、 ETSI TS 102 588 V9.1.0 (2011-01)Technical Specification Smart Cards;Application invocation Application ProgrammingInterface (API) by a UICC webserver for Java Card platform;(Release 9)floppy3ETSI ETSI TS 102 588 V9.1.0 (2011-01)2Release 9 Reference RTS/SCP-T102588v910 Keywords API, smart card ETSI
2、650 Route des Lucioles F-06921 Sophia Antipolis Cedex - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16 Siret N 348 623 562 00017 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88 Important notice Individual copies of the present document can be dow
3、nloaded from: http:/www.etsi.org The present document may be made available in more than one electronic version or in print. In any case of existing or perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF). In case of dispute, the referen
4、ce shall be the printing on ETSI printers of the PDF version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or change of status. Information on the current status of this and other ETSI documents is
5、 available at http:/portal.etsi.org/tb/status/status.asp If you find errors in the present document, please send your comment to one of the following services: http:/portal.etsi.org/chaircor/ETSI_support.asp Copyright Notification No part may be reproduced except as authorized by written permission.
6、 The copyright and the foregoing restriction extend to reproduction in all media. European Telecommunications Standards Institute 2011. All rights reserved. DECTTM, PLUGTESTSTM, UMTSTM, TIPHONTM, the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members. 3GP
7、PTM is a Trade Mark of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. LTE is a Trade Mark of ETSI currently being registered for the benefit of its Members and of the 3GPP Organizational Partners. GSM and the GSM logo are Trade Marks registered and owned by t
8、he GSM Association. ETSI ETSI TS 102 588 V9.1.0 (2011-01)3Release 9 Contents Intellectual Property Rights 4g3Foreword . 4g31 Scope 5g32 References 5g32.1 Normative references . 5g32.2 Informative references 5g33 Abbreviations . 6g34 Description . 6g34.1 Architecture 6g34.2 Registration and deregistr
9、ation . 7g34.3 Invocation . 8g34.4 Transfer of response data . 8g34.5 Response header management 8g34.6 ProactiveHandler and ProactiveResponseHandler . 9g3Annex A (normative): Application invocation API by a UICC Webserver for the Java Card platform 10g3Annex B (normative): Application invocation AP
10、I by a UICC Webserver for the Java Card platform 11g3Annex C (normative): Application invocation API by a UICC Webserver for the Java Card platform package version management . 12g3Annex D (informative): Change history . 13g3History 14g3ETSI ETSI TS 102 588 V9.1.0 (2011-01)4Release 9 Intellectual Pr
11、operty Rights IPRs essential or potentially essential to the present document may have been declared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: “Intellectual Property Rights (IPRs);
12、 Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards“, which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web server (http:/webapp.etsi.org/IPR/home.asp). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches
13、, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document. Foreword This Technical Specification (TS) has been produced b
14、y ETSI Technical Committee Smart Card Platform (SCP). The contents of the present document are subject to continuing work within TC SCP and may change following formal TC SCP approval. If TC SCP modifies the contents of the present document, it will then be republished by ETSI with an identifying ch
15、ange of release date and an increase in version number as follows: Version x.y.z where: x the first digit: 0 early working draft; 1 presented to TC SCP for information; 2 presented to TC SCP for approval; 3 or greater indicates TC SCP approved document under change control. y the second digit is inc
16、remented for all changes of substance, i.e. technical enhancements, corrections, updates, etc. z the third digit is incremented when editorial only changes have been incorporated in the document. ETSI ETSI TS 102 588 V9.1.0 (2011-01)5Release 9 1 Scope The present document defines an API that allows
17、a UICC based SCWS defined by OMA to forward Http requests to an Applet and to receive the response from the Applet. It also defines an API for the Applet to register and unregister to the SCWS. 2 References References are either specific (identified by date of publication and/or edition number or ve
18、rsion number) or non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the reference document (including any amendments) applies. In the case of a reference to a TC SCP document, a non specific reference implicitly refers to the lat
19、est version of that document in the same Release as the present document. Referenced documents which are not found to be publicly available in the expected location might be found at http:/docbox.etsi.org/Reference. NOTE: While any hyperlinks included in this clause were valid at the time of publica
20、tion ETSI cannot guarantee their long term validity. 2.1 Normative references The following referenced documents are necessary for the application of the present document. 1 “Hypertext Transfer Protocol - HTTP/1.1“. NOTE: available at http:/www.ietf.org/rfc/rfc2616.txt. 2 ETSI TS 102 241: “Smart car
21、ds; UICC Application Programming Interface (UICC API) for Java Card (TM)“. 3 OMA “Smartcard -Web Server Enabler Architecture“, OMA-AD-Smartcard-Web-Server-V1-0-20070209-C. 4 OMA “Smartcard-Web-Server“, OMA-TS-Smartcard-Web-Server-V1-0-20070209-C. 5 Sun Microsystems “Application Programming Interface
22、, Java Card Platform, 3.0.1 Classic Edition“. 6 Sun Microsystems “Runtime Environment Specification, Java Card Platform, 3.0.1 Classic Edition“. 7 Sun Microsystems “Virtual Machine Specification Java Card Platform, 3.0.1 Classic Edition“. NOTE: SUN Java Card Specifications can be downloaded at http:
23、/ . 8 ETSI TS 101 220: “Smart Cards; ETSI numbering system for telecommunication application providers“. 9 ETSI TS 102 225: “Smart Cards; Secured packet structure for UICC based applications“. 2.2 Informative references The following referenced documents are not necessary for the application of the
24、present document but they assist the user with regard to a particular subject area. Not applicable. ETSI ETSI TS 102 588 V9.1.0 (2011-01)6Release 9 3 Abbreviations For the purposes of the present document, the following abbreviations apply: AID Application IDentifier API Application Program Interfac
25、e CAT Card Application Toolkit CAT_TP Card Application Toolkit Transport Protocol FFS For Further Study Http HyperText Transfer Protocol HTTP HyperText Transfer Protocol JCRE Java Card Run-time Environment SCWS Smart Card based Web Server NOTE: According to OMA specifications 3 and 4. 4 Description
26、4.1 Architecture The present document describes an API and a SCWS Runtime Environment that enables Java Card platform based applets, defined in 5, 6, 7, to register to and unregister from an SCWS implemented in the UICC, defined by OMA in 3 and 4. The API enables a registered Applet to receive an in
27、coming Http request that is forwarded by the SCWS. The API provides the necessary methods to allow registered Applets to respond with a correctly formatted Http response to the SCWS. The API provides means to the Applet to access the Http header data and the content of the Http request, to send spec
28、ific Http status values, and to set the content of the Http response. The Http request and response are defined in the Hypertext Transfer Protocol - HTTP/1.1 1. This API allows application programmers to extend the functionality of the SCWS defined by OMA in 3 and 4. ETSI ETSI TS 102 588 V9.1.0 (201
29、1-01)7Release 9 102 221 based Applications ( e.g. SIM Applet or USIM Applet) ADF File System Server Other Applications not based on 102 221 Toolkit Applet ( e.g. Toolkit service, Remote Management Applications, Browser Applications) SCWS uicc.system package uicc.toolkit package uicc.access package J
30、ava Card TM Packages CAT Runtime Environment Triggering Entity Java Card TM Runtime Environment Items that are defined in this specification SCWS Runtime Environment uicc.scws package Figure 1 Smartcard Webserver (SCWS): handles Http request as defined by OMA in 3 and 4 and provides a mechanism to t
31、he Applet for the registration. SCWS Runtime Environment: Extensions to the Java Card platform described in 5, 6, 7 and the CAT Runtime Environment described in TS 102 241 2 to facilitate the communications between Applets and the SCWS. Applet: these derive from javacard.framework.Applet and provide
32、 the entry points: process, select, deselect, install as defined in the “ Runtime Environment Specification, Java Card Platform, 3.0.1 Classic Edition “ 6. Registry of the SCWS: is provided as a JCRE entry point object defined in 6, and provides an interface to the Applet to pass a name to the SCWS
33、for registration and deregistration. The registry is part of the SCWS Runtime Environment. SCWS API: consists of the package uicc.scws, provides the methods to register and deregister, to receive Http requests and to provide the content of the Http response. 4.2 Registration and deregistration The r
34、egistration of Applets to the SCWS enables the server to invoke a specific applet when it has received an Http request. Applet Instances can register with a name to the SCWS. The mapping of the Http request to the name of the applet is described by OMA in 3 and 4 by the use of administrative command
35、s FFS other non-Http based mechanism. It is not possible to register several Applets under the same name to the SCWS. It is possible for an Applet to register several times with different names to the SCWS. The Applet can also deregister from the SCWS. When the Applet deregisters from the SCWS the m
36、apping information is deleted from the registry. If an Applet is deleted then the registration information in the SCWS Registry is deleted by the SCWS Runtime Environment. If the Applet is in a non selectable state, its registration to the SCWS is still valid. ETSI ETSI TS 102 588 V9.1.0 (2011-01)8R
37、elease 9 4.3 Invocation The SCWS invokes the Applets according to the mapping information when the complete Http request has been received by the SCWS. Only an Applet that is in selectable state can be invoked by the SCWS. If Applet execution ends without any invocation of the flush() method and wit
38、hout throwing an exception the SCWS shall finalize the response and send it. 4.4 Transfer of response data There are two transfer modes defined for the SCWS API: “fixed buffer size mode“ and “chunked mode“. The API offers a method to switch between transfer modes. This method must be called before c
39、alling finalizeHeader() and before the first call of appendContent(). The default transfer mode is “fixed buffer size“. The header attributes (“Content-Length: xxx“ and “Transfer-Encoding: chunked“) will be set according to the active transfer mode by the SCWS runtime environment. The Application is
40、 not supposed to set these attributes. The SCWS runtime environment is not required to enforce this policy. The behaviour of the SCWS runtime environment is undefined if the application manipulates the header attributes for content length and transfer encoding. In “fixed buffer size mode“ an excepti
41、on will be thrown by appendContent() if the buffer size would be exceeded. In “fixed buffer size mode“ no data are sent out before the application has called the flush() method, subsequent calls are permitted but have no effect. In “chunked mode“ a call of flush() sends all data in the response buff
42、er. If there are no data in the response buffer no data will be sent. If a call of appendContent() exceeds the buffer size in “chunked mode“ the data in the response buffer will be sent implicitly. Exceptions thrown by the invoked Applet shall not be propagated to the terminal, and the SCWS shall se
43、nd an error status code according to HTTP 1.1 1. In case of “chunked mode“, some response data could have already been sent by the SCWS. In this case, no error shall be sent by the SCWS. In case of “fixed buffer size mode“, the status code is always sent by the SCWS. 4.5 Response header management R
44、esponse header fields can be provided by applications by using the appendHeaderVariable() methods. The following headers shall be added by the SCWS if not provided by the application: Status line, indicating success status (200 - OK or 204 - No Content). Server field, containing “OMA Smart Card Web
45、Server“ or a customized string. If status code 200 is returned, Content-type field, indicating “text/plain“. If status code 200 is returned, Content-length and Transfer-Encoding, according to clause 4.4. ETSI ETSI TS 102 588 V9.1.0 (2011-01)9Release 9 4.6 ProactiveHandler and ProactiveResponseHandle
46、r The rules about the availability of the ProactiveHandler and the ProactiveResponseHandler as defined in TS 102 241 2 are extended according to the following rules: The ProactiveHandler shall be available for applets that are invoked by an incoming Http request (i.e. by one of the methods doGet(),
47、doPost(), doDelete(), doHead(), doOptions(), doPut(), and doTrace() in the same way as if it would be available for an applet which was triggered by the method processToolkit() in the current card state. If available, the ProactiveHandler shall be available for these applets until the termination of
48、 the method that was invoked by the incoming Http request. The availability of the ProactiveResponseHandler shall depend on the availability of the ProactiveHandler as defined in TS 102 241 2, except that it is available until the termination of the method that was invoked by the incoming Http reque
49、st. Applets implementing the ToolkitInterface as defined in TS 102 241 2 in addition to the SCWS interface will be triggered in the processToolkit() method upon reception of any Toolkit event. Implementation dependent on a central CAT_TP multiplexing application as defined in TS 102 225 9 may be present in the card. It must not block the ProactiveHandler when an applet is invoked by an incoming Http request. ETSI ETSI TS 102 588 V9.1.0 (2011-01)10Re
