com.ibm.jc
Class CapFile

java.lang.Object
  com.ibm.jc.CapFile

public class CapFile

extends java.lang.Object

Allows to load a Java Card package from a CAP-file. After loading various information is avaliable from public fields. Furthermore, this class allows to manage Global Platform properties such as DAP blocks and Delegated Management tokens, which can be stored in CAP-files.

Field Summary

static byte	ACC_APPLET CAP file package flag indicating if an Applet component is included in this package.
static byte	ACC_EXPORT CAP file package flag indicating if an Export component is included in this package.
static byte	ACC_INT CAP file package flag indicating if Java type int is used in this package.
byte[][]	aids The list of applets contained in this package.
byte[][]	allComponents CAP components available in this CAP file.
static int	CAP_V21 CAP file version 2.1
static int	CAP_V22 CAP file version 2.2
int	capVersion The CAP file version as indicated in the Header Component.
byte[]	code The package data which is actually uploaded to the card.
byte[][]	components CAP components in the sequence as to be loaded onto the card.
DAPBlock[]	dapBlocks A list of Load File DAP blocks.
int	effCodeSize Effective code size of the package when loaded onto the card.
byte	flags Bit mask holding CAP file package flags.
byte[][]	imports The list of packages imported by this package.
InstallToken[]	installTokens A list of Install Tokens for delegated installation.
LoadToken[]	loadTokens A list of Load Tokens for delegated loading.
int	numDapBlocks Number of DAP blocks in the dapBlocks array.
int	numInstallTokens Number of Install Tokens in the installTokens array.
int	numLoadTokens Number of Load Tokens in the loadTokens array.
java.lang.String	pkg The Java package name.
byte[]	pkgId The package AID.
java.lang.String	pkgInternal Internal package name as included in Header component.
java.lang.String	pkgPath The package path in the CAP file.
int	pkgVersion Package version.
int	s_applets Size of all applet AIDs in this package (in bytes).
int	s_classes Size of all class information in this package (in bytes).
int	s_exports Size of all export information this package (in bytes).
int	s_methods Size of all methods in this package (in bytes).
int	s_pkgAID Size of the package AID (in bytes).
int	s_statics Size of all static data this package (in bytes).

Constructor Summary

CapFile(java.lang.String f, java.lang.String pkg)
Constructor.

Method Summary

