com.ibm.jc
Class CardManager

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

public class CardManager

extends SecurityDomain

This class implements the off-card behavior of the Global Platform Card Manager which incorporates the Global Platform Environment, the Issuer Security Domain and the Cardholder Verification Methods.

Field Summary

static int	CM_LOCKED Card Manager life cycle state
static int	CVM_BLOCK CVM change operation: transition to BLOCKED state
static int	CVM_FORMAT_ASCII CVM encoding format ASCII
static int	CVM_FORMAT_BCD CVM encoding format BCD
static int	CVM_FORMAT_HEX CVM encoding format HEX
static int	CVM_UNBLOCK CVM change operation: transition to ACTIVE state
static byte[]	daid default card manager AID
static int	GET_ALL Mode flag to get Applets and Security Domains
static int	GET_APPLETS Mode flag to get Applets only
static int	GET_SECURITY_DOMAINS Mode flag to get Security Domains only
static int	INITIALIZED Card Manager life cycle state
static int	NOT_AVAILABLE Card Manager life cycle state
static int	OP_READY Card Manager life cycle state
static int	SECURED Card Manager life cycle state
static int	TERMINATED Card Manager life cycle state

Fields inherited from class com.ibm.jc.SecurityDomain

LOAD_ALL, LOAD_COMP, LOAD_DEBUG, LOAD_RND

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, 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

CardManager()

CardManager(JCApplet app)
Create the off-card representation of the Card Manager.

CardManager(JCard card, byte[] aid)
Create the off-card representation of the Card Manager.

CardManager(JCard card, byte[] aid, int aidBeg, int aidLen)
Create the off-card representation of the Card Manager.

CardManager(JCard card, byte[] aid, int aidBeg, int aidLen, byte state)
Create the off-card representation of the Card Manager.

Method Summary

void	changeUnblockPIN(int tries, byte[] pin) Open Platform 2.0.1' PIN CHANGE/UNBLOCK command.
void	cvmBlockUnblock(int operation) This command allowes to block/unblock the CVM.
void	cvmUpdate(byte[] pin, int pinOff, int pinLen, int format, int tryLimit) This command updates the CVM value and/or the CVM try limit.
void	flush() Flush secure channel parametes, resets the session state and flushes off-card cache of registry information.
java.lang.Object[]	getApplets(int mode, int format, boolean queryCard) Returns Applets and/or Security Domains listed in the card registry.
byte[]	getCardProdLifeCycle() Returns the Card Manager production life cycle (CPLC) data as returned in the select FCI.
byte[]	getFciDiscretionaryData() Returns the FCI Discretionary data as returned in the select FCI.
LoadFile[]	getLoadFiles(int format, boolean queryCard) Returns Load Files listed in the card registry.
int	getMaxBlockLen() Returns the maximum block (APDU payload) length.
int[]	getOSInfo() Reads the card production life cycle info from the card and returns operating system information.
int	getPrivileges() The Card Manager has no privileges associated.
byte[]	getSDManagementData() Returns the Security Domain Management data as returned in the select FCI.
int	getState() Returns the current Card Manager life cycle state.
byte[]	select() Select the Card Manager (parital select possible).
byte[]	setAID(byte[] id, boolean onCard) Sets the AID of the Card Manager.
void	setMaxBlockLen(int len) Sets the maximum block (APDU payload) length.
byte[]	storeAID(byte[] id, int off, int len, boolean onCard) Sets the AID of the Card Manager.
void	update() Updates the life cycle state and the AID of the Card Manager cached off-card.

Methods inherited from class com.ibm.jc.SecurityDomain

delete, deleteKeyObject, deleteObject, generateReceipt, installForExtradition, installForInstall, installForInstallAndMakeSelectable, installForLoad, installForMakeSelectable, installForPersonalization, load, verifyReceipt

Methods inherited from class com.ibm.jc.OPApplet

beginRMACSession, deleteKey, endRMACSession, externalAuthenticate, getData, getKey, getKeys, getMaxPayload, getSCP, getSecurityLevel, getSessionMode, getSessionState, getStatus, getStatus, initializeUpdate, initializeUpdate, putData, putKey, 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

NOT_AVAILABLE

public static final int NOT_AVAILABLE

Card Manager life cycle state

See Also:

Constant Field Values

OP_READY

public static final int OP_READY

Card Manager life cycle state

See Also:

Constant Field Values

INITIALIZED

public static final int INITIALIZED

Card Manager life cycle state

See Also:

Constant Field Values

SECURED

public static final int SECURED

Card Manager life cycle state

See Also:

Constant Field Values

CM_LOCKED

public static final int CM_LOCKED

Card Manager life cycle state

See Also:

Constant Field Values

TERMINATED

public static final int TERMINATED

Card Manager life cycle state

See Also:

