ds.ov2.util
Class Installation_arguments

java.lang.Object
  ds.ov2.util.Installation_arguments

public class Installation_arguments
extends Object

Decode Java Card applet installation arguments into an APDU_Serializable array. Relies on parts of the OV-chip protocol layer. Therefore the installation arguments must be encoded as for the OV-chip protocol: A sequence of plain data bytes without intermediate length information. Two short arguments must for instance be encoded with 4 bytes.

The byte array which the applet install method receives contains the applet ID, some control info and the actual installation arguments (called applet data in the SUN docs) in a length-value encoding (see Applet.install for the details). This class can parse the complete data to find the actual installation arguments. Decoded are however only the installation arguments and not the other stuff.

When specifying the installation arguments in some applet installation programm one typically has to prepend a size byte to the encoded installation arguments. Sometimes (for instance for the global platform manager) an additional leading 0xC9 must be inserted. (This 0xC9 is a tag that tells the global platform that the bytes that follow are applet installation arguments, if I remember correctly.) In the example of the two shorts one would have to specify 0xC9 0x04 plus 4 data bytes.

To encode the installation arguments in the host driver one can use Convert_serializable.array_to_bytes as in the following code fragment

    APDU_Serializable[] arguments = ...
    int arg_length = Misc.length_of_serializable_array(arguments);
    assert arg_length < 127;
    byte[] serialized_args = new byte[arg_length + 2];
    serialized_args[0] = (byte)0xC9;
    serialized_args[1] = (byte)arg_length;
    int res = Convert_serializable.array_to_bytes(arguments, serialized_args, 2); 
    assert res == serialized_args.length;
 

The arguments array in the host driver most be compatible (in the sense of Convert_serializable.check_compatibility) to the ones that are used in the applet and passed into decode.

The specification of the data format of the installation arguments comes from SUN as well as the emulators cref and jcwde. But it would be expecting far too much that SUN tools follow SUN specifications. An applet running in cref or jcwde only sees the actual installation arguments in the byte array that the install method gets. No applet ID, no control info, not even a length byte. When CREF_INSTALL_ARG_HACK is defined the code here works around this bug. If it is undefined one will get strange errors inside cref and jcwde.

This is a static class.

CPP Preprocessing

This class uses the following cpp defines: PACKAGE, PUBLIC, ASSERT, CREF_INSTALL_ARG_HACK

Execution Environment:

card

Author:

Hendrik Tews

Version:

$Revision: 1.9 $

Last Commit:

$Date: 2009-04-09 10:42:16 $ by $Author: tews $

Constructor Summary

protected

Installation_arguments() Static class, object creation disabled.

Method Summary

static void

decode(byte[] bytes, short start, byte len, APDU_Serializable[] arguments) Decode the actual applet installation arguments.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Installation_arguments

protected Installation_arguments()

Static class, object creation disabled.

Method Detail

decode

public static void decode(byte[] bytes,
                          short start,
                          byte len,
                          APDU_Serializable[] arguments)

Decode the actual applet installation arguments. The first three arguments are the unmodified arguments from the install method. The last argument are the declared installation arguments. This method checks (with ASSERT) that the size of the installation arguments fits with the incoming data.

When CREF_INSTALL_ARG_HACK is defined this method tries to work around the bugs in the cref and jcwde emulators.

Parameters:

bytes - the array containing the raw data

start - the starting offset in bytes

len - the length of the raw data

arguments - the declared arguments into which the raw data is decoded