void	appendDapBlock(byte[] aid, byte[] sig) Deprecated.
void	appendDapBlock(byte[] aid, byte[] sig, java.lang.String targetFile) Deprecated.
void	appendDapBlock(byte[] aid, byte[] sig, java.lang.String targetFile, int dapAlg, java.lang.Object cert) Add a new DAP block to the CAP-file.
void	appendInstallToken(byte[] sig, byte[] appAID, byte[] instAID, int privs, byte[] params) Deprecated.
void	appendInstallToken(byte[] sig, byte[] appAID, byte[] instAID, int privs, byte[] params, java.lang.String targetFile) Add a new Install Token to the CAP-file
void	appendLoadToken(byte[] sig, byte[] sdaid, byte[] params) Deprecated.
void	appendLoadToken(byte[] sig, byte[] sdaid, byte[] params, java.lang.String targetFile) Add a new Load Token to the CAP-file.
void	clearMetaInf() Remove all DAP/DM information for the current package from the CAP-file.
static java.lang.String	fSig(java.lang.String sig, int indent, int len) Formats a signature string for printing.
byte[]	generateDAP(java.lang.Object key) Deprecated.
byte[]	generateDAP(java.lang.Object key, int dapAlg) Generates a Load File Data Block signature.
static byte[]	generateInstallToken(byte[] pkg, int pkgBeg, int pkgLen, byte[] app, int appBeg, int appLen, byte[] inst, int instBeg, int instLen, int privs, byte[] param, int paramBeg, int paramLen, java.lang.Object key) Generates an install token to be used in delegated installation.
byte[]	generateLoadToken(byte[] sd, int sdBeg, int sdLen, byte[] param, int paramBeg, int paramLen, java.lang.Object key) Generates a load token to be used in delegated loading.
byte[]	getCodeHeader() Returns information to be prepended to the code before loading onto the card.
byte[]	getEncodedDapBlocks() Concatenates all encoded DAP blocks as needed for loading.
byte[]	getLoadFile() Builds the concatentaion of the load file header and the load file data.
byte[]	getLoadFileDataHash() Generates a SHA-1 digest over the load file data.
byte[]	getLoadFileHash() Generates a SHA-1 digest over the load file.
java.lang.String	infoString() Returns a printable string providing all known information about the CAP file.
void	installAuthorize(byte[] appAID, byte[] instAID, int privs, byte[] params, java.lang.Object key) Deprecated.
void	installAuthorize(byte[] appAID, byte[] instAID, int privs, byte[] params, java.lang.Object key, java.lang.String targetFile) Generates an Install Token and writes the Install Token information to the CAP-file.
void	loadAuthorize(byte[] sdaid, byte[] params, java.lang.Object key) Deprecated.
void	loadAuthorize(byte[] sdaid, byte[] params, java.lang.Object key, java.lang.String targetFile) Generates a Load Token and writes the Load Token information to the CAP-file.
static java.lang.Object	makePrivateCert(byte[] pkcs12, java.lang.String pin) Makes a private certificate object from PKCS#12 data.
void	readCapFile(java.lang.String f, java.lang.String pkg) Loads a Java Card package from a CAP-file and fills up the public fields.
void	signCapFile(byte[] aid, java.lang.Object key) Deprecated.
void	signCapFile(byte[] aid, java.lang.Object key, java.lang.String targetFile) Deprecated.
void	signCapFile(byte[] aid, java.lang.Object key, java.lang.String targetFile, int dapAlg) Generates a DAP block and writes the DAP information to the CAP-file.

Methods inherited from class java.lang.Object

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

Field Detail

CAP_V21

public static final int CAP_V21

CAP file version 2.1

See Also:

capVersion, Constant Field Values

CAP_V22

public static final int CAP_V22

CAP file version 2.2

See Also:

capVersion, Constant Field Values

ACC_INT

public static final byte ACC_INT

CAP file package flag indicating if Java type int is used in this package.

See Also:

flags, Constant Field Values

ACC_EXPORT

public static final byte ACC_EXPORT

CAP file package flag indicating if an Export component is included in this package.

See Also:

flags, Constant Field Values

ACC_APPLET

public static final byte ACC_APPLET

CAP file package flag indicating if an Applet component is included in this package.

See Also:

flags, Constant Field Values

capVersion

public int capVersion

The CAP file version as indicated in the Header Component. An 8 bit value describing major and minor version of the CAP file. The low order 4 bits are the minor number.

See Also:

CAP_V21, CAP_V22

components

public byte[][] components

CAP components in the sequence as to be loaded onto the card. Ten byte arrays holding the data of the CAP file components: Header.cap, Directory.cap, Import.cap, Applet.cap (optional), Class.cap, Method.cap, StaticField.cap, Export.cap (optional), ConstantPool.cap, RefLocation.cap. This represents the load sequence as proposed in JavaCard and mandated by Visa Open Platform/Global Platform. Missing (optional) components might be null.

See Also:

code, allComponents

allComponents

public byte[][] allComponents

CAP components available in this CAP file. Twelve byte arrays holding the data of the CAP file components: Header.cap, Directory.cap, Import.cap, Applet.cap (optional), Class.cap, Method.cap, StaticField.cap, Export.cap (optional), ConstantPool.cap, RefLocation.cap, Descriptor.cap, Debug.cap (optional; JavaCard 2.2 only). Missing (optional) components might be null.

See Also:

code, components

code

public byte[] code

