| Development Kit User’s Guide |    
|
| Development Kit User’s Guide |
|
| C H A P T E R 4 |
|
Running the Samples |
The samples directory under JC_CLASSIC_HOME contains classic applet applications and reference applications that demonstrate the features of the Java Card 3, Classic Edition API. The reference application samples are blue print-like applications that demonstrate the interactions between various applications on the card using advanced features such as SIO and events.
This chapter describes the procedures for running the samples and contains the following sections:
This section contains the following general procedures that developers use to build and run a sample. By default, the build script in the binary release produces a 32-bit version of cref that supports dual interfaces of T=CL and T=1 protocols.
Each sample has a build.xml in its applet folder and, if applicable, client folder. If changes are made to a sample source file, developers can quickly test their changes by using build.xml with the ant tool to build a sample without running it. The ant tool uses the build.xml and the Development Kit tools to compile the Java programming language sources, convert the Java programming language class files, generate the APDU script files, and build the sample.
The ant tool runs the tools required to build the sample and generates the required output files. It displays a build status message at completion of the task.
See Part II and Programming Notes, Java Card 3 Platform, Classic Edition for information about creating classic applets.
Before building and running a sample, verify that ant can be run from the command line and that JC_CLASSIC_HOME is set to the Development Kit installation directory in the Environment Variables dialog. Contents of All Releases identifies the directory in which the Development Kit was installed. See Contents of All Releases for installation and configuration instructions.
Three general actions are performed when running a sample:
1. In a Command Prompt window, start the RI by using the cref command with the options specified by the sample.
See Chapter 9 for more information about using cref and its command line options.
2. In a second Command Prompt window, from the sample directory containing the appropriate build.xml file run the ant command with the appropriate target:
In the command, target represents the run option (such as all or run1-1) specified in the procedures for running the sample. Each sample might use one or more targets to run specific APDU scripts or multiple parts of the sample applet. The required targets are described in the procedures used to run an individual sample
With the exception of the Transit, RMIPurse, and SecureRMIPurse samples, a custom name can be specified for the output file generated by the ant command. Use the following command syntax to specify a custom name for the output file:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file This command redirects the output from the APDUtool execution to the .outputfile_name file.
3. Perform any additional actions required by the individual sample’s run procedure.
Additional actions might include restarting the RI and using ant with an appropriate target to run additional APDU scripts generated by the build. These actions are described in the procedures used to run each sample.
The following sections describe the following development kit samples in order of their complexity and provide procedures for running them:
HelloWorld is a minimal applet utilizing the simplest source code and meta-files. See HelloWorld Sample.
See Channels Sample.
See Service Sample.
See Utility Sample.
See Wallet Sample.
See PhotoCard Sample.
The basic example used is a program that manages a counter remotely, and is able to decrement, increment, and return the value of an account. See RMIPurse Sample and Chapter 15, Programming to the Java Card RMI Client-Side API.
This sample is only included in bundles intended solely for distribution inside the U.S. See SecureRMIPurse Sample.
This sample is only included in bundles intended solely for distribution inside the U.S. See SignatureMessageRecovery Sample.
The HelloWorld sample demonstrates the base structure of a Java Card 3 platform applet that developers can use to develop, deploy, create, execute, delete, and unload a stand-alone module.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref
| Note - cref command options are not required in this sample. |
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\HelloWorld\applet directory.
b. Enter the ant all command at the command prompt.
In this sample, the ant all command builds the applet, executes the APDU script, and creates an output file in the applet directory. The ant script names the output file either default.out or the custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the HelloWorld.expected.out file.
The Channels sample demonstrates the behavior of Java Card technology-based logical channels by showing how two applets that interact with each other can each be selected for use at the same time.
The applets may use a contact or contactless interface for communication with the terminal. The Channels sample demonstrates the selection of an applet on both interfaces. The sample also demonstrates use of ExtendedLength APDU.
The Channels sample mimics the behavior of a wireless device connected to a network service. A connection manager tracks whether the device is connected to the service and whether the connection is local or remote.
While it is connected, the user’s account is debited on a unit of time basis. The debit rate is based on whether the connection is local or remote, and uses either the contacted or contactless interface.
The sample employs two applets to simulate the behavior of logical channels:
When the user turns on the device, the ConnectionManager applet is selected. The ConnectionManager implements the ExtendedLength interface to handle APDUs with larger data segments such as the ones used for key exchange in the sample. Every unit of time the terminal sends a message containing the area code to the card.
When the user wants to use the service, the AccountAccessor applet is selected on another logical channel so that the terminal can query the balance. The AccountAccessor can return the balance only if the ConnectionManager is active. The ConnectionManager applet sets the connection and tracks the connection status. Based on the value of an area code variable, the ConnectionManager determines whether the connection is local or remote. It also determines whether the connection is contacted or contactless. AccountAccessor uses this information to debit the account at the appropriate rate. The connection is disabled when the user completes the call or when the account is depleted.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref
| Note - cref command options are not required in this sample. |
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\Channels\applet directory.
b. Enter the ant all command at the command prompt.
In this sample, the ant all command builds the applet, executes the APDU script, and creates an output file in the applet directory. The ant script names the output file either default.out or the custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the Channels.expected.out file.
Java Card platform provides a service framework of classes and interfaces that allow a Java Card technology-based applet to be designed as an aggregation of service components. Service demo essentially demonstrates this. The class Main.java adds a TestService to process the APDUs dispatched by the client. Based on the contents of INS command in the APDU sent it does the following:
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref
| Note - cref command options are not required in this sample. |
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\Service\applet directory.
b. Enter the ant all command at the command prompt.
In this sample, the ant all command builds the applet, executes the APDU script, and creates an output file in the applet directory. The ant script names the output file either default.out or the custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the service.expected.out file.
The Utility sample demonstrates how the utility APIs can be used in an application. This applet is a simple version of a hypothetical broker applet that is used to assist the user in buying and selling stocks. The applet uses constructed TLVs and primitive TLVs to manage the portfolio. The communication with the broker is also in the form of TLVs and uses the math API to determine the value of a trade. It also uses the new integer API to construct an integer from byte array and set integers in byte arrays for TLV objects.
This applet provides the following features:
Uses the standard PIN API in the Java Card platform to protect access to the applet.
The applet uses a portfolio constructed TLV to store the information regarding all the stocks that the user currently holds. The information is stored in the form of stockInfo constructed TLV. Each stockInfo TLV contains the following:
The applet assists the user in buying and selling stocks by creating a “signed” purchasing or selling request for the broker in the form of a stock purchase request constructed TLV or sell stock request constructed TLV. Before the request is generated, the applet checks to see if the user has enough stocks in case the request is to sell the stock and enough account balance if the request is to buy new stock. The request is sent back to the terminal where the terminal application may retrieve the TLV from the response APDU and send it to the broker.
If the trade is successful, the broker sends back a confirmation message in the form a sell confirmation TLV or purchase confirmation TLV. The applet retrieves the information from the confirmation TLV and updates the portfolio as follows:
User may use this feature to get information regarding a specific stock rather than retrieving the whole portfolio. If a stock is not found, the appropriate exception is thrown. The information is returned in the form of a stockInfo TLV that contains the following:
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref
| Note - cref command options are not required in this sample. |
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\Utility\applet directory.
b. Enter the ant all command at the command prompt.
In this sample, the ant all command builds the applet, executes the APDU script, and creates an output file in the applet directory. The ant script names the output file either default.out or the custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the utility.expected.out file.
The Wallet sample demonstrates a simplified cash card application. It keeps a balance, and exercises some of the Java Card API features such as the use of a PIN to control access to the applet.
The script file wallet.scr contains the sequence in which this is done.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref
| Note - cref command options are not required in this sample. |
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\Wallet\applet directory.
b. Enter the ant all command at the command prompt.
In this sample, the ant all command builds the applet, executes the APDU script, and creates an output file in the applet directory. The ant script names the output file either default.out or the custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the wallet.expected.out file.
The sample generates the following four APDU scripts that demonstrate the object deletion mechanism, applet deletion, and package deletion:
odDemo1-1.scr does not depend on any other sample. The final state of cref memory must be saved to a file for odDemo1-2.scr to use.
The odDemo1-2.scr sample must be run after odDemo1-1.scr because the initial state of cref must be the same as its final state after running odDemo1-1.scr. After running odDemo1-2.scr, the final state of cref must be saved to a file so it can be used by odDemo1-3.scr.
The odDemo1-3.scr sample must be run after odDemo1-2.scr because the initial state of cref must be the same as its final state after running odDemo1-2.scr.
The four APDU scripts are run individually from a Command Prompt window. The RI must be restarted before running each APDU script.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref -o e2p
2. In a different Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\ObjectDeletion\applet directory.
b. Enter the ant all command at the command prompt.
In this sample, the ant all command generates the APDU script.
3. In the cref Command Prompt window, stop the RI by using ctrl + c.
4. In the cref Command Prompt window, restart the RI by entering the following command:
5. In the applet Command Prompt window, enter the following command at the command prompt:
ant run1-1
The ant run1-1 command executes the od1-1.scr APDU script and creates an output file in the applet directory. The ant script names the output file either default.out or the custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
6. Verify that the contents of the output file in the applet directory are the same as the contents of the od1-1.expected.out file.
7. In the cref Command Prompt window, restart the RI by entering the following command:
8. In the applet Command Prompt window, enter the following command at the command prompt:
ant run1-2
The ant run1-2 command executes the od1-2.scr APDU script and creates an output file (default.out) in the applet directory. See Step 5 for the command line required to specify a custom output file name.
9. Verify that the contents of the output file in the applet directory are the same as the contents of the od1-2.expected.out file.
10. In the cref Command Prompt window, restart the RI by entering the following command:
11. In the applet Command Prompt window, enter the following command at the command prompt:
ant run1-3
The ant run1-3 command executes the od1-3.scr APDU script and creates an output file (default.out) in the applet directory. See Step 5 for the command line required to specify a custom output file name.
12. Verify that the contents of the output file in the applet directory are the same as the contents of the od1-3.expected.out file.
13. In the cref Command Prompt window, restart the RI by entering the following command:
14. In the applet Command Prompt window, enter the following command at the command prompt:
ant run2
The ant run2 command executes the od2.scr APDU script and creates an output file (default.out) in the applet directory. See Step 5 for the command line required to specify a custom output file name.
15. Verify that the contents of the output file in the applet directory are the same as the contents of the od2.expected.out file.
16. In the cref Command Prompt window, restart the RI by entering the following command:
17. In the applet Command Prompt window, enter the following command at the command prompt:
ant run2-2
The ant run2-2 command executes the od2-2.scr APDU script and creates an output file (default.out) in the applet directory. See Step 5 for the command line required to specify a custom output file name.
18. Verify that the contents of the output file in the applet directory are the same as the contents of the od2-2.expected.out file.
19. In the cref Command Prompt window, restart the RI by entering the following command:
20. In the applet Command Prompt window, enter the following command at the command prompt:
ant run3
The ant run3 command executes the od3.scr APDU script and creates an output file (default.out) in the applet directory. See Step 5 for the command line required to specify a custom output file name.
21. Verify that the contents of the output file in the applet directory are the same as the contents of the od3.expected.out file.
22. In the cref Command Prompt window, restart the RI by entering the following command:
23. In the applet Command Prompt window, enter the following command at the command prompt:
ant run3-2
The ant run3-2 command executes the od3-2.scr APDU script and creates an output file (default.out) in the applet directory. See Step 5 for the command line required to specify a custom output file name.
24. Verify that the contents of the output file in the applet directory are the same as the contents of the od3-2.expected.out file.
The PhotoCard sample illustrates how to use the large address space available in the 32-bit version of the RI. The sample uses the large address space of the smart card’s EEPROM memory to store up to four GIF images. The images are included with the sample.
The PhotoCard sample consists of two parts: a card applet and a client program communicating with it. The photocard sample employs a collection of arrays to store large amounts of data. The arrays allow the applet to take advantage of the platform’s capabilities by transparently storing data.
The design and coding of applications that use the large address space to access memory must adhere to the target platform’s requirements. Smart cards have limited resources, code cannot be guaranteed to behave identically on different cards. For example, if the photocard applet runs on a card with less mutable persistent memory available for storage, it might run out of memory space when it attempts to store the images. A set of inputs might not produce the same set of outputs in an RI with different characteristics. The applet code must account for any different implementation-specific behavior.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref -o demoee
Starting the RI with the -o demoee option and filename causes the RI to save the EEPROM contents to a file named demoee. See Chapter 9 for more information about using cref and its command line options.
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\PhotoCard\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command executes the APDU script, installs the photocard application, and creates an output file (default.out) in the applet directory.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the photocard-applet.expected.out file.
4. In the cref Command Prompt window, restart the RI by using the following command:
cref -z -i demoee
Starting the RI with the -z -i demoee option and filename causes the RI to use the contents of the demoee file to initialize the EEPROM and to display the resource consumption statistics. See Chapter 9 for more information about using cref and its command line options.
5. In the applet Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\PhotoCard\client directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s client directory, the ant all command executes the APDU script and an output file (actual_output.txt) in the applet directory.
6. Verify that the contents of the actual_output.txt file are the same as the contents of the photocard-client.expected.out file.
A Java Card RMI application consists of two parts: a card applet and a client program communicating with it. In this case, the RMIPurse applet is installed in EEPROM image. For further details see Chapter 15, Programming to the Java Card RMI Client-Side API.
The RMIPurse sample uses the card applet PurseApplet, the Purse interface and its implementation PurseImpl. These classes reside in the package com.sun.javacard.samples.RMIDemo. The client-side program PurseClient resides in the package com.sun.javacard.clientsamples.purseclient.
The Purse interface describes the supported functionality: methods for obtaining the account balance, debiting and crediting the account, and obtaining and setting an account number. The interface also defines the constants used for error reporting. The PurseImpl class implements Purse.
The card applet, PurseApplet, creates and registers instances of the dispatcher and the Java Card RMI service.
The client-side program, PurseClient, represents a simple Java Card RMI client. The program opens a connection with a card, creates the Java Card RMI Connect instance, and selects the Java Card applet (in this case, the PurseApplet). The program then gets the initial reference from PurseApplet (the reference to an instance of PurseImpl) and casts it to the Purse interface type. This allows PurseImpl to be treated as a local object. The program can then exercise the card by debiting and crediting different amounts, and by setting and getting the account number. The program demonstrates error handling by intentionally attempting to set an account number of incorrect size. This causes a UserException to be thrown with the appropriate error code.
The client part of the RMIDemo can be run without parameters or with the -i parameter:
For more information on these formats, see Chapter 8 of the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Classic Edition.
|
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref -o demoee
Starting the RI with the -o demoee option and filename causes the RI to save the EEPROM contents to a file named demoee. See Chapter 9 for more information about using cref and its command line options.
2. Open a second Command Prompt window and perform the following:
JC_CLASSIC_HOME\samples\classic_applets\RMIPurse\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command executes the APDU script and installs the RMI application.
3. In the cref Command Prompt window, restart the RI by using the following command:
cref -i demoee
Starting the RI with the -i demoee option and filename causes the RI to use the contents of the demoee file to initialize the EEPROM. See Chapter 9 for more information about using cref and its command line options.
4. In the applet Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\RMIPurse\client directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s client directory, the ant all command executes the APDU script and generates the rmidemo.actual.output file.
5. Verify that the contents of the rmidemo.actual.output file in the client directory are the same as the contents of the rmidemo.expected.output file in the RMIPurse directory.
This sample is available only in bundles intended solely for distribution inside the U.S.
The SecureRMIPurse sample is a version of RMIPurse with an added security service. SecureRMIPurse uses the card applet SecurePurseApplet, the Purse interface and its implementation SecurePurseImpl, and a definition of the security service MySecurityService. These classes reside in the package com.sun.javacard.samples.SecureRMIDemo. The sample also uses the client-side program SecurePurseClient and the specialized card accessor CustomCardAccessor. These classes reside in the package com.sun.javacard.clientsamples.SecurePurseClient.
The Purse interface is similar to the interface used in the non-secure case, however, there is an extra constant: REQUEST_DENIED. This constant is used to report situations where the client tries to invoke a method that it is not allowed to access.
The MySecurityService class is a security service that is responsible for ensuring data integrity by verifying checksums on incoming commands and attaching checksums to outgoing commands. The program also requires the client to authenticate itself as the principal application provider or principal cardholder by sending a two-byte PIN.
The implementation of Purse, SecurePurseImpl, is similar to the non-secure case, however, at the beginning of each method call, a call is made to the security service that ensures that the business rules are satisfied and that the data is not corrupted.
The applet, SecurePurseApplet, is similar to the non-secure case, with the exception that it creates and registers an instance of MySecurityService.
The client-side program, SecurePurseClient, is similar to the non-secure case, with the exception that instead of a generic card accessor, it uses its own implementation, CustomCardAccessor, to perform additional preprocessing and postprocessing of data and to support the additional command, authenticateUser.
SecurePurseClient also requires verification of the user. After the applet is inserted, a PIN must be given to the card-side applet by calling authenticateUser on CustomCardAccessor.
When authenticateUser is called, CustomCardAccessor prepares and sends the following command:
On the card side, MySecurityService processes the command. If the PIN is correct, then the appropriate flags are set in the security service and a confirmation response is returned to the client. Once authentication is passed, the client program receives the balance, credits the account, and again receives the balance. The program demonstrates error handling when the client attempts to debit a number of units from the account. This causes the program to throw a UserException with the code REQUEST_DENIED.
As with RMIDemo, the client part of the SecureRMIDemo can be run without parameters or with the -i parameter:
For more information on these formats, see Chapter 8 of the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Classic Edition.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref -o demoee
Starting the RI with the -o demoee option and filename causes the RI to save the EEPROM contents to a file named demoee. See Chapter 9 for more information about using cref and its command line options.
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\SecureRMIPurse\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command executes the APDU script and installs the secure RMI application.
3. In the cref Command Prompt window, restart the RI by using the following command:
cref -i demoee
Starting the RI with the -i demoee option and filename causes the RI to use the contents of the demoee file to initialize the EEPROM. See Chapter 9 for more information about using cref and its command line options.
4. In the applet Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\SecureRMIPurse\client directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s client directory, the ant all command executes the APDU script that generates the securermidemo.expected.out file.
5. Verify that the contents of the securermidemo.expected.output file in the client directory are the same as the contents of the securermidemo.expected.output file in the SecureRMIPurse directory.
This sample is available only in bundles intended solely for distribution inside the U.S.
Message recovery refers to the mechanism whereby part of the message used to create the message digest is also included as padding in the signature block. During signature verification, the message data padding does not need to be explicitly sent to the verifying entity, it can automatically be extracted from the signature block.
This section describes the order of operations for signing and verifying.
1. The user invokes a combination of the update and sign methods to generate a signature based on message data provided by the user.
2. The sign method returns an indication to the user of the portion of the message that was included as padding in the signature.
This is required so that the user knows what remaining data must still be sent along with the signature block.
1. The user initializes the signature object with signature at the very beginning so it can get the recoverable data at the earliest.
2. The user invokes a combination of the update and verify methods to verify the signature based on the message data provided by the user.
3. The verify method verifies the signature by comparing the accumulated hash with the hash in the message representative recovered during initialization.
This sample consists of two scripts representing two scenarios for Signature with Message Recovery. The first script, sigMsgFullRec.scr, shows the scenario in which the message to sign is small enough that the entire message itself becomes part of the signature padding (hence the name “Full Recovery” since you can recover the full message from the signature itself). The second script, sigMsgPartRec.scr, demonstrates the scenario in which the message to sign is large enough that only some part of it is included in the signature padding (hence the name “Partial Recovery”). The scenarios are detailed next:
The sequence of events resulting from running this script are:
1. The script sends to the sample application a small message to sign.
2. The application initializes the signature object with the algorithm Signature.ALG_RSA_SHA_ISO9796_MR and signs the message. Because the message is small enough, the application returns the signature data to the script.
3. The script then simulates the verification phase in which it sends the signature data to the sample application asking it to verify the message.
The application recovers the original message from the signature data and also verifies the signature, then returns the original data back to the script. (If the signature verification fails, it returns an error code).
The sequence of events resulting from running this script are:
1. The script sends to the sample application a large message to be signed.
2. The application initializes the signature object with algorithm Signature.ALG_RSA_SHA_ISO9796_MR and signs the message. Because the message is too large to fit in the signature, the application returns back to the script the number of bytes of original message that is embedded in the signature data. The application also returns back to the script the signature data.
3. The script then simulates the verification phase in which it sends the signature data to the sample application.
4. The application recovers the partial message and returns back to the script.
5. The script sends the remainder of the message to the application to verify the signature.
6. The application verifies the signature against the entire message and returns success.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by entering the following command at the command prompt:
cref
| Note - cref command options are not required in this sample. |
2. In a different Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\classic_applets\SignatureMessageRecovery\applet directory.
b. Enter the following command at the command prompt:
ant run1
The ant run1 command builds the applet and runs the sigMsgPartRec.scr script that generates the sigMsgPartRec.actual.output file.
3. Verify the contents of the sigMsgPartRec.actual.output file in the applet directory are the same as the contents of the sigMsgPartRec.expected.output file in the SignatureMessageRecovery directory.
4. In the cref Command Prompt window, restart the RI by using the following command:
cref
5. In the applet Command Prompt window, enter the following command at the command prompt:
ant run2
The ant run2 command builds the applet and runs the sigMsgFullRec.scr script that generates the sigMsgfullRec.actual.output file.
6. Verify the contents of the sigMsgfullRec.actual.output file are the same as the contents of the sigMsgfullRec.expected.output file.
The following sections describe the reference applet demonstrations and how to run them:
See Biometry Sample Application.
This sample is only included in bundles intended solely for distribution inside the U.S. See JavaPurseCrypto Sample.
See JavaPurse Sample Application.
This sample is only included in bundles intended solely for distribution inside the U.S. See Transit Sample.
In this sample, a user password is enrolled on the card and a candidate password is matched against the enrolled password demonstrating the basic functionality of the biometric API. See How the Biometric API Works.
The steps described in FIGURE 4-1 illustrate the sequence of events that occur when the sample application uses the biometric API. Note that the sequence of steps depicted is a scenario in which everything works well. In other usages, other sequences of steps occur when things do not work well (such as an error occurring during the enrollment process, the matching process, the card-blocked state, or the non-initialized state). FIGURE 4-1 also illustrates the sequence for enrolling the PASSWORD bio-template done by SampleBioServer.
FIGURE 4-1 Biometric Sample Sequence Diagram
1. The off-card tool (see Off-card Tool) takes a hard coded password and sends it to the card for enrollment.
The applet selected on-card is the SampleBioServer applet. See SamplePasswdBioServer Class.
2. The SampleBioServer applet stores the password as the reference template with a hard coded number of tries allowed before block (5).
3. For matching, the APDUscript asks the on-card client (SamplePasswdBioApplet) to ask the SharedBioTemplate for the public template.
For this sample, the public template only contains the version number of the implementation and the length of stored password representing the requirement for password capture. See SamplePasswdBioApplet Class and SamplePasswdOwnerBioTemplate Class.
4. The script sends for matching the same password used for enrollment.
The card has a matching algorithm and calculates the score based on the stored password and received password.
5. The card returns verification successful to the script.
For this sample, the off-card tool is a simple apdutool script used for both enrolling and matching.
This class implements the OwnerBioTemplate interface and is what the BioBuilder constructs when asked for a OwnerBioTemplate interface for the BioBuilder.PASSWORD bio-type. This class provides the enrollment and matching capability to clients.
This class represents the BioServer applet on the card. It is responsible for communicating with off-card clients with APDUs and with on-card client applets with an implementation of ShareableBioTemplate that it implements. This class causes the enrolling of the password biometric while communicating with an off-card tool that sends the password down to the BioServer. This class is also the interface to the on-card and off-card clients for the biometric functionality on the card.
This represents an on-card client applet for the password biometric sample. It communicates with an off-card tool to get the password and calls the match method on the ShareableBioTemplate reference it gets from the Java Card runtime environment, which is given the SamplePasswdBioServer applet AID.
The biometric API is designed to perform three basic functions:
One of the requirements of the architecture is that biometric verification must happen on-card for security reasons. The card cannot send out a person’s biometric information for verification to be done off-card. The reasoning here is the same as for a PIN, which is that it would not be secure to do so.
During the enrollment process, a person’s biometric information is captured off-card and then transferred on-card for storage and verification purpose. Since Java Card technology-based cards are generally limited in their resources, the entire data captured off-card is not sent to the card. What is sent is a digested version of the biometric data and is very specific to a particular algorithm. For this sample, however, a password is small enough that the entire password is transferred to the card.
The user-specific data transferred makes up a reference template that is used later for verification. At the end of the enrollment process, there also exists an associated public template. The public template consists of information for the off-card tool to capture the relevant information from the user during verification.
For example, in the Precise Biometrics implementation of the fingerprint biometric API, the public template contains the coordinates, relative to the reference point for capturing fingerprint information. The off-card tool looks at these coordinates and extracts that information from the user. The public template defines the data requirements for verification. For this sample, the public template does not contain any such specification since the entire password is compared. In the sample, the public template just contains version information.
During the verification process the user enters biometric information into a sensor or input device. The information gathered from the user input is defined by the public template (see Enrollment Process). This information might be pre-processed off-card and transferred to the card for verification. The on-card biometric application performs the verification given the reference template with pre-existing user information and the new information that came in. The following describe the verification sequence:
1. The host issues a verification request to the card.
2. The card returns the public template to the host.
3. The host captures user information and extracts the data defined by the public template.
The host might perform data-processing specific to the biometric algorithm.
4. The host sends extracted verification data to the card.
5. The card matches the captured data with its own representation stored in the reference template.
The matching process results in a score of how well the user information matches the reference template information.
6. The card compares the score with the threshold for acceptable criteria and returns the verification result to the host.
The following restrictions apply for the Oracle implementation of the password biometric:
The array containing password data during enrollment or matching must have the password laid out as a byte array with each character represented by a byte starting from index offset. There can be no other information in the byte array from index offset to index offset+length-1. For example, password “tests” must be represented by the byte array {116, 101, 115, 116, 115} starting at index 0 with length 5.
The public template for the stored password returned during a matching session is a byte array (dest) with formatting as shown below. The version for this implementation is 1.0.0, so the dest array would be as follows, where passwd length represents the length of the enrolled password.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref -o e2p
Starting the RI with the -o e2p option and filename causes the RI to save the EEPROM contents to a file named e2p. See Chapter 9 for more information about using cref and its command line options.
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\reference_apps\Biometry\Server\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command executes the APDU script and installs the secure RMI application.
3. In the cref Command Prompt window, restart the RI by using the following command:
cref -i e2p
Starting the RI with the -i e2p option and filename causes the RI to use the contents of the e2p file to initialize the EEPROM. See Chapter 9 for more information about using cref and its command line options.
4. In the applet Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\reference_apps\Biometry\Client\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s client directory, the ant all command executes the APDU script.
5. Verify that the output displayed in the Command Prompt window is the same as the contents of the biometry-client.expected.out file.
The JavaPurse sample application consists of two components, a JavaPurse applet and a JavaLoyalty applet.
The JavaPurse applet demonstrates a simple electronic cash application. The applet is selected and initialized with various parameters such as the Purse ID, the expiration date of the card, the Master and User PINs, maximum balance, and maximum transaction. Transaction operations perform the actual debits and credits to the electronic purse. If a configured loyalty applet is assigned for the CAD performing the transaction, JavaPurse communicates with it to grant loyalty points. In this sample, JavaLoyalty is the provided loyalty applet.
A number of transaction sessions are simulated where amounts are credited and debited from the card. In an additional session, transactions with intentional errors are attempted to demonstrate the security features of the card.
The JavaLoyalty applet is a minimalistic loyalty applet that interacts with the JavaPurse applet and demonstrates the use of shareable interfaces. The shareable JavaLoyaltyInterface is defined in a separate library package, com.sun.javacard.SampleLibrary.
JavaLoyalty applet is registered with JavaPurse when a Parameter Update APDU command with an appropriate parameter tag is executed, and when the AID part of the parameter corresponds to the AID of the JavaLoyalty applet. The applet contains a grantPoints method. This method implements the main interaction with the client. The grantPoints method implementing the JavaLoyaltyInterface is requested when the first two bytes of the CAD ID in a request by a JavaPurse transaction correspond to the two bytes of CAD ID in the corresponding Parameter Update APDU command.
JavaLoyalty maintains the balance of loyalty points. The JavaLoyalty applet contains methods to credit and debit the account of points and to get and set the balance.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\reference_apps\PurseWithLoyalty\JavaPurse\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command executes the APDU script and generates the output file.The ant script names the output file either default.out or a custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the javapurse.expected.ouput file.
This sample is available only in bundles intended solely for distribution inside the U.S.
The JavaPurseCrypto sample application consists of two components, a JavaPurseCrypto applet and a JavaLoyalty applet. The JavaPurseCrypto applet employs a version of JavaPurse that uses a DES MAC algorithm. A DES MAC is a cryptographic signature that uses DES encryption on all or part of a message (APDU). JavaPurseCrypto uses the DES MAC to verify several of the APDUs. Instead of zeros in the signature currently in JavaPurse, it contains a real signature that can be programmatically signed and verified. Other programs that might interact with JavaPurseCrypto are not affected because all signing and verifying of the signature occurs only within JavaPurseCrypto.
The JavaPurseCrypto sample uses transient DES keys. The use of transient DES keys by the sample highlights the fact that the DES cryptography API has been enhanced to eliminate persistent memory usage when transient DES keys are provided. Eliminating the use of persistent memory when transient DES keys are used provides better performance in a contactless applet.
As in the JavaPurse sample, the JavaLoyalty applet is a minimalistic loyalty applet that interacts with JavaPurseCrypto and demonstrates the use of shareable interfaces. See JavaPurse Sample Application for additional information about the JavaLoyalty applet.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\reference_apps\PurseWithLoyalty\JavaPurseCrypto\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command executes the APDU script and generates the output file.The ant script names the output file either default.out or a custom name specified in the command line. To specify a custom name for the output file, use the following command:
ant -Dredirect.output=outputfile_name target
In this command, outputfile_name represents the name of the output file and target represents either the all or run options of the ant command. In this case, the all target is used. This command redirects the output from the APDUtool execution to the outputfile_name file.
3. Verify that the contents of the output file in the applet directory are the same as the contents of the javapursecrypto.expected.out file.
This sample is available only in bundles intended solely for distribution inside the U.S, and so it can not be used in global bundles.
The Transit sample illustrates a contactless card-based transit applet. This sample consists of the transit applet and two client applications, the POSTerminal client application and the TransitTerminal client application.
A typical transit scenario is pre-scripted in the TransitDemo file, including crediting and checking the balance (a $99 initial balance) on the transit card at the POS terminal, entering and exiting the transit system through the Turnstile Transit terminal (a $10 fee for the trip), and finally checking the new balance (an $89 balance) on the transit card at the POS terminal.
Because the terminal uses random number generation for challenge/response and for generating session key, the contents of the actual output files generated by running this sample will vary from that of the expected output files for the following instructions:
The TransitDemo or TransitDemo.bat script automatically starts and stops cref when needed to simulate interaction sessions with the POS terminal and the turnstile transit terminal.
1. Open a Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\bin directory.
b. Start the RI by using the following command at the command prompt:
cref -o transitCard
2. Open a second Command Prompt window and perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\reference_apps\Transit\Transit\applet directory.
b. Enter the following command at the command prompt:
ant all
In this sample’s applet directory, the ant all command generates the APDU script and downloads the CAP file.
3. In the cref Command Prompt window, restart the RI by using the following command:
cref -i transitCard -o transitCard
Starting the RI with the -i transitCard -o transitCard options and filenames causes the RI to use the contents of the transitCard file to initialize the EEPROM and to save the EEPROM contents to a file named transitCard. See Chapter 9 for more information about using cref and its command line options.
4. In the applet Command Prompt window, perform the following:
a. Navigate to the JC_CLASSIC_HOME\samples\reference_apps\Transit\Transit\client directory.
b. Enter the following command at the command prompt:
ant run1
In this sample’s client directory, the ant run1 command compiles and builds the client.jar and generates the actual_output1.txt file.
5. Verify that the contents of the actual_output1.txt file are the same as the contents of the TransitClient_1.expected.output file.
Because the terminal uses random number generation for challenge/response and for generating session key, the contents of the actual_output1.txt file will vary from the TransitClient_1.expected.output file for the following instructions:
6. In the cref Command Prompt window, restart the RI by using the following command:
cref -i transitCard -o transitCard
7. In the applet Command Prompt window, enter the following command at the command prompt:
ant run2
In this sample’s client directory, the ant run2 command compiles and builds the client.jar and generates the actual_output2.txt file.
8. Verify that the contents of the actual_output2.txt file are the same as the contents of the TransitClient_2.expected.output file.
Because the terminal uses random number generation for challenge/response and for generating session key, the contents of the actual_output2.txt file will vary from the TransitClient_2.expected.output file for the following instructions:
9. In the cref Command Prompt window, restart the RI by using the following command:
cref -i transitCard -o transitCard
10. In the applet Command Prompt window, enter the following command at the command prompt:
ant run3
In this sample’s client directory, the ant run3 command compiles and builds the client.jar and generates the actual_output3.txt file.
11. Verify that the contents of the actual_output3.txt file are the same as the contents of the TransitClient_3.expected.output file.
Because the terminal uses random number generation for challenge/response and for generating session key, the contents of the actual_output3.txt file will vary from the TransitClient_3.expected.output file for the following instructions:
12. In the cref Command Prompt window, restart the RI by using the following command:
cref -i transitCard -o transitCard
13. In the applet Command Prompt window, enter the following command at the command prompt:
ant run4
In this sample’s client directory, the ant run4 command compiles and builds the client.jar and generates the actual_output4.txt file.
14. Verify that the contents of the actual_output4.txt file are the same as the contents of the TransitClient_4.expected.output file.
Because the terminal uses random number generation for challenge/response and for generating session key, the contents of the actual_output4.txt file will vary from the TransitClient_4.expected.output file for the following instructions:
| Development Kit User’s Guide | October-2010 |
|
Copyright © 2010, Oracle and/or its affiliates. All rights reserved.
Run the HelloWorld