Home

JavaCard Runtime Environment Specification, Version

1. In addition the SELECT FILE APDU command to select an applet instance is extended to specify a new or already opened logical channel on which the specified applet instance is to be selected The term origin logical channel refers to the logical channel on which the command is received based on the logical channel number encoding within the CLA byte as described in Section 4 3 Forwarding APDU Commands To a Logical Channel on page 4 9 4 5 4 5 1 Applet Selection There are two ways to select an applet instance in the Java Card platform with a MANAGE CHANNEL OPEN command Section 4 5 1 Applet Selection with MANAGE CHANNEL OPEN on page 4 13 or with a SELECT FILE command Section 4 5 2 Applet Selection with SELECT FILE on page 4 15 The Java Card RE shall guarantee that an applet that is designed to run on any logical channel can be selected on any of the available logical channels on the card The resources accessed by the applet instance must be the same irrespective of the logical channel on which it is selected Applet Selection with MANAGE CHANNEL OPEN Upon receiving a MANAGE CHANNEL OPEN command on an I O interface the Java Card RE shall run the following procedure 1 The MANAGE CHANNEL OPEN command uses CLA b000000cc where cc in the bits b2 b1 denotes the origin logical channel 0 3 or CLA 0100dddd where dddd in the bits b4 b1 denote the origin logical channel 4 19 INS 0x70 an
2. java lang ArrayStoreException 0x03 java lang ClassCastException 0x04 java lang Exception 0x05 java lang IndexOutOfBoundsException 0x06 java lang NegativeArraySizeException 0x07 java lang NullPointerException 0x08 java lang RuntimeException 0x09 java lang SecurityException 0x0A java io IOException 0x0B java rmi RemoteException 0x0C javacard framework APDUException 0x20 javacard framework CardException 0x21 javacard framework CardRuntimeException 0x22 javacard framework ISOException 0x23 javacard framework PINException 0x24 javacard framework SystemException 0x25 Chapter 8 Remote Method Invocation Service 8 11 8 3 5 3 8 12 javacard framework TransactionException 0x26 javacard framework UserException 0x27 javacard security CryptoException 0x30 javacard framework service ServiceException 0x40 javacardx biometry BioException 0x50 0x60 javacardx external ExternalException javacardx framework tlv TLVException 0x70 javacardx framework util UtilException 0x80 Following is the encoding when a user defined exception is thrown by the remote method The exception_type item represents the closest API defined exception type It may be returned during any remote method invocation The reason item is the Java Card platform exception reason code or 0 for the subclasses of java lang java rmi or java
3. MANAGE CHANNEL Command Processing The Java Card RE shall intercept all APDU messages coming into the card perform card management functions such as selecting or deselecting applet instances and shall forward APDU messages to the appropriate applet instance As part of its card management functions the Java Card RE notifies applet instances about selection events a function it performs by calling the applet instances select and deselect methods With the addition of logical channels in Java Card platform the Java Card RE includes a multichannel dispatching mechanism as well as checks to ensure applet integrity during multi channel operations The Java Card RE must ensure that applets written to operate in a single logical channel environment operate consistently on a multiple logical channel smart card Java Card platform defines a class of APDU commands called MANAGE CHANNEL commands The functions the Java Card RE must perform by using MANAGE CHANNEL command processing are MANAGE CHANNEL OPEN Open a new logical channel from an already open logical channel Two variations of this command are supported m The Java Card RE selects the new logical channel specified in the command Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 a The Java Card RE automatically assigns a new logical channel MANAGE CHANNEL CLOSE Close a specified logical channel from another open logical channel
4. 11 3 4 3 Applet Package and Contained Instances Deletion The Java Card RE shall guarantee that deletion of the applet package and contained instances is not attempted and thereby deemed unsuccessful in the following cases m Another package on the card depends on this package as expressed in the CAP file s import component m An object owned by any of the applet instances being deleted is referenced from an object owned by an applet instance on the card that is not being deleted m An object owned by any of the applet instances being deleted is referenced from a static field of a package that is not being deleted m An applet instance belonging to the contexts of any of the applet instances being deleted is active on the card Otherwise if the applet package is resident in mutable memory the Java Card RE shall delete the applet package and contained instances Note The applet and package deletion attempt may fail due to security considerations or resource limitations The deletion of applet package and contained instances operation must be atomic If a reset or power fail occurs during the deletion process it must result in either an unsuccessful deletion of the applet package and contained instances or a successfully completed deletion of the applet package and contained instances before any applet is selected on the card Following an unsuccessful deletion of the applet package and contained instances any object or p
5. APDU setIncomingAndReceive Method This method returns the number of bytes received The returned number may be between 0 and 32767 Additionally when the 3 byte Lc format is used the data bytes received are placed at OFFSET_EXT_CDATA 7 of the APDU buffer APDUL receiveBytes short Method This method returns the number of bytes received The returned number may be between 0 and 32767 APDU setOutgoing Method These methods return the number of bytes expected Le by the CAD The returned number may be between 0 and 32767 When the T 0 transfer protocol is in use for a Case 2E P3 0 or Case 4 command this method returns 32767 When the T 1 transfer protocol is in use for a Case 2E or Case 4E command and Le is set to 0x0000 this method returns 32767 APDU setOutgoingLength short Method This method allows the caller to specify the number of bytes to send to the CAD The number specified may be between 0 and 32767 APDU sendBytes short short APDU sendBytesLong bytel short short Methods These methods allow the caller to specify the number of bytes to send to the CAD The number specified may be between 0 and 32767 9 5 Security and Crypto Packages The getInstance method in the following classes returns an implementation instance in the context of the calling applet of the requested algorithm javacard security MessageDigest Chapter 9 API Topics 9 9 javacard security InitializedMessageDigest jav
6. nore nore nore nore nore norte nore nore nore nore nore nore nore nore nore nore nore nore nore nore nore nore nore nore _RSA_512 _RSA_736 _RSA_768 _RSA_896 _RSA_1024 _RSA_1280 _RSA_1536 _RSA_1984 _RSA_2048 _RSA_4096 _DSA_512 _DSA_768 _DSA_1024 _EC_FP_112 _EC_F2M_11 _EC_FP_128 _EC_F2M_13 _EC_FP_160 _EC_F2M_16 _EC_FP_192 _EC_F2M_19 _EC_FP_256 _EC_FP_384 1 3 3 512 736 768 896 1024 1280 1536 1984 2048 4096 5125 768 1024 L12 113 128 e314 L60 163 192 193 256 384 _AES_128 128 _AES_192 192 A KOREAN_SE AES_256 256 ED_128 HMAC_SHA_1_BLOCK 128 64 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 public static final short LI public static final short L public static final short LI 12 15 ENGT ENGT ENGT TH_HMAC_SHA_256_BLOCK_64 64 TH_HMAC_SHA_384_BLOCK_64 128 TH_HMAC_SHA_512_BLOCK_64 128 Class javacard security KeyPair publ publ publ publ publ 12 16 ic ic ic ie ie sta sta sta sta sta tic tic tic tic tic final final final final final by by by by by Le Ce Ce Ce te ALG_
7. s context is active when either an instance of the applet is already active or when another applet instance from the same package is active For more information about contexts see Section 6 1 2 Contexts and Context Switching on page 6 2 An attempt to select an applet instance when the applet s context is active is referred to as a multiselection attempt If successful multiselection occurs and the applet instance becomes multiselected Multiselectable applets shall implement the javacard framework MultiSelectable interface In case of multiselection the applet instance is informed by invoking its methods MultiSelectable select and MultiSelectable deselect during selection and deselection respectively When an applet instance not currently active is the first one selected in its package its Applet select method is called Subsequent multiselections to this applet instance or selection of other applet instances in the same package shall result in a call to MultiSelectable select method This method is defined in the MultiSelectable interface Its only purpose is to inform the applet instance that it will be multiselected The applet instance may accept or reject a multiselection attempt If a multiselection attempt is made on an applet which does not implement the MultiSelectable interface the selection shall be rejected by the Java Card RE When a multiselected applet instance is deselected from one of the logical channels
8. Applet Deselection An applet instance is deselected either upon receipt of a MANAGE CHANNEL CLOSE command or as a result of a SELECT FILE command that selects a different or the same applet instance on the specified logical channel In either case when an applet instance is deselected the following procedure shall be followed by the Java Card RE m If the applet instance to be deselected is active on more than one logical channel or another applet instance from the same package is also active the Java Card RE sets the currently selected applet instance to be the applet instance being deselected and calls its MultiSelectable deselect appInstStillActive method where the appInstStillActive parameter is set to true if the same applet instance is still active on another logical channel A context switch occurs into the applet instance s context at this point see Section 6 1 2 Contexts and Context Switching on page 6 2 m Otherwise the Java Card RE sets the currently selected applet instance to be the applet instance being deselected and calls its Applet deselect method Upon return or uncaught exception the Java Card RE clears the fields of all CLEAR_ON_DESELECT transient objects in the context of deselected applet instance Note Note that the deselection is always successful even if the applet instance throws an exception from within the deselect method Runtime Environment Specification Java Card Platform v3
9. Products covered by and information contained in this service manual are controlled by U S Export Control laws and may be subject to the export or import laws in other countries Nuclear missile chemical biological weapons or nuclear maritime end uses or end users whether direct or indirect are strictly prohibited Export or reexport to countries subject to U S embargo or to entities identified on U S export exclusion lists including but not limited to the denied persons and specially designated nationals lists is strictly prohibited DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS REPRESENTATIONS AND WARRANTIES INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON INFRINGEMENT ARE DISCLAIMED EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID Copyright 2008 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 Etats Unis Tous droits r serv s Sun Microsystems Inc d tient les droits de propri t intellectuelle relatifs la technologie incorpor e dans le produit qui est d crit dans ce document En particulier et ce sans limitation ces droits de propri t intellectuelle peuvent inclure un ou plusieurs des brevets am ricains list s a l adresse http www sun com patents et un ou plusieurs des brevets suppl mentaires ou des applications de brevet en attente aux Etats Unis et dans les autres pays Droits de go
10. javacard security CryptoException class 12 6 javacard security KeyAgreement class 12 6 javacard security KeyBuilder class 12 6 javacard security KeyPair class 12 9 javacard security MessageDigest class 12 9 javacard security RandomData class 12 10 javacard security Signature class 12 10 javacardx crypto Cipher class 12 11 12 12 yi a javacardx external ExternalExeption class 12 14 javacardx external Memory class 12 14 javacardx framework math BigNumber 12 14 javacardx framework math BigNumber class 12 14 javacardx framework tlv BERTag class 12 14 javacardx framework tlv TLVException class 12 15 javacardx framework util UtilException class 12 15 JCSystem class 9 11 Index 4 JDK Glossary 6 L legacy applets 4 3 library package Glossary 6 local variable Glossary 6 logical channel Glossary 6 logical channels 4 1 basic 4 2 4 5 forwarding APDU commands to 4 9 opening and closing 4 12 M MAC Glossary 6 MANAGE CHANNEL CLOSE 4 18 MANAGE CHANNEL command processing 4 12 MANAGE CHANNEL OPEN 4 13 mask production Glossary 6 masking Glossary 6 Message Authentication Code Glossary 6 messages Java Card RMI 8 3 method Glossary 6 methods accessing array object 6 20 class instance object 6 17 shareable interface 6 18 standard interface 6 17 deselect 3 3 identifier 8 8 install 3 1 invocation 8 4 process 3 3 select 3 2 static 6 7 multichannel dispatching mechanism 4
11. the firewall again allows B to access any of its objects and prevents B from accessing non shared objects in the context of A Determining the Previous Context When an applet calls JcSystem get PreviousContextAID the Java Card RE shall return the instance AID of the applet instance active at the time of the last context switch Java Card RE Context The Java Card RE context does not have an AID If an applet calls the getPreviousContextAID method when the context of the applet was entered directly from the Java Card RE context this method returns null If the applet calls getPreviousContextAID from a method that may be accessed either from within the applet itself or when accessed via a shareable interface from an external applet it shall check for nu11 return before performing caller AID authentication Shareable Interface Details A shareable interface is simply one that extends either directly or indirectly the tagging interface javacard framework Shareable This Shareable interface is similar in concept to the Remote interface used by the RMI facility in which calls to the interface methods take place across a local remote boundary Java Card API Shareable Interface Interfaces extending the Shareable tagging interface have this special property Calls to the interface methods take place across Java Card platform s applet firewall boundary by means of a context switch The Shareable interface serves to identify all sh
12. 0 Classic Edition XX Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 1 Introduction This book is targeted for the Classic Edition The Java Card Platform Version 3 0 consists of two editions The Classic Edition is based on an evolution of the Java Card Platform Version 2 2 2 and is backward compatible with it targeting resource constrained devices that solely support applet based applications You may disregard the specifications for the Connected Edition if you are interested in the functionality found only in the Classic Edition The Connected Edition features a significantly enhanced runtime environment and a new virtual machine It includes new network oriented features such as support for web applications including the Java Servlet APIs and also support for applets with extended and advanced capabilities An application written for or an implementation of the Connected Edition may use features found in the Classic Edition Therefore you will need to use the specifications for both the Classic Edition and the Connected Edition The runtime environment RE for the Java Card Platform Version 3 0 comprises the Java Card virtual machine VM the Java Card Application Programming Interface API classes and industry specific extensions and support services This document the Runtime Environment Specification Java Card Platform Version 3 0 Classic Edition specifie
13. 12 multiselectable applets 4 4 4 7 Glossary 6 multiselected applet Glossary 6 multiselection attempt 4 7 multi session functionality 4 2 N namespace Glossary 6 native method Glossary 6 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 nibble Glossary 6 O object owner Glossary 7 object oriented Glossary 6 objects Glossary 7 access behavior 6 16 accessing 6 6 across contexts 6 8 array 6 16 array methods 6 20 class instance 6 19 class instance fields 6 17 class instance methods 6 17 Java Card RE entry point 6 8 ownership 6 4 persistent 2 1 5 2 remote 8 1 remote identifier 8 5 remote reference descriptor 8 5 sharing 6 1 6 7 throwing exception 6 18 transient 5 1 7 5 CLEAR_ON_DESELECT 5 2 6 6 CLEAR_ON_RESET 5 2 6 6 clearing 5 2 contexts 6 6 required behavior 5 1 origin logical channe Glossary 7 owning context Glossary 7 P package Glossary 7 packages crypto 9 9 security 9 9 parameter encoding 8 8 PCD Glossary 7 persistent object Glossary 7 persistent objects 2 1 5 2 PICC activation behavior 4 5 PIX Glossary 7 power loss 3 4 process method 3 3 Proximity Coupling Device Glossary 7 R RAM Glossary 7 random access memory Glossary 7 read only memory Glossary 8 reference implementation Glossary 7 remote interface Glossary 7 Remote Method Invocation Glossary 5 remote methods 8 1 Glossary 8 remote object 8 1 Gloss
14. 3 8 2 2 Method Invocation 8 4 Data Formats 8 4 8 3 1 Remote Object Identifier 8 5 8 3 2 Remote Object Reference Descriptor 8 5 8 3 3 Method Identifier 8 8 8 3 4 Parameter Encoding 8 8 8 3 4 1 Primitive Data Type Parameter Encoding 8 8 vi Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 8 4 8 5 8 3 4 2 Array Parameter Encoding 8 9 8 3 5 Return Value Encoding 8 10 8 3 5 1 Normal Response Encoding 8 10 8 3 5 2 Exception Response Encoding 8 11 8 3 5 3 Error Response Encoding 8 12 APDU Command Formats 8 13 8 4 1 SELECT FILE Command 8 13 8 4 2 INVOKE Command 8 15 RMIService Class 8 16 8 5 1 setInvokeInstructionByte Method 8 17 8 5 2 processCommand Method 8 17 API Topics 9 1 9 1 9 2 9 3 9 4 9 5 Resource Use Within the API 9 1 Exceptions Thrown by API Classes 9 1 Transactions Within the API 9 2 APDU Class 9 2 9 4 1 T 0 Specifics for Outgoing Data Transfers 9 2 9 4 1 1 Constrained Transfers With No Chaining 9 3 9 4 1 2 Regular Output Transfers 9 4 9 4 1 3 Additional T 0 Requirements 9 5 9 4 2 T 1 Specifics for Outgoing Data Transfers 9 5 9 4 2 1 Constrained Transfers With No Chaining 9 5 9 4 2 2 Regular Output Transfers 9 6 9 4 3 T 1 Specifics for Incoming Data Transfers 9 7 9 4 3 1 Incoming Transfers Using Chaining 9 7 9 4 4 Extended Length APDU Specifics 9 7 9 4 4 1 Extended Length API Semantics 9 8 Security and Crypto Packages 9 9 Contents vii
15. 3 5 3 Error Response Encoding on page 8 12 Note Even though the select_response structure uses the C like union notation the lengths of the alternate representations within the union do not use any padding to normalize their lengths The format of the remote_ref_descriptor to be used in this response as well as all subsequent responses remote_ref_with_class or remote_ref_with_interfaces is determined by the value of the P2 byte of the SELECT FILE command Note Only the RMIService instance that processes the SELECT FILE command sets or changes the format of the remote object reference descriptor based on the value of the P2 byte Once set or changed the RMIService instance uses only that format in all Java Card RMI responses it generates INVOKE Command TABLE 8 2 lists the format required for the Invoke command for a remote method invocation request TABLE 8 2 Invoke Command Format Field Value Description CLA b1000 yycc or The cc in bits b2 b1 denotes the origin logical channel b1010 yycc or number in the range 1 3 The yy in bits b4 b3 of the blly0 ddaad type 4 formats denote secure messaging The dddd in bits b4 b1 denote the origin logical channel number in the range 4 19 using 0 origin notation The y in bit b6 of the type 16 format denotes secure messaging See TABLE 4 2 for CLA field encoding formats INS value of invoke_ins returned in the previous invoke_ins select_respo
16. 4 18 and set the state so that no applet is active on the specified logical channel Assign the CLEAR_ON_DESELECT transient memory segment for the new logical channel in the following cases If any applet instance from the same package as that of the candidate applet instance is active on another logical channel assign the same CLEAR_ON_DESELECT transient memory segment to this logical channel Otherwise assign a different zero filled CLEAR_ON_DESELECT transient memory segment to this new logical channel Check whether the candidate applet instance accepts selection If the candidate applet s context is active the Java Card RE shall set the candidate applet instance as the currently selected applet instance and call the MultiSelectable select appInstAlreadyActive method where the parameter appInstAlreadyActive is set to true if the same applet instance is already active on another logical channel A context switch into the candidate applet instance s context occurs at this point see Section 6 1 2 Contexts and Context Switching on page 6 2 Otherwise if the candidate applet s context is not active the Java Card RE shall set the candidate applet instance as the currently selected applet instance and call the Applet select method A context switch into the candidate applet instance s context occurs at this point If the applet instance s select method throws an exception or returns false then the Java Car
17. 9 6 JCSystem Class 9 11 9 7 Optional Extension Packages 9 11 10 Virtual Machine Topics 10 1 10 1 Resource Failures 10 1 10 2 Security Violations 10 1 11 Applet Installation and Deletion 11 1 11 1 The Installer 11 2 11 1 1 Installer Implementation 11 2 11 1 2 Installer AID 11 3 11 1 3 Installer APDUs 11 3 11 1 4 CAP File Versions 11 3 11 1 5 Installer Behavior 11 4 11 1 6 Installer Privileges 11 5 11 2 The Newly Installed Applet 11 5 11 2 1 Installation Parameters 11 6 11 3 The Applet Deletion Manager 11 7 11 3 1 Applet Deletion Manager Implementation 11 7 11 3 2 Applet Deletion Manager AID 11 8 11 3 3 Applet Deletion Manager APDUs 11 8 11 3 4 Applet Deletion Manager Behavior 11 8 11 3 4 1 Applet Instance Deletion 11 9 11 3 4 2 Applet Library Package Deletion 11 11 11 3 4 3 Applet Package and Contained Instances Deletion 11 12 11 3 5 Applet Deletion Manager Privileges 11 13 12 API Constants 12 1 12 1 Class javacard framework APDU 12 1 viii Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 12 2 12 3 12 4 12 5 12 6 12 7 12 8 12 9 12 10 12 11 12 12 12 13 12 14 12 15 12 16 12 17 12 18 12 19 12 20 12 21 12 22 12 23 12 24 12 25 Class javacard framework APD U Exception 12 2 Interface javacard framework ISO7816 12 2 Class javacard Class javacard Class javacard Class javacard Class javacard Class javacard Class javacard Class javacard C
18. ATR was sent and the card is now ready to accept APDU commands Proximity Card PICC Activation Behavior The following describes the PICC activation behavior 1 After the successful completion of the PICC activation sequence on the contactless interface the Java Card RE performs its initialization if the contacted interface is not already active and then checks to see if its internal state indicates that a particular applet instance is the default applet instance for the basic logical channel on the contactless I O interface If the default applet is not a multiselectable applet see Section 4 2 Multiselectable Applets on page 4 7 and either an instance of the default applet is already active on the contacted interface or another applet instance from the same package is active on the contacted interface the Java Card RE sets its state to indicate that no applet is active on the basic logical channel Otherwise the Java Card RE makes this applet instance the currently selected applet instance on the basic logical channel on the contactless I O interface and informs the applet instance of its selection if the applet s Chapter 4 Logical Channels and Applet Selection 4 5 4 1 3 4 6 context is active on the contacted interface calls the MultiSelectable select method with the appInstAlreadyActive set to indicate if the same applet instance is already active and otherwise if the applet s context is not active on the cont
19. It is not necessary to clear the fields of transient objects before power is removed from a card However it is necessary to guarantee that the previous contents of such fields cannot be recovered once power is lost m CLEAR_ON_DESELECT The object s fields except for the length field are cleared whenever the applet is deselected and no other applets from the same package are active on the card Because a card reset implicitly deselects the currently selected applet the fields of CLEAR_ON_DESELECT objects are also cleared by the same events specified for CLEAR_ON_RESET The currently selected applet is explicitly deselected its deselect method is called only when a SELECT FILE command or MANAGE CHANNEL CLOSE command is processed The currently selected applet is deselected and then the fields of all CLEAR_ON_DESELECT transient objects owned by the applet are cleared if no other applets from the same package are active on the card regardless of whether the SELECT FILE command Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 m Fails to select an applet m Selects a different applet m Reselects the same applet Chapter 5 Transient Objects 5 3 5 4 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER Applet Isolation and Object Sharing Any implementation of the Java Card RE shall support isolation of conte
20. Java Card Platform Version 3 0 Classic Edition Chapter 11 Applet Installation and Deletion 11 3 11 1 5 11 4 Installer Behavior Java Card RE implementers shall also define other behaviors of their Installer including for the following Whether or not installation can be aborted and how this is done What happens if an exception reset or power fail occurs during installation What happens if another applet is selected before the Installer is finished with its work The Java Card RE shall guarantee that an applet will not be deemed successfully installed in the following cases The applet package as identified by the package AID is already resident on the card The applet package contains an applet with the same Java Card platform name as that of another applet already resident on the card The Java Card platform name of an applet identified by the AID item is described in Section 6 5 of the Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition The applet package requires more memory than is available on the card The applet package references a package that is not resident on the card The applet package references another package already resident on the card but the version of the resident package is not binary compatible with the applet package For more information on binary compatibility in the Java programming language see Java Language Specification Binary compatibility in Java Card techno
21. Of 3 2 select Method Applets remain in a suspended state until they are explicitly selected Selection occurs when the Java Card RE receives a SELECT FILE APDU command in which the name data matches the AID of the applet Applet selection can also occur on a MANAGE CHANNEL OPEN command Selection causes an applet to become the currently selected applet For more details see Section 4 5 Applet Selection on page 4 13 Prior to calling select the Java Card RE shall deselect the previously selected applet The Java Card RE indicates this to the applet by invoking the applet s deselect method or if concurrently selected on more than one logical channel its MultiSelectable deselect method for more details see Section 4 2 Multiselectable Applets on page 4 7 The Java Card RE informs the applet of selection by invoking its select method or if being concurrently selected on more than one logical channel its MultiSelectable select method for more details see Section 4 2 Multiselectable Applets on page 4 7 The applet may decline to be selected by returning false from the call to the select method or by throwing an exception If the applet returns true the actual SELECT FILE APDU command is supplied to the applet in the subsequent call to its process method so that the applet can examine the APDU contents The applet can process the SELECT FILE APDU command exactly like it processes any other APDU command It can r
22. RE must ensure the following when the contactless I O interface of a card concurrently operating over both the contacted as well as the contactless I O interfaces is reset a The transaction in progress in the currently selected applet instance executing on a logical channel on the contactless I O interface if any must be aborted m Each applet instance that was active on a logical channel over the contactless I O interface must be deselected If the contactless interface using the SWP interface standard is being logically reset the applet instances are explicitly deselected by calling the applicable deselect method Otherwise the instances are implicitly deselected and the deselect method is not called m All the logical channels open on the contactless I O interface are implicitly closed m Transient data of CLEAR_ON_DESELECT objects associated with each applet instance that was active on a logical channel over the contactless I O interface and that does not have an applet instance from the same package active on any logical channel over the contacted I O interface is reset to the default value Chapter 3 Java Card Applet Lifetime 3 5 3 6 Note To establish a card session over both contacted and contactless interfaces concurrently on cards on which the ISO7816 2 defined reset signal input RST contact resets the card the CAD must initiate the contacted session first A power loss or card reset on the contacted interfac
23. Specification Java Card Platform v3 0 Classic Edition e March 2008 public static final byte ALG_DES_CBC_IS09797_M1 2 public static final byte ALG_DES_CBC_ISO09797_M2 3 public static final byte ALG_DES_CBC_PKCS5 4 public static final byte ALG _DES_ECB NOPAD 5 public static final byte ALG_DES_ECB IS09797_M1 6 public static final byte ALG_DES_ECB IS09797_M2 7 public static final byte ALG_DES_ECB PKCS5 8 public static final byte ALG_RSA_ISO14888 9 public static final byte ALG_RSA_PKCS1 10 public static final byte ALG_RSA_IS09796 11 public static final byte ALG_RSA_NOPAD 12 public static final byte ALG_AES BLOCK_128_CBC_NOPAD 13 public static final byte ALG_AES_BLOCK_128 ECB NOPAD 14 public static final byte ALG _RSA_PKCS1_OAEP 15 public static final byte ALG_KOREAN_SEED_ECB_NOPAD 16 public static final byte ALG _KOREAN_SEED_CBC_NOPAD 17 public static final byte ALG_AES_BLOCK_192_CBC_NOPAD 18 public static final byte ALG_AES_BLOCK_192_ ECB NOPAD 19 public static final byte ALG_AES_BLOCK_256_CBC_NOPAD 20 public static final byte ALG_AES_BLOCK_256_ECB NOPAD 21 public static final byte ALG_AES_ CBC_IS09797_M1 22 public static final byte ALG_AES_ CBC_IS09797_M2 23 public static final byte ALG_AES_CBC_PKCS5 24 public static final byte ALG_AES_ ECB 1TS09797_M1 25 public
24. TLVException public public public public public public public public public public public 12 28 Class sta sta sta sta sta sta sta sta sta sta sta tic tic tic tic tic tic tic tic tic tic tic final final final final final final final final final final final S s nor nort nort nort nort nort nort nort nort nort nort a a a t INVALID_PARAM 1 ILLEGAL SIZE 2 EMPTY_TAG 3 EMPTY_TLV 4 MALFORMED_TAG 5 MALFORMED_TLV 6 INSUFFICIENT_STORAGE 7 TAG _SIZE_GREATER_THAN_127 8 TAG _NUMBER_GREATER_THAN_32767 9 LV_SIZE_GREATER_THAN_32767 10 LV_LENGTH_GREATER_THAN_ 32767 11 javacardx framework util UtilException public static final short ILLEGAL VALUE 1 public static final short TYPE_MISMATCHED 2 Chapter 12 API Constants 12 15 12 16 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 Glossary active applet instance AID application identifier APDU API applet applet developer applet execution context applet firewall applet package assigned logical channel an applet instance that is selected on at least one of the logical channels defined by ISO 7816 a string used to uniquely identify
25. amp SUN microsystems Runtime Environment Specification Java Card Platform Version 3 0 Classic Edition Sun Microsystems Inc www sun com March 2008 Copyright 2008 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 U S A All rights reserved Sun Microsystems Inc has intellectual property rights relating to technology embodied in the product that is described in this document In particular and without limitation these intellectual property rights may include one or more of the U S patents listed at ttp www sun com patents and one or more additional patents or pending patent applications in the U S and in other countries U S Government Rights Commercial software Government users are subject to the Sun Microsystems Inc standard license agreement and applicable provisions of the FAR and its supplements Use is subject to license terms This distribution may include materials developed by third parties Parts of the product may be derived from Berkeley BSD systems licensed from the University of California Sun Sun Microsystems the Sun logo Solaris Java Java Card Javadoc JDK Servlet and JVM are trademarks or registered trademarks of Sun Microsystems Inc in the U S and other countries UNIX is a registered trademark in the U S and other countries exclusively licensed through X Open Company Ltd The Adobe logo is a registered trademark of Adobe Systems Incorporated
26. can only be one currently selected applet instance at a given time Applets with the capability of being selected on multiple logical channels at the same time or accepting other applets belonging to the same package being selected simultaneously are referred to as multiselectable applets Refer to FIGURE 4 2 below Chapter 4 Logical Channels and Applet Selection 4 3 No applet is active on the new or only logical channel when one of the following occurs a The card is reset and no applet is designated as the default applet instance for the basic channel on the contacted I O interface or the default applet instance for the basic channel on the contacted I O interface rejects selection m The card successfully completes its PICC activation sequence and no applet is designated as the default applet instance for the basic channel on the contactless I O interface or the default applet instance for the basic channel on the contactless I O interface rejects selection a A MANAGE CHANNEL OPEN command on the basic channel opens a new channel and no applet is designated as the default applet instance for that logical channel m A new logical channel is opened when a MANAGE CHANNEL OPEN command is issued on a logical channel other than the basic channel on which there is no active applet m A SELECT FILE command fails when attempting to select an applet instance 4 1 4 4 Default Applets Normally applet instances become sele
27. card applications and certain types of files in card file systems An AID consists of two distinct pieces a 5 byte RID resource identifier and a 0 to 11 byte PIX proprietary identifier extension The RID is a resource identifier assigned to companies by ISO The PIX identifiers are assigned by companies A unique AID is assigned for each package In addition a unique AID is assigned for each applet in the package The package AID and the default AID for each applet defined in the package are specified in the CAP file They are supplied to the converter when the CAP file is generated an acronym for Application Protocol Data Unit as defined in ISO 7816 4 an acronym for Application Programming Interface The API defines calling conventions by which an application program accesses the operating system and other services within the context of this document a Java Card applet which is the basic unit of selection context functionality and security in Java Card technology a person creating an applet using Java Card technology context of a package that contains currently active applet the mechanism that prevents unauthorized accesses to objects in contexts other than currently active context see library package the logical channel on which the applet instance is either the active applet instance or will become the active applet instance Glossary 1 atomic operation atomicity ATR basic logical channel big endi
28. code 0x9000 and if the P2 0 variant is used one data byte containing the newly assigned logical channel number If the candidate applet instance is not a multiselectable applet as defined in Section 4 2 Multiselectable Applets on page 4 7 and the candidate applet s context is active the Java Card RE shall close the new logical channel The Java Card RE responds with status code 0x6985 SW_CONDITIONS_NOT_SATISFIED Assign the CLEAR_ON_DESELECT transient memory segment for the new logical channel If the applet s context is active assign the CLEAR_ON_DESELECT transient memory segment associated with that context to this logical channel Otherwise assign a new zero filled CLEAR_ON_DESELECT transient memory segment to this new logical channel Check whether the candidate applet instance accepts selection If the candidate applet s context is active the Java Card RE shall set the candidate applet instance as the currently selected applet instance and call the MultiSelectable select method where the parameter appInstAlreadyActive is set to true if the same applet instance is already active on another logical channel A context switch into the candidate applet instance s context occurs at this point For more details on contexts see Section 6 1 2 Contexts and Context Switching on page 6 2 Otherwise if the candidate applet s context is not active the Java Card RE shall set the candidate applet inst
29. computer in its own right and can integrate a card reader as one of its components In addition to being a smart card reader a terminal can process data exchanged between itself and the smart card the basic unit of program execution A process can have several threads running concurrently each performing a different job such as waiting for events or performing a time consuming job that the program doesn t need to complete before going on When a thread has finished its job it is suspended or destroyed The Java Card virtual machine can support only a single thread of execution Java Card technology programs cannot use class Thread or any of the thread related keywords in the Java programming language an atomic operation in which the developer defines the extent of the operation by indicating in the program code the beginning and end of the transaction Glossary 8 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 transient object the state of transient objects do not persist from one CAD session to the next and are reset to a default state at specified intervals Updates to the values of transient objects are not atomic and are not affected by transactions verification a process performed on a CAP file that ensures that the binary representation of the package is structurally correct word an abstract storage unit A word is large enough to hold a value of type byte short reference or returnA
30. final byte TYPE_RSA_PRIVATE 5 public static final byte TYPE_RSA_CRT_PRIVATE 6 public static final byte TYPE_DSA_PUBLIC 7 public static final byte TYPE_DSA_PRIVATE 8 public static final byte TYPE_EC_F2M PUBLIC 9 public static final byte TYPE_EC_F2M PRIVATE 10 public static final byte TYPE_EC_FP_PUBLIC 11 public static final byte TYPE_EC_FP PRIVATE 12 public static final byte TYPE_AES TRANSIENT RESET 13 public static final byte TYPE_AES TRANSIENT _DESELECT 14 public static final byte TYPE_AES 15 public static final byte TYPE _KOREAN_SEED_ TRANSIENT RESET 16 public static final byte TYPE KOREAN _SEED_ TRANSIENT _DESELECT 17 public static final byte TYPE_KOREAN_SEED 18 public static final byte TYPE _HMAC_ TRANSIENT RESET 19 public static final byte TYPE _HMAC_ TRANSIENT _DESELECT 20 public static final byte TYPE_HMAC 21 public static final byte TYPE_RSA_PRIVATE_TRANSIENT_RESET 22 public static final byte TYPE _RSA_PRIVATE_TRANSIENT_DESELECT 23 public static final byte TYPE_RSA_CRT_ PRIVATE _TRANSIENT_RESET 24 public static final byte TYPE_RSA_CRT_PRIVATE_TRANSIENT_DESELECT 25 public static final byte TYPE_DSA_PRIVATE_TRANSIENT_RESET 26 public static final byte TYPE _DSA_PRIVATE
31. for the specified logical channel are not available or the logical channel is already open the Java Card RE responds with status code 0x6A86 SW_INCORRECT_P1P2 6 The new logical channel on the I O interface that received the MANAGE CHANNEL OPEN command is now open This logical channel will be the assigned channel for the applet instance that will be selected on it 7 Determine the applet instance to be selected on the new logical channel m If the origin logical channel is the basic logical channel logical channel 0 then Ifa default applet instance for the new logical channel on the I O interface is defined pick the default applet instance for that logical channel as the candidate for selection on the new logical channel Otherwise set the Java Card RE state so that no applet is active on the new logical channel The Java Card RE responds with status code 0x9000 and if the P2 0 variant is used one data byte containing the newly assigned logical channel number m If the origin logical channel is not the basic logical channel a If an applet instance is active on the origin logical channel pick the applet instance as the candidate for selection on the new logical channel 4 14 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 4 5 2 10 11 Otherwise set the Java Card RE state so that no applet is active on the new logical channel The Java Card RE responds with status
32. framework SystemException public static final short ILLEGAL VALUE 1 public static final short NO_TRANSIENT_SPACE 2 public static final short ILLEGAL TRANSIENT 3 public static final short ILLEGAL AID 4 public static final short NO_RESOURCE 5 public static final short ILLEGAL_USE 6 12 7 Class javacard framework TransactionExceptio n public static final short IN_PROGRESS 1 public static final short NOT_IN_PROGRESS 2 12 4 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 public static final short BUFF ER_FULL 3 public static final short INTERNAL FAILURE 4 12 8 Class javacard framework service Dispatcher public static final byte public static final byte public static final byte public static final byte 12 9 Class PROCESS_NONE PROCESS_INP PROCESS_COMMAND PROCESS_OUT byte 0 UT_DATA byte 1 byte 2 PUT_DATA byte 3 javacard framework service RMIService public static final byte DEFAULT_RMI_INVOKE_INSTRUCTION 12 10 Class 0x38 javacard framework service ServiceExce ption public static public static public static public static public static public static public static final short final short final short final short final short final short final short ILLEGAL_PARAM 1 DIS
33. instances being deleted is active on the card Otherwise the Java Card RE shall delete the applet instances Note The applet deletion attempt may fail due to security considerations or resource limitations 11 10 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 11 3 4 2 The multiple applet instance deletion operation must be atomic If a reset or power fail occurs during the deletion process it must result in either an unsuccessful multiple applet instance deletion or a successfully completed multiple applet instance deletion before any applet is selected on the card Following an unsuccessful multiple applet instance deletion all applet instances shall be selectable and all objects owned by the applets shall remain unchanged The functionality of all applet instances on the card remains the same as prior to the unsuccessful attempt Following a successful multiple applet instance deletion it shall not be possible to select any of the deleted applets and no object owned by the deleted applets can be accessed by any applet currently on the card or by a new applet created in the future The resources used by the applet instances may be recovered for reuse The AID of the deleted applet instances may be reassigned to new applet instances Applet Library Package Deletion The Java Card RE shall guarantee that applet library package deletion is not attempted and thereby deemed unsuc
34. io exceptions exception_subclass_response ul exception_subclass_tag 0x83 ul exception_type s2 reason Error Response Encoding The following encoding represents an error condition on the card The error may occur due to marshalling unmarshalling or resource related problems rror_response ul error_tag 0x99 s2 error_detail Following are the values of the error_detail item a The Remote Object Identifier is invalid or ineligible for Java Card RMI 0x0001 m The Remote Method could not be identified 0x0002 m The Remote Method signature did not match the parameter format 0x0003 a Insufficient resources available to unmarshall parameters 0x0004 a Insufficient resources available to marshall response 0x0005 a Java Card Remote Method Invocation protocol error 0x0006 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 m Internal Error occurred OxFFFF 8 4 8 4 1 APDU Command Formats Section 8 3 Data Formats on page 8 4 described the various elements included in the data portion of the Java Card RMI messages This section describes the complete format of the APDU commands the header as well as the data portion containing the message elements described earlier Note Java Card RMI message protocol supports only the 1 byte encodings of the Lc and Le values of the APDU data length SELECT FILE Command TABLE 8 1 lists the formats
35. meaning after the invocation of the setOutgoingNoChaining method calls to the waitExtension method shall throw an APDUException with reason code ILLEGAL_USE Regular Output Transfers When the no chaining mode of output transfer is not requested by the applet meaning the setOutgoing method is used any ISO IEC 7816 3 4 compliant T 1 protocol transfer sequence may be used If the applet aborts early and sends less than the applet response length Lr set via setOutgoingLength method only the data bytes written via the send methods of the APDU class are sent to the CAD Note The waitExtension method may be invoked by the applet at any time The waitExtension method shall send an S block command with WTX request of INF units which is equivalent to a request of 1 additional work waiting time in T 0 mode See ISO IEC 7816 3 2004 Chain Abortion by the CAD If the CAD aborts a chained outbound transfer using an S block ABORT request see ISO IEC 7816 3 2004 the sendBytes or sendBytesLong method shall throw an APDUException with reason code T1_IFD_ABORT Calls to sendBytes or sendBytesLong methods from this point on shall result in an APDUException with reason code ILLEGAL_USE If an ISOException is thrown by the applet after the T1_IFD_ABORT exception is thrown the Java Card RE Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 9 4 3 9 4 3 1 9 4 4 shall discard
36. more non abstract classes that extend the javacard framework Applet class a data item known within a block but inaccessible to code outside the block For example any variable defined within a method is a local variable and cannot be used outside the method as seen at the card edge works as a logical link to an application on the card A logical channel establishes a communications session between a card applet and the terminal Commands issued on a specific logical channel are forwarded to the active applet on that logical channel For more information see the ISO IEC 7816 Specification Part 4 http www iso org an acronym for Message Authentication Code MAC is an encryption of data for security purposes refers to embedding the Java Card virtual machine runtime environment and applets in the read only memory of a smart card during manufacture a procedure or routine associated with one or more classes in object oriented languages implements the javacard framework MultiSelectable interface Multiselectable applets can be selected on multiple logical channels at the same time They can also accept other applets belonging to the same package being selected simultaneously an applet instance that is selected and therefore active on more than one logical channel simultaneously a set of names in which all names are unique a method that is not implemented in the Java programming language but in another language T
37. nort nort nort Nort ILLEGAL_USE 1 BUFFER_BOUNDS 2 BAD_LENGTH 3 IO_ERROR 4 NO_TO_GETRESPONSE 0XAA T1_IFD_ABORT OxAB NO_TO_REISSUE 0xAC Interface javacard framework 1ISO7816 publ publ publ publ publ publ publ publ publ lic ic Lic Lic ic lic rE Lic Lic final static final static final static final static final static final static final static final static final static short short short short short short short short SW_COMMAND_CHAINING_NOT_SUPPORTED short SW_NO_ERROR short 0x9000 SW_BYTES_REMATNING_00 0x6 SW_WARNING_STATE_UNCHANGED SW_WRONG_LENGTH 0x6700 SW_LOGICA SW_SECURE_MESSAGING_NOT_SUPPORTED SW_LAST_COMMAND_EXPECTED SW_SECURITY_STATUS_NOT_SATI _ CHANNEL _NOT_SUPPORTED 100 0x6200 0x6881 0x6882 0x6883 0x6884 SFIED 0x6982 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 publ publi publ publ publi publ publi publ publ publi publi publi publi publi publi publi publi publi publi publi publi publi publi publi publi lic lic lic lic lic lic publi short short short short short short short short short short short short sho
38. only when the APDU received supports extended length format Note that the maximum length that can be supported using extended length semantics by the Java Card technology API is 32767 An implementation which supports the optional javacardx apdu package shall support APDUs with extended length up to 32767 Applet process APDU Method When the APDU received is a Case 3E or 4E and contains an Lc encoding of extended length the APDU buffer contained in the APDU object upon entry into the Applet process APDU method shall encode the header data format as described in ISO 7816 3 Specification in its first seven bytes as shown in TABLE 9 1 When the T 0 transfer protocol is in use a Case 3E and 4E APDU is enclosed within an ENVELOPE ISO Inter industry CLA INS 0xC2 command as described in ISO 7816 4 2005 Specification The ENVELOPE command header is processed by the Java Card RE and only the enclosed Case 3E or Case 4E APDU command is placed in the APDU buffer using the format shown in TABLE 9 1 TABLE 9 1 APDU Buffer Format for Extended Length offset 0 offset 1 offset 2 offset 3 offset 4 offset 5 offset 6 offset 7 CLA INS P1 P2 3 byte Le undefined As shown in the table the header data at offset 4 5 and 6 of the APDU buffer contains a 3 byte Lc value as defined in ISO 7816 4 The 3 byte length may encode a number from 1to 32767 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008
39. required for the Select command for an RMI based applet Note b indicates binary notation using bit numbering as in the ISO 7816 specification The most significant bit is b8 The least significant bit is b1 An x notation represents a don t care TABLE 8 1 Select File Command Field Value Description CLA b000000cc The cc in bits b2 b1 denote the origin logical or channels number in the range 0 3 b0100dddd The dddd in bits b4 b1 denote the origin logical channel number 4 19 using 0 origin notation See TABLE 4 1 for CLA field encoding format INS OxA4 SELECT FILE PI 0x04 Select by AID Chapter 8 Remote Method Invocation Service 8 13 TABLE 8 1 Select File Command Field Value Description P2 b000x00xx Return FCI information The bits b2 b1 are used for partial selection if supported If bit b5 is 1 the remote reference descriptor uses the remote_ref_with_interfaces format otherwise it uses the alternate remote_ref_with_class format Le Le Length of the AID Data AID AID of the applet to be selected between 5 and 16 bytes Following is the format of the response Note that the applet may extend the format to include additional information if necessary before sending the response back to the CAD The additional information must retain the TLV format and must not introduce any additional information under the jc_rmi_data_tag select_response ul fci_tag Ox6F u
40. static final byte ALG_AES_ ECB ITS09797_M2 26 public static final byte ALG_AES_ECB PKCS5 27 public static final byte MODE_DECRYPT 1 public static final byte MODE_ENCRYPT 2 Chapter 12 API Constants 12 13 12 23 Class javacardx external ExternalException public static final short NO_SUCH_SUBSYSTEM 1 public static final short INVALID PARAM 2 public static final short INTERNAL _ERROR 3 12 24 Class javacardx external Memory public static final short MEMORY_TYPE_MIFARE short 1 public static final short MEMORY_TYPE_EXTENDED_STORE short 2 12 25 Class javacardx framework math BigNumber public static final byte FORMAT _BCD byte 1 public static final byte FORMAT _HEX byte 2 12 26 12 14 Class javacardx framework tlv BERTag public static final byte BER_TAG_CLASS_ UNIVERSAL byte 0 public static final byte BER_TAG_ CLASS APPLICATION byte 1 public n tatic final byte BER_TAG CLASS _CONTEXT_SPECIFIC byte 2 public static final byte BER_TAG_ CLASS PRIVAT n Gy byte 3 public static final boolean BER_TAG_TYPE_CONSTRUCTED true n T public n tatic final boolean BER_TAG_ TYPE PRIMITIVE false Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 L227 Class javacardx framework tlv
41. support the Java programming language keyword transient However Java Card technology provides methods to create transient arrays with primitive components or references to Object Note In this section the term field is used to refer to the component of an array object also The term transient object is a misnomer It can be incorrectly interpreted to mean that the object itself is transient However only the contents of the fields of the object except for the length field have a transient nature As with any other object in the Java programming language transient objects within the Java Card platform exist as long as they are referenced from m The stack m Local variables A class static field a A field in another existing object A transient object within the Java Card platform has the following required behavior m The fields of a transient object shall be cleared to the field s default value zero false or null at the occurrence of certain events see Section 5 1 Events That Clear Transient Objects on page 5 2 m For security reasons the fields of a transient object shall never be stored in a persistent memory technology Using current smart card technology as an example the contents of transient objects can be stored in RAM but never in EEPROM The purpose of this requirement is to allow transient objects to be used to store session keys m Writes to the fields of a transient object sha
42. the number of bytes in the class_name item to represent the name of the remote class in UTF 8 string notation The value of this item must be non zero The class_name item is the variable length representation of the name of the implementation class or superclass of the remote object in UTF 8 string notation The class referenced in the remote object reference descriptor must directly implement a remote interface If the implementation class of the remote object does not directly implement a remote interface the class name of the closest superclass of the implementation class which directly implements a remote interface must be used remote_ref_with_interfaces item is the definition of a remote object reference using the names of the interfaces and uses the following format Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 remote_ref_with_interfaces u2 remote_ref_id OxFFFF ul hash_modifier_length ul hash_modifier hash_modifier_length ul remote_interface_count rem_interface_def remote_interfaces remote_interface_count The definition of the remote_ref_id the hash_modifier_length and the hash_modifier item are the same as that described earlier in the remote_ref_with_class structure The remote_interface_count item indicates the number of rem_interface_def format entries in the remote_interfaces item This number must be less than 16 The remote_interfaces item compris
43. the objects owned by the applet instance and associated Java Card RE structures 11 8 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 11 3 4 1 m Applet library package deletion involves the removal of all the card resident components of the CAP file including code and any associated Java Card RE management structures m Deletion of the applet package and the contained applet instances involves the removal of the card resident code and Java Card RE structures associated with the applet package and all the applet instances and objects in the context of the package and associated Java Card RE structures Invocation of the Method javacard framework AppletEvent uninstall Whenever one or more applet instances is being deleted the Applet Deletion Manager shall inform each of the applets of potential deletion by invoking if implemented the applet s uninstall method When multiple applet instances are being deleted the order of invocation of the uninstall methods is unspecified Prior to following the stepwise sequence described in Section 11 3 4 1 Applet Instance Deletion on page 11 9 Section 11 3 4 2 Applet Library Package Deletion on page 11 11 or Section 11 3 4 3 Applet Package and Contained Instances Deletion on page 11 12 the Java Card RE shall do the following m Perform any security and authorization checks required for the deletion of each of the applet instances to be
44. this method builds a response APDU as described in that section When called with an INVOKE command with the format described in Section 8 4 2 INVOKE Command on page 8 15 this method must call the specified remote method of the identified remote object with the specified parameters It must catch all exceptions thrown by the remote method When an exception is caught or the remote method returns this method must build a response APDU in the format described in Section 8 4 2 INVOKE Command on page 8 15 Prior to invoking the remote method the following errors must be detected and must result in an error response in the format described in Section 8 3 5 3 Error Response Encoding on page 8 12 m The remote object identifier is not valid m The remote object identifier was not returned during the current selection session m The method identifier does not match any remote methods in the remote class associated with the identified remote object m The length of the INVOKE message is inconsistent with the signature of the remote method m There is insufficient space to allocate array parameters for the remote method The implementation must support at least eight input parameters of type array In addition upon return from the remote method the following errors must be detected and must result in an error response in the format described in Section 8 3 5 3 Error Response Encoding on page 8 12 Chapter 8 Remote
45. 0 Classic Edition e March 2008 4 1 1 4 1 2 interface if any is therefore the default applet instance for logical channel 0 on the contacted interface Similarly the default card applet instance for the contactless interface if any is therefore the default applet instance for logical channel 0 on the contactless interface A card that supports both I O interfaces could designate the same applet instance or a different applet instance as the default card applet instance for each interface Card Reset Behavior The following describes card reset behavior 1 After card reset or power on which is a form of reset on the contacted I O interface the Java Card RE performs its initialization and checks to see if its internal state indicates that a particular applet instance is the default applet instance for the basic logical channel If so the Java Card RE makes this applet instance the currently selected applet instance on the basic logical channel and the applet s select method is called If this method throws an exception or returns false the Java Card RE sets its state to indicate that no applet is active on the basic logical channel When a default card applet instance becomes active upon card reset it shall not require its process method to be called The applet instance s process method is not called during default applet selection because there is no SELECT FILE APDU 2 The Java Card RE ensures that the Answer to Reset
46. 0 Classic Edition e March 2008 4 6 1 MANAGE CHANNEL CLOSE Command Upon receiving a MANAGE CHANNEL CLOSE command on an I O interface the Java Card RE shall run the following procedure 1 4 7 The MANAGE CHANNEL CLOSE command uses CLA b000000cc where cc in the bits b2 b1 denotes the origin logical channel 0 3 or CLA 0100dddd where dddd in the bits b4 b1 denote the origin logical channel 4 19 INS 0x70 P1 0x80 and P2 specifies the logical channel to be closed If the MANAGE CHANNEL CLOSE command has non zero secure messaging bits b4 b3 in the CLA byte when the origin logical channel is 0 3 or non zero bit b6 when the origin logical channel is 4 19 the Java Card RE responds with status code 0x6882 SW_SECURE_MESSAGING_NOT_SUPPORTED If the MANAGE CHANNEL command is issued with P1 not equal 0 or 0x80 the Java Card RE responds with status code 0x6A81 SW_FUNC_NOT_SUPPORTED If the origin logical channel on the I O interface that received the MANAGE CHANNEL CLOSE command is not open the Java Card RE responds with status code 0x6881 SW_LOGICAL_CHANNEL_NOT_SUPPORTED If the Java Card RE supports only the basic logical channel on the I O interface that received the MANAGE CHANNEL CLOSE command the Java Card RE responds with status code 0x6881 SW_LOGICAL_CHANNEL_NOT_SUPPORTED If the specified logical channel to close is the basic logical channel logical channel 0 or the specified lo
47. 10 avacardx crypto Cipher 12 11 12 12 avacardx external ExternalExeption 12 14 avacardx external Memory 12 14 javacardx framework tlv BERTag 12 14 javacardx framework tlv TLVException 12 15 javacardx framework util UtilException 12 15 commands APDU 4 9 APDU formats 8 13 INVOKE 8 15 MANAGE CHANNEL CLOSE 4 18 MANAGE CHANNEL OPEN 4 13 MANAGE CHANNEL processing 4 12 processing 4 19 SELECT FILE 4 15 8 13 commit capacity 7 5 component 5 1 constant pool Glossary 3 constants API javacard framework APDU 12 1 javacard framework APDUException 12 2 javacard framework ISO7816 12 2 javacard framework JCSystem 12 4 javacard framework PINException 12 4 javacard framework service Dispatcher 12 5 javacard framework service RMIService 12 5 javacard framework service ServiceException 12 5 javacard framework SystemException 12 4 javacard framework TransactionException 1 2 4 javacard security Checksum 12 6 javacard security CryptoException 12 6 javacard security KeyAgreement 12 6 javacard security KeyBuilder 12 6 javacard security KeyPair 12 9 javacard security MessageDigest 12 9 javacard security RandomData 12 10 javacard security Signature 12 10 javacardx crypto Cipher 12 11 12 12 javacardx external ExternalExeption 12 14 javacardx external Memory 12 14 javacardx framework math BigNumber 12 14 javacardx framework tlv BERTag 12 14 javacardx framework tlv TLVException 12 15 javacardx framework util UtilE
48. 20 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 7 Transactions and Atomicity A transaction is a logical set of updates of persistent data For example transferring some amount of money from one account to another is a banking transaction It is important for transactions to be atomic Either all of the data fields are updated or none are The Java Card RE provides robust support for atomic transactions so that card data is restored to its original pre transaction state if the transaction does not complete normally This mechanism protects against events such as power loss in the middle of a transaction and against program errors that might cause data corruption should all steps of a transaction not complete normally 7 1 Atomicity Atomicity defines how the card handles the contents of persistent storage after a stop failure or fatal exception during an update of a single object or class field or array component If power is lost during the update the applet developer shall be able to rely on what the field or array component contains when power is restored The Java Card platform guarantees that any update to a single persistent object or class field will be atomic In addition the Java Card platform provides single component level atomicity for persistent arrays That is if the smart card loses power during the update of a data element field in an object class or compon
49. 4 global arrays 6 9 7 5 H heap Glossary 4 l I O interface 4 1 install method 3 1 installation 3 1 applet 11 1 parameters 11 6 installation program Glossary 4 installer 11 2 Glossary 4 instance variables Glossary 5 instantiation Glossary 5 instruction Glossary 5 interfaces accessing shareable 6 19 accessing shareable methods 6 18 accessing standard 6 19 accessing standard methods 6 17 javacard framework ISO7816 12 2 shareable 6 11 6 13 interfaces contact and contactless 4 1 internally visible Glossary 5 INVOKE command 8 15 isolation 6 1 Index 3 J JAR file Glossary 5 Java Archive file Glossary 5 Java Card applet 3 1 Java Card RE cleanup 7 4 entry point objects 6 8 Glossary 5 privileges 6 10 Java Card RE entry point objects Glossary 5 Java Card Remote Method Invocation RMI Service 8 1 Java Card RMI 8 1 messages 8 3 Java Development Kit Glossary 6 Java virtual machine 2 1 javacard framework APDU class 12 1 javacard framework APDUException class 12 2 javacard framework ISO7816 interface 12 2 javacard framework JCSystem 12 4 A avacard framework PINException class 12 4 javacard framework service Dispatcher class 12 5 javacard framework service RMIService class 12 5 avacard framework service ServiceException class 12 5 javacard framework SystemException class 12 4 javacard framework TransactionException class 12 4 javacard security Checksum class 12 6
50. DU commands to direct their Applet Deletion Manager in its work The model is that the Applet Deletion Manager on the card is initiated by an applet deletion program running on the CAD In order for applet deletion to succeed this CAD applet deletion program shall be able to do the following m Recognize the card m SELECT FILE the Applet Deletion Manager on the card Coordinate the applet deletion process by sending the appropriate APDUs to the card Applet Deletion Manager These APDUs include the following a Authentication information to ensure that the applet deletion is authorized a Identify the applet s code or instance to be deleted from the card s memory The Application Programming Interface Java Card Platform Version 2 2 2 does not specify the details of the CAD applet deletion program nor the APDUs passed between it and the Applet Deletion Manager 11 3 4 Applet Deletion Manager Behavior Java Card RE implementers shall also define other behaviors of their Applet Deletion Manager including the following m Whether or not applet deletion can be aborted and how this is done a What happens if an exception reset or power fail occurs during applet deletion m What happens if another applet is selected before the Applet Deletion Manager is finished with its work The following three categories of applet deletion are required on the card a Applet instance deletion involves the removal of the applet object instance and
51. ES_MAC4_ 1S09797_M2 tatic final byte ALG_DES_MAC8_1IS09797_M2 ll fo public n tatic final byte ALG_DES_MAC4_ PKCS5 Il N public n tatic final byte ALG_DES_MAC8_PKCS5 ll ee public n public static final byte ALG_RSA_SHA_IS0O9796 9 n tatic final byte ALG_RSA_SHA_PKCS1 Il bh io public n public static final byte ALG_RSA_MD5_PKCS1 11 n n public static final byte ALG_RSA_RIPEMD160_IS09796 12 public static final byte ALG_RSA_RIPEMD160_PKCS1 13 n public static final byte ALG_DSA_SHA 14 n public static final byte ALG_RSA_SHA RFC2409 15 n n public static final byte ALG_RSA_MD5_RFC2409 16 public static final byte ALG_ECDSA_SHA 17 n public static final byte ALG_AES MAC 128 NOPAD 18 n public static final byte ALG_DES_MAC4_ 1S09797_1_M2 ALG3 n public static final byte ALG_DES_MAC8_1S09797_1_M2 ALG3 n public static final byte ALG_RSA_SHA PKCS1_ PSS 21 n 12 10 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ 12 19 lic ic lic lic ic lic ic lic lic iG Lie lic ic lic ie lic lic sta sta sta sta sta sta sta sta sta sta sta sta sta st
52. Installer will need to do the following tasks m Read and write directly to memory bypassing the object system and or standard security m Access objects owned by other applets or by the Java Card RE m Invoke non entry point methods of the Java Card RE m Be able to invoke the install method of a newly installed applet Again it is up to each Java Card RE implementer to determine the Installer implementation and supply such features in their Java Card RE implementations as necessary to support their Installer Java Card RE implementers are also responsible for the security of such features so that they are not available to normal applets 11 2 The Newly Installed Applet A single interface exists between the Installer and the applet that is being installed After the Installer correctly prepares the applet for execution performed steps such as loading and linking the Installer shall invoke the applet s instal1 method This method is defined in the Applet class The precise mechanism by which an applet s install byte short byte method is invoked from the Installer is a Java Card RE implementer defined implementation detail However there shall be a context switch so that any context related operations performed by the install method such as creating new objects are done in the context of the new applet and not in the context of the Installer The Installer shall also ensure that array objects created in the class in
53. JCSystem commitTransaction all conditionally updated fields or array components are restored to their previous values If the applet encounters an internal problem or decides to cancel the transaction it can programmatically undo conditional updates by calling JcSystem abortTransaction T Transaction Duration A transaction always ends when the Java Card RE regains programmatic control upon return from the applet s select deselect process uninstall or install methods This is true whether a transaction ends normally with an applet s call to commitTransaction or with an abortion of the transaction either programmatically by the applet or by default by the Java Card RE For more details on transaction abortion refer to Section 7 6 Aborting a Transaction on page 7 3 Transaction duration is the life of a transaction between the call to JCcSystem beginTransaction and either a call to commitTransaction or an abortion of the transaction 7 4 Nested Transactions The model currently assumes that nested transactions are not possible There can be only one transaction in progress at a time If JCSystem beginTransaction is called while a transaction is already in progress a TransactionException is thrown 7 2 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 The JCSystem getTransactionDepth method is provided to allow you to determine if a transaction is in progress 7 5 T
54. Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER O Java Card Applet Lifetime For the purposes of this specification applet refers to an applet written for the Java Card platform An applet instance s lifetime begins when it is successfully registered with the Java Card RE via the Applet register method Applets registered with the Applet register method exist until deleted by the Applet Deletion Manager Section 11 3 The Applet Deletion Manager on page 11 7 The Java Card RE initiates interactions with the applet via the applet s public methods install select deselect and process An applet shall implement the static install byte short byte method If the install byte short byte method is not implemented the applet s objects cannot be created or initialized A Java Card RE implementation shall call an applet s install select deselect and process methods as described below When the applet is installed on the smart card the static install byte short byte method is called once by the Java Card RE for each applet instance created The Java Card RE shall not call the applet s constructor directly 2l install Method When the install byte short byte method is called the applet instance does not yet exist The main task of the install method within the applet is to create an instance of the Applet subclass using its constructor and to register the instance All other ob
55. Method Invocation Service 8 17 8 18 a There is insufficient space to allocate the array response from the remote method The implementation must support an APDU buffer of at least 133 bytes m A remote object is being returned and its associated remote object identifier was not previously returned during the current selection session and there is insufficient space to add the remote object identifier to the session remote object identifier list The implementation must support at least eight remote object identifiers during a selection session In addition the object access firewall rules must be enforced in a manner similar to that of the invokevirtual instruction Section 6 2 8 4 Accessing Class Instance Object Methods on page 6 17 by this method when a remote method is invoked Only methods of a remote object owned by the context of the currently selected applet may be invoked Allocation of Incoming Objects Because array parameters to remote methods are transmitted by value array objects need to be allocated on the card when a remote method with array arguments is invoked via the INVOKE command Global array objects Section 6 2 2 Global Arrays on page 6 9 must be used for incoming remote method arguments Global arrays have the following properties m They are owned by the Java Card RE but they can be freely accessed from all contexts m They are temporary objects and cannot be stored in any object m They are n
56. OCOL_MEDIA_MASK byte 0xF0 public static final byte PROTOCOL_MEDIA_DEFAULT byte 0x00 public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A byte 0x80 public static final byte PROTOCOL_MEDIA CONTACTLESS_TYPI byte 0x90 tj w Il public static final byte PROTOCOL_MEDIA_USB byte 0xA0 public static final byte STATE_INITIAL 0 public static final byte STATE_PARTIAL_INCOMING 1 public static final byte STATE_FULL_INCOMING 2 public static final byte STATE_OUTGOING 3 12 1 publ publ publ publ publ publ publ 12 2 12 3 12 2 lic ic lic lic ic lic ic tatic tatic tatic tatic tatic tatic tatic final final final final final final final byt byt byt byt byt byt byt STATE_OUTGOING_LENGTH_KNOWN STATE_PARTIAL OUTGOING 5 STATE_FULL_OUTGOING 6 4 GETRES PONS STATE_ERROR_NO_T0O_ le byte 1 STATE_ERROR_T1_IFD_ABORT STATE_ERROR_IO byte 3 T STATE_ERROR_NO_TO_REISSUE byte 2 byte 4 Class javacard framework APDUException publ publ publ publ publ publ ic lic lic ic lic ic publ lic static static tatic tatic tatic tatic tatic final final final final final final final short S Nort nort
57. PATCH_TABLE_FULL 2 COMMAND_DATA_TOO_LONG 3 CANNOT_ACCESS_IN_COMMAND 4 CANNOT_ACCESS_OUT_COMMAND 5 COMMAND_IS_ R 1K FINISHED 6 MOTE_OBJECT_NOT_EXPORTED 7 Chapter 12 API Constants 12 5 12 11 Class javacard security Checksum public static final byte ALG_1IS03309_CRC16 ie public static final byte ALG_1IS03309_CRC32 2 12 12 Class javacard security CryptoException public static final short ILLEGAL_VALUE 1 public static final short UNINITIALIZED _KEY 2 public static final short NO_SUCH_ALGORITHM 3 public static final short INVALID_INIT 4 public static final short ILLEGAL_USE 5 12 13 Class javacard security KeyAgreement public static final byte ALG_EC_SVDP_DH 1 public static final byte ALG_EC_SVDP_DH_KDF 1 public static final byte ALG_EC_SVDP_DHC 2 public static final byte ALG_EC_SVDP_DHC_KDF 2 public static final byte ALG_EC_SVDP_DH_PLAIN 3 public static final byte ALG_EC_SVDP_DHC_PLAIN 4 12 14 Class javacard security KeyBuilder public static final byte TYPE _DES TRANSIENT RESET 1 public static final byte TYPE_DES_ TRANSIENT _DESELECT 2 public static final byte TYPE_DES 3 public static final byte TYPE_RSA_PUBLIC 4 12 6 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 public static
58. Point Objects Like all Java Card RE Entry Point Objects methods of temporary Java Card RE Entry Point Objects can be invoked from any context However references to these objects cannot be stored in class variables instance variables or array components The Java Card RE detects and restricts attempts to store references to these objects as part of the firewall functionality to prevent unauthorized reuse The APDU object and all Java Card RE owned exception objects are examples of temporary Java Card RE Entry Point Objects Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 2 m Permanent Java Card RE Entry Point Objects Like all Java Card RE Entry Point Objects methods of permanent Java Card RE Entry Point Objects can be invoked from any context Additionally references to these objects can be stored and freely re used Java Card RE owned AID instances are examples of permanent Java Card RE Entry Point Objects The Java Card RE is responsible for the following tasks m Determining what privileged services are provided to applets m Defining classes containing the entry point methods for those services m Creating one or more object instances of those classes m Designating those instances as Java Card RE Entry Point Objects m Designating Java Card RE Entry Point Objects as temporary or permanent m Making references to those objects available to applets as needed Note Only the me
59. RSA ly ALG_RSA_CRT ALG_DSA ALG_EC_F2M ALG_EC_FP BY 2 4 Class javacard security MessageDigest publ publ publ publ publ publ publ publ publ publ publ publ ic ic IG ic iG T ic ic ic ic ic ic sta sta sta sta sta sta sta sta sta sta sta sta tic tic tic tic tic tic tic tic tic tic tic tic final final final final final final final final final final final final by by by byt byt byt byt byt byt byt byt byt Ce Ce ce ALG_S ALG_MI ALG_RIPI ALG_S ALG_S ALG_S HA D5 H_S H_M HA D5 t 2 EMD160 A_256 A_384 A_512 RIPEMD1 HA_256 HA_384 HA 512 35 Il iN ll ol byte byte byte 20 16 byte 20 32 48 64 Chapter 12 API Constants 12 9 12 17 Class javacard security RandomData public static final byte ALG_PSEUDO_RANDOM 1 public static final byte ALG_SECURE_RANDOM 2 12 18 Class javacard security Signature public static final byte ALG_DES_MAC4 NOPAD 1 Gl public static final byte ALG_DES_MAC8_ NOPAD 2 tatic final byte ALG_D Gl S_MAC4_1S09797_M1 Il Ww public n tatic final byte ALG_DES_MAC8_IS09797_M1 I e public n n Il ul public static final byte ALG_D
60. Segments In both cases of multiselection the applets must implement the MultiSelectable interface If the applets do not support this feature the selection must be rejected by the Java Card RE 4 3 Forwarding APDU Commands To a Logical Channel According to Section 5 4 of the ISO 7816 4 2005 Specification the interindustry values of the CLA byte equal to 0x0X and 0x1X in the APDU command encode channel numbers in the range 0 3 whereas interindustry values of the CLA byte equal to Ox4Y Ox5Y Ox6Y and 0x7Y in the APDU command encode channel numbers in the range 4 19 In addition cards compliant with Java Card platform specification v 3 0 must also support proprietary class values of the CLA byte equal to 0x8X 0x9X OxAx and OxBX for channel numbers in the range 0 3 and proprietary class values of the CLA byte equal to 0xCY OxDY 0xEY and OxFY for channel numbers 4 19 using 0 origin notation The bit encoding of the proprietary class values of the CLA byte mirror that of the ISO 7816 4 2005 Specification defined interindustry values with the most significant bit b8 set to 1 TABLE 4 1 and TABLE 4 2 show the supported encodings of the CLA byte Chapter 4 Logical Channels and Applet Selection 4 9 The two least significant bits b2 b1 of the X nibble encodes the logical channels numbers 0 3 whereas the Y nibble b4 b1 encodes logical channel numbers in the range 4 19 using 0 origin notation When an APDU command is received t
61. Table The corollary to this requirement is that Applet Deletion Manager component shall not be able to be invoked on a logical channel where a non Applet Deletion Manager applet is an active applet instance nor when no applet is active A Java Card RE implementer could choose to implement the Applet Deletion Manager as an applet If so the Applet Deletion Manager might be coded to extend the Applet class and to respond to invocations of the select process and deselect methods and if necessary the methods of the javacard framework MultiSelectable interface However a Java Card RE implementer could also implement the Applet Deletion Manager in other ways as long as it provides the SELECTable behavior to the outside world In this case the Java Card RE implementer has the freedom to provide some other mechanism by which APDUs are delivered to the Applet Deletion Manager code module Chapter 11 Applet Installation and Deletion 11 7 11 3 2 Applet Deletion Manager AID Because the Applet Deletion Manager is SELECTable it shall have an AID which may be the same as that of the Applet Installer Java Card RE implementers are free to choose their own AIDs by which their Applet Deletion Manager is selected Multiple Applet Deletion Managers may be implemented 11 3 3 Applet Deletion Manager APDUs The Java Card API does not specify any APDUs for the Applet Deletion Manager Java Card RE implementers are entirely free to choose their own AP
62. _TRANSIENT_DESELECT 27 public static final byte TYPE_EC_F2M PRIVATE _TRANSIENT_RESET 28 public static final byte TYPE_EC_FP_PRIVATE_TRANSIENT_RESET 30 public static final byte TYPE_EC_FP_PRIVATE_TRANSIENT_DESELECT 31 public static final short LENGTH_DES 64 public static final short LENGTH_DES3_2KEY 128 public static final short LENGTH_DES3_3KEY 192 Chapter 12 API Constants 12 7 12 8 publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ publ pub Lic ic Lic Lic ic Lic ic lic lic ic lic lic ic lic ic lic lic ic lic ic lic lic ic lic ic lic lic publ IG static static static static static static static static static static static static static static static static static static static static static static static static static static static static final final final final final final final final final final final final final final final final final final final final final final final final final final final final nore nore nore nore
63. a sta sta sta tic tic tic tic tic tic tic tic tic tic tic tic tic tic tic tic tic final final final final final final final final final final final final final final final final final byt byt byt byt byt byt byt byt byt byt byt byt byt byt byt byt byt Class javacardx publ publ publ publ publ publ publ publ publ ic Lic Lic LG Lie T Lic lic ic sta sta sta sta sta sta sta sta sta tic tic tic tic tic tic tic tic tic final final final final final final final final final by by byt byt byt byt byt byt byt Ce Ce ALG_RSA_MD5_PKCS1_PSS 22 ALG _RSA_RIPEMD160_PKCS1_PSS 23 ALG _HMAC_SHA1 24 ALG_HMAC_SHA_256 25 ALG_HMAC_SHA_384 26 ALG _HMAC_SHA_512 24S ALG_HMAC_MD5 28 ALG _HMAC_RIPEMD160 29 ALG_RSA_SHA_IS09796_MR 30 ALG _RSA_RIPEMD160_IS09796_MR 31 ALG _KOREAN_SEED_MAC_NOPAD 32 ALG_ECDSA_SHA_256 33 ALG_ECDSA_SHA_384 34 ALG_AES_MAC_192_NOPAD 35 ALG_AES_MAC_256_NOPAD 36 MODE_SIGN 1 MODE_VERIFY 2 biometry BioBuilder FACIAL FEATURE byte 1 VOICE_PRINT byte 2 FINGERPRINT byte 3 IRIS_SCAN byte 4 RETINA_SCAN by
64. a server applet For this to work there must be a way for the client applet to obtain the SIO from the server applet in the first place The Java Card RE provides a mechanism to make this possible The Applet class and the JcSystem class provide methods to enable a client to request services from the server Applet getShareableInterfaceObject AID byte Method This method is implemented by the server applet instance It shall be called by the Java Card RE to mediate between a client applet that requests to use an object belonging to another applet and the server applet that makes its objects available for sharing The default behavior shall return nu11 which indicates that an applet does not participate in inter applet communication A server applet that is intended to be invoked from another applet needs to override this method This method should examine the clientAID and the parameter If the clientAID is not one of the expected AIDs the method should return nu11 Similarly if the parameter is not recognized or if it is not allowed for the clientAID the method also should return null Otherwise the applet should return an SIO of the shareable interface type that the client has requested Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 7 2 The server applet need not respond with the same SIO to all clients The server can support multiple types of shared interfaces for different pur
65. a whole the set of classes that implement the API This includes core and extension packages Responsibilities include applet selection sending APDU bytes and managing atomicity the process by which dynamically allocated storage is automatically reclaimed during the execution of a program a common pool of free memory usable by a program A part of the computer s memory used for dynamic memory allocation in which blocks of memory are used in an arbitrary order The Java Card virtual machine s heap is not required to be garbage collected Objects allocated from the heap are not necessarily reclaimed the on card mechanism to download and install CAP files The installer receives executable binary from the off card installation program writes the binary into the smart card memory links it with the other classes on the card and creates and initializes any data structures used internally by the Java Card Runtime Environment the off card mechanism that employs a card acceptance device CAD to transmit the executable binary in a CAP file to the installer running on the card Glossary 4 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 instance variables instantiation instruction internally visible JAR file Java Card Platform Remote Method Invocation Java Card Runtime Environment Java Card RE Java Card Virtual Machine Java Card VM Java Card RE entry point objects
66. acard security Signature javacard security RandomData javacard security KeyAgreement javacard security Checksum javacardx crypto Cipher An implementation of the Java Card RE may implement zero or more of the algorithms listed in the Application Programming Interface Java Card Platform Version 2 2 2 When an algorithm that is not implemented is requested this method shall throw a CryptoException with reason code NO_SUCH_ALGORITHM Implementations of the above classes shall extend the corresponding base class and implement all the abstract methods All data allocation associated with the implementation instance shall be performed at the time of instance construction to ensure that any lack of required resources can be flagged early during the installation of the applet Similarly the buildKey method of the javacard security KeyBuilder class returns an implementation instance of the requested Key type The Java Card RE may implement zero or more types of keys When a key type that is not implemented is requested the method shall throw a CryptoException with reason code NO_SUCH_ALGORITHM In the same fashion the constructor for the javacard security KeyPair class creates a KeyPair instance for the specified key type The Java Card RE may implement zero or more types of keys When a key type that is not implemented is requested the method shall throw a CryptoException with reason code NO_SUCH_ALGORITHM Implementations of key types shall im
67. ackage that depends on the package continues to function unaffected The functionality of all applets on the card remains the same as prior to the unsuccessful attempt Following a successful deletion of the applet package and contained instances it shall not be possible to install another package that depends on the deleted package Additionally it shall be possible to reinstall the same package with exactly the same package AID or an upgraded version of the deleted package onto the card The resources used by the applet package may be recovered for reuse 11 12 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 11 3 5 Following a successful deletion of the applet package and contained instances it shall not be possible to select any of the deleted applets and no object owned by the deleted applets can be accessed by any applet currently on the card or by a new applet created in the future The resources used by the applet instances may be recovered for reuse The AID for the deleted applet instances may be reassigned to new applet instances Applet Deletion Manager Privileges Although an Applet Deletion Manager may be implemented as an applet an Applet Deletion Manager typically requires access to features that are not available to other applets For example depending on the Java Card RE implementer s implementation the Applet Deletion Manager needs to do the following m Read and wri
68. acted interface calls the Applet select method If multiselection is required for selecting the default applet but the default applet does not implement the MultiSelectable interface or if the select method throws an exception or returns false the Java Card RE sets its state to indicate that no applet is active on the basic logical channel on the contactless I O interface When a default card applet instance becomes active after the successful completion of the PICC activation sequence on the contactless interface it shall not require its process method to be called The applet instance s process method is not called during default applet selection because there is no SELECT FILE APDU 2 The Java Card RE ensures that the Answer to Select ATS if applicable was sent and the card is now ready to accept APDU commands Default Applet Selection Behavior on Opening a New Channel The following default applet selection behavior occurs on opening a new logical channel When a MANAGE CHANNEL command is issued on the basic logical channel and a new logical channel is opened the Java Card RE checks if there is a designated default applet instance for the newly opened logical channel If so the Java Card RE makes this applet instance the currently selected applet instance on the new logical channel and the applet s select method MultiSelectable select method if required is called If this method throws an exception or returns false then th
69. also known as non static fields in object oriented programming to produce a particular object from its class template This involves allocation of a data structure with the types specified by the template and initialization of instance variables with either default values or those provided by the class s constructor function a statement that indicates an operation for the computer to perform and any data to be used in performing the operation An instruction can be in machine language or a programming language items that are not externally visible These items are not described in a package s export file but some such items use private tokens to represent internal references See also externally visible an acronym for Java Archive file which is a file format used for aggregating many files into one a subset of the Java Platform Remote Method Invocation RMI system It provides a mechanism for a client application running on the CAD platform to invoke a method on a remote object on the card consists of the Java Card virtual machine the framework and the associated native methods a subset of the Java virtual machine which is designed to be run on smart cards and other resource constrained devices The Java Card VM acts an engine that loads Java class files and executes them with a particular set of semantics objects owned by the Java Card RE context that contain entry point methods These methods can be invoked from any
70. an binary compatibility bytecode CAD CAP file CAP file component Glossary 2 card session cast an operation that either completes in its entirety or no part of the operation completes at all state in which a particular operation is atomic Atomicity of data updates guarantee that data are not corrupted in case of power loss or card removal an acronym for Answer to Reset An ATR is a string of bytes sent by the Java Card platform after a reset condition logical channel 0 the only channel that is active at card reset This channel is permanent and can never be closed a technique of storing multibyte data where the high order bytes come first For example given an 8 bit data item stored in big endian order the first bit read is considered the high bit in a Java Card system a change in a Java programming language package results in a new CAP file A new CAP file is binary compatible with equivalently does not break compatibility with a preexisting CAP file if another CAP file converted using the export file of the preexisting CAP file can link with the new CAP file without errors machine independent code generated by the compiler and executed by the Java virtual machine an acronym for Card Acceptance Device The CAD is the device in which the card is inserted the CAP file is produced by the Converter and is the standard file format for the binary compatibility of the Java Card platform A CAP file conta
71. ance as the currently selected applet instance and call the Applet select method A context switch into the candidate applet instance s context occurs at this point If the applet instance s select method throws an exception or returns false then the Java Card RE closes the new logical channel The Java Card RE responds with status code 0x6999 SW_APPLET_SELECT_FAILED The Java Card RE responds with status code 0x9000 and if the P2 0 variant is used 1 data byte containing the newly assigned logical channel number Note Unlike the SELECT FILE commands to select an applet instance the MANAGE CHANNEL command is never forwarded to the applet instance Applet Selection with SELECT FILE Upon receiving a SELECT FILE command on an I O interface the Java Card RE shall run the following procedure Chapter 4 Logical Channels and Applet Selection 4 15 4 16 The Applet SELECT FILE command uses CLA b000000cc where cc in the bits b2 b1 specifies the logical channel to be selected 0 3 or CLA 0100dddd where dddd in the bits b4 b1 denote the origin logical channel 4 19 and INS OxA4 If the SELECT FILE command has non zero secure messaging bits b4 b3 in the CLA byte when the origin logical channel is 0 3 or non zero bit b6 when the origin logical channel is 4 19 it is deemed not to be an Applet SELECT FILE command The Java Card RE simply forwards the command to the active applet on the specified
72. ared objects Any object that needs to be shared through the applet firewall shall directly or indirectly implement this interface Only those methods specified in a shareable interface are available through the firewall Implementation classes can implement any number of shareable interfaces and can extend other shareable implementation classes Chapter6 Applet Isolation and Object Sharing 6 13 6 2 7 6 2 7 1 6 14 Like any Java platform interface a shareable interface simply defines a set of service methods A service provider class declares that it implements the shareable interface and provides implementations for each of the service methods of the interface A service client class accesses the services by obtaining an object reference casting it to the shareable interface type and invoking the service methods of the interface The shareable interfaces within the Java Card technology shall have the following properties m When a method in a shareable interface is invoked a context switch occurs to the context of the object s owner m When the method exits the context of the caller is restored a Exception handling is enhanced so that the currently active context is correctly restored during the stack frame unwinding that occurs as an exception is thrown Obtaining Shareable Interface Objects Inter applet communication is accomplished when a client applet invokes a shareable interface method of a SIO belonging to
73. ary 8 identifier 8 5 reference descriptor 8 5 Reserved for Future Use Glossary 8 reset 3 4 7 3 card behavior 4 5 return value encoding 8 10 RFU Glossary 8 RI Glossary 7 RID Glossary 8 RMI 8 1 Glossary 5 Glossary 8 RMIService class 8 1 8 16 ROM Glossary 8 runtime environment Glossary 8 S security packages 9 9 violations 10 1 security packages 9 9 SELECT FILE 4 15 SELECT FILE command 8 13 select method 3 2 selected applet 4 3 selection 3 2 applet 4 13 8 3 shareable interface Glossary 8 shareable interface object Glossary 8 Shareable Interface Objects SIOs 6 7 shareable interfaces 6 11 SIO Glossary 8 SIOs 6 7 6 11 obtaining 6 14 smart card Glossary 8 static accessing class fields 6 16 Index 5 fields 6 7 methods 6 7 T tear 7 3 terminal Glossary 8 thread Glossary 8 transaction Glossary 8 transactions 7 1 aborting 7 3 duration 7 2 failure 7 3 nested 7 2 within the API 9 2 transient keyword 5 1 transient object 5 1 7 5 Glossary 9 U uninstall method for applets 11 9 V verification Glossary 9 virtual machine 10 1 resource failures 10 1 security violations 10 1 W word Glossary 9 Index 6 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008
74. ason code is transmitted to the client application In essence the exception object is transmitted by value a When an exception not defined in the Java Card API is thrown by a remote method the closest superclass exception type from the API and the embedded reason code is transmitted to the client application In this case the closest API defined superclass exception object is transmitted by value The client application can distinguish an inexact exception from an exact one Functional Limitations The definition of the supported subset of Java Card RMI for the Java Card Platform Version 3 0 implies functional limitations during the execution of Java Card API remote methods Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 a CAD client application remote objects cannot be passed as arguments to remote methods m Card remote objects cannot be passed as arguments to remote methods m Applets on the card cannot invoke remote methods on the CAD client m Method argument data and return values along with the Java Card RMI protocol overhead must fit within the size constraints of an APDU command and APDU response respectively 8 2 8 2 1 RMI Messages The Java Card RMI message protocol consists of two commands that are used to m Get the initial remote object reference for the Java Card RMI based applet The initial remote object reference is the seed remote object that t
75. at used in the Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 8 3 1 8 3 2 Remote Object Identifier A remote object identifier is a 16 bit unsigned number that uniquely identifies a remote object on the card Remote Object Reference Descriptor The remote object reference descriptor includes the remote object identifier as well as information to instantiate the proxy class on the CAD client The remote object reference descriptor uses one of two alternate formats The representation based on the name of the class uses the remote_ref_with_class format The representation based on the names of the implemented remote interfaces uses the remote_ref_with_interfaces format A remote object reference descriptor is therefore defined as follows remote_ref_descriptor union ref_null remote_ref_null remote_ref_with_class remote_ref_c remote_ref_with_interfaces remote_ref_i Note Even though this structure uses the C like union notation the lengths of the alternate representations within the union do not use any padding to normalize their lengths The following items are in the remote_ref_descriptor structure ref_nul1 is the representation of a null reference using the following format ref _null u2 remote_ref_id OxFFFF The remote_ref_id item must be the reserve
76. ated with it When a new object is created it is associated with the currently active context but the object is owned by the applet instance within the currently active context when the object is instantiated An object can be owned by an applet instance or by the Java Card RE Following are the combined rules of context and object ownership within the firewall m Every applet instance belongs to a context All applet instances from the same package belong to the same context m Every object is owned by an applet instance or the Java Card RE An applet instance is identified by its AID When executing in an instance method of an object or a static class method called from within the object s owner must be in the currently active context Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 For example assume that applets A and B are in the same package and applet C is in another package A and B therefore belong to the same context 1 C belongs to a different context 2 For an illustration of this situation see FIGURE 6 2 If context 1 is the currently active context and a method m1 in an object owned by applet A is invoked no context switch occurs If method m1 invokes a method m2 in an object owned by applet B again no context switch occurs in spite of the object owner change and no firewall restrictions apply However if the method m2 now calls a method m0 in an object owned
77. avior on page 6 16 are met during the execution of invoke type bytecodes For example a context switch may be caused by an attempt to access a shareable object that belongs to an applet instance that resides in a different package The result of a context switch is a new currently active context During a context switch the previous context and object owner information is pushed on an internal VM stack a new context becomes the currently active context and the invoked method executes in this new context Upon exit from that method the VM performs a restoring context switch The original context of the caller of the method is popped from the stack and is restored as the currently active context Context switches can be nested The maximum depth depends on the amount of VM stack space available Most method invocations in Java Card technology do not cause a context switch For example a context switch is unnecessary when an attempt is made to access an object that belongs to an applet instance that resides in the same package Context switches only occur during invocation of and return from certain methods as well as during exception exits from those methods see Section 6 2 8 Class and Object Access Behavior on page 6 16 Further details of contexts and context switching are provided in later sections of this chapter Object Ownership Any given object in the Java Card platform s object space has a context and an owner associ
78. by applet C firewall restrictions apply and if access is allowed a context switch shall occur Upon return to method m2 from the method m0 the context of applet B is restored FIGURE 6 2 Context Switching and Object Access applet space context 1 context 2 no context switch Package A Package B applet firewall Keep the following points in mind a When the m1 method in the object owned by applet A calls the method m2 in the object owned by applet B the context does not change but the owner of the object does change If the JCSystem getAID method is called from method m2 within context 1 the AID of applet B is returned a When method m2 calls method m0 in an object owned by applet C applet B is the owner of the object when the context switches from 1 to 2 Therefore if the JCSystem getAID method is called from method m0 within context 2 the AID of applet C shall be returned If the JcSystem getPreviousContextAID method is called the AID of applet B shall be returned Chapter 6 Applet Isolation and Object Sharing 6 5 6 1 4 6 1 5 6 6 m When the JCSystem getAID method is called from method m2 after the return from method m0 in context 2 the AID of applet B is returned However if the JCSystem getPreviousContextAID method is called the AID of the applet which called into context 1 or nu11 if Java Card RE is returned and not the AID of applet C Object Access In general an object can only be acce
79. bytes bArray offset Li 1 length Lc of control info bArray offset Li 2 offset Li Lc 1 control info bArray offset Li Lc 2 length La of applet data bArray offset Li Lc 3 offset Li Lc La 2 applet data Any of the length items Li Lc La may be zero If length Li is non zero the instance AID bytes item is the proposed AID of the applet instance The control info item of the parameter data is implementation dependent and is specified by the Installer Other than the need for the entire parameter data to not be greater than 127 bytes the Java Card API does not specify anything about the contents of the applet data item of the global byte array installation parameter This is fully defined by the applet designer and can be in any format desired In addition the applet data portion is intended to be opaque to the Installer Java Card RE implementers should design their Installers so that it is possible for an installation program running in a CAD to specify the applet data delivered to the Installer The Installer simply forwards this along with the other items in the format defined above to the target applet s install method in the bArray parameter A typical implementation might define a Java Card RE implementer proprietary APDU command that has the semantics call the applet s install method passing the contents of the accompanying applet data 11 6 Runtime Environment Specification Java Card P
80. cation Java Card Platform v3 0 Classic Edition e March 2008 6 1 2 1 FIGURE 6 1 Contexts Within the Java Card Platform s Object System Java Card RE Context applet space context 1 context 2 applet A applet C applet B applet D Package A Package B applet firewall In addition the Java Card RE maintains its own Java Card RE context This context is much like the context of an applet but it has special system privileges so that it can perform operations that are denied to contexts of applets For example access from the Java Card RE context to any applet instance s context is allowed but the converse access from an applet instance s context to the Java Card RE context is prohibited by the firewall Active Contexts in the VM At any point in time there is only one active context within the VM This is called the currently active context This can be either the Java Card RE context or an applet s context All bytecodes that access objects are checked at runtime against the currently active context in order to determine if the access is allowed A java lang SecurityException is thrown when an access is disallowed Chapter 6 Applet Isolation and Object Sharing 6 3 6 1 2 2 6 1 3 6 4 Context Switching in the VM If access is allowed the VM determines if a context switch is required A context switch occurs when certain well defined conditions as described in Section 6 2 8 Class and Object Access Beh
81. ce the point in time when the remote reference was returned a A valid remote object cannot be garbage collected during the lifetime of the remote reference In addition a remote object reference descriptor of an object must only be returned from the card if it is exported See the class javacard framework service CardRemoteObject Otherwise an exception is thrown See the class javacard framework service RMIService 8 16 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 8 5 1 8 5 2 setInvokeInstructionByte Method This method sets the value of invoke_ins described in Section 8 4 1 SELECT FILE Command on page 8 13 which is returned in the response to the SELECT FILE command The change in the Java Card RMI protocol only goes into effect the next time this RMIService instance processes the SELECT FILE command If this method is not called the default instruction byte value DEFAULT_RMI_INVOKE_INSTRUCTION is used processCommand Method The processCommand method of the RMIService class is invoked by the applet to process an incoming RMI message RMIService collaborates with other services by using the common service format CSF in the APDU buffer It processes only the incoming Java Card RMI APDU commands and produces output as described in the previous sections When called with a SELECT FILE command with format described in Section 8 4 1 SELECT FILE Command on page 8 13
82. cessful in the following cases m A reachable non garbage instance of a class belonging to the package being deleted exists on the card m Another package on the card depends on this package as expressed in the CAP file s import component Otherwise if the applet library package is resident in mutable memory the Java Card RE shall delete the applet library package Note The package deletion attempt may fail due to security considerations or resource limitations The applet library package deletion operation must be atomic If a reset or power fail occurs during the deletion process it must result in either an unsuccessful applet library package deletion or a successfully completed applet library package deletion before any applet is selected on the card Following an unsuccessful applet library package deletion any object or package that depends on the package continues to function unaffected The functionality of all applets on the card remains the same as prior to the unsuccessful attempt Chapter 11 Applet Installation and Deletion 11 11 Following a successful applet library package deletion it shall not be possible to install another package which depends on the deleted package Additionally it shall be possible to reinstall the same package with exactly the same package AID or an upgraded version of the deleted package onto the card The resources used by the applet library package may be recovered for reuse
83. context and allow non privileged users applets to request privileged Java Card RE system services Java Card RE entry point objects can be either temporary or permanent temporary references to temporary Java Card RE entry point objects cannot be stored in class variables instance variables or array components The Java Card RE detects and restricts attempts to store references to these objects as part of the firewall functionality to prevent unauthorized reuse Examples of these objects are APDU objects and all Java Card RE owned exception objects permanent references to permanent Java Card RE entry point objects can be stored and freely reused Examples of these objects are Java Card RE owned AID instances Glossary 5 JDK software library package local variable logical channel MAC mask production masking method multiselectable applets multiselected applet namespace native method nibble object oriented Glossary 6 an acronym for Java Development Kit The JDK software is a Sun Microsystems Inc product that provides the environment required for software development in the Java programming language The JDK software is available for a variety of operating systems for example Sun Microsystems Solaris OS and Microsoft Windows a Java programming language package that does not contain any non abstract classes that extend the class javacard framework Applet An applet package contains one or
84. creating objects within the transaction can be deemed to be a programming error When this occurs the Java Card RE may to ensure the security of the card and to avoid heap space loss lock up the card session to force tear or reset processing Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 7 7 Transient Objects and Global Arrays Only updates to persistent objects participate in the transaction Updates to transient objects and global arrays are never undone regardless of whether or not they were inside a transaction 7 8 Commit Capacity Because platform resources are limited the number of bytes of conditionally updated data that can be accumulated during a transaction is limited The Java Card technology provides methods to determine how much commit capacity is available on the implementation The commit capacity represents an upper bound on the number of conditional byte updates available The actual number of conditional byte updates available may be lower due to management overhead A TransactionException is thrown if the commit capacity is exceeded during a transaction 7 9 Context Switching Context switches shall not alter the state of a transaction in progress If a transaction is in progress at the time of a context switch see Section 6 1 2 Contexts and Context Switching on page 6 2 updates to persistent data continue to be conditional in the new context until
85. cted only via a successful SELECT FILE command However some smart card CAD applications require a default card applet instance to become implicitly selected after every card reset In addition some CAD applications may also require a default applet selection when a new logical channel is opened In a similar manner some smart card proximity coupling device PCD applications require a default card applet instance to become implicitly selected after the proximity card PICC activation sequence successfully completes In addition default applet selection may also be required on each new logical channel opened during the contactless session The Java Card platform allows the card implementer to designate a default applet instance for each of the logical channels supported by the card For any logical channel the card implementation may designate an applet instance as the default applet instance for that logical channel Alternatively for any logical channel the implementation may choose to designate no default applet instance at all Logical channels may share the same applet instance as the default applet instance for more than one channel Upon card reset on the contacted interface and upon the completion of the PICC activation sequence on the contactless interface only the basic logical channel channel 0 is automatically opened The default card applet instance for the contacted Runtime Environment Specification Java Card Platform v3
86. d The framework objects created by the Java Card RE exist for the lifetime of the virtual machine Because the execution lifetime of the virtual machine and the Java Card RE framework span Card Acceptance Device CAD or card reader sessions of the card the lifetimes of objects created by applets also span CAD sessions Objects that have this property are called persistent objects Card sessions are those periods when the card is inserted into the CAD powered up and exchanging streams of APDUs with the CAD The card session ends when the card is removed from the CAD 1 The terms Java Virtual Machine and JVM mean a Virtual Machine for the Java platform Note The acronym CAD is used here and throughout this specification to refer to both types of card readers the conventional Card Acceptance Device CAD for contacted I O interfaces and the Proximity Coupling Device PCD for contactless interfaces The Java Card RE implementer shall make an object persistent when m The Applet register method is called The Java Card RE stores a reference to the instance of the applet object The Java Card RE implementer shall ensure that instances of class applet are persistent m A reference to an object is stored in a field of any other persistent object or in a class s static field This requirement stems from the need to preserve the integrity of the Java Card RE s internal data structures 2 2 Runtime Environment Specification
87. d P1 0 Two variants of this command are supported m P2 0 when the Java Card RE shall assign a new logical channel number m P2 the logical channel number specified Chapter 4 Logical Channels and Applet Selection 4 13 a Ifthe MANAGE CHANNEL OPEN command has non zero secure messaging bits b4 b3 in the CLA byte when the origin logical channel is 0 3 or non zero bit b6 when the origin logical channel is 4 19 the Java Card RE responds with status code 0x6882 SW_SECURE_MESSAGING_NOT_SUPPORTED a If the MANAGE CHANNEL command is issued with P1 not equal to 0 or 0x80 or if the unsigned value of P2 is greater than 19 the Java Card RE responds with status code 0x6A81 SW_FUNC_NOT_SUPPORTED 2 If the origin logical channel on that I O interface is not open the Java Card RE responds with status code 0x6881 SW_LOGICAL_CHANNEL_NOT_SUPPORTED 3 If the Java Card RE supports only the basic logical channel on that I O interface the Java Card RE responds with status code 0x6881 SW_LOGICAL_CHANNEL_NOT_SUPPORTED 4 If the P2 0 variant is used m If the expected length value Le is not equal to 1 the Java Card RE responds with status code 0x6C01 SW_CORRECT_LENGTH_00 0x01 m If resources for the new logical channel are not available the Java Card RE responds with status code 0x6A81 SW_FUNC_NOT_SUPPORTED 5 If the P2 0 variant is used If the specified logical channel number is not supported or resources
88. d RE but not completely specified in the Application Programming Interface Java Card Platform Version 2 2 2 Chapter 10 Virtual Machine Topics describes virtual machine resource failures and security violations Chapter 11 Applet Installation and Deletion provides an overview of the Applet Installer and Java Card RE required behavior Chapter 12 API Constants provides the numeric value of constants that are not specified in the Application Programming Interface Java Card Platform Version 2 2 2 Glossary provides definitions of selected terms used in the entire Classic Edition Using UNIX Commands This document might not contain information about basic UNIX commands and procedures such as shutting down the system booting the system and configuring devices Refer to the following for this information a Software documentation that you received with your system m Solaris Operating System documentation which is at http docs sun com Preface xvii Shell Prompts Shell Prompt C shell machine name C shell superuser machine name Bourne shell and Korn shell Bourne shell and Korn shell superuser Typographic Conventions Typeface Meaning Examples AaBbCc123 The names of commands files Edit your Login file and directories on screen Use 1s a to list all files computer output You have mail AaBbCc123 What you type when contrasted su with on screen compu
89. d RE state is set so that no applet is active on the specified logical channel The logical channel remains open and the Java Card RE responds with status code 0x6999 SW_APPLET_SELECT_FAILED The Java Card RE shall set the candidate applet instance as the currently selected applet instance and call the Applet process method with the SELECT FILE APDU as the input parameter A context switch occurs into the applet instance s context at this point Upon return from the applet instance s process method the Java Card RE sends the applet instance s response as the response to the SELECT FILE command Chapter 4 Logical Channels and Applet Selection 4 17 Note If the SELECT FILE command does not conform to the exact format of an Applet SELECT FILE command described in item 1 above or if there is no matching AID the SELECT FILE command is forwarded to the active applet instance if any on that logical channel for processing as a normal applet APDU command If there is a matching AID and the SELECT FILE command fails the Java Card RE always sets the state in which no applet is active on that logical channel If the matching AID is the same as the active applet instance on the specified logical channel the Java Card RE still goes through the process of deselecting the applet instance and then selecting it Reselection could fail leaving the card in a state in which no applet is active on that logical channel 4 6 4 18
90. d including CLEAR_ON_DESELECT transient objects owned by the currently selected applet Note The Java Card RE can access both methods and fields of X Method access is the mechanism by which the Java Card RE enters the context of an applet Although the Java Card RE could invoke any method through the firewall it shall only invoke the select process deselect and getShareableInterfaceObject see Section 6 2 7 1 Applet getShareableInterfaceObject AID byte Method on page 6 14 methods defined in the Applet class and methods on the objects passed to the API as parameters The Java Card RE context is the currently active context when the VM begins running after a card reset The Java Card RE context is the root context and is always either the currently active context or the bottom context saved on the stack Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 4 6 2 4 1 6 2 4 2 Shareable Interfaces Shareable interfaces are a feature in the Java Card API to enable applet interaction A shareable interface defines a set of shared interface methods These interface methods can be invoked from one context even if the object implementing them is owned by an applet in another context In this specification an object instance of a class implementing a shareable interface is called a Shareable Interface Object SIO To the owning context the SIO is a normal object who
91. d value 0xFFFF remote_ref_with_class is the definition of a remote object reference using the class name and uses the following format Chapter 8 Remote Method Invocation Service 8 5 8 6 remote_ref with_class 4 u2 remote_ref_id OxFFFF ul hash_modifier_length ul hash_modifier hash_modifier_length ul pkg_name_length ul package_name pkg_name_length ul class_name_length ul class_name class_name_length The remote_ref_id item represents the remote reference identifier The value of this field must not be OxFFFF which denotes the nu11 reference The hash_modifier item is an UTF 8 string of length specified in the hash_modifier_length item and is used to ensure that method identifier hash codes are unique The pkg_name_length item is the number of bytes in the package_name item to represent the name of the package in UTF 8 string notation The value of this item must be non zero The package_name item is the variable length representation of the fully qualified name of the package which contains the remote class in UTF 8 string notation The fully qualified name of the package represented here uses the internal form wherein the ASCII periods that normally separate the indentifiers that make up the fully qualified name are replaced by ASCII forward slashes For example the internal form of the normally fully qualified package name of the package java rmi is java rmi The class_name_length item is
92. ddress Two words are large enough to hold a value of integer type Glossary 9 Glossary 10 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 Index A accessing array object methods 6 20 array objects 6 16 class instance object fields 6 17 class instance object methods 6 17 class instance objects 6 19 objects 6 6 across contexts 6 8 shareable interface 6 19 methods 6 18 standard interface methods 6 17 standard interfaces 6 19 static class fields 6 16 active applet instance 4 1 4 3 AID Glossary 1 Answer to Reset Glossary 2 APDU 4 1 Glossary 1 commands 4 9 APDU class 9 2 incoming data transfers T 1 specifics 9 7 outgoing data transfers T 0 specifics 9 2 T 1 specifics 9 5 API 9 1 Glossary 1 constants 12 1 applet Glossary 1 active instance 4 1 4 3 concurrent operations 3 5 context 4 7 currently selected instance 4 3 default Glossary 3 card instance 4 4 instance 4 4 selection behavior 4 6 deletion 3 1 11 1 manager 11 7 deselection 3 2 4 18 developer Glossary 1 execution context Glossary 1 firewall 6 1 6 4 Glossary 1 installation 3 1 11 1 parameters 11 6 installer 11 2 isolation 6 1 Java Card 3 1 legacy 4 3 life cycle 3 1 methods 3 1 multiselectable 4 4 4 7 Glossary 6 multiselected Glossary 6 package Glossary 1 selected 4 3 selection 3 2 4 1 4 13 8 3 MANAGE CHANNEL OPEN 4 13 SELECT FILE 4 15 uninstall meth
93. deleted If the checks fail an error is returned and the applet deletion fails m Otherwise check if an applet instance belonging to the contexts of the applet instances being deleted is active on the card If so an error is returned and the applet instance deletion fails m Otherwise perform the following steps for each of the applet instances to be deleted If the applet instance being deleted implements the AppletEvent interface set the currently selected applet to that of the applet instance and invoke the uninstall method of the applet instance a A context switch into the context of the applet instance occurs upon invocation a If an uncaught exception is thrown during the execution of the uninstall method it is caught and ignored Applet Instance Deletion The Java Card RE shall guarantee that applet instance deletion is not attempted and thereby deemed unsuccessful in the following cases m An object owned by the applet instance is referenced from an object owned by another applet instance on the card Chapter 11 Applet Installation and Deletion 11 9 m An object owned by the applet instance is referenced from a static field on any package on the card m An applet instance belonging to the context of the applet instance being deleted is active on the card Otherwise the Java Card RE shall delete the applet instance Note The applet deletion attempt may fail due to security considerations or resource lim
94. e Java Card RE closes the new logical channel The applet instance s process method is not called during default applet selection because there is no SELECT FILE APDU A default applet instance shall not require its process method to be called If a default applet instance is successfully selected then APDU commands can be sent directly to the applet instance on that logical channel If no applet is active then only SELECT FILE commands for applet selection or MANAGE CHANNEL commands can be processed on that logical channel A MANAGE CHANNEL command issued over an I O interface shall open a new logical channel only on the same I O interface Similarly a SELECT FILE command issued over an I O interface to open a new logical channel shall open a new logical channel only on the same I O interface Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 The mechanism for specifying the default applet instance for a logical channel is not defined in the Java Card API It is a Java Card RE implementation detail and is left to the individual implementers 4 2 Multiselectable Applets Applets having the capability of being selected on multiple logical channels at the same time or accepting other applets belonging to the same package being selected simultaneously are referred to as multiselectable applets Note All applets within a package shall be multiselectable or none shall be An applet
95. e results in a card tear and card reset event even if a contactless session is in progress An RF signal loss or logical reset on the contactless interface must not affect an ongoing contacted session On some cards the ISO7816 2 defined reset signal input RST is used to reset only the contacted I O interface On some other cards the contacted I O interface may be an universal serial bus interface USB or some other physical interconnect which logically transports ISO 7816 4 APDU commands and responses When the contacted I O interface of such a card concurrently operating over both the contacted as well as the contactless I O interfaces with full operational power is reset the Java Card RE must ensure the following m The ongoing contactless session must not be affected m The transaction in progress in the currently selected applet instance executing on a logical channel on the contacted I O interface if any when the contacted I O interface reset occurs is aborted m Each applet instance that was active on a logical channel over the contacted I O interface when the contacted I O interface was reset must be explicitly deselected and the applicable deselect method is called m Transient data of CLEAR_ON_DESELECT objects associated with each applet instance that was active on a logical channel over the contacted I O interface and that does not have an applet instance from the same package active on any logical channel over the contac
96. ear or Reset Transaction Failure If power is lost tear or the card is reset or some other system failure occurs while a transaction is in progress the Java Card RE shall restore to their previous values all fields and array components conditionally updated since the previous call to JCSystem beginTransaction This action is performed automatically by the Java Card RE when it reinitializes the card after recovering from the power loss reset or failure The Java Card RE determines which of those objects if any were conditionally updated and restores them Note The contents of an array component that is updated using the Util arrayCopyNonAtomic method or the Util arrayFillNonAtomic method while a transaction is in progress are not predictable following a tear or reset during that transaction Note Object space used by instances created during the transaction that failed due to power loss or card reset can be recovered by the Java Card RE 7 6 Aborting a Transaction Transactions can be aborted either by an applet or by the Java Card RE Note The contents of an array component that is updated using the Util arrayCopyNonAtomic method or the Util arrayFillNonAtomic method while a transaction is in progress are not predictable following the abortion of the transaction Chapter 7 Transactions and Atomicity 7 3 7 6 1 7 6 2 7 6 3 7 4 Programmatic Abortion If an applet encounters an internal p
97. eceives Response to incorrect APDUs include an error condition of some kind m When another applet is selected on this logical channel or when the card is reset or when power is removed from the card the Installer becomes deselected and remains suspended until the next time that it is selected Installer Implementation The Installer need not be implemented as an applet on the card The requirement is only that the Installer functionality be SELECTable The corollary to this requirement is that Installer component shall not be able to be invoked on a logical channel on which a non Installer applet is an active applet instance nor when no applet is active Obviously a Java Card RE implementer could choose to implement the Installer as an applet If so then the Installer might be coded to extend the Applet class and respond to invocations of the select process and deselect methods and if necessary the methods of the javacard framework MultiSelectable interface But a Java Card RE implementer could also implement the Installer in other ways as long as it provides the SELECTable behavior to the outside world In this case the Java Card RE implementer has the freedom to provide some other mechanism by which APDUs are delivered to the Installer code module Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 11 12 11 1 3 11 1 4 Installer AID Because the Installer is SELECTable it shal
98. ecification of the Classic Edition of the Java Card Platform Version 3 0 Runtime Environment Java Card Runtime Environment or Java Card RE A vendor of a Java Card technology enabled device provides an implementation of the Java Card RE A Java Card RE implementation within the context of this specification refers to a vendor s implementation of the Java Virtual Machine VM for the Java Card platform Java Card virtual machine or Java Card VM the Java Card Application Programming Interface API or other component based on the Java Card technology specifications A reference implementation is an implementation produced by Sun Microsystems Inc Application software written for the Java Card platform is referred to as a Java Card technology based applet Java Card applet or card applet 1 The terms Java Virtual Machine and JVM mean a Virtual Machine for the Java TM platform XV Who Should Use This Specification This specification is intended to assist implementers of the Java Card RE in creating an implementation developing a specification to extend the Java Card technology specifications or in creating an extension to the runtime environment for the Java Card platform This specification is also intended for Java Card applet developers who want a greater understanding of the Java Card technology specifications Before You Read This Specification Before reading this guide you should be familiar with the Java pro
99. ecognize the clientAID or the parameter m The server applet does not communicate with this client m The server applet does not communicate with this client as specified by the parameter m The applet s getShareableInterfaceObject method throws an uncaught exception Chapter6 Applet Isolation and Object Sharing 6 15 6 2 8 6 2 8 1 6 2 8 2 6 16 Class and Object Access Behavior A static class field is accessed when one of the following Java programming language bytecodes is executed getstatic putstatic An object is accessed when one of the following Java programming language bytecodes is executed using the object s reference getfield putfield invokevirtual invokeinterface athrow lt T gt aload lt T gt astore arraylength checkcast instanceof lt T gt refers to the various types of array bytecodes such as baload sastore etc This list also includes any special or optimized forms of these bytecodes that can be implemented in the Java Card VM such as getfield_b and getfield_s_this Prior to performing the work of the bytecode as specified by the Java VM the Java Card VM will perform an access check on the referenced object If access is denied a java lang SecurityException is thrown The access checks performed by the Java Card VM depend on the type and owner of the referenced object the bytecode and the currently active context They are described in the following sections Accessing Static Clas
100. ect is owned by an applet in the currently active context access is allowed Otherwise if the object is designated a Java Card RE Entry Point Object access is allowed Otherwise if the Java Card RE is the currently active context access is allowed Otherwise access is denied Accessing Shareable Interfaces Bytecodes checkcast instanceof If the object is owned by an applet in the currently active context access is allowed Otherwise if the object s class implements a Shareable interface and if the object is being cast into checkcast or is being verified as being an instance of instanceof an interface that extends the Shareable interface access is allowed Otherwise if the Java Card RE is the currently active context access is allowed Otherwise access is denied Chapter6 Applet Isolation and Object Sharing 6 19 6 2 8 11 Accessing Array Object Methods Note The method access behavior of global arrays is identical to that of Java Card RE Entry Point Objects Bytecodes invokevirtual m If the array is owned by an applet in the currently active context access is allowed m Otherwise if the array is designated a global array access is allowed Context is switched to the array owner s context Java Card RE context m Otherwise if Java Card RE is the currently active context access is allowed Context is switched to the array owner s context m Otherwise access is denied 6
101. ed so one context can access an object belonging to another context These mechanisms are provided in the Java Card API and are discussed in the following sections m Section 6 2 1 Java Card RE Entry Point Objects on page 6 8 m Section 6 2 2 Global Arrays on page 6 9 m Section 6 2 3 Java Card RE Privileges on page 6 10 m Section 6 2 4 Shareable Interfaces on page 6 11 Java Card RE Entry Point Objects Secure computer systems must have a way for non privileged user processes that are restricted to a subset of resources to request system services performed by privileged system routines In the Java Card API this is accomplished using Java Card RE Entry Point Objects These are objects owned by the Java Card RE context but they are flagged as containing entry point methods The firewall protects these objects from access by applets The entry point designation allows the methods of these objects to be invoked from any context When that occurs a context switch to the Java Card RE context is performed These methods are the gateways through which applets request privileged Java Card RE system services The requested service is performed by the entry point method after verifying that the method parameters are within bounds and all objects passed in as parameters are accessible from the caller s context Following are the two categories of Java Card RE Entry Point Objects a Temporary Java Card RE Entry
102. eived by the card or an APDU with extended length value greater than 32767 is requested the Java Card RE shall respond to the CAD with the error response status SW_WRONG_LENGTH If the implementation supports extended length APDU formats extended length semantics shall be enabled at the APDU class methods only if the currently selected applet implements the javacardx apdu ExtendedLength interface If the implementation supports extended length APDU formats when the T 0 APDU transfer protocol is in use and receives an ENVELOPE command but the currently selected applet on the origin logical channel does not implement the ExtendedLength interface the ENVELOPE command must be forwarded to the Chapter 9 API Topics 9 7 9 4 4 1 9 8 currently selected applet on the origin logical channel If the implementation supports extended length APDU formats when the T 1 APDU transfer protocol is in use and receives an APDU command that requires extended length semantics at the APDU class methods but the currently selected applet does not implement the ExtendedLength tagging interface the Java Card RE shall respond to the CAD with the error response status SW_WRONG_LENGTH Extended Length API Semantics The following sections describe the semantics of the applet visible API which is enabled when the applet implements the javacardx apdu ExtendedLength interface These semantics are presented at the API level to the extended length capable applet
103. ent Applet B Requests Services from Applet A 1 Applet B can request service from applet A by invoking one of the shareable interface methods of SIO During the invocation the Java Card VM performs a context switch The original currently active context B is saved on a stack and the context of the owner A of the actual object O becomes the new currently active context A s implementation of the shareable interface method SI method executes in A s context The SI method can determine the AID of its client B via the JCSystem getPreviousContextAID method This is described in Section 6 2 5 Determining the Previous Context on page 6 13 The method determines whether or not it will perform the service for applet B Because of the context switch the firewall allows the SI method to access all the fields and methods of object O and any other object in the context of A At the same time the firewall prevents the method from accessing non shared objects in the context of B The SI method can access the parameters passed by B and can provide a return value to B During the return the Java Card VM performs a restoring context switch The original currently active context B is popped from the stack and again becomes the currently active context Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 5 6 2 5 1 6 2 6 6 2 6 1 6 Because of the context switch
104. ent of an array that shall be preserved across CAD sessions that data element shall be restored to its previous value Some methods also guarantee atomicity for block updates of multiple data elements For example the atomicity of the Util arrayCopy method guarantees that either all bytes are correctly copied or else the destination array is restored to its previous byte values An applet might not require atomicity for array updates The Util arrayCopyNonAtomic method is provided for this purpose It does not use the transaction commit buffer even when called with a transaction in progress 72 Transactions An applet might need to atomically update several different fields or array components in several different objects Either all updates take place correctly and consistently or else all fields or components are restored to their previous values The Java Card platform supports a transactional model in which an applet can designate the beginning of an atomic set of updates with a call to the JCSystem beginTransaction method Each object update after this point is conditionally updated The field or array component appears to be updated reading the field or array component back yields its latest conditional value but the update is not yet committed When the applet calls JcSystem commitTransaction all conditional updates are committed to persistent storage If power is lost or if some other system failure occurs prior to the completion of
105. es a sufficient list of rem_interface_def format entries containing the names of remote interfaces implemented This list is such that when combined with their remote superinterfaces the complete set of remote interfaces implemented by the remote object can be enumerated The rem_interface_def item uses the following format rem_interface_def ul pkg_name_length ul package_name pkg_name_length ul interface_name_length ul interface_name interface_name_length The items in the rem_interface_def structure are as follows The pkg_name_length item is the number of bytes used in the package_name item to represent the name of the package in UTF 8 string notation If the value of this item is 0 it indicates that the package name of the previous remote_interfaces item must be used instead The value of this item in remote_interfaces 0 must not be 0 The package_name item is the pkg_name_length byte length representation of the fully qualified name of the package which contains the remote interface in UTF 8 string notation The fully qualified name of the package represented here uses the internal form wherein the ASCII periods that normally separate the indentifiers that make up the fully qualified name are replaced by ASCII forward slashes For example the internal form of the normally fully qualified package name of the package java rmi is java rmi Chapter 8 Remote Method Invocation Service 8 7 The interface_
106. espond to the SELECT FILE APDU with data see Section 3 3 process Method on page 3 3 for details or it can flag errors by throwing an ISOException with the appropriate returned status word The status word and optional response data are returned to the CAD Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 The Applet selectingApplet method shall return true when called during the select method The Applet selectingApplet method continues to return true during the subsequent process method which is called to process the SELECT FILE APDU command If the applet declines to be selected the Java Card RE returns an APDU response status word of IS07816 SW_APPLET_SELECT_FAILED to the CAD Upon selection failure the Java Card RE state is set to indicate that no applet is selected See Section 4 5 Applet Selection on page 4 13 for more details After successful selection all subsequent APDUs directed to the assigned logical channel are delivered to the currently selected applet via the process method 30 process Method All APDUs are received by the Java Card RE and preprocessed All commands except for the MANAGE CHANNEL command result in an instance of the APDU class containing the command being passed to the process APDU method of the currently selected applet Note A SELECT FILE APDU command might cause a change in the currently selected applet prior to the call to
107. ession is in progress An RF signal loss or logical reset on the contactless interface must not affect an ongoing contacted session The Java Card RE processes APDUs sequentially whether received over the same I O interface or over two different I O interfaces The I O subsystem must present concurrently received APDUs to the Java Card RE command dispatcher sequentially The arbitration required to make concurrently received APDU commands sequential as well as the mechanisms used to ensure proper synchronization with the CAD for contact and with the proximity coupling device PCD for contactless are not specified in this specification The I O subsystem must ensure that APDU commands received over the contactless I O interface are given higher priority but without causing a timeout on any concurrently received APDU command over the contacted I O interface The algorithm used for this purpose is not specified in this specification A new applet written for version 2 2 of the Java Card platform can be designed to take advantage of logical channel support Such an applet can take advantage of multi session functionality can be concurrently selected alongside another applet on a different logical channel and even be selected multiple times simultaneously on different logical channels As shown in FIGURE 4 1 an implementation may support from one to twenty logical channels on each I O interface each with its own distinct CLEAR_ON_DESELECT memo
108. ets 4 7 Forwarding APDU Commands To a Logical Channel 4 9 Opening and Closing Logical Channels 4 12 4 4 1 MANAGE CHANNEL Command Processing 4 12 Applet Selection 4 13 4 5 1 Applet Selection with MANAGE CHANNEL OPEN 4 13 4 5 2 Applet Selection with SELECT FILE 4 15 Applet Deselection 4 18 4 6 1 MANAGE CHANNEL CLOSE Command 4 19 Other Command Processing 4 19 5 Transient Objects 5 1 5 1 Events That Clear Transient Objects 5 2 6 Applet Isolation and Object Sharing 6 1 6 1 6 2 Applet Firewall 6 1 6 1 1 Firewall Protection 6 1 6 1 2 Contexts and Context Switching 6 2 6 1 2 1 Active Contexts inthe VM 6 3 6 1 2 2 Context Switching in the VM 6 4 6 1 3 Object Ownership 6 4 6 1 4 Object Access 6 6 6 1 5 Transient Objects and Contexts 6 6 6 1 6 Static Fields and Methods 6 7 6 1 6 1 Optional Static Access Checks 6 7 Object Access Across Contexts 6 8 iv Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 1 6 2 2 6 2 3 6 2 4 6 2 7 Java Card RE Entry Point Objects 6 8 Global Arrays 6 9 Java Card RE Privileges 6 10 Shareable Interfaces 6 11 6 2 4 1 Server Applet A Builds a Shareable Interface Object 6 11 6 2 4 2 Client Applet B Obtains the Shareable Interface Object 6 11 6 2 4 3 Client Applet B Requests Services from Applet A 6 12 Determining the Previous Context 6 13 6 2 5 1 Java Card RE Context 6 13 Shareable Interface Details 6 13 6 2 6 1 Java Card API Shareable I
109. ext of the currently selected applet instance and that is active on another logical channel access is denied See Section 4 2 Multiselectable Applets on page 4 7 Otherwise if the object s class implements a Shareable interface and if the interface being invoked extends the Shareable interface access is allowed Context is switched to the object owner s context Otherwise if the Java Card RE is the currently active context access is allowed Context is switched to the object owner s context Otherwise access is denied Throwing Exception Objects Bytecodes athrow If the object is owned by an applet in the currently active context access is allowed Otherwise if the object is designated a Java Card RE Entry Point Object access is allowed Otherwise if the Java Card RE is the currently active context access is allowed Otherwise access is denied Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 8 8 6 2 8 9 6 2 8 10 Accessing Classes Bytecodes checkcast instanceof If the object is owned by an applet in the currently active context access is allowed Otherwise if the object is designated a Java Card RE Entry Point Object access is allowed Otherwise if the Java Card RE is the currently active context access is allowed Otherwise access is denied Accessing Standard Interfaces Bytecodes checkcast instanceof If the obj
110. gical channel number is greater than 19 the Java Card RE responds with status code 0x6A81 SW_FUNC_NOT_SUPPORTED If the specified logical channel to close is currently open on the I O interface that received the MANAGE CHANNEL CLOSE command deselect the active applet instance if any on the specified logical channel as described above in Section 4 6 Applet Deselection on page 4 18 The specified logical channel is now closed The Java Card RE responds with status code 0x9000 Otherwise if the specified logical channel is closed or not available on that I O interface the Java Card RE responds with warning status code 0x6200 SW_WARNING_STATE_UNCHANGED Other Command Processing When an APDU other than a SELECT FILE or MANAGE CHANNEL command is received the logical channel to be used for dispatching the command is based on the CLA byte as described in Section 4 3 Forwarding APDU Commands To a Logical Channel on page 4 9 Chapter 4 Logical Channels and Applet Selection 4 19 4 20 When the Java Card RE receives an APDU other than a SELECT FILE or MANAGE CHANNEL command with either of the following m An unsupported logical channel number in the CLA byte m An unopened logical channel number in the CLA byte It shall respond to the APDU with status code 0x6881 SW_LOGICAL_CHANNEL_NOT_SUPPORTED If there is no active applet instance on the logical channel to be used for dispatching the command the Java Ca
111. gramming language the other Java Card technology specifications and smart card technology A good resource for becoming familiar with Java technology and Java Card technology is the Sun Microsystems Inc web site located at http java sun com You should also be familiar with the Java Card technology website at http java sun com products javacard How This Specification Is Organized Chapter 1 Introduction gives an overview of the information contained in this specification Chapter 2 Lifetime of the Java Card Virtual Machine defines the lifetime of the Java Card virtual machine Chapter 3 Java Card Applet Lifetime defines the lifetime of an applet Chapter 4 Logical Channels and Applet Selection describes how the Java Card RE handles applet selection Chapter 5 Transient Objects describes the properties of transient objects Chapter 6 Applet Isolation and Object Sharing describes applet isolation and object sharing xvi Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 Chapter 7 Transactions and Atomicity describes the functionality of atomicity and transactions Chapter 8 Remote Method Invocation Service describes the server side card side functionality of the Remote Method Invocation RMI feature of Java Card Platform Version 3 0 Chapter 9 API Topics describes API functionality required of a Java Car
112. gurant sur les listes d exclusion d exportation americaines y compris mais de maniere non exclusive la liste de personnes qui font objet d un ane de ne pas participer d une facon directe ou indirecte aux exportations des produits ou des services qui sont regi par la legislation americaine en matiere de controle des exportations et la liste de ressortissants specifiquement designes sont rigoureusement interdites LA DOCUMENTATION EST FOURNIE EN L ETAT ET TOUTES AUTRES CONDITIONS DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE A L APTITUDE A UNE UTILISATION PARTICULIERE OU A L ABSENCE DE CONTREFACON 4 Adobe PostScript Contents Contents iii Figures xi Tables xiii Preface xv Introduction 1 1 Lifetime of the Java Card Virtual Machine 2 1 Java Card Applet Lifetime 3 1 3 1 3 2 3 3 3 4 3 5 3 6 install Method 3 1 select Method 3 2 process Method 3 3 deselect Method s 3 3 uninstall Method 3 4 Power Loss and Reset 3 4 3 6 1 Concurrent Operations Over Multiple Interfaces 3 5 Logical Channels and Applet Selection 4 1 4 1 Default Applets 4 4 4 2 4 3 4 4 4 5 4 6 4 7 4 1 1 Card Reset Behavior 4 5 4 1 2 Proximity Card PICC Activation Behavior 4 5 4 1 3 Default Applet Selection Behavior on Opening a New Channel 4 6 Multiselectable Appl
113. he CAD client application needs to begin remote method invocations m Send a remote method invocation request to the card To ensure that the protocol is compatible with all applications the SELECT FILE command is used for getting the initial reference The response to the SELECT FILE command allows the remote method invocation command itself to be customized by the applet Applet Selection The selection command used to retrieve the initial reference is the ISO 7816 4 SELECT FILE command with the following options in the header a Direct selection by DF Name that is selection by AID This is the normal option used to select all applet instances in the Java Card platform a Return FCI File Control Information 1S07816 4 optional template This is an additional option that indicates that the applet is expected to return FCI information In addition an alternate RFU variant of the Return FCI option is required to configure the RMIService for an alternate Java Card RMI protocol format For more details see Section 8 4 1 SELECT FILE Command on page 8 13 The answer to this command is a constructed TLV tag length value data structure ISO 7816 6 that includes the following information a The byte to be used as instruction byte INS for subsequent invocation commands Chapter 8 Remote Method Invocation Service 8 3 8 2 2 a The initial remote object reference descriptor The descriptor includes the remote object iden
114. he CAP file format does not support native methods four bits a programming methodology based on the concept of an object which is a data structure encapsulated with a set of routines called methods which operate on the data Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 object owner objects origin logical channel owning context package PCD persistent object PIX RAM random access memory reference implementation remote interface the applet instance within the currently active context when the object is instantiated An object can be owned by an applet instance or by the Java Card RE in object oriented programming unique instances of a data structure defined according to the template provided by its class Each object has its own values for the variables belonging to its class and can respond to the messages methods defined by its class the logical channel on which an APDU command is issued the context in which an object is instantiated or created a namespace within the Java programming language that can have classes and interfaces an acronym for Proximity Coupling Device The PCD is a contactless card reader device persistent objects and their values persist from one CAD session to the next indefinitely Objects are persistent by default Persistent object values are updated atomically using transactions The term persistent does not mean the
115. he Java Card RE shall process it and determine whether or not the command has logical channel information If logical channel information is encoded the card dispatches the APDU command to the appropriate logical channel on that I O interface All other APDU commands are forwarded to the basic logical channel logical channel 0 on that I O interface TABLE 4 1 ISO 7816 4 2005 Specification Interindustry CLA Semantics CLA byte encoding Semantic details b0000 00zz Type 4 last or only command in chain no SM Sb0001 00zz Type 4 not last command in chain no SM Sb0000 yyzz Type 4 last or only command in chain with SM Sb0001 yyzz Type 4 not last command in chain with SM b0010 uuuu RFU b0011 uuuu RFU b0100 zzzz Type 16 last or only command in chain no SM Sb0101 zzzz Type 16 not last command in chain no SM Sb0ly0 zzzz Type 16 last or only command in chain with SM SbOly1l zzzz Type 16 not last command in chain with SM NOTATION u undefined y Secure Messaging SM indicator See ISO 7816 4 2005 Specification Section 6 for further information Z Logical channel indicator Type 4 supports logical channels 0 3 Type 16 supports logical channels 4 19 TABLE 4 2 Java Card Technology Proprietary CLA Semantics CLA byte encoding Semantic details b 1000 00zz Type 4 last or only command in chain no SM b1001 00zz Type 4 not last command in chain no SM b 1000 yyzz Type 4 last or only command in chai
116. ic rmi m The Java Class Libraries An Annotated Reference Second Edition Java Series by Patrick Chan Rosanna Lee and Doug Kramer Addison Wesley 1999 m ISO 7816 Specification Parts 1 6 http www iso org m EMV 96 Integrated Circuit Card Specification for Payment Systems Version 3 0 EMV 2000 Integrated Circuit Card Specification for Payment Systems Version 4 0 http www emvco com Documentation Support and Training Sun Function URL Documentation http www sun com documentation Support http www sun com support Training http www sun com training Third Party Web Sites Sun is not responsible for the availability of third party web sites mentioned in this document Sun does not endorse and is not responsible or liable for any content advertising products or other materials that are available on or through such sites or resources Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content goods or services that are available on or through such sites or resources Preface xix Sun Welcomes Your Comments Sun Microsystems is interested in improving its documentation and welcomes your comments and suggestions You can submit your comments to jc bandol spec feedback sun com Please include the title of your document with your feedback Runtime Environment Specification Java Card Platform v3
117. in its throws clause Additionally in the remote method declaration a remote object declared as the return value must be declared as the remote interface not the implementation class of that interface 8 1 8 1 1 1 8 1 1 2 8 1 1 3 8 2 Java Card RMI imposes additional constraints on the definition of remote methods These constraints are a result of the Java Card platform language subset and other feature limitations Parameters and Return Values The parameters of a remote method must only include parameters of the following types m Any supported primitive data types m Any single dimension array of a supported primitive data type The return value of a remote method must only be one of the following types m Any supported primitive data type m Any single dimension array type of a supported primitive data type a Any remote interface type a A void return All parameters including array parameters are always transmitted by value during the remote method invocation The return values from a remote method are transmitted by value for primitive types and arrays Return values that are remote object references are transmitted by reference using a remote object reference descriptor Exceptions Java Card RMI uses the following simplified model for returning exceptions thrown by remote methods a When an exception defined in the Java Card API is thrown by a remote method the exact exception type and the embedded re
118. ins an executable binary representation of the classes of a Java programming language package The CAP file also contains the CAP file components see also CAP file component The CAP files produced by the converter are contained in Java Archive JAR files a Java Card platform CAP file consists of a set of components which represent a Java programming language package Each component describes a set of elements in the Java programming language package or an aspect of the CAP file A complete CAP file must contain all of the required components Header Directory Import Constant Pool Method Static Field and Reference Location The following components are optional the Applet Export and Debug The Applet component is included only if one or more Applets are defined in the package The Export component is included only if classes in other packages may import elements in the package defined The Debug component is optional It contains all of the data necessary for debugging a package a card session begins with the insertion of the card into the CAD The card is then able to exchange streams of APDUs with the CAD The card session ends when the card is removed from the CAD the explicit conversion from one data type to another Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 constant pool context context switch Converter currently active context currently selected applet c
119. ion encoded in the CLA byte of the APDU command header the application programmer is advised not to parse the CLA byte directly The following methods in the javacard framework APDU class may be used to extract application specific information m APDU isISOInterindustryCLA m APDU isSecureMessagingCLA m APDU isCommandChainingCLA m APDU getCLAChannel m APDU isValidCLA Chapter 4 Logical Channels and Applet Selection 4 11 Note An asterisk indicates binary notation b using bit numbering as in the ISO7816 specification Most significant bit is b8 Least significant bit is b1 4 4 4 4 1 4 12 Opening and Closing Logical Channels According to Section 5 5 2 of the ISO 7816 4 Specification the following two ways to open a logical channel in the smart card exist 1 By selecting an applet instance on a new logical channel This is accomplished by issuing an Applet SELECT FILE APDU command and specifying the logical channel number in the CLA byte of the command If this logical channel is currently closed it shall be opened and the specified applet instance shall be selected See Section 4 5 2 Applet Selection with SELECT FILE on page 4 15 2 By issuing a MANAGE CHANNEL OPEN APDU command MANAGE CHANNEL commands are provided to open a logical channel from another logical channel or to close a logical channel from another logical channel See Section 4 4 1 MANAGE CHANNEL Command Processing on page 4 12
120. ions there is no requirement that they be performed together during the same card session for the following reasons m Applet packages in ROM are preloaded and prelinked at card issuance but instances of applets from these packages may be installed by the Installer during a card session m Applet packages may be downloaded and linked by the Installer during one card session but applet instances from these packages may be installed by the Installer during a different card session 11 1 m Library packages may be preloaded in ROM or downloaded and linked by the Installer during a card session There are no applets to install within a library package 11 1 Tike 11 2 The Installer The mechanisms necessary to install an applet on smart cards using Java Card technology are embodied in an on card component called the Installer To the CAD the Installer appears to be an applet It has an AID and it becomes the currently selected applet when this AID is successfully processed by a SELECT FILE command Once selected on a logical channel the Installer behaves in much the same way as any other applet as follows m It receives all APDUs dispatched to this logical channel just like any other active applet m Its design specification prescribes the various kinds and formats of APDUs that it expects to receive along with the semantics of those commands under various preconditions m It processes and responds to all APDUs that it r
121. itations The applet instance deletion operation must be atomic If a reset or power fail occurs during the deletion process it must result in either an unsuccessful applet instance deletion or a successfully completed applet instance deletion before any applet is selected on the card Following an unsuccessful applet instance deletion the applet instance shall be selectable and all objects owned by the applet shall remain unchanged The functionality of all applet instances on the card remains the same as prior to the unsuccessful attempt Following a successful applet instance deletion it shall not be possible to select that applet and no object owned by the applet can be accessed by any applet currently on the card or by a new applet created in the future The resources used by the applet instance may be recovered for reuse The AID of the deleted applet instance may be reassigned to a new applet instance Multiple Applet Instance Deletion The Java Card RE shall guarantee that multiple applet instance deletion is not attempted and thereby deemed unsuccessful in the following cases m An object owned by any of the applet instances being deleted is referenced from an object owned by an applet instance on the card which is not being deleted m An object owned by any of the applet instances being deleted is referenced from a static field on a package on the card m An applet instance belonging to the contexts of any of the applet
122. itialization lt clinit gt methods of the applet package are also owned by the context of the new applet The Installer shall not invoke the install byte short byte method of an applet if another applet from the same package is active on the card The applet instantiation shall be deemed unsuccessful The Installer shall ensure that during the execution of the install method the new applet not the Installer is the currently selected applet In addition any CLEAR_ON_DESELECT objects created during the install method shall be associated with the selection context of the new applet Chapter 11 Applet Installation and Deletion 11 5 The installation of an applet is deemed complete if all steps are completed without failure or an exception being thrown up to and including successful return from executing the Applet register method At that point the installed applet is selectable The maximum size of the parameter data is 127 bytes The bArray parameter is a global array install byte bArray short bOffset byte bLength and for security reasons is zeroed after the return from the install method just as the APDU buffer is zeroed on return from an applet s process method 11 2 1 Installation Parameters The format of the input data passed to the target applet s install method in the bArray parameter is as follows bArray offset length Li of instance AID bArray offset 1 offset Li instance AID bytes 5 16
123. jects that the applet needs during its lifetime can be created as is feasible Any other preparations necessary for the applet to be selected and accessed by a CAD also can be done as is feasible The install method obtains initialization parameters from the contents of the incoming byte array parameter Typically an applet creates various objects initializes them with predefined values sets some internal state variables and calls either the Applet register method or the Applet register byte short byte method to specify the AID applet IDentifier as defined in ISO 7816 5 to be used to select it This installation is 3 1 considered successful when the call to the Applet register method completes without an exception The installation is deemed unsuccessful if the install method does not call the Applet register method or if an exception is thrown from within the install method prior to the Applet register method being called or if the Applet register method throws an exception If the installation is unsuccessful the Java Card RE shall perform all cleanup when it regains control That is all conditional updates to persistent storage shall be returned to the state they had prior to calling the install method If the installation is successful the Java Card RE can mark the applet as available for selection Only one applet instance can be successfully registered each time the Java Card RE calls the Applet install method
124. l ensure that Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 3 6 1 m Transient data is reset to the default value m The transaction in progress if any when power was lost or reset occurred is aborted m All applet instances that were active when power was lost or reset occurred become implicitly deselected In this case the deselect method is not called m If the Java Card RE implements default applet selection see Section 4 1 Default Applets on page 4 4 the default applet is selected as the active applet instance for the basic logical channel channel 0 and the default applet s select method is called Otherwise the Java Card RE sets its state to indicate that no applet is active on the basic logical channel Concurrent Operations Over Multiple Interfaces A Java Card technology compliant proximity contactless card operates in the ACTIVE state and processes commands defined in the ISO 14443 Specification Parts 1 4 or using the commands defined by the SWP interface standard ETSI TS 102 613 The following conditions are deemed as a reset of the contactless I O interface m The ISO 14443 Supervisory block S block DESELECT command results in the proximity card entering the HALT state m A loss of RF field results in the proximity card entering the POWER OFF state A contactless interface which is accessed using the SWP interface is logically reset The Java Card
125. l fci_length ul application_data_tag 0x6 ul application_data_length ul jc_rmi_data_tag Ox5E ul jc_rmi_data_length u2 version 0x0202 ul invoke_ins union normal_ref_response normal_initial_ref normal_null_response null_initial_ref error_response initial_ref_error initial_ref ez The jc_rmi_data_length item is the combined length in bytes of the version item invoke_ins item and the initial_ref item The application_data_length item is jc_rmi_data_length 2 The fci_length item is application_data_length 2 The response data includes invoke_ins the instruction byte to use in the method invocation command It also includes initial_ref the initial remote object reference descriptor The initial_ref item corresponds to the remote object designated as the initial reference to the RMIService instance during construction The initial_ref item can be a normal_ref_response item described in Section 8 3 5 1 Normal Response Encoding on page 8 10 or a nul11 representation using a normal_null_response item described in that same section if the initial Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 8 4 2 remote reference object is not enabled for remote access Also note that if an error occurs during the marshalling of the initial remote reference descriptor an error response is returned in initial_ref instead of using the error_response item format described in Section 8
126. l have an AID Java Card RE implementers are free to choose their own AIDs by which their Installer is selected Multiple installers may be implemented Installer APDUs The Java Card specification does not specify any APDUs for the Installer Java Card RE implementers are free to choose their own APDU commands to direct their Installer in its work The model is that the Installer on the card is initiated by an installation program running on the CAD For installation to succeed this CAD installation program shall be able to do the following m Recognize the card m SELECT FILE the Installer on the card Coordinate the installation process by sending the appropriate APDUs to the card Installer These APDUs will include the following a Authentication information to ensure that the installation is authorized The applet code to be loaded into the card s memory Linkage information to link the applet code with code already on the card a Instance initialization parameter data to be sent to the applet s install method The Application Programming Interface Java Card Platform Version 2 2 2 does not specify the details of the CAD installation program nor the APDUs passed between it and the Installer CAP File Versions The Installer shall support the following CAP file versions m Version 2 1 as specified in the Java Card 2 1 1 Virtual Machine Specification m Version 2 2 as specified in the Virtual Machine Specification
127. lack of resources condition such as heap space that is recoverable shall result in a SystemException with reason code NO_RESOURCE The factory methods in JCSystem used to create transient arrays throw a SystemException with reason code NO_TRANSIENT_SPACE to indicate lack of transient space All other non recoverable virtual machine errors such as stack overflow shall result in a virtual machine error These conditions shall cause the virtual machine to halt When such a non recoverable virtual machine error occurs an implementation can optionally require the card to be muted or blocked from further use 10 2 Security Violations The Java Card RE throws a java lang SecurityException exception when it detects an attempt to illegally access an object belonging to another applet across the firewall boundary A java lang SecurityException exception may optionally be thrown by a Java Card VM implementation to indicate a violation of fundamental language restrictions such as attempting to invoke a private method in another class For security reasons the Java Card RE implementation may mute the card instead of throwing the exception object 10 1 10 2 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 1 1 Applet Installation and Deletion Applet installation and deletion on smart cards using Java Card technology is a complex topic The design of the Application Program
128. lass javacard Class javacard Class javacard Class javacard Class javacard Class javacard Class javacard Class javacardx Class javacardx Class javacardx Class javacardx Class javacardx Class javacardx Class javacardx framework framework framework framework framework framework framework security security security security security security security security JCSystem 12 4 P N Exception 12 4 SystemException 12 4 TransactionException 12 4 service Dispatcher 12 5 service RMIService 12 5 service ServiceException 12 5 Checksum 12 6 CryptoException 12 6 KeyAgreement 12 6 Builder 12 6 Keyl KeyPair 12 9 MessageDigest 12 9 RandomData 12 10 Signature 12 10 biometry BioBuilder 12 11 biometry BioException 12 12 biometry BioTemplate 12 12 crypto Cipher 12 12 external external Memory 12 14 framework math BigNumber 12 14 ExternalException 12 14 12 26 12 27 12 28 Glossary Glossary 1 Class javacardx Class javacardx Class javacardx framework tl v BERTag 12 14 framework tl TLVException 12 15 V framework util UtilException 12 15 Contents ix x Index Index 1 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 FIGURE 4 1 FIGURE 4 2 FIGURE 4 3 FIGURE 6 1 FIGURE 6 2 Figu
129. latform v3 0 Classic Edition e March 2008 11 3 11 3 1 The Applet Deletion Manager The mechanisms necessary to delete an applet on smart cards using Java Card technology are embodied in an on card component called the Applet Deletion Manager To the CAD the Applet Deletion Manager appears to be an applet and may be one and the same as the Applet Installer It has an AID and it becomes the currently selected applet instance when this AID is successfully processed by a SELECT FILE command Once selected on a logical channel the Applet Deletion Manager behaves in much the same way as any other applet as follows m It receives all APDUs dispatched to this logical channel just like any other active applet m Its design specification prescribes the various kinds and formats of APDUs that it expects to receive along with the semantics of those commands under various preconditions m It processes and responds to all APDUs that it receives Response to incorrect APDUs include an error condition of some kind m When another applet is selected on this logical channel or when the card is reset or when power is removed from the card the Applet Deletion Manager becomes deselected and remains suspended until the next time it is selected Applet Deletion Manager Implementation The Applet Deletion Manager need not be implemented as an applet on the card The requirement is only that the Applet Deletion Manager functionality be SELEC
130. ll not have a performance penalty Using current smart card technology as an example the contents of transient objects can be stored in RAM while the contents of persistent objects can be stored in EEPROM Typically RAM technology has a much faster write cycle time than EEPROM a Writes to the fields of a transient object shall not be affected by transactions That is an abortTransaction never causes a field in a transient object to be restored to a previous value This behavior makes transient objects ideal for small amounts of temporary applet data that is frequently modified but that need not be preserved across CAD or select sessions 5 1 5 2 Events That Clear Transient Objects Persistent objects are used for maintaining states that shall be preserved across card resets When a transient object is created one of two events is specified that causes its fields to be cleared CLEAR_ON_RESET transient objects are used for maintaining states that shall be preserved across applet selections but not across card resets CLEAR_ON_DESELECT transient objects are used for maintaining states that must be preserved while an applet is selected but not across applet selections or card resets Details of the two clear events are as follows m CLEAR_ON_RESET The object s fields except for the length field are cleared when the card is reset When a card is powered on this also causes a card reset Note
131. logical channel The Applet SELECT FILE command uses Selection by DF name with P1 0x04 The Java Card RE shall support both of the following m Selection by exact DF name AID with P2 b0000xx00 b4 b3 are don t care and a The RFU variant described in ISO 7816 4 Specification with P2 b0001xx00 b4 b3 are don t care All other partial DF name SELECT FILE options b2 b1 variants are Java Card RE implementation dependent All file control information options codes b4 b3 of the P2 parameter shall be supported by the Java Card RE and interpreted and processed by the applet instance itself If resources for the specified logical channel in bits cc of the CLA are not available the Java Card RE responds with status code 0x6881 SW_LOGICAL_CHANNEL_NOT_SUPPORTED If the specified logical channel is not open on the I O interface that received the SELECT FILE command it is now opened and the Java Card RE state is set so that no applet is active on this new logical channel The specified logical channel will be the assigned channel for the applet instance that will be active on it The Java Card RE searches the internal applet table which lists all successfully installed applet instances on the card for an applet instance with a matching AID If a matching applet instance is found it is picked as the candidate applet instance Otherwise if no AID match is found If there is no active applet instance on
132. logy is discussed in the Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition A class in the applet package is found to contain more package visible virtual methods or instance fields than the limitations enumerated in Section 2 2 4 3 of the Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition A reset or power fail occurs while executing the applet s install method and before successful return from the Applet register method see Section 3 1 install Method on page 3 1 The applet s install method throws an exception before successful return from the Applet register method see Section 3 1 install Method on page 3 1 When applet installation is unsuccessful the Java Card RE shall guarantee that objects created during the execution of the install method or by the Java Card RE on its behalf initialized static arrays can never be accessed by any applet on the card In particular any reference in CLEAR_ON_RESET transient space to an object created during an unsuccessful applet installation must be reset as a nu11 reference Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 11 1 6 Installer Privileges Although an Installer may be implemented as an applet an Installer typically requires access to features that are not available to other applets For example depending on the Java Card RE implementer s implementation the
133. m A single contacted I O interface based on ISO 7816 4 standards over the USB interface specified in the ISO 7816 12 specification and or the European Telecommunications Standards Institute ETSI TS 102 600 specification m A single contactless I O interface based on the ISO 14443 specifications or the ETSI defined single wire protocol SWP TS 102 613 specification m Dual I O interfaces one contacted and one contactless interface based on the standards described above Logical channel sessions as described in this chapter may be supported over any of these interfaces In addition a dual interface card may be able to sustain logical channel sessions over both the contacted and the contactless interface simultaneously An implementation may support between 1 and 20 logical channels over the contacted I O interface Similarly an implementation may support between 1 and 20 logical channels over the contactless I O interface When both I O interfaces are concurrently active the number of logical channels supported on each of the two interfaces is also implementation specific 4 1 4 2 Note To establish a card session over both contacted and contactless interfaces concurrently on cards on which the ISO7816 2 defined reset signal input RST contact resets the card the CAD must initiate the contacted session first A power loss or card reset on the contacted interface results in a card tear and card reset event even if a contactless s
134. ming Interface Java Card Platform Version 2 2 2 is intended to give Java Card RE implementers as much freedom as possible in their implementations However some basic common specifications are required to allow Java Card applets to be installed and deleted without knowing the implementation details of a particular installer or deletion manager This specification defines the concepts of an Installer and an Applet Deletion Manager and specifies minimal requirements to achieve interoperability across a wide range of possible Installer implementations The Applet Installer is an optional part of the Runtime Environment Specification Java Card Platform Version 3 0 Classic Edition An implementation of the Java Card RE does not necessarily need to include a post issuance Installer However if implemented the installer is required to support the behavior specified in this chapter If the implementation of the Java Card RE includes a post issuance Installer an Applet Deletion Manager that supports the behavior specified in this chapter is also required Section 11 1 The Installer on page 11 2 describes CAP file loading and linking For more information on CAP files see the Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition Section 11 2 The Newly Installed Applet on page 11 5 describes applet installation Even though the loading and linking operations are described together with the installation operat
135. mitive return types arrays of primitive data types using the same format for the param item as described in Section 8 3 4 Parameter Encoding on page 8 8 using the following format normal_param_response ul normal_tag 0x81 param normal_value The null_array_param format described in Section 8 3 4 Parameter Encoding on page 8 8 is not used to represent a null array reference Instead a null object reference as well as a null array reference shares the following common format normal_null_response ul normal_tag 0x81 ref_null null_array_or_ref In addition a remote object reference descriptor type is also encapsulated using the normal response format as follows normal_ref_response ul normal_tag 0x81 remote_ref_descriptor remote_ref Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 8 3 5 2 Exception Response Encoding Following is the encoding when an API defined exception is thrown by the remote method It may be returned during any remote method invocation The reason item is the Java Card platform exception reason code or 0 for a java lang java rmi or java io exceptions exception_response ul exception_tag 0x82 ul exception_type s2 reason Following are the values for the exception_type item java lang Throwable 0x00 java lang ArithmeticException 0x01 java lang ArrayIndexOutOfBoundsException 0x02
136. n with SM 4 10 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 TABLE 4 2 Java Card Technology Proprietary CLA Semantics Continued CLA byte encoding Semantic details b1001 yyzz Type 4 not last command in chain with SM b1010 00zz Type 4 last or only command in chain no SM b1011 00zz Type 4 not last command in chain no SM b1010 yyzz Type 4 last or only command in chain with SM b1011 yyzz Type 4 not last command in chain with SM b1100 zzzz Type 16 last or only command in chain no SM b1101 zzzz Type 16 not last command in chain no SM Sblly0 zzzz Type 16 last or only command in chain with SM Sbliyl zzzz Type 16 not last command in chain with SM NOTATION u undefined y Secure Messaging indicator See ISO 7816 4 2005 Specification Section 6 for further information Z Logical channel indicator Type 4 supports logical channels 0 3 Type 16 supports logical channels 4 19 Note CLA byte 0xFX cannot encode logical channel 19 because CLA 0xFF is a reserved value for Protocol Type Selection In compliance with ISO 7816 4 2005 Specification logical channel number 19 is not available when using this CLA byte The Java Card RE always forwards the command as is to the appropriate applet instance In particular the Java Card RE does not clear the logical channel encoding bits of the CLA byte To avoid the complexity of the transport informat
137. n_value field may only take the values 0 for false and 1 for true All the other fields can take any value in their range 8 3 4 2 Array Parameter Encoding The representation of the null array parameter and arrays of the boolean byte short and int component types include the length information and are respectively encoded as follows null_array_param ul length OxFF boolean_array_param ul length OxFF ul boolean_value length byte_array_param ul length OxFF sl byte_value length short_array_param ul length OxFF s2 short_value length int_array_param ul length OxFF s4 int_value length Note The length field in each of this array data structure represents the number of elements of the array not its size in bytes Chapter 8 Remote Method Invocation Service 8 9 8 3 5 8 3 5 1 8 10 Return Value Encoding A return value may be any of the parameter types described in the previous section encapsulated within a normal response format In addition the return value may represent a remote object reference type a null return type various exceptions and the error type The generic structure of a return value is as follows return_response ul tag ul value The return value using the return_response encoding is always followed by a good completion status code of 0x9000 in the response APDU Normal Response Encoding A normal response encapsulates pri
138. name_length item is the number of bytes in the interface_name item to represent the name of the remote interface in UTF 8 string notation The interface_name item is the variable length representation of the name of the remote interface implemented by the remote object in UTF 8 string notation 8 3 3 Method Identifier A method identifier is always used in association with a remote object reference A method identifier is defined as follows u2 method_id The method_id is a unique 16 bit hashcode identifier of the remote method within the remote class This 16 bit hashcode consists of the first two bytes of the SHA 1 message digest function performed on a class specific hash modifier string followed by the name of the method followed by the method descriptor representation in UTF 8 format Representation of a method descriptor is the same as that described in The Java Virtual Machine Specification Section 4 3 3 8 3 4 Parameter Encoding Every parameter has the following generic format param ul value 8 3 4 1 Primitive Data Type Parameter Encoding Primitive data types void boolean byte short and int are respectively encoded as follows void_param boolean_param ul boolean_value byte_param sl byte_value 8 8 Runtime Environment Specification Java Card Platform v3 0 Classic Edition March 2008 short_param s2 short_value int_param s4 int_value The boolea
139. ng 6 9 6 2 3 6 10 At the time of publication of this specification the only global arrays required in the Java Card API are the APDU buffer and the byte array input parameter bArray to the applet s install method Note Because of the global status of the APDU buffer the Application Programming Interface Java Card Platform Version 2 2 2 specifies that this buffer is cleared to zeroes whenever an applet is selected before the Java Card RE accepts a new APDU command This is to prevent an applet s potentially sensitive data from being leaked to another applet via the global APDU buffer The APDU buffer can be accessed from a shared interface object context and is suitable for passing data across different contexts The applet is responsible for protecting secret data that may be accessed from the APDU buffer Java Card RE Privileges Because it is the system context the Java Card RE context has a special privilege It can invoke a method of any object on the card For example assume that object X is owned by applet A Normally only the context of A can access the fields and methods of X But the Java Card RE context is allowed to invoke any of the methods of X During such an invocation a context switch occurs from the Java Card RE context to the context of the applet that owns X Again because it is the system context the Java Card RE context can access fields and components of any object on the car
140. nse P1 02 RMI major version P2 02 RMI minor version Data As described below As described below Chapter 8 Remote Method Invocation Service 8 15 Following is the structure of the data part of the request command invoke_data u2 object_id u2 method_id param parameters The object_id is the remote object identifier of the object whose remote method is to be invoked The method to be invoked is specified by the method_id item and each parameter is specified by a param structure The response format uses the return_response structure as described in Section 8 3 5 Return Value Encoding on page 8 10 8 5 RMIService Class The RMIService class implements the Java Card RMI protocol and processes the RMI access commands described earlier SELECT FILE and INVOKE It performs the function of the transport layer for Java Card RMI commands on the card The RMIService object maintains a list of remote objects that have been returned during the current applet selection session It enforces the following rules for the lifetime of the remote object references a A remote reference is valid only when the INVOKE command is processed by the RMIService instance that returned the reference a A remote reference is valid with any applet instance in the package of the applet instance that returned it a A remote reference is valid as long as at least one applet instance within the same package has been active at all times sin
141. nterface 6 13 Obtaining Shareable Interface Objects 6 14 6 2 7 1 Applet getShareableInterfaceObject AID byte Method 6 14 6 2 7 2 JCSystem getAppletShareableInterfaceObject Method 6 15 Class and Object Access Behavior 6 16 6 2 8 1 Accessing Static Class Fields 6 16 6 2 8 2 Accessing Array Objects 6 16 6 2 8 3 Accessing Class Instance Object Fields 6 17 6 2 8 4 Accessing Class Instance Object Methods 6 17 6 2 8 5 Accessing Standard Interface Methods 6 17 6 2 8 6 Accessing Shareable Interface Methods 6 18 6 2 8 7 Throwing Exception Objects 6 18 6 2 8 8 Accessing Classes 6 19 6 2 8 9 Accessing Standard Interfaces 6 19 6 2 8 10 Accessing Shareable Interfaces 6 19 6 2 8 11 Accessing Array Object Methods 6 20 Contents v 7 Transactions and Atomicity 7 1 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 Atomicity 7 1 Transactions 7 2 Transaction Duration 7 2 Nested Transactions 7 2 Tear or Reset Transaction Failure 7 3 Aborting a Transaction 7 3 7 6 1 Programmatic Abortion 7 4 7 6 2 Abortion by the Java Card RE 7 4 7 6 3 Cleanup Responsibilities of the Java Card RE 7 4 Transient Objects and Global Arrays 7 5 Commit Capacity 7 5 Context Switching 7 5 8 Remote Method Invocation Service 8 1 8 1 8 2 8 3 Java Card Platform RMI 8 1 8 1 1 Remote Objects 8 1 8 1 1 1 Parameters and Return Values 8 2 8 1 1 2 Exceptions 8 2 8 1 1 3 Functional Limitations 8 2 RMI Messages 8 3 8 2 1 Applet Selection 8
142. objects from being accessed by this code The Runtime Environment Specification Java Card Platform Version 3 0 Classic Edition specifies the basic minimum protection requirements of contexts and firewalls because the features described in this document are not transparent to the applet developer Developers shall be aware of the behavior of objects APIs and exceptions related to the firewall Java Card RE implementers are free to implement additional security mechanisms beyond those of the applet firewall as long as these mechanisms are transparent to applets and do not change the externally visible operation of the VM Contexts and Context Switching Firewalls essentially partition the Java Card platform s object system into separate protected object spaces called contexts These are illustrated in FIGURE 6 1 The firewall is the boundary between one context and another The Java Card RE shall allocate and manage a context for each Java API package containing applets All applet instances within a single Java API package share the same context There is no firewall between individual applet instances within the same package That is an applet instance can freely access objects belonging to another applet instance that resides in the same package 6 2 1 Note that a library package is not assigned a separate context Objects from a library package belong to the context of the creating applet instance Runtime Environment Specifi
143. od 11 9 applet instance active Glossary 1 application identifier Glossary 1 Application Programming Interface Glossary 1 Application Protocol Data Unit Glossary 1 arrays accessing object methods 6 20 global 6 9 7 5 Index 1 objects accessing 6 16 assigned channel of an applet instance 4 14 4 16 assigned logical channel Glossary 1 atomic operation Glossary 2 atomicity 7 1 Glossary 2 ATR Glossary 2 B basic logical channel 4 2 4 5 Glossary 2 big endian Glossary 2 binary compatibility Glossary 2 bytecode Glossary 2 Cc CAD 2 1 Glossary 2 CAP file Glossary 2 component Glossary 2 card initialization time 2 1 reset behavior 4 5 sessions 2 1 Card Acceptance Device 2 1 Glossary 2 card session Glossary 2 cast Glossary 2 class access behavior 6 16 javacard framework APDU 12 1 javacard framework APDUException 12 2 javacard framework PINException 12 4 javacard framework service Dispatcher 12 5 javacard framework service RMIService 12 5 avacard framework service ServiceException 1 2 5 javacard framework SystemException 12 4 javacard framework TransactionException 12 4 javacard security Checksum 12 6 javacard security CryptoException 12 6 javacard security KeyAgreement 12 6 javacard security KeyBuilder 12 6 javacard security KeyPair 12 9 j J J J J J aig Ai a avacard security MessageDigest 12 9 avacard security RandomData 12 10 avacard security Signature 12
144. okespecial causes no context switch Public static fields and public static methods are accessible from any context Static methods execute in the same context as their caller Objects referenced in static fields are just regular objects They are owned by whomever created them and standard firewall access rules apply If it is necessary to share them across multiple contexts these objects need to be Shareable Interface Objects SIOs see Section 6 2 4 Shareable Interfaces on page 6 11 Of course the conventional Java technology protections are still enforced for static fields and methods In addition when applets are installed the Installer verifies that each attempt to link to an external static field or method is permitted Installation and specifics about linkage are beyond the scope of this specification Optional Static Access Checks The Java Card RE may perform optional runtime checks that are redundant with the constraints enforced by a verifier A Java Card VM may detect when code violates fundamental language restrictions such as invoking a private method in another class and report or otherwise address the violation Chapter 6 Applet Isolation and Object Sharing 6 7 6 2 6 2 1 6 8 Object Access Across Contexts The applet firewall confines an applets actions to its designated context To enable applets to interact with each other and with the Java Card RE some well defined yet secure mechanisms are provid
145. on the contactless I O interface Rules of multiselection apply as described in Section 4 2 Multiselectable Applets on page 4 7 Legacy applets written for version 2 1 of the Java Card platform running on version 2 2 need not be aware of logical channel support to work correctly The Java Card RE must guarantee that an applet that was not designed to be aware of multiple sessions is not selected more than once or concurrently with another applet from the same package FIGURE 4 1 Logical Channels for Distinct Applets Contact Logical Channels Contactless Logical Channels Applet B Package Package P1 P3 CLEAR_ON_DESELECT Memory Segments Support for multiple logical channels with multiple selected applet instances requires a change to the Java Card platform version 2 1 concept of selected applet Because more than one applet instance can be selected at the same time and one applet instance can be selected on different logical channels simultaneously it is necessary to differentiate the state of the applet instances in more detail An applet instance is be considered an active applet instance if it is currently selected in at least one logical channel up to a maximum of forty Each active applet instance from a distinct package executes with a distinct CLEAR_ON_DESELECT transient memory segment see FIGURE 4 1 An applet instance is the currently selected applet instance only if it is processing the current command There
146. ontext is not the context of the currently selected applet even if the attempting context is that of an active applet instance on another logical channel the method shall throw a java lang SystemException with reason code of ILLEGAL_TRANSIENT If an attempt is made to access a transient object of CLEAR_ON_DESELECT type when the currently active context is not the context of the currently selected applet even if the attempting context is that of an active applet instance on another logical channel the Java Card RE shall throw a java lang SecurityException Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 1 6 6 1 6 1 Applets that are part of the same package share the same context Every applet instance from a package shares all its object instances with all other instances from the same package This includes transient objects of both CLEAR_ON_RESET type and CLEAR_ON_DESELECT type owned by these applet instances The transient objects of CLEAR_ON_DESELECT type owned by any applet instance in the same package shall be accessible when any of the applet instances is the currently selected applet Static Fields and Methods Instances of classes objects are owned by contexts Classes themselves are not There is no runtime context check that can be performed when a class static field is accessed Neither is there a context switch when a static method is invoked Similarly inv
147. ot subject to transactions The implementation may choose to maintain the data portion of these global array objects used for remote method parameters in the APDU buffer itself Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 9 API Topics The topics in this chapter complement the requirements specified in the Application Programming Interface Java Card Platform Version 2 2 2 9 1 Resource Use Within the API Unless specified in the Application Programming Interface Java Card Platform Version 2 2 2 the implementation shall support the invocation of API instance methods even when the owner of the object instance is not the currently selected applet Unless specifically called out the implementation shall not use resources such as transient objects of CLI 9 2 EFAR_ON_DI I ESELECT type Exceptions Thrown by API Classes All exception objects thrown by the API implementation shall be temporary Java Card RE Entry Point Objects Temporary Java Card RE Entry Point Objects cannot be stored in class variables instance variables or array components see Section 6 2 1 Java Card RE Entry Point Objects on page 6 8 9 1 9 3 Transactions Within the API Unless explicitly called out in the API descriptions implementation of the Java Card API methods shall not initiate or otherwise alter the state of a transaction in progress Unless explicitl
148. package that can be imported by classes in other packages in the Java Card platform any classes interfaces their constructors methods and fields that can be accessed from another package according to the Java programming language semantics as defined by the Java Language Specification and Java Card API package access control restrictions see Java Language Specification section 2 2 1 1 Externally visible items may be represented in an export file For a library package all externally visible items are represented in an export file For an applet package only those externally visible items that are part of a shareable interface are represented in an export file the process by which a Java virtual machine VM allows an unreferenced object instance to release non memory resources for example close and open files prior to reclaiming the object s memory Finalization is only performed on an object when that object is ready to be garbage collected meaning there are no references to the object Finalization is not supported by the Java Card virtual machine The method finalize is not called automatically by the Java Card virtual machine see applet firewall a type of persistent mutable memory It is more efficient in space and power than EPROM Flash memory can be read bit by bit but can be updated only as a block Thus flash memory is typically used for storing additional programs or large chunks of data that are updated as
149. plement the associated interface All data allocation associated with the key implementation instance shall be performed at the time of instance construction to ensure that any lack of required resources can be flagged early during the installation of the applet The MessageDigest object uses temporary storage for intermediate results when the update method is invoked This intermediate state need not be preserved across power up and reset The object is reset to the state it was in when previously initialized via a call to reset The Signature and Cipher objects use temporary storage for intermediate results when the update method is invoked This intermediate state need not be preserved across power up and reset The object is reset to the state it was in when previously initialized via a call to init 9 10 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 The Checksum object uses temporary storage for intermediate results when the update method is invoked This intermediate state need not be preserved across power up and reset The object is reset to the state it was in when previously initialized upon a tear or card reset event 9 6 JCSystem Class In the Java Card platform version 3 0 the getVersion method returns short 0x0202 D7 Optional Extension Packages Some API packages in the Java Card technology are designated as extension packages and may be optionally suppo
150. pletShareableInterfaceObject Method on page 6 15 to request a shared interface object reference from applet A Chapter 6 Applet Isolation and Object Sharing 6 11 6 2 4 3 6 12 Applet A receives the request and the AID of the requester B via Applet getShareableInterfaceObject and determines whether it will share object O with applet B A s implementation of the getShareableInterfaceObject method executes in A s context If applet A agrees to share with applet B A responds to the request with a reference to O As this reference is returned as type Shareable none of the fields or methods of O are visible Applet B receives the object reference from applet A casts it to the interface type SI and stores it in object reference variable SIO Even though SIO actually refers to A s object O SIO is an interface of type SI Only the shareable interface methods defined in SI are visible to B The firewall prevents the other fields and methods of O from being accessed by B In this sequence applet B initiates communication with applet A using the special system method in the JCSystem class to request a Shareable Interface Object from applet A Once this communication is established applet B can obtain other Shareable Interface Objects from applet A using normal parameter passing and return mechanisms It can also continue to use the special JCSystem method described above to obtain other Shareable Interface Objects Cli
151. poses and use clientAID and parameter to determine which kind of SIO to return to the client JCSystem getAppletShareableInterfaceObject Method The JCSystem class contains the method getAppletShareableInterfaceObject which is invoked by a client applet to communicate with a server applet The Java Card RE shall implement this method to behave as follows 1 The Java Card RE searches its internal applet table which lists all successfully installed applets on the card for one with serverAID If not found nul11 is returned 2 If the server applet instance is not a multiselectable applet instance and is currently active on another logical channel a SecurityException is thrown See Section 4 2 Multiselectable Applets on page 4 7 3 The Java Card RE invokes this applet s getShareableInterfaceObject method passing the clientAID of the caller and the parameter 4 A context switch occurs to the server applet and its implementation of getShareableInterfaceObject proceeds as described in the previous section The server applet returns a SIO or nu11 5 getAppletShareableInterfaceObject returns the same SIO or nu11 to its caller For enhanced security the implementation shall make it impossible for the client to tell which of the following conditions caused a nul1 value to be returned m The serverAID was not found m The server applet does not participate in inter applet communication m The server applet does not r
152. rd RE shall respond to the APDU with status code 0x6999 SW_APPLET_SELECT_FAILED When an APDU other than a Applet SELECT FILE or a MANAGE CHANNEL command is received and there is an active applet instance on the logical channel to be used for dispatching the command the Java Card RE sets the active applet instance on the origin channel as the currently selected applet instance and invokes the process method passing the APDU as a parameter This causes a context switch from the Java Card RE context into the currently selected applet instance s context For more information on contexts see Section 6 1 2 Contexts and Context Switching on page 6 2 When the process method exits the VM switches back to the Java Card RE context The Java Card RE sends the response APDU and waits for the next command APDU Note that the Java Card RE dispatches the APDU command as is to the applet instance for processing via the process method Therefore the CLA byte in the command header contains in its least significant bits the origin channel number An applet designed to run on any logical channel needs to mask out these two bits before checking for specific values Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 5 Transient Objects Applets sometimes require objects that contain temporary transient data that need not be persistent across CAD sessions The Java Card platform does not
153. re is an object oriented database on the card or that objects are serialized and deserialized just that the objects are not lost when the card loses power see AID application identifier temporary working space for storing and modifying data RAM is non persistent memory that is the information content is not preserved when power is removed from the memory cell RAM can be accessed an unlimited number of times and none of the restrictions of EEPROM apply a fully functional and compatible implementation of a given technology It enables developers to build prototypes of applications based on the technology an interface which extends directly or indirectly the interface java rmi Remote Each method declaration in the remote interface or its super interfaces includes the exception java rmi RemoteException or one of its superclasses in its throws clause In a remote method declaration if a remote object is declared as a return type it is declared as the remote interface not the implementation class of that interface In addition Java Card RMI imposes additional constraints on the definition of remote methods These constraints are as a result of the Java Card platform language subset and other feature limitations Glossary 7 remote methods remote object RFU RID RMI ROM read only memory runtime environment shareable interface shareable interface object SIO smart card terminal thread tran
154. res Logical Channels for Distinct Applets 4 3 Different Applet Instances in Same Package 4 8 Same Applet Instance Selected on Multiple Logical Channels 4 9 Contexts Within the Java Card Platform s Object System 6 3 Context Switching and Object Access 6 5 xi xii Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 TABLE 4 1 TABLE 4 2 TABLE 8 1 TABLE 8 2 TABLE 9 1 Tables ISO 7816 4 2005 Specification Interindustry CLA Semantics 4 10 Java Card Technology Proprietary CLA Semantics 4 10 Select File Command 8 13 Invoke Command Format 8 15 APDU Buffer Format for Extended Length 9 8 xiii xiv Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 Preface Java Card technology combines a portion of the Java programming language with a runtime environment optimized for smart cards and related small memory embedded devices The goal of Java Card technology is to bring many of the benefits of the Java programming language to the resource constrained world of smart cards The Classic Edition of the Java Card platform is defined by three specifications this Runtime Environment Specification Java Card Platform Version 3 0 Classic Edition the Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition and the Application Programming Interface for the Java Card Platform Version 3 0 Classic Edition This document is a sp
155. roblem or decides to cancel the transaction it can programmatically undo conditional updates by calling JCSystem abortTransaction If this method is called all conditionally updated fields and array components since the previous call to JCSystem beginTransaction are restored to their previous values and the JCSystem getTransactionDepth value is reset to 0 Abortion by the Java Card RE If an applet returns from the select deselect process or install methods when an applet initiated transaction is in progress the Java Card RE automatically aborts the transaction and proceeds as if an uncaught exception was thrown If the Java Card RE catches an uncaught exception from the select deselect process or install methods when an applet initiated transaction is in progress the Java Card RE automatically aborts the transaction Note The abortion of a transaction by the Java Card RE does not directly affect the response status sent to the CAD The response status is determined as described in Section 3 3 process Method on page 3 3 Cleanup Responsibilities of the Java Card RE Object instances created during the transaction that is being aborted can be deleted only if references to these deleted objects can no longer be used to access these objects The Java Card RE shall ensure that a reference to an object created during the aborted transaction is equivalent to a nu11 reference Alternatively programmatic abortion after
156. rt short short shor byt byt byt byt byt byt byt byt byt byt SW_FILE_INVALID SW_APP SW_DATA_INVALID SW_CONDITIONS_NOT SW_COMMAND_NOT_ALLOWE __SATISFII SW_RI SW_CORRECT_LI SW_INS_NOT_S SW_CLA_NOT_S CLA_ISO781 INS_EXTERNAL AUTH SW_WRONG_DATA 0x6A80 FUNC_NOT_SUPPORTED SW_FILE_NOT_FOUND SW_INCORRECT_P1P2 SW_WRONG_P1P2 SW_UNKNOWN 0x6F00 SW_FILE_FULL 0x6A84 OFFSET_CLA 0 OFFSET_INS 1 OFFSET_P1 2 OFFSET_P2 3 OFFSET_LC 4 OFFSET_CDATA 5 OFFSET_EXT_CDATA INS_SELECT byte 1ET_SELECT_FATLED ECORD_NOT_FOUND ENGTH_00 UPPORT UPPORT L6 0x00 ENTICAT ED 0x6985 0x6986 0x6999 Ox6A81 0Ox6A82 0x6A83 Ox6A86 0x6C00 0x6D00 Ox6E00 byte 0x82 Chapter 12 API Constants 12 3 12 4 Class javacard framework JCSystem T public static final byte NOT_A_TRANSIENT_OBJECT 0 public static final byte CLEAR_ON_RESET 1 public static final byte CLEAR_ON_DESELECT 2 public static final byte MEMORY_TYPE_PERSISTENT 0 public static final byte MEMORY_TYPE_TRANSIENT_RESET 1 public static final byte MEMORY_TYPE_TRANSIENT_DESELECT 2 125 Class javacard framework PINException public static final short ILLEGAL VALUE 1 12 6 Class javacard
157. rted by an implementation But if supported all the classes in the package and its subpackages must be implemented by the platform and reside on the card The following are optional Java Card technology extension packages javacardx apdu This package enables support for advanced APDU mechanisms This package must be implemented if and only if the platform supports the extended length APDU protocol defined in the ISO 7816 4 2005 Specification javacardx biometry This package contains classes and interfaces which can be used to build a biometric server application javacardx crypto This package contains functionality which may be subject to export controls for implementing a security and cryptography framework javacardx external This package contains functionality for implementing mechanisms to access memory subsystems which are not directly addressable by the Java Card RE on the Java Card platform javacardx framework This package contains a framework of classes and interfaces for efficiently implementing typical Java Card technology based applets If implemented this package must include all the contained sub packages util math and tlv Chapter9 API Topics 9 11 9 12 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 cHapter 10 Virtual Machine Topics This chapter details virtual machine resource failures and security violations 10 1 Resource Failures A
158. rwise if the object is owned by an applet in the currently active context access is allowed Otherwise access is denied Accessing Class Instance Object Methods Bytecodes invokevirtual If the object is owned by an applet in the currently active context access is allowed Otherwise if the object is designated a Java Card RE Entry Point Object access is allowed Context is switched to the object owner s context shall be Java Card RE Otherwise if Java Card RE is the currently active context access is allowed Context is switched to the object owner s context Otherwise access is denied Accessing Standard Interface Methods Bytecodes invokeinterface Chapter6 Applet Isolation and Object Sharing 6 17 6 2 8 6 6 2 8 7 6 18 If the object is owned by an applet in the currently active context access is allowed Otherwise if the object is designated a Java Card RE Entry Point Object access is allowed Context is switched to the object owner s context shall be Java Card RE Otherwise if the Java Card RE is the currently active context access is allowed Context is switched to the object owner s context Otherwise access is denied Accessing Shareable Interface Methods Bytecodes invokeinterface If the object is owned by an applet in the currently active context access is allowed Otherwise if the object is owned by a non multiselectable applet instance that is not in the cont
159. ry segment Only one logical channel logical channel number 0 the basic logical channel becomes active on the contacted I O interface following a card reset Similarly only one logical channel logical 0 the basic logical channel becomes active on the contactless I O interface following a PICC activation sequence A MANAGE CHANNEL APDU command may be issued on this logical channel to instruct the card to open a new logical channel Applet instances can be selected on different logical channels using the SELECT FILE APDU command just as they would in a single logical channel environment The MANAGE CHANNEL APDU command is also used for closing a logical channel Note that the basic logical channel is permanent and can never be closed as long as the I O interface remains activated On a card that is able to sustain logical channel sessions over both interfaces simultaneously there are two sets of twenty logical channels possible A logical channel number 0 on the contacted I O interface is not the same as the logical channel number 0 on the contactless I O interface An applet instance selected on a logical channel on the contacted I O interface would normally receive APDUs only from the contacted I O interface However it can receive APDUs from the Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 contactless I O interface also only if the applet instance is concurrently selected on a logical channel
160. s Fields Bytecodes getstatic putstatic m If the Java Card RE is the currently active context access is allowed m Otherwise if the bytecode is putstatic and the field being stored is a reference type and the reference being stored is a reference to a temporary Java Card RE Entry Point Object or a global array access is denied m Otherwise access is allowed Accessing Array Objects Bytecodes lt T gt aload lt T gt astore arraylength checkcast instanceof m If the Java Card RE is the currently active context access is allowed Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 6 2 8 3 6 2 8 4 6 2 8 5 Otherwise if the bytecode is aastore and the component being stored is a reference type and the reference being stored is a reference to a temporary Java Card RE Entry Point Object or a global array access is denied Otherwise if the array is owned by an applet in the currently active context access is allowed Otherwise if the array is designated global access is allowed Otherwise access is denied Accessing Class Instance Object Fields Bytecodes getfield putfield If the Java Card RE is the currently active context access is allowed Otherwise if the bytecode is put field and the field being stored is a reference type and the reference being stored is a reference to a temporary Java Card RE Entry Point Object or a global array access is denied Othe
161. s the Java Card RE functionality required by the Java Card technology Any implementation of Java Card technology shall provide this necessary behavior and environment 1 1 1 2 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 2 Lifetime of the Java Card Virtual Machine In a PC or workstation the Java virtual machine runs as an operating system process When the OS process is terminated the Java programming language applications and their objects are automatically destroyed In Java Card technology the execution lifetime of the virtual machine VM is the lifetime of the card Most of the information stored on a card shall be preserved even when power is removed from the card Persistent memory technology such as EEPROM enables a smart card to store information when power is removed Because the VM and the objects created on the card are used to represent application information that is persistent the Java Card VM appears to run forever When power is removed the VM only stops temporarily When the card is next reset the VM starts again and recovers its previous object heap from persistent storage Aside from its persistent nature the Java Card virtual machine is just like the Java virtual machine The card initialization time is the time after masking and prior to the time of card personalization and issuance At the time of card initialization the Java Card RE is initialize
162. saction the methods of a remote interface an object whose remote methods can be invoked remotely from the CAD client A remote object is described by one or more remote interfaces acronym for Reserved for Future Use see AID application identifier an acronym for Remote Method Invocation RMI is a mechanism for invoking instance methods on objects located on remote virtual machines meaning a virtual machine other than that of the invoker memory used for storing the fixed program of the card A smart card s ROM contains operating system routines as well as permanent data and user applications No power is needed to hold data in this kind of memory ROM cannot be written to after the card is manufactured Writing a binary image to the ROM is called masking and occurs during the chip manufacturing process see Java Card Runtime Environment Java Card RE an interface that defines a set of shared methods These interface methods can be invoked from an applet in one context when the object implementing them is owned by an applet in another context an object that implements the shareable interface a card that stores and processes information through the electronic circuits embedded in silicon in the substrate of its body Unlike magnetic stripe cards smart cards carry both processing power and information They do not require access to remote databases at the time of a transaction a Card Acceptance Device that is typically a
163. se fields and methods can be accessed To any other context the SIO is an instance of the shareable interface and only the methods defined in the shareable interface are accessible All other fields and methods of the SIO are protected by the firewall Shareable interfaces provide a secure mechanism for inter applet communication as described in the following sections Server Applet A Builds a Shareable Interface Object 1 To make an object available for sharing with another applet in a different context applet A first defines a shareable interface SI A shareable interface extends the interface javacard framework Shareable The methods defined in the shareable interface SI represent the services that applet A makes accessible to other applets 2 Applet A then defines a class C that implements the shareable interface SI C implements the methods defined in SI C may also define other methods and fields but these are protected by the applet firewall Only the methods defined in SI are accessible to other applets 3 Applet A creates an object instance O of class C O belongs to applet A and the firewall allows A to access any of the fields and methods of O Client Applet B Obtains the Shareable Interface Object 1 To access applet A s object O applet B creates an object reference SIO of type SI 2 Applet B invokes a special method JCSystem getAppletShareableInterfaceObject described in Section 6 2 7 2 TCSystem getAp
164. ssed by its owning context that is when the owning context is the currently active context The firewall prevents an object from being accessed by another applet in a different context In implementation terms each time an object is accessed the object s owner context is compared to the currently active context If these do not match the access is not performed and a SecurityException is thrown An object is accessed when one of the following bytecodes is executed using the object s reference getfield putfield invokevirtual invokeinterface athrow lt T gt aload lt T gt astore arraylength checkcast instanceof lt T gt refers to the various types of array bytecodes such as baload and sastore This list includes any special or optimized forms of these bytecodes implemented in the Java Card VM such as getfield_b and getfield_s_this Transient Objects and Contexts Transient objects of CLEAR_ON_RESET type behave like persistent objects in that they can be accessed only when the currently active context is the object s owning context the currently active context at the time when the object was created Transient objects of CLEAR_ON_DESELECT type can only be created or accessed when the currently active context is the context of the currently selected applet If any of the makeTransient factory methods of JcSystem class are called to create a CLEAR_ON_DESELECT type transient object when the currently active c
165. t INS gt or lt INS gt procedure byte mechanism 2 The card sends lt 0x61 Lr Le gt completion status bytes 3 The CAD sends GET RESPONSE command with new Le lt Lr 4 The card sends new Le bytes of output data using the standard T 0 lt INS gt or lt INS gt procedure byte mechanism 5 Repeat steps 2 4 as necessary to send the remaining output data bytes Lr as required 6 The card sends lt SW1 SW2 gt completion status on completion of the Applet process method ISO 7816 4 CASE 4 In Case 4 Le is determined after the following initial exchange 1 The card sends lt 0x61 Lr gt status bytes 2 The CAD sends GET RESPONSE command with Le lt Lr The rest of the protocol sequence is identical to CASE 2 described above In all cases of constrained outbound transfers with no chaining if the applet aborts early and sends less than Le bytes zeros shall be sent instead to fill out the length of the transfer expected by the CAD Regular Output Transfers When the no chaining mode of output transfer is not requested by the applet that is the setOutgoing method is used any ISO IEC 7816 3 4 compliant T 0 protocol transfer sequence may be used If the applet aborts early and sends less than the applet response length Lr set via setOutgoingLength method only the data bytes written via the send methods of the APDU class are sent to the CAD Note The waitExtension method may be invoked by the applet a
166. t any time The waitExtension method shall request an additional work waiting time ISO IEC 7816 3 2004 using the 0x60 procedure byte Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 9 4 1 3 9 4 2 9 4 2 1 Additional T 0 Requirements At any time when the T 0 output transfer protocol is in use and the APDU class is awaiting a GET RESPONSE command from the CAD in reaction to a response status of lt 0x61 xx gt from the card if the CAD sends in a different command on the same origin logical channel or a command on a different origin logical channel the sendBytes or the sendBytesLong methods shall throw an APDUException with reason code NO_T0_GETRESPONSE At any time when the T 0 output transfer protocol is in use and the APDU class is awaiting a command reissue from the CAD in reaction to a response status of lt 0x6C xx gt from the card if the CAD sends in a different command on the same origin logical channel or a command on a different origin logical channel the sendBytes or the sendBytesLong methods shall throw an APDUException with reason code NO_TO_REISSUE Calls to sendBytes or sendBytesLong methods after the NO_TO0_GETRESPONSE exception or the NO_TO_REISSUE exception is thrown shall result in an APDUException with reason code ILLEGAL_USE If an ISOException is thrown by the applet after the NO_TO_GETRESPONSE exception or the NO_TO0_REISSUE exception is thrown the Ja
167. t make up a package and converts the package to a CAP file The Converter also produces an export file when an object instance method is invoked an owning context of this object becomes the currently active context the Java Card RE keeps track of the currently selected Java Card applet Upon receiving a SELECT FILE command with this applet s AID the Java Card RE makes this applet the currently selected applet The Java Card RE sends all APDU commands to the currently selected applet a new component added to the CAP file The new component must conform to the general component format It is silently ignored by a Java Card virtual machine that does not recognize the component The identifiers associated with the new component are recorded in the custom_component item of the CAP file s Directory component an applet that is selected by default on a logical channel when it is opened If an applet is designated the default applet on a particular logical channel on the Java Card platform it becomes the active applet by default when that logical channel is opened using the basic channel an acronym for Electrically Erasable Programmable Read Only Memory see Java Card RE entry point objects Glossary 3 Export file externally visible finalization firewall flash memory framework garbage collection heap installer installation program a file produced by the Converter that represents the fields and methods of a
168. te 5 HAND_GEOMETRY byte 6 SIGNATURE byte 7 KEYSTROKES byte 8 LIP_MOVEMENT byte 9 Chapter 12 API Constants 12 11 public static final byte THERMAL FACE byte 10 public static final byte THERMAL HAND byte 11 public static final byte GAIT_STYLE byte 12 public static final byte BODY_ODOR byte 13 public static final byte DNA_SCAN byte 14 public static final byte EAR_GEOMETRY byte 15 public static final byte FINGER_GEOMETRY byte 16 public static final byte PALM GEOMETRY byte 17 public static final byte VEIN_PATTERN byte 18 public static final byte PASSWORD byte 31 public static final byte DEFAULT_INITPARAM byte 0 12 20 Class javacardx biometry BioException public static final short ILLEGAL_VALUE short 1 public static final short INVALID_DATA short 2 public static final short NO_SUCH_BIO_TEMPLATE short 3 public static final short NO_TEMPLATES ENROLLED short 4 public static final short ILLEGAL USE short 5 12 21 Class javacardx biometry BioTemplate public static final short MINIMUM_SUCCESSFUL_MATCH_SCOR short 16384 Lar public static final short MATCH NEEDS MORE_DATA short 1 12 22 Class javacardx crypto Cipher public static final byte ALG_DES_CBC_NOPAD 1 12 12 Runtime Environment
169. te directly to memory bypassing the object system and or standard security m Access objects owned by other applets or by the Java Card RE m Invoke non entry point methods of the Java Card RE Again it is up to each Java Card RE implementer to determine the Applet Deletion Manager implementation and supply such features in their Java Card RE implementations as necessary to support their Applet Deletion Manager Java Card RE implementers are also responsible for the security of such features so that they are not available to normal applets Chapter 11 Applet Installation and Deletion 11 13 11 14 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 1 2 API Constants Some of the API classes do not have values specified for their constants in Application Programming Interface Java Card Platform Version 2 2 2 If constant values are not specified consistently by implementers of this Runtime Environment Specification Java Card Platform Version 3 0 Classic Edition industry wide interoperability is impossible This chapter provides the required values for constants that are not specified in the Application Programming Interface Java Card Platform Version 2 2 2 12 1 Class javacard framework APDU public static final byte PROTOCOL_TYPE_MASK byte 0x0F public static final byte PROTOCOL_TO 0 public static final byte PROTOCOL_T1 Te public static final byte PROT
170. ter output password AaBbCc123 Book titles new words or terms Read Chapter 6 in the User s Guide words to be emphasized These are called class options Replace command line variables You must be superuser to do this with real names or values To delete a file type rm filename The settings on your browser might differ from these settings Related Documentation References to various documents or products are made in this guide so you might want to have them available m Application Programming Notes for the Java Card Platform Version 2 2 2 a Application Programming Interface Java Card Platform Version 3 0 Classic Edition xviii Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 m Application Programming Interface Java Card Platform Version 3 0 Connected Edition m Runtime Environment Specification Java Card Platform Version 3 0 Connected Edition m Virtual Machine Specification Java Card Platform Version 3 0 Classic Edition m Virtual Machine Specification Java Card Platform Version 3 0 Connected Edition m The Java Language Specification by James Gosling Bill Joy and Guy L Steele Addison Wesley 1996 m The Java Virtual Machine Specification Java Series Second Edition by Tim Lindholm and Frank Yellin Addison Wesley 1999 m The Java Remote Method Invocation Specification Sun Microsystems Inc http java sun com javase technologies core bas
171. the applet is deselected 3 5 uninstall Method This method is defined in the javacard framework AppletEvent interface When the Java Card RE is preparing to delete the applet instance the Java Card RE calls this method if implemented by the applet to inform it of the deletion request Upon return from this method the Java Card RE checks for reference dependencies before deleting the applet instance This method may be called multiple times once for each applet deletion attempt 3 6 3 4 Power Loss and Reset Power loss occurs under one of the following conditions m The card is withdrawn from the CAD m When operating in contactless only mode the card loses carrier energy from the radio frequency RF field and enters the POWER OFF state as defined in the ISO 14443 Specification Parts 1 4 m When operating in contactless only mode the card receives a Supervisory block S block DESELECT command and enters the HALT state as defined in the ISO 14443 Specification Parts 1 4 m When operating in contactless only mode a card whose contactless interface is accessed through a contactless front end using the European Telecommunications Standards Institute ETSI defined single wire protocol SWP standard ETSI TS 102 613 is reset by a data link layer SHDLC RSET signal m A mechanical or electrical failure occurs on the card When power is reapplied to the card and on card reset warm or cold the Java Card RE shal
172. the method MultiSelectable deselect is called Only when the multiselected applet instance is the last active applet instance in the applet s context is its regular method Applet deselect called The following list describes the two cases of multiselection Chapter 4 Logical Channels and Applet Selection 4 7 4 8 1 When two distinct applet instances from within the same package are multiselected each applet instance shares the same CLEAR_ON_DESELECT memory transient segment The applet instances share objects within the context firewall as well as their transient data The Java Card RE shall not reset this CLEAR_ON_DESELECT transient objects until all applet instances within the package are deselected see FIGURE 4 2 FIGURE 4 2 Different Applet Instances in Same Package Logical Channels oft feds T Applet A Applet B Package P3 CLEAR_ON_DESELECT Memory Segments 2 When the same applet instance is multiselected on two different logical channels simultaneously it shares the CLEAR_ON_DESELECT memory segment space across logical channels The Java Card RE shall not reset the CLEAR_ON_DESELECT transient objects until all applet instances within the package are deselected see FIGURE 4 3 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 FIGURE 4 3 Same Applet Instance Selected on Multiple Logical Channels Logical Channels Applet A Package P4 CLEAR_ON_DESELECT Memory
173. the process method The actual change occurs before the call to the select method On normal return the Java Card RE automatically appends 0x9000 as the completion response status word to any data already sent by the applet At any time during process the applet may throw an ISOException with an appropriate status word in which case the Java Card RE catches the exception and returns the status word to the CAD If any other exception is thrown during process the Java Card RE catches the exception and returns the status word 1907816 SW_UNKNOWN to the CAD 3 4 deselect Method s When the Java Card RE receives a SELECT FILE APDU command in which the name matches the AID of an applet the Java Card RE calls the Applet deselect method of the currently selected applet or if concurrently selected on more than one logical channel its MultiSelectable deselect method For more details see Section 4 2 Chapter 3 Java Card Applet Lifetime 3 3 Multiselectable Applets on page 4 7 Applet deselection may also be requested by the MANAGE CHANNEL CLOSE command For more details see Section 4 6 Applet Deselection on page 4 18 The deselect method allows the applet to perform any cleanup operations that may be required to allow some other applet to execute The Applet selectingApplet method shall return false when called during the deselect method Exceptions thrown by the deselect method are caught by the Java Card RE but
174. the response status in its reason code The Java Card RE shall restart APDU processing with the newly received command and resume APDU dispatching T 1 Specifics for Incoming Data Transfers Incoming Transfers Using Chaining Chain Abortion by the CAD If the CAD aborts a chained inbound transfer using an S block ABORT request see ISO IEC 7816 3 2004 the set IncomingAndReceive or receiveBytes method shall throw an APDUException with reason code T1_IFD_ABORT Calls to receiveBytes sendBytes or sendBytesLong methods from this point on shall result in an APDUException with reason code ILLEGAL_USE If an ISOException is thrown by the applet after the T1_IFD_ABORT exception is thrown the Java Card RE shall discard the response status in its reason code The Java Card RE shall restart APDU processing with the newly received command and resume APDU dispatching Extended Length APDU Specifics The card may support extended length APDU exchanges with the CAD as described in the ISO 7816 3 Specification If the implementation does not support extended length APDU formats when the T 0 APDU transfer protocol is in use and receives an ENVELOPE ISO Inter industry CLA INS 0xC2 command it must forward the ENVELOPE command to the currently selected applet on the origin logical channel If the implementation does not support extended length APDU formats when the T 1 APDU transfer protocol is in use and an APDU with extended length is rec
175. the specified logical channel the Java Card RE responds with status code 0x6999 SW_APPLET_SELECT_FAILED Otherwise the active applet instance on this logical channel is set as the currently selected applet instance and the SELECT FILE command is forwarded to that applet instance s process method A context switch into the applet instance s context occurs at this point see Section 6 1 1 Firewall Protection on page 6 1 If the implementation supports partial DF name selection and the AID of an applet instance is a truncation of the AID of another applet instance on the card implementation defined rules of first DF name selection may be applicable Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 Applets may use the SELECT FILE command for their own internal processing Upon return from the applet s process method the Java Card RE sends the applet instance s response as the response to the SELECT FILE command If the candidate applet instance is not a multiselectable applet and the candidate applet s context is active the logical channel remains open and the Java Card RE records an error response status code of 0x6985 SW_CONDITIONS_NOT_SATISFIED Prior to sending the response code if there is an active applet instance on the logical channel then the Java Card RE may optionally deselect the applet instance as described in Section 4 6 Applet Deselection on page
176. the transaction is committed or aborted Chapter 7 Transactions and Atomicity 7 5 7 6 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 8 Remote Method Invocation Service Java Card platform Remote Method Invocation Java Card RMI is a subset of the Java platform Remote Method Invocation RMI system It provides a mechanism for a client application running on the CAD platform to invoke a method on a remote object on the card The on card transport layer for Java Card RMI is provided in the package javacard framework service by the class RMIService It is designed as a service requested by the Java Card RMI based applet when it is the currently selected applet The Java Card RMI message is encapsulated within the APDU object passed into the RMIService methods 8 1 Java Card Platform RMI This section defines the subset of the RMI system that is supported by Java Card platform RMI ome Remote Objects A remote object is one whose remote methods can be invoked remotely from the CAD client A remote object is described by one or more remote interfaces A remote interface is an interface that extends directly or indirectly the interface java rmi Remote The methods of a remote interface are referred to as remote methods A remote method declaration includes the exception java rmi RemoteException or one of its superclasses such as java io IOException or java lang Exception
177. thods of these objects are accessible through the firewall The fields of these objects are still protected by the firewall and can only be accessed by the Java Card RE context Only the Java Card RE itself can designate Entry Point Objects and whether they are temporary or permanent Java Card RE implementers are responsible for implementing the mechanism by which Java Card RE Entry Point Objects are designated and how they become temporary or permanent Global Arrays The global nature of some objects requires that they be accessible from any context The firewall would ordinarily prevent these objects from being used in a flexible manner The Java Card VM allows an object to be designated as global All global arrays are temporary global array objects These objects are owned by the Java Card RE context but can be accessed from any context However references to these objects cannot be stored in class variables instance variables or array components The Java Card RE detects and restricts attempts to store references to these objects as part of the firewall functionality to prevent unauthorized reuse For added security only arrays can be designated as global and only the Java Card RE itself can designate global arrays Because applets cannot create them no API methods are defined Java Card RE implementers are responsible for implementing the mechanism by which global arrays are designated Chapter 6 Applet Isolation and Object Shari
178. tifier and information to identify the associated class Method Invocation To request a method invocation the CAD client provides the following information a The remote object identifier This identifier is used to uniquely identify the object on the card m The invoked method identifier This designator uniquely identifies the remote method within the remote object class or superclass m The values of the arguments These values are raw values for primitive data types and for arrays a length followed by the values The response to the invocation request may include one of the following items A primitive return value This is a raw primitive data type value a An array of primitive components This is a length followed by the raw primitive data type values a A remote object reference descriptor The descriptor includes the remote object identifier and information to instantiate a proxy instance of the remote card object a An exception This is thrown by the remote method 8 3 8 4 Data Formats This section describes the formats used to encapsulate the following m A remote object identifier that identifies the remote object on the card a A remote object reference descriptor that describes the remote object on the card for the CAD client m A method identifier that identifies the remote method on the card m The method parameters and return values This section uses a C like structure notation similar to th
179. tless I O interface is reset to the default value m If the Java Card RE implements default applet selection see Section 4 1 Default Applets on page 4 4 the default applet is selected as the active applet instance for the basic logical channel channel 0 on the contacted I O interface and the default applet s select method is called Otherwise the Java Card RE sets its state to indicate that no applet is active on the basic logical channel on the contacted I O interface Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 CHAPTER 4 Logical Channels and Applet Selection The Java Card Platform version 3 0 provides support for logical channels The ability to allow a terminal to open up to twenty sessions into the smart card over any I O interface one session per logical channel Logical channels functionality is described in detail in the ISO 7816 4 2005 Specification Cards receive requests for service from the CAD in the form of APDUs The SELECT FILE APDU and MANAGE CHANNEL OPEN APDU are used by the Java Card RE to designate the active applet instance for a logical channel session Once selected an applet instance receives all subsequent APDUs dispatched to that logical channel until the applet instance becomes deselected Java Card platforms support the following I O interface configurations a Asingle contacted I O interface conforming to ISO 7816 parts 1 4 specifications
180. ustom CAP file component default applet EEPROM entry point objects the constant pool contains variable length structures representing various string constants class names field names and other constants referred to within the CAP file and the Export File structure Each of the constant pool entries including entry zero is a variable length structure whose format is indicated by its first tag byte There are no ordering constraints on entries in the constant pool entries One constant pool is associated with each package There are differences between the Java platform constant pool and the Java Card technology based constant pool For example in the Java platform constant pool there is one constant type for method references while in the Java Card constant pool there are three constant types for method references The additional information provided by a constant type in Java Card technologies simplifies resolution of references protected object space associated with each applet package and Java Card RE All objects owned by an applet belong to context of the applet s package a change from one currently active context to another For example a context switch is caused by an attempt to access an object that belongs to an applet instance that resides in a different package The result of a context switch is a new currently active context a piece of software that preprocesses all of the Java programming language class files tha
181. uvernement des Etats Unis logiciel commercial Les droits des utilisateur du gouvernement des Etats Unis sont soumis aux termes de la licence standard Sun Microsystems et aux conditions appliqu es de la FAR et de ces compl ments L utilisation est soumise aux termes de la Licence Cette distribution peut comprendre des composants d velopp s par des tierces parties Des parties de ce produit pourront tre d riv es des syst mes Berkeley BSD licenci s par l Universit de Californie Sun Sun Microsystems le logo Sun Solaris Java Java Card Javadoc JDK Servlet et JVM sont des marques de fabrique ou des marques d pos es de Sun Microsystems Inc aux Etats Unis et dans d autres pays UNIX est une marque d pos e aux Etats Unis et dans d autres pays et licenci e exlusivement par X Open Company Ltd Le logo Adobe est une marque d pos e de Adobe Systems Incorporated Les produits qui font l objet de ce manuel d entretien et les informations qu il contient sont regis par la legislation americaine en matiere de controle des exportations et peuvent etre soumis au droit d autres pays dans le domaine des exportations et importations Les utilisations finales ou utilisateurs finaux pour des armes nucleaires des missiles des armes biologiques et chimiques ou du nucleaire maritime directement ou indirectement sont strictement interdites Les exportations ou reexportations vers des pays sous embargo des Etats Unis ou vers des entites fi
182. va Card RE shall discard the response status in its reason code The Java Card RE shall restart APDU processing with the newly received command and resume APDU dispatching T 1 Specifics for Outgoing Data Transfers The setOutgoing and setOutgoingNoChaining methods in the APDU class are used to specify that data needs to be returned to the CAD These methods return the expected length Le value as follows when extended length semantics are not enabled see Section 9 4 4 1 Extended Length API Semantics on page 9 8 ISO 7816 4 CASE 1 0 ISO 7816 4 CASE 2 Le If Le 0 256 ISO 7816 4 CASE 3 0 ISO 7816 4 CASE 4 Le If Le 0 256 Constrained Transfers With No Chaining When the no chaining mode of output transfer is requested by the applet by calling the setOutgoingNoChaining method the following protocol specifics shall be followed Chapter 9 API Topics 9 5 9 4 2 2 9 6 Notation Le CAD expected length Lr Applet response length set via setOutgoingLength method The transport protocol sequence shall not use block chaining Specifically the M bit more data bit shall not be set in the PCB of the I blocks during the transfers ISO IEC 7816 3 2004 The entire outgoing data Lr bytes shall be transferred in one I block If the applet aborts early and sends less than Lr bytes zeros shall be sent instead to complete the remaining length of the block Note When the no chaining mode is used
183. xception 12 15 constants API 12 1 context Glossary 3 Index 2 Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 switch Glossary 3 context applet 4 7 contexts 6 2 6 13 currently active 6 3 Java Card RE 6 3 6 10 object accessing across 6 8 rules in firewall 6 4 switching 6 2 7 5 in the VM 6 4 system 6 10 Converter Glossary 3 crypto packages 9 9 currently active context Glossary 3 currently selected applet Glossary 3 currently selected applet instance 4 3 custom CAP file component Glossary 3 D data formats 8 4 default applet Glossary 3 deletion 3 1 applet 11 1 11 7 deselect method 3 3 deselection 3 2 applet 4 18 E EEPROM Glossary 3 Electrically Erasable Programmable Read Only Memory Glossary 3 encoding error response 8 12 exception response 8 11 normal response 8 10 parameter 8 8 return value 8 10 entry point objects Glossary 3 entry point objects Java Card RE Glossary 5 error response encoding 8 12 exceptions objects 6 18 response encoding 8 11 thrown by the API 9 1 Export file Glossary 4 extension packages 9 11 externally visible Glossary 4 F fields 5 1 accessing class instance object 6 17 accessing static class 6 16 static 6 7 finalization Glossary 4 firewall Glossary 4 applet 6 1 flash memory Glossary 4 formats APDU command 8 13 data 8 4 framework Glossary 4 G garbage collection Glossary
184. xts and applets Isolation means that one applet cannot access the fields or objects of an applet in another context unless the other applet explicitly provides an interface for access The Java Card RE mechanisms for applet isolation and object sharing are detailed in the following sections 6 1 6 1 1 Applet Firewall The applet firewall within Java Card technology is runtime enforced protection and is separate from the Java technology protections The Java programming language protections still apply to Java Card applets The Java programming language ensures that strong typing and protection attributes are enforced Applet firewalls are always enforced in the Java Card VM They allow the VM to automatically perform additional security checks at runtime Firewall Protection The Java Card technology based firewall Java Card firewall provides protection against the most frequently anticipated security concern developer mistakes and design oversights that might allow sensitive data to be leaked to another applet An applet may be able to obtain an object reference from a publicly accessible location However if the object is owned by an applet protected by its own firewall the requesting applet must satisfy certain access rules before it can use the reference to access the object 6 1 6 1 2 The firewall also provides protection against incorrect code If incorrect code is loaded onto a card the firewall still protects
185. y called out in the API descriptions updates to internal implementation state within the API objects must be conditional Internal state updates must participate in any ongoing transaction 9 4 9 4 1 9 2 APDU Class The APDU class encapsulates access to the ISO 7816 4 based I O across the card serial line The APDU class is designed to be independent of the underlying I O transport protocol The Java Card RE may support T 0 or T 1 transport protocols or both T 0 Specifics for Outgoing Data Transfers The setOutgoing and setOutgoingNoChaining methods in the APDU class are used to specify that data needs to be returned to the CAD These methods return the expected length Le value as follows when extended length semantics are not enabled see Section 9 4 4 1 Extended Length API Semantics on page 9 8 ISO 7816 4 CASE 1 Not applicable Assume Case 2 ISO 7816 4 CASE 2 P3 If P3 0 256 ISO 7816 4 CASE 3 Not applicable Assume Case 4 ISO 7816 4 CASE 4 256 For compatibility with legacy CAD terminals that do not support block chained mechanisms the APDU class allows a non chained transfer mode selection via the setOutgoingNoChaining method The related behaviors are discussed in the following sections Runtime Environment Specification Java Card Platform v3 0 Classic Edition e March 2008 9 4 1 1 Constrained Transfers With No Chaining When the no chaining mode of output transfer is requested by the applet b
186. y calling the setOutgoingNoChaining method the following protocol sequence shall be followed When the no chaining mode is used that is after the invocation of the setOutgoingNoChaining method calls to the waitExtension method shall throw an APDUException with reason code ILLEGAL_USE Notation Le CAD expected length Lr Applet response length set via setOutgoingLength method lt INS gt the protocol byte equal to the incoming header INS byte which indicates that all data bytes will be transferred next lt INS gt the protocol byte that is the complement of the incoming header INS byte which indicates that 1 data byte will be transferred next lt SW1 SW2 gt the response status bytes as in ISO7816 4 ISO 7816 4 CASE 2 Le Lr 1 The card sends Lr bytes of output data using the standard T 0 lt INS gt or lt INS gt procedure byte mechanism 2 The card sends lt SW1 SW2 gt completion status on completion of the Applet process method Lr lt Le 1 The card sends lt 0x61 Lr gt completion status bytes 2 The CAD sends GET RESPONSE command with Le Lr 3 The card sends Lr bytes of output data using the standard T 0 lt INS gt or lt INS gt procedure byte mechanism 4 The card sends lt SW1 SW2 gt completion status on completion of the Applet process method Chapter 9 API Topics 9 3 9 4 1 2 9 4 Lr gt Le 1 The card sends Le bytes of output data using the standard T 0 l

JavaCard Runtime Environment Specification, Version

Contents

Download Pdf Manuals

Related Search

Related Contents