The package data which is actually uploaded to the card. This is a concatenation of the CAP components: Header.cap, Directory.cap, Import.cap, Applet.cap (optional), Class.cap, Method.cap, StaticField.cap, Export.cap (optional), ConstantPool.cap, RefLocation.cap.

See Also:

components, allComponents

pkgVersion

public int pkgVersion

Package version. The 16 bit value describes major and minor version of the package implementation. The low order 8 bits are the minor number.

flags

public byte flags

Bit mask holding CAP file package flags.

See Also:

ACC_INT, ACC_EXPORT, ACC_APPLET

pkgId

public byte[] pkgId

The package AID.

pkg

public java.lang.String pkg

The Java package name.

pkgInternal

public java.lang.String pkgInternal

Internal package name as included in Header component.

pkgPath

public java.lang.String pkgPath

The package path in the CAP file.

aids

public byte[][] aids

The list of applets contained in this package. This field might be null if no applets are included in this package.

imports

public byte[][] imports

The list of packages imported by this package. Each entry has the form [major(1 byte), minor (1 byte), aid (N bytes)].

effCodeSize

public int effCodeSize

Effective code size of the package when loaded onto the card. This is just a rough guess.

See Also:

#s_pkgAId, s_applets, s_classes, s_methods, s_statics, s_exports

s_pkgAID

public int s_pkgAID

Size of the package AID (in bytes).

See Also:

effCodeSize

s_applets

public int s_applets

Size of all applet AIDs in this package (in bytes).

See Also:

effCodeSize

s_classes

public int s_classes

Size of all class information in this package (in bytes).

See Also:

effCodeSize

s_methods

public int s_methods

Size of all methods in this package (in bytes).

See Also:

effCodeSize

s_statics

public int s_statics

Size of all static data this package (in bytes).

See Also:

effCodeSize

s_exports

public int s_exports

Size of all export information this package (in bytes).

See Also:

effCodeSize

dapBlocks

public DAPBlock[] dapBlocks

A list of Load File DAP blocks.

See Also:

numDapBlocks

numDapBlocks

public int numDapBlocks

Number of DAP blocks in the dapBlocks array.

See Also:

dapBlocks

loadTokens

public LoadToken[] loadTokens

A list of Load Tokens for delegated loading.

See Also:

numLoadTokens

numLoadTokens

public int numLoadTokens

Number of Load Tokens in the loadTokens array.

See Also:

loadTokens

installTokens

public InstallToken[] installTokens

A list of Install Tokens for delegated installation.

See Also:

numInstallTokens

numInstallTokens

public int numInstallTokens

Number of Install Tokens in the installTokens array.

See Also:

installTokens

Constructor Detail

CapFile

public CapFile(java.lang.String f,
               java.lang.String pkg)
        throws java.lang.Exception

Constructor. Loads a Java Card package from a CAP-file.

Parameters:

f - CAP file to be loaded.

pkg - Java package name of the package in the JAR file. If null the first package found will be loaded.

Throws:

java.lang.Exception - If the CAP-file could no be loaded or parsed.

See Also:

readCapFile

Method Detail

readCapFile

public void readCapFile(java.lang.String f,
                        java.lang.String pkg)
                 throws java.lang.Exception

Loads a Java Card package from a CAP-file and fills up the public fields.

Parameters:

f - CAP-file to be loaded.

Throws:

java.lang.Exception - If CAP file could no be loaded or parsed.

getLoadFileDataHash

public byte[] getLoadFileDataHash()

Generates a SHA-1 digest over the load file data. (excluding DAP blocks and tag/length bytes)

Returns:

the SHA-1 digest.

Throws:

JCException - if the key is not valid or no load file data available.

getLoadFileHash

public byte[] getLoadFileHash()

Generates a SHA-1 digest over the load file. (including DAP blocks and tag/length bytes)

Returns:

the SHA-1 digest.

getLoadFile

public byte[] getLoadFile()

Builds the concatentaion of the load file header and the load file data.