Constant Field Values

CVM_FORMAT_HEX

public static final int CVM_FORMAT_HEX

CVM encoding format HEX

See Also:

Constant Field Values

CVM_FORMAT_ASCII

public static final int CVM_FORMAT_ASCII

CVM encoding format ASCII

See Also:

Constant Field Values

CVM_FORMAT_BCD

public static final int CVM_FORMAT_BCD

CVM encoding format BCD

See Also:

Constant Field Values

CVM_BLOCK

public static final int CVM_BLOCK

CVM change operation: transition to BLOCKED state

See Also:

Constant Field Values

CVM_UNBLOCK

public static final int CVM_UNBLOCK

CVM change operation: transition to ACTIVE state

See Also:

Constant Field Values

GET_APPLETS

public static final int GET_APPLETS

Mode flag to get Applets only

See Also:

Constant Field Values

GET_SECURITY_DOMAINS

public static final int GET_SECURITY_DOMAINS

Mode flag to get Security Domains only

See Also:

Constant Field Values

GET_ALL

public static final int GET_ALL

Mode flag to get Applets and Security Domains

See Also:

Constant Field Values

daid

public static final byte[] daid

default card manager AID

Constructor Detail

CardManager

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

Create the off-card representation of the Card Manager.

Parameters:

card - the JavaCard on which this Card Manager resides on.

aid - the buffer containing the AID of the Card Manager.

aidBeg - offset into aid.

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

state - the life cycle state of the Card Manager.

See Also:

NOT_AVAILABLE, OP_READY, INITIALIZED, SECURED, CM_LOCKED, TERMINATED

CardManager

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

Create the off-card representation of the Card Manager.

Parameters:

card - the JavaCard on which this Card Manager resides on.

aid - the buffer containing the AID of the Card Manager.

aidBeg - offset into aid

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

CardManager

public CardManager(JCard card,
                   byte[] aid)

Create the off-card representation of the Card Manager.

Parameters:

card - the JavaCard on which this Card Manager resides on.

aid - the buffer containing the AID of the Card Manager.

CardManager

public CardManager(JCApplet app)

Create the off-card representation of the Card Manager.

Parameters:

app - CardManager object.

See Also:

OPApplet

CardManager

public CardManager()

Method Detail

getPrivileges

public int getPrivileges()

The Card Manager has no privileges associated. An exception of type JCException will be thrown.

Overrides:

getPrivileges in class OPApplet

Returns:

the applet privileges.

See Also:

OPApplet.NO_PRIVS, OPApplet.SD_PRIV, OPApplet.SD_DAP_PRIV, OPApplet.SD_DELEGATE_PRIV, OPApplet.MANDATED_DAP_PRIV, OPApplet.CM_LOCK_PRIV, OPApplet.CARD_TERMINATE_PRIV, OPApplet.IMP_SELECTABLE_PRIV, OPApplet.PIN_CHANGE_PRIV

getMaxBlockLen

public int getMaxBlockLen()

Returns the maximum block (APDU payload) length.

Returns:

max. block length.

setMaxBlockLen

public void setMaxBlockLen(int len)

Sets the maximum block (APDU payload) length.

Parameters:

len - desired max. block length (should be in the range 32-255).

select

public byte[] select()

Select the Card Manager (parital select possible). The method tries to parse the FCI returned by the card and extracts Security Domain Management Data, Card Production Life Cycle (CPLC) data, FCI discretionary data and the maximum block (APDU payload) length, if available.

Overrides:

select in class OPApplet

Returns:

response APDU.

Throws:

JCException - if invalid response.

See Also:

getFciDiscretionaryData(), getSDManagementData(), getCardProdLifeCycle(), getMaxBlockLen()

cvmBlockUnblock

public void cvmBlockUnblock(int operation)

This command allowes to block/unblock the CVM. This is an extension to the Global Platform specification.

Parameters:

operation - indicates whether the CVM shall be block or unblocked.

Throws:

JCException - if parameters are invalid or the command failed.

See Also:

CVM_BLOCK, CVM_UNBLOCK

cvmUpdate

public void cvmUpdate(byte[] pin,
                      int pinOff,
                      int pinLen,
                      int format,
                      int tryLimit)

This command updates the CVM value and/or the CVM try limit. This is an extension to the Global Platform specification. The command is only allowed in the context of a secure channel using SCP 02.

Parameters:

pin - array holding the CVM value. If the CVM value is not to be updated, this parameter can be null.

pinOff - the offset into pin.

pinLen - the CVM length in the range of 4-12. If the format is CVM_FORMAT_HEX or CVM_FORMAT_ASCII this parameter indicates the number of CVM value bytes in pin. If the format is CVM_FORMAT_BCD this parameter indicates the number of nibbles within pin representing the CVM value. In the latter case the least significant nibble might be unused if the CVM length is odd.

format - the CVM encoding format (e.g. CVM_FORMAT_HEX).

tryLimit - the desired CVM try limit in the range of 1-15. If this value is zero the CVM state is set to INACTIVE. If this value is negative, the CVM try limit is not updated.

Throws:

JCException - if parameters are invalid or the command failed.

See Also:

CVM_FORMAT_HEX, CVM_FORMAT_ASCII, CVM_FORMAT_BCD

changeUnblockPIN

public void changeUnblockPIN(int tries,
                             byte[] pin)

Open Platform 2.0.1' PIN CHANGE/UNBLOCK command. Changes or unblocks the Global PIN.

Parameters:

tries - Max. false retry limit in case of a PIN change.

pin - New PIN value to be set (ASCII digits in the range 0x30-0x39). If null the PIN is unblocked and the parameters are ignored.

Throws:

JCException - if PIN or session state is invalid.

flush

public void flush()

Flush secure channel parametes, resets the session state and flushes off-card cache of registry information.

Overrides:

flush in class OPApplet

getOSInfo

public int[] getOSInfo()

Reads the card production life cycle info from the card and returns operating system information.

Returns:

array holding OS ID, OS release date and OS release level (in this order).

getLoadFiles

public LoadFile[] getLoadFiles(int format,
                               boolean queryCard)

Returns Load Files listed in the card registry. This method either returns the information cached off-card, or sends one or more Global Platform GET STATUS commands to the card to retrieve the information. In the latter case the off-card cache is updated. If supported by the card, information about existing Executable Modules within the Load Files is also retrieved.

Parameters:

format - format

queryCard - if false the info comes from the off-card cache, otherwise the card is consulted.

Returns:

array of Load Files. Might be null if the card is empty.

Throws:

JCException - if any error occurs.

getApplets

public java.lang.Object[] getApplets(int mode,
                                     int format,
                                     boolean queryCard)

Returns Applets and/or Security Domains listed in the card registry. This function either returns the information cached off-card, or sends one or more Global Platform GET STATUS commands to the card to retrieve the information. In the latter case the off-card cache is updated.

Parameters:

mode - defines whether Applets, Security Domains or both are to be returned.

format - format

queryCard - if false the info comes from the off-card cache, otherwise the card is consulted.

Returns:

array holding objects of type OPApplet, SecurityDomain, or both (depending on the mode). If the card is empty null is returned.

Throws:

JCException - if parameters are invalid or a GET STATUS command fails.

See Also:

GET_APPLETS, GET_SECURITY_DOMAINS, GET_ALL

getCardProdLifeCycle

public byte[] getCardProdLifeCycle()

Returns the Card Manager production life cycle (CPLC) data as returned in the select FCI.

Returns:

the CPLC (6 bytes). Might be null if not available.

getFciDiscretionaryData

public byte[] getFciDiscretionaryData()

Returns the FCI Discretionary data as returned in the select FCI.

Returns:

the FCI Discretionary Data. Might be null if not available.

getSDManagementData

public byte[] getSDManagementData()

Returns the Security Domain Management data as returned in the select FCI.

Returns:

the Security Domain Management data. Might be null if not available.

update

public void update()

Updates the life cycle state and the AID of the Card Manager cached off-card. A Global Platform GET STATUS command is sent to the card to achieve this.

Throws:

JCException - if any error occurs.

See Also:

getState(), com.jc.JCApplet.getAID

getState

public int getState()

Returns the current Card Manager life cycle state. (this information comes from the off-card cache, use update() to update the cache).

Overrides:

getState in class OPApplet

Returns:

the card manager life cycle state.

See Also:

NOT_AVAILABLE, OP_READY, INITIALIZED, SECURED, CM_LOCKED, TERMINATED, update()

setAID

public byte[] setAID(byte[] id,
                     boolean onCard)

Sets the AID of the Card Manager. If the AID is to be modified on-card, an Open Platform 2.0.1' PUT DATA command is sent to the card to achieve this.

Parameters:

id - array holding the new AID (array is not copied). If null, the default AID is set.

onCard - if true, the AID is modified off-card and on-card, otherwise the AID is only modified off-card.

Returns:

the new AID.

See Also:

storeAID(byte[], int, int, boolean)

storeAID

public byte[] storeAID(byte[] id,
                       int off,
                       int len,
                       boolean onCard)

Sets the AID of the Card Manager. If the AID is to be modified on-card, a Global Platform 2.1.1 STORE DATA command is sent to the card to achieve this.

Parameters:

id - array holding the new AID. If null, the default AID is set.

off - offset into id.

len - length of the new AId.

onCard - if true, the AID is modified off-card and on-card, otherwise the AID is only modified off-card.

Returns:

the new AID.

See Also:

setAID(byte[], boolean)