com.ibm.jc
Class SecurityDomain

java.lang.Object
  com.ibm.jc.JCApplet
      com.ibm.jc.OPApplet
          com.ibm.jc.SecurityDomain

Direct Known Subclasses:

CardManager

public class SecurityDomain

extends OPApplet

This class implements the off-card behavior of a Security Domain (usually a Provider Security Domain) on a Global Platform JavaCard. It provides functionality to install, load, personalize, extradite and delete applications. Some of the functionality is only available if the Security Domain has DAP Verification or/and Delegated Management privileges.

Field Summary

static int	LOAD_ALL loading mode: load concatenated CAP-file components
static int	LOAD_COMP loading mode: load CAP-file components seperately
static int	LOAD_DEBUG loading mode: do not skip descriptor/debug component
static int	LOAD_RND loading mode: load with random APDU size

Fields inherited from class com.ibm.jc.OPApplet

ADD_NEW_KEYSET, APDU_BIG_MAC, APDU_CLR, APDU_CRMAC, APDU_CRMAC_ENC, APDU_ENC, APDU_MAC, APDU_MAC_START, APDU_RMAC, APDU_SUPER_MAC, APPLICATION_LCD, BLOCKED, CARD_TERMINATE_PRIV, CM_LCD, CM_LOCK_PRIV, GS_FIRST_ALL, GS_FORMAT_1, GS_FORMAT_2, GS_NEXT, icv, IMP_SELECTABLE_PRIV, INSTALLED, K_dek, K_ea, K_m, K_rm, Kkek, LOAD_FILE_LCD, LOAD_FILE_MODULE_LCD, LOCKED, LOGICALLY_DELETED, macSize, MANDATED_DAP_PRIV, MODIFY_KEYSET, msgMode, NO_PRIVS, NO_SESSION, NOT_AVAILABLE, PERSONALIZED, PIN_CHANGE_PRIV, REPLACE_KEYSET, ricv, rmbuf, SCP_01_05, SCP_01_15, SCP_02_04, SCP_02_05, SCP_02_0A, SCP_02_0B, SCP_02_14, SCP_02_15, SCP_02_1A, SCP_02_1B, SCP_UNDEFINED, scpMode, SD_DAP_PRIV, SD_DELEGATE_PRIV, SD_PRIV, SELECTABLE, SESSION_AUTH, SESSION_OK, sessionMode, VOP_201, VOP_211, VOP_NONE

Fields inherited from class com.ibm.jc.JCApplet

apdu

Constructor Summary

SecurityDomain()

SecurityDomain(JCApplet app)
Create the off-card representation of a Security Domain.

SecurityDomain(JCard card, byte[] aid, int aidBeg, int aidLen)
Create the off-card representation of a Security Domain.

SecurityDomain(JCard card, byte[] aid, int aidBeg, int aidLen, byte state, byte privs)
Create the off-card representation of a Security Domain.

Method Summary

byte[]	delete(byte[] id, int beg, int len, boolean last) Deprecated.
void	deleteKeyObject(int keyID, int keyVersion) This corresponds with the Global Platform DELETE [key] command.
byte[]	deleteObject(byte[] aid, int beg, int len, boolean deleteRelated) This corresponds with the Global Platform DELETE command.
static byte[]	generateReceipt(byte[] d, int beg, int len, OPKey rKey) Generate a load, install, extradition or delete receipt.
byte[]	installForExtradition(byte[] sdAID, int sdAIDBeg, int sdAIDLen, byte[] instAID, int instAIDBeg, int instAIDLen, byte[] token, int tokenBeg) This method corresponds with the Global Platform INSTALL [for extradition] command.
byte[]	installForInstall(byte[] pkgAID, int pkgAIDBeg, int pkgAIDLen, byte[] appAID, int appAIDBeg, int appAIDLen, byte[] instAID, int instAIDBeg, int instAIDLen, int privs, byte[] param, int paramBeg, int paramLen, byte[] token, int tokenBeg) This method corresponds with the Global Platform INSTALL [for install] command.
byte[]	installForInstallAndMakeSelectable(byte[] pkgAID, int pkgAIDBeg, int pkgAIDLen, byte[] appAID, int appAIDBeg, int appAIDLen, byte[] instAID, int instAIDBeg, int instAIDLen, int privs, byte[] param, int paramBeg, int paramLen, byte[] token, int tokenBeg) This method corresponds with the Global Platform INSTALL [for install and make selectable] command.
void	installForLoad(byte[] pkgAID, int pkgAIDBeg, int pkgAIDLen, byte[] sdAID, int sdAIDBeg, int sdAIDLen, byte[] dap, int dapBeg, byte[] param, int paramBeg, int paramLen, byte[] token, int tokenBeg) This method corresponds with the Golbal Platform INSTALL [for load] command.
void	installForMakeSelectable(byte[] instAID, int instAIDBeg, int instAIDLen, int privs, byte[] token, int tokenBeg) This corresponds with the Global Platform INSTALL [for make selectable] command.
void	installForPersonalization(byte[] instAID, int instAIDBeg, int instAIDLen) This method corresponds with the Global Platform INSTALL [for personalization] command.
byte[]	load(CapFile capfile, int[] progress, int mode, java.io.PrintWriter msgOut, int mbl) Loads a CAP-file (package) onto the card by utilizing the Global Platform LOAD command.
static void	verifyReceipt(byte[] d, int beg, int len, OPKey rKey) Verify a load, install, extradition or delete receipt generated during one of these operations via Delegated Management.

Methods inherited from class com.ibm.jc.OPApplet

beginRMACSession, deleteKey, endRMACSession, externalAuthenticate, flush, getData, getKey, getKeys, getMaxPayload, getPrivileges, getSCP, getSecurityLevel, getSessionMode, getSessionState, getState, getStatus, getStatus, initializeUpdate, initializeUpdate, putData, putKey, select, send, sendAPDU, setKey, setSCP, setSecurityLevel, setStatus, storeData, storeKeyset, storePKDAPKey

Methods inherited from class com.ibm.jc.JCApplet

equals, getAID, getCard, getTerminal, setAID, setCard, setHeader

Methods inherited from class java.lang.Object

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

Field Detail

LOAD_ALL

public static final int LOAD_ALL

loading mode: load concatenated CAP-file components

See Also:

Constant Field Values

LOAD_COMP

public static final int LOAD_COMP

loading mode: load CAP-file components seperately

See Also:

Constant Field Values

LOAD_RND

public static final int LOAD_RND

loading mode: load with random APDU size

See Also:

Constant Field Values

LOAD_DEBUG

public static final int LOAD_DEBUG

loading mode: do not skip descriptor/debug component

See Also:

Constant Field Values

Constructor Detail

SecurityDomain

public SecurityDomain(JCard card,
                      byte[] aid,
                      int aidBeg,
                      int aidLen,
                      byte state,
                      byte privs)

Create the off-card representation of a Security Domain.

Parameters:

card - the JavaCard this Security Domain resides on.

aid - the buffer containing the AID of the Security Domain.

aidBeg - offset into aid.

aidLen - the length of the Security Domain AID. This value must be in the range [5;16].

state - the life cycle state of the Security Domain.

privs - the privileges of the Security Domain.

See Also:

OPApplet

SecurityDomain

public SecurityDomain(JCard card,
                      byte[] aid,
                      int aidBeg,
                      int aidLen)

Create the off-card representation of a Security Domain.

Parameters:

card - the JavaCard this Security Domain resides on.

aid - the buffer containing the AID of the Security Domain.

aidBeg - offset into aid.

aidLen - the length of the Security Domain AID. This value must be in the range [5;16].

See Also:

OPApplet

SecurityDomain

public SecurityDomain(JCApplet app)

Create the off-card representation of a Security Domain.

Parameters:

app - SecurityDomain object.

See Also:

OPApplet

SecurityDomain

public SecurityDomain()

Method Detail

installForLoad

public void installForLoad(byte[] pkgAID,
                           int pkgAIDBeg,
                           int pkgAIDLen,
                           byte[] sdAID,
                           int sdAIDBeg,
                           int sdAIDLen,
                           byte[] dap,
                           int dapBeg,
                           byte[] param,
                           int paramBeg,
                           int paramLen,
                           byte[] token,
                           int tokenBeg)

This method corresponds with the Golbal Platform INSTALL [for load] command. It is used to initate the load procedure and signals that one or more Global Platform LOAD commands will follow.

Parameters:

pkgAID - Load File (package) AID.

pkgAIDBeg - offset in pkgAID.

pkgAIDLen - Load File AID length.

sdAID - Security Domain AID. This Security Domain will become the associated Security Domain for any application within the load file. If this parameter is null the currently selected Security Domain is used.

sdAIDBeg - offset in sdAID.

sdAIDLen - Security Domain AID length.

dap - the Load File Data Block Hash (SHA-1 hash over the Load File). This parameter is only required in the case of Delegated Loading and/or DAP Verification (Global Platform 2.1.1). Otherwise (e.g. in case of GP 2.0.1' DAP verification) it can be null.

dapBeg - offset in dap.

param - optional load parameters. Might be null.

paramBeg - offset in param.

paramLen - load parameters length.

token - the Load Token (128 bytes RSA PKCS#1 signature). This parameter is only required in case of Delegated Loading and can be null otherwise.

tokenBeg - offset in token.

Throws:

JCException - if parameters are invalid or the command fails.

installForInstall

public byte[] installForInstall(byte[] pkgAID,
                                int pkgAIDBeg,
                                int pkgAIDLen,
                                byte[] appAID,
                                int appAIDBeg,
                                int appAIDLen,
                                byte[] instAID,
                                int instAIDBeg,
                                int instAIDLen,
                                int privs,
                                byte[] param,
                                int paramBeg,
                                int paramLen,
                                byte[] token,
                                int tokenBeg)

This method corresponds with the Global Platform INSTALL [for install] command. It is used to install an applet that has previously been loaded onto the card.

Parameters:

pkgAID - Load File (package) AID of the package including the Executable Module (applet) to be installed.

pkgAIDBeg - offset in pkgAID.

pkgAIDLen - Load file AID length.

appAID - AID of the applet to be installed.

appAIDBeg - offset in appAID.

appAIDLen - applet AID length.

instAID - AID of the applet instance to be created. If this parameter is null the instance AID will default to the applet AID.

instAIDBeg - offset in instAID.

instAIDLen - instance AID length.

privs - the desired application privileges (see below).

param - application/system specific install parameters. Might be null.

paramBeg - offset in param.

paramLen - install parameters length.

token - the Install Token (128 bytes RSA PKCS#1 signature). This parameter is only required in case of Delegated Installation and can be null otherwise.

tokenBeg - offset in token.

Returns:

In case of delegated installation an array holding the following data is returned: Install Receipt, Confirmation Counter, Card Unique Data, Load File AID and instance AID. The information is returned in the order described here and each item is length|value coded. The verifyReceipt() method takes this information as input. In case of non-delegated installation null is returned.

Throws:

JCException - if parameters are invalid or the command fails.

See Also:

verifyReceipt(byte[], int, int, com.ibm.jc.OPKey), com.ibm.jc.OPApplet.SD_PRIV, com.ibm.jc.OPApplet.SD_DAP_PRIV, com.ibm.jc.OPApplet.SD_DELEGATE_PRIV, com.ibm.jc.OPApplet.CM_LOCK_PRIV, com.ibm.jc.OPApplet.CARD_TERMINATE_PRIV, com.ibm.jc.OPApplet.IMP_SELECTABLE_PRIV, com.ibm.jc.OPApplet.PIN_CHANGE_PRIV, com.ibm.jc.OPApplet.MANDATED_DAP_PRIV, com.ibm.jc.OPApplet.NO_PRIVS

installForInstallAndMakeSelectable

public byte[] installForInstallAndMakeSelectable(byte[] pkgAID,
                                                 int pkgAIDBeg,
                                                 int pkgAIDLen,
                                                 byte[] appAID,
                                                 int appAIDBeg,
                                                 int appAIDLen,
                                                 byte[] instAID,
                                                 int instAIDBeg,
                                                 int instAIDLen,
                                                 int privs,
                                                 byte[] param,
                                                 int paramBeg,
                                                 int paramLen,
                                                 byte[] token,
                                                 int tokenBeg)

This method corresponds with the Global Platform INSTALL [for install and make selectable] command. It is used to install an applet that has previously been loaded onto the card and making it selectable.

Parameters:

pkgAID - Load File (package) AID of the package including the Executable Module (applet) to be installed.

pkgAIDBeg - offset in pkgAID.

pkgAIDLen - Load file AID length.

appAID - AID of the applet to be installed.

appAIDBeg - offset in appAID.

appAIDLen - applet AID length.

instAID - AID of the applet instance to be created. If this parameter is null the instance AID will default to the applet AID.

instAIDBeg - offset in instAID.

instAIDLen - instance AID length.

privs - the desired application privileges (see below).

param - application/system specific install parameters. Might be null.

paramBeg - offset in param.

paramLen - install parameters length.

token - the Install Token (128 bytes RSA PKCS#1 signature). This parameter is only required in case of Delegated Installation and can be null otherwise.

tokenBeg - offset in token.

Returns:

In case of delegated installation an array holding the following data is returned: Install Receipt, Confirmation Counter, Card Unique Data, Load File AID and instance AID. The information is returned in the order described here and each item is length|value coded. The verifyReceipt() method takes this information as input. In case of non-delegated installation null is returned.

Throws:

JCException - if parameters are invalid or the command fails.

See Also:

verifyReceipt(byte[], int, int, com.ibm.jc.OPKey), com.ibm.jc.OPApplet.SD_PRIV, com.ibm.jc.OPApplet.SD_DAP_PRIV, com.ibm.jc.OPApplet.SD_DELEGATE_PRIV, com.ibm.jc.OPApplet.CM_LOCK_PRIV, com.ibm.jc.OPApplet.CARD_TERMINATE_PRIV, com.ibm.jc.OPApplet.IMP_SELECTABLE_PRIV, com.ibm.jc.OPApplet.PIN_CHANGE_PRIV, com.ibm.jc.OPApplet.MANDATED_DAP_PRIV, com.ibm.jc.OPApplet.NO_PRIVS

installForMakeSelectable

public void installForMakeSelectable(byte[] instAID,
                                     int instAIDBeg,
                                     int instAIDLen,
                                     int privs,
                                     byte[] token,
                                     int tokenBeg)

This corresponds with the Global Platform INSTALL [for make selectable] command. It is used to make an installed application selectable. Furthermore, is also allows to update the Implicit Selectable privilege.

Parameters:

instAID - AID of the applet instance which is to be made selectable.

instAIDBeg - offset in instAID.

instAIDLen - instance AID length.

privs - the desired application privilege for Implicit Selectable (see below).

token - the Install Token (128 bytes RSA PKCS#1 signature). This parameter is only required in case of Delegated Installation and can be null otherwise.

tokenBeg - offset in token.

Throws:

JCException - if parameters are invalid or the command fails.

See Also:

com.ibm.jc.OPApplet.IMP_SELECTABLE_PRIV, com.ibm.jc.OPApplet.NO_PRIVS

installForExtradition

public byte[] installForExtradition(byte[] sdAID,
                                    int sdAIDBeg,
                                    int sdAIDLen,
                                    byte[] instAID,
                                    int instAIDBeg,
                                    int instAIDLen,
                                    byte[] token,
                                    int tokenBeg)

This method corresponds with the Global Platform INSTALL [for extradition] command. It is used to associate an application with another Security Domain. The Security Domain to which this application is currently associated is the currently selected application.

Parameters:

sdAID - AID of the Security Domain to which the application is to be extradited

sdAIDBeg - offset in sdAID.

sdAIDLen - Security Domain AID length.

instAID - AID of the application to be extradited.

instAIDBeg - offset in instAID.

instAIDLen - instance AID length.

token - the Extradition Token (128 bytes RSA PKCS#1 signature). This parameter is only required in case of Delegated Extradition and can be null otherwise.

tokenBeg - offset in token.

Returns:

In case of delegated extradition an array holding the following data is returned: Extradition Receipt, Confirmation Counter, Card Unique Data, old Security Domain AID, instance AID and new Security Domain AID. The information is returned in the order described here and each item is length|value coded. The verifyReceipt() method takes this information as input. In case of non-delegated installation null is returned.

Throws:

JCException - if parameters are invalid or the command fails.

See Also:

verifyReceipt(byte[], int, int, com.ibm.jc.OPKey)

installForPersonalization

public void installForPersonalization(byte[] instAID,
                                      int instAIDBeg,
                                      int instAIDLen)

This method corresponds with the Global Platform INSTALL [for personalization] command. It is used to indicate that the currently selcted Security Domain shall personalize one of its associated applications and a subsequent STORE DATA command is expected.

Parameters:

instAID - AID of the application to be personalized.

instAIDBeg - offset in instAID.

instAIDLen - instance AID length.

Throws:

JCException - if parameters are invalid or the command fails.

load

public byte[] load(CapFile capfile,
                   int[] progress,
                   int mode,
                   java.io.PrintWriter msgOut,
                   int mbl)

Loads a CAP-file (package) onto the card by utilizing the Global Platform LOAD command. It's assumed that the required INSTALL [for load] command has already been sent.

Parameters:

capfile - the CAP-file object to load.

progress - if this reference is non-null then this object signals the progress of the upload via this array. progress[1] contains the total size of the data to be uploaded and progress[0] the amount that is already transferred. Whenever the numbers are updated this method calls progress.notifyAll().

mode - the loading mode (can be mixed): LOAD_ALL - load concatenated CAP-file components (default) LOAD_COMP - load CAP-file components separately LOAD_RND - load with random APDU size (can be combined with the other two modes). LOAD_DEBUG - load debug and descriptor components (if available)

msgOut - if not null, load information is printed to this stream (e.g. the component names (mode equals 0x02 only), component sizes at end of load process, etc.).

mbl - max. block length. Maximum command APDU payload.

Returns:

in case of delegated loading this is an array holding the load receipt, confirmation counter, card identification data, load file AID and security domain AID. The information is returned in the order described here and each item is length|value coded. The verifyReceipt method takes this information as input. In case of non delegated loading null will be returned.

Throws:

JCException - if parameters or response data is invalid.

See Also:

verifyReceipt(byte[], int, int, com.ibm.jc.OPKey), LOAD_ALL, LOAD_COMP, LOAD_DEBUG, LOAD_RND

deleteKeyObject

public void deleteKeyObject(int keyID,
                            int keyVersion)

This corresponds with the Global Platform DELETE [key] command.

Parameters:

keyID - key identifier of the key to be deleted.

keyVersion - key version of the key to be deleted.

Throws:

JCException - if the command fails.

deleteObject

public byte[] deleteObject(byte[] aid,
                           int beg,
                           int len,
                           boolean deleteRelated)

This corresponds with the Global Platform DELETE command. Delete a uniquely identifiable object such as an Executable Load File, an Application or an Executable Load File and its related Applications.

Parameters:

aid - AID of the object to be deleted.

beg - offset in aid.

len - AID length.

deleteRelated - true if related objects are also to be deleted, false otherwise.

Returns:

in case of delegated deletion this is an array holding the delete receipt, confirmation counter, card identification data and the AID of the deleted object. The information is returned in the order described here and each item is length|value coded. The verifyReceipt() method takes this information as input. In case of non delegated deletion null will be returned.

Throws:

JCException - if parameters or response data is invalid.

See Also:

OPApplet.deleteKey(int, int), verifyReceipt(byte[], int, int, com.ibm.jc.OPKey)

delete

public byte[] delete(byte[] id,
                     int beg,
                     int len,
                     boolean last)

Deprecated.

Open Platform 2.0.1' DELETE command.

Parameters:

id - application identifier of instance or package to be deleted.

beg - offset in id.

len - AID length.

last - true if this is the last or only object to be deleted, false otherwise.

Returns:

in case of delegated deletion this is an array holding the delete receipt, confirmation counter, card identification data and the AID of the deleted object. The information is returned in the order described here and each item is length|value coded. The verifyReceipt() method takes this information as input. In case of non delegated deletion null will be returned.

Throws:

JCException - if parameters or response data is invalid.

See Also:

verifyReceipt(byte[], int, int, com.ibm.jc.OPKey)

verifyReceipt

public static void verifyReceipt(byte[] d,
                                 int beg,
                                 int len,
                                 OPKey rKey)

Verify a load, install, extradition or delete receipt generated during one of these operations via Delegated Management.

Parameters:

d - the receipt followed by its generation data as returned by the methods: load(), installForInstall(), installForInstallAndMakeSelectable(), installForExtradition() or delete().

rKey - the (DES) key to verify the signature.

See Also:

load(com.ibm.jc.CapFile, int[], int, java.io.PrintWriter, int), delete(byte[], int, int, boolean), installForInstall(byte[], int, int, byte[], int, int, byte[], int, int, int, byte[], int, int, byte[], int), #installForInstallAndMakeSelektable, installForExtradition(byte[], int, int, byte[], int, int, byte[], int), generateReceipt(byte[], int, int, com.ibm.jc.OPKey)

generateReceipt

public static byte[] generateReceipt(byte[] d,
                                     int beg,
                                     int len,
                                     OPKey rKey)

Generate a load, install, extradition or delete receipt.

Parameters:

d - the receipt generation data (not padded).

beg - offset in d.

len - receipt generation data length.

rKey - the (DES) key to be used for receipt generation.

Returns:

the eight byte receipt (DES MAC).

See Also:

verifyReceipt(byte[], int, int, com.ibm.jc.OPKey)