Returns:

the load file.

Throws:

JCException - if the key is not valid or no load file data available.

generateInstallToken

public static byte[] generateInstallToken(byte[] pkg,
                                          int pkgBeg,
                                          int pkgLen,
                                          byte[] app,
                                          int appBeg,
                                          int appLen,
                                          byte[] inst,
                                          int instBeg,
                                          int instLen,
                                          int privs,
                                          byte[] param,
                                          int paramBeg,
                                          int paramLen,
                                          java.lang.Object key)

Generates an install token to be used in delegated installation.

Parameters:

pkg - package AID.

pkgBeg - offset in pkg.

pkgLen - length of the AID in pkg.

app - applet AID in the package.

appBeg - offset in app.

appLen - length of the AID in app.

inst - desired instance AID. If null it defaults to the applet AID.

instBeg - offset in inst.

instLen - length of the AID in inst.

privs - desired application privileges.

param - install parameters (raw format). This parameter is optional and can be null.

paramBeg - offset in param.

paramLen - length of install parameters.

key - the RSA private certificate to be used for token generation.

Returns:

the install token.

Throws:

JCException - if the key is not valid

See Also:

makePrivateCert(byte[], java.lang.String)

generateLoadToken

public byte[] generateLoadToken(byte[] sd,
                                int sdBeg,
                                int sdLen,
                                byte[] param,
                                int paramBeg,
                                int paramLen,
                                java.lang.Object key)

Generates a load token to be used in delegated loading.

Parameters:

sd - AID of the security domain to be associated withe the package and it's applets. This parameter is optional and can be null.

sdBeg - offset in sd.

sdLen - length of the AID in sd.

param - load parameters (raw format). This parameter is optional and can be null.

paramBeg - offset in param.

paramLen - length of install parameters.

key - the RSA private certificate to be used for token generation.

Returns:

the load token.

Throws:

JCException - if the key is not valid or no load file data available.

See Also:

makePrivateCert(byte[], java.lang.String)

generateDAP

public byte[] generateDAP(java.lang.Object key,
                          int dapAlg)

Generates a Load File Data Block signature. Both DES DAP generation algorithms are supported: VOP 2.0.1' and GP 2.1.1

Parameters:

key - DES key or RSA private key to be used for signature generation. This can be an OPKey object (DES) or a private certificate object (RSA).

dapAlg - the DAP generation algorithm. Only applicable in case of DES DAP, otherwise this parameter is ignored.

Returns:

the signature (DAP).

Throws:

JCException - if the key is not valid or no load file data available.

See Also:

com.ibm.jc.DAPBlock.DES_DAP_ALG_201, com.ibm.jc.DAPBlock.DES_DAP_ALG_211, makePrivateCert(byte[], java.lang.String)

generateDAP

public byte[] generateDAP(java.lang.Object key)

Deprecated.

Generates a load file data block signature. (Load File DAP, see 13.7 VOP 2.0.1')

Parameters:

key - DES key or RSA private key to be used for signature generation. This can be an OPKey object (DES) or a private certificate object (RSA).

Returns:

the signature (DAP).

Throws:

JCException - if the key is not valid or no load file data available.

See Also:

makePrivateCert(byte[], java.lang.String)

signCapFile

public void signCapFile(byte[] aid,
                        java.lang.Object key,
                        java.lang.String targetFile,
                        int dapAlg)

Generates a DAP block and writes the DAP information to the CAP-file. Note that this operation invalidates all Load Tokens since they depend on the DAP blocks.

Parameters:

aid - AID of the target Security Domain to do the DAP verification.

key - the DAP generation key (OPKey obejct for DES keys, private certificate object otherwise).

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

dapAlg - the DAP generation algorithm. Only applicable in case of DES DAP, otherwise this parameter is ignored.

See Also:

com.ibm.jc.DAPBlock.DES_DAP_ALG_201, com.ibm.jc.DAPBlock.DES_DAP_ALG_211, makePrivateCert(byte[], java.lang.String)

signCapFile

public void signCapFile(byte[] aid,
                        java.lang.Object key,
                        java.lang.String targetFile)

Deprecated.

Generates a DAP block and writes the DAP information to the CAP-file. Note that this operation invalidates all Load Tokens since they depend on the DAP blocks.

Parameters:

aid - AID of the target Security Domain to do the DAP verification.

key - the DAP generation key (OPKey obejct for DES keys, private certificate object otherwise).

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

See Also:

makePrivateCert(byte[], java.lang.String)

signCapFile

public void signCapFile(byte[] aid,
                        java.lang.Object key)

Deprecated.

Generates a DAP block and writes the DAP information to the CAP-file. Note that this operation invalidates all Load Tokens since they depend on the DAP blocks.

Parameters:

aid - AID of the target Security Domain to do the DAP verification.

key - the DAP generation key (OPKey obejct for DES keys, private certificate object otherwise).

See Also:

makePrivateCert(byte[], java.lang.String)

loadAuthorize

public void loadAuthorize(byte[] sdaid,
                          byte[] params,
                          java.lang.Object key,
                          java.lang.String targetFile)

Generates a Load Token and writes the Load Token information to the CAP-file.

Parameters:

params - load parameters or null.

key - the Load Token generation key (a private certificate object).

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

See Also:

makePrivateCert(byte[], java.lang.String)

loadAuthorize

public void loadAuthorize(byte[] sdaid,
                          byte[] params,
                          java.lang.Object key)

Deprecated.

Generates a Load Token and writes the Load Token information to the CAP-file.

Parameters:

params - load parameters or null.

key - the Load Token generation key (a private certificate object).

See Also:

makePrivateCert(byte[], java.lang.String)

installAuthorize

public void installAuthorize(byte[] appAID,
                             byte[] instAID,
                             int privs,
                             byte[] params,
                             java.lang.Object key,
                             java.lang.String targetFile)

Generates an Install Token and writes the Install Token information to the CAP-file.

Parameters:

appAID - the applet AID.

instAID - the instance AID or null.

privs - the application privileges.

params - install parameters or null.

key - the Install Token generation key (a private certificate object).

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

See Also:

makePrivateCert(byte[], java.lang.String)

installAuthorize

public void installAuthorize(byte[] appAID,
                             byte[] instAID,
                             int privs,
                             byte[] params,
                             java.lang.Object key)

Deprecated.

Generates an Install Token and writes the Install Token information to the CAP-file.

Parameters:

appAID - the applet AID.

instAID - the instance AID or null.

privs - the application privileges.

params - install parameters or null.

key - the Install Token generation key (a private certificate object).

See Also:

makePrivateCert(byte[], java.lang.String)

appendLoadToken

public void appendLoadToken(byte[] sig,
                            byte[] sdaid,
                            byte[] params,
                            java.lang.String targetFile)

Add a new Load Token to the CAP-file.

Parameters:

sig - the Load Token.

sdaid - Security Domain AID.

params - load parametes.

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

appendLoadToken

public void appendLoadToken(byte[] sig,
                            byte[] sdaid,
                            byte[] params)

Deprecated.

Add a new Load Token to the CAP-file.

Parameters:

sig - the Load Token.

sdaid - Security Domain AID.

params - load parametes.

appendInstallToken

public void appendInstallToken(byte[] sig,
                               byte[] appAID,
                               byte[] instAID,
                               int privs,
                               byte[] params,
                               java.lang.String targetFile)

Add a new Install Token to the CAP-file

Parameters:

sig - the Install Token.

appAID - the applet AID.

instAID - the instance AID or null.

privs - the application privileges.

params - install parameters or null.

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

appendInstallToken

public void appendInstallToken(byte[] sig,
                               byte[] appAID,
                               byte[] instAID,
                               int privs,
                               byte[] params)

Deprecated.

Add a new Install Token to the CAP-file

Parameters:

sig - the Install Token.

appAID - the applet AID.

instAID - the instance AID or null.

privs - the application privileges.

params - install parameters or null.

clearMetaInf

public void clearMetaInf()

Remove all DAP/DM information for the current package from the CAP-file.

getCodeHeader

public byte[] getCodeHeader()

Returns information to be prepended to the code before loading onto the card. This includes DAP block(s), if any, and the load file tag/length bytes.

Returns:

header data

getEncodedDapBlocks

public byte[] getEncodedDapBlocks()

Concatenates all encoded DAP blocks as needed for loading.

Returns:

concatenated DAP blocks

appendDapBlock

public void appendDapBlock(byte[] aid,
                           byte[] sig,
                           java.lang.String targetFile,
                           int dapAlg,
                           java.lang.Object cert)

Add a new DAP block to the CAP-file. Note that this operation invalidates all Load Tokens since they depend on the DAP blocks.

Parameters:

aid - Security Domain AID.

sig - DAP.

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

dapAlg - the DAP generation algorithm. Only applicable in case of DES DAP, otherwise this parameter is ignored.

cert - private certificate object used to generate the DAP. This parameter is only applicalbe in case of PK DAP. This parameter might be null.

See Also:

com.ibm.jc.DAPBlock.DES_DAP_ALG_201, com.ibm.jc.DAPBlock.DES_DAP_ALG_211, makePrivateCert(byte[], java.lang.String)

appendDapBlock

public void appendDapBlock(byte[] aid,
                           byte[] sig,
                           java.lang.String targetFile)

Deprecated.

Add a new DAP block to the CAP-file. Note that this operation invalidates all Load Tokens since they depend on the DAP blocks.

Parameters:

aid - Security Domain AID.

sig - DAP.

targetFile - the location and name of the target CAP-file if the original file is not to be modified, null otherwise. Note: if targetFile is not null, the CAP-file object represents the target file upon method invocation.

appendDapBlock

public void appendDapBlock(byte[] aid,
                           byte[] sig)

Deprecated.

Add a new DAP block to the CAP-file. Note that this operation invalidates all Load Tokens since they depend on the DAP blocks.

Parameters:

aid - Security Domain AID.

sig - DAP.

infoString

public java.lang.String infoString()

Returns a printable string providing all known information about the CAP file.

Returns:

info string.

makePrivateCert

public static java.lang.Object makePrivateCert(byte[] pkcs12,
                                               java.lang.String pin)

Makes a private certificate object from PKCS#12 data. A private certificate is a RSA private key accompanied by its X.509 certificate. The PKCS#12 source must include exactly one such private certificate. The resulting object can then be passed to various other methods, for instance, to sign CAP-files or to authorize delegated operations.

Parameters:

pkcs12 - the PKCS#12 encoded data.

pin - the PIN protecting the PKCS#12 data.

Returns:

the private certificate obejct or null if the method fails for any reason.

See Also:

generateInstallToken(byte[], int, int, byte[], int, int, byte[], int, int, int, byte[], int, int, java.lang.Object), generateLoadToken(byte[], int, int, byte[], int, int, java.lang.Object), generateDAP(java.lang.Object, int), signCapFile(byte[], java.lang.Object, java.lang.String, int), loadAuthorize(byte[], byte[], java.lang.Object, java.lang.String), installAuthorize(byte[], byte[], int, byte[], java.lang.Object, java.lang.String), appendDapBlock(byte[], byte[], java.lang.String, int, java.lang.Object)

fSig

public static java.lang.String fSig(java.lang.String sig,
                                    int indent,
                                    int len)

Formats a signature string for printing. The string is cut into multiple lines of desired length with a number of blanks prepended.

Parameters:

sig - signature string to be formated.

indent - number of blanks to be prepended to each line except the first.

len - desired line length.

Returns:

the formated signature string.