com.ibm.jc
Class OPApplet

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

Direct Known Subclasses:

pkcs15, SecurityDomain, SWIM

public class OPApplet

extends JCApplet

This class implements the off-card behavior of an applet on a (Open) Global Platform JavaCard. It provides functionality to manage keys and to communicate over a secure channel as defined in Global Platform 2.1.1 ( Secure Messaging Protocol (SCP) 01 and 02). Note: It's optional for an applet to support any of the Open Platform commands provided here.

Field Summary

static int	ADD_NEW_KEYSET PutKey mode: add new key set
protected static int	APDU_BIG_MAC Indicates MAC spanning multiple APDU - if APDU_MAC is on
static int	APDU_CLR Security level: No secure messaging
static int	APDU_CRMAC Security level: C-MAC and R-MAC (command and response MACing) Applicable for SCP 02 only.
static int	APDU_CRMAC_ENC Security level: C-DECRYPTION, C-MAC and R-MAC Applicable for SCP 02 only.
static int	APDU_ENC Security level: C-DECRYPTION and C-MAC (command MACing and encryption)
static int	APDU_MAC Security level: C-MAC (command MACing)
protected static int	APDU_MAC_START Indicates the first APDU.
static int	APDU_RMAC Security level: R-MAC (response MACing).
static int	APDU_SUPER_MAC Deprecated.
static byte	APPLICATION_LCD Accessing application/Security Domain life cycle data.
static int	BLOCKED application life cycle state
static int	CARD_TERMINATE_PRIV application privilege: Card Terminate
static byte	CM_LCD Accessing Card Manager life cycle data.
static int	CM_LOCK_PRIV application privilege: Card Manager Lock
static byte	GS_FIRST_ALL Get first or all occurence(s)
static byte	GS_FORMAT_1 Response structured according Global Platform 2.1.1 table 9-22 and 9-24
static byte	GS_FORMAT_2 Response structured according Global Platform 2.1.1 table 9-23
static byte	GS_NEXT Get next occurence(s)
protected byte[]	icv Temp buffer for DES ICV.
static int	IMP_SELECTABLE_PRIV application privilege: Implicit Selectable (default applet)
static int	INSTALLED application life cycle state
protected byte[]	K_dek Session key for sensitive data encryption.
protected byte[]	K_ea Session key for encryption and authentication.
protected byte[]	K_m Session key for C-MAC generation.
protected byte[]	K_rm Session key for R-MAC generation.
protected OPKey	Kkek Static key encryption key of the key set version used during Initialize Update.
static byte	LOAD_FILE_LCD Accessing Executable Load File life cycle data.
static byte	LOAD_FILE_MODULE_LCD Accessing Executable Load File and Executable Module life cycle data.
static int	LOCKED application life cycle state
static int	LOGICALLY_DELETED application life cycle state
static int	macSize Deprecated.
static int	MANDATED_DAP_PRIV application privilege: Mandated DAP verification
static int	MODIFY_KEYSET PutKey mode: modify key set
protected int	msgMode Secure messaging mode
static int	NO_PRIVS application privilege: none
static int	NO_SESSION Session state: No secure channel session established
static int	NOT_AVAILABLE application life cycle state
static int	PERSONALIZED application life cycle state
static int	PIN_CHANGE_PRIV application privilege: PIN Change
static int	REPLACE_KEYSET PutKey mode: replace key set
protected byte[]	ricv Temp buffer for DES ICV.
protected byte[]	rmbuf Buffer for R-MAC calculation
static int	SCP_01_05 secure channel protocol 01 option '05' (compatible with VOP 2.0.1')
static int	SCP_01_15 secure channel protocol 01 option '15'
static int	SCP_02_04 secure channel protocol 02 option '04'
static int	SCP_02_05 secure channel protocol 02 option '05'
static int	SCP_02_0A secure channel protocol 02 option '0A'
static int	SCP_02_0B secure channel protocol 02 option '0B'
static int	SCP_02_14 secure channel protocol 02 option '14'
static int	SCP_02_15 secure channel protocol 02 option '15'
static int	SCP_02_1A secure channel protocol 02 option '1A'
static int	SCP_02_1B secure channel protocol 02 option '1B'
static int	SCP_UNDEFINED secure channel protocol undefined
protected int	scpMode Secure Channel Protocol mode
static int	SD_DAP_PRIV application privilege: Security Domain with DAP verification
static int	SD_DELEGATE_PRIV application privilege: Security Domain with Delegated Managment
static int	SD_PRIV application privilege: Security Domain
static int	SELECTABLE application life cycle state
static int	SESSION_AUTH Session state: Secure channel established (mutual authentication done)
static int	SESSION_OK Session state: Card authenticated (Initialize Update done)
protected int	sessionMode Global Platform session mode
static int	VOP_201 Open Platform 2.0.1' compatible session mode
static int	VOP_211 Global Platform 2.1.1 session mode
static int	VOP_NONE No Global Platform session established

Fields inherited from class com.ibm.jc.JCApplet

apdu

Constructor Summary

OPApplet()

OPApplet(JCApplet app)
Create the off-card representation of an OpenPlatform JavaCard applet.

OPApplet(JCard card, byte[] aid, int aidBeg, int aidLen)
Create the off-card representation of an OpenPlatform JavaCard applet.

OPApplet(JCard card, byte[] aid, int aidBeg, int aidLen, byte state, byte privs)
Create the off-card representation of an OpenPlatform JavaCard applet.

Method Summary

void	beginRMACSession(int secLevel, byte[] data, int off, int len) Global Platform BEGIN R-MAC SESSION command.
OPKey	deleteKey(int keySet, int keyId) Delete specified key from key set.
void	endRMACSession() Global Platform END R-MAC SESSION command.
void	externalAuthenticate(int secLevel) Global Platform EXTERNAL AUTHENTICATE command.
void	flush() Flush secure channel parametes and reset the session state.
byte[]	getData(int p1, int p2) Global Platform GET DATA command.
OPKey	getKey(int keySet, int keyId) Looks for a key in the off-card repository.
OPKey[]	getKeys() Returns the off-card key repository.
int	getMaxPayload() Returns the maximum command APDU payload (Lc) length, which can currently be sent depending on the secuity level of the secure channel.
int	getPrivileges()
int	getSCP() Returns current secure channel protocol version.
int	getSecurityLevel() Returns the security level of the current secure channel session.
int	getSessionMode()
int	getSessionState()
int	getState()
byte[]	getStatus(byte p1) Deprecated.
byte[]	getStatus(byte p1, byte p2, byte[] qualifier, int off, int len) Global Platform GET STATUS command.
void	initializeUpdate(int keySet, int keyId) Deprecated. use initializeUpdate(int keySet, int keyId, int scp)
void	initializeUpdate(int keySet, int keyId, int scp) Global Platform INITIALIZE UPDATE command.
void	putData(int p1, int p2, byte[] data, int beg, int len) Visa Open Platform PUT DATA command.
void	putKey(int mode, OPKey[] keys, int rSet) Global Platform PUT KEY command.
byte[]	select() Select applet.
byte[]	send(byte[] data, int beg, int len) Send some APDU via the applets secure channel.
protected byte[]	sendAPDU(int lc, int le) Send APDU via secure channel.
OPKey	setKey(OPKey key) Add some key to the applets off-card repository.
void	setSCP(int scp) Allows defining the secure channel protocol to be used in subsequent implicit channel setup.
void	setSecurityLevel(int level) Deprecated.
void	setStatus(byte p1, int p2, byte[] id) Global Platform SET STATUS command.
void	storeData(byte[] data, int beg, int len, int blockNumber, boolean last) Global Platform STORE DATA command.
void	storeKeyset(OPKey[] keys, int rSet) Set Secure Channel key information via a Global Platform STORE DATA command.
void	storePKDAPKey(OPKey key) Set DAP verification public key information via a Global Platform STORE DATA command.

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

application life cycle state

See Also:

Constant Field Values

LOGICALLY_DELETED

public static final int LOGICALLY_DELETED

application life cycle state

See Also:

Constant Field Values

INSTALLED

public static final int INSTALLED

application life cycle state

See Also:

Constant Field Values

SELECTABLE

public static final int SELECTABLE

application life cycle state

See Also:

Constant Field Values

PERSONALIZED

public static final int PERSONALIZED

application life cycle state

See Also:

Constant Field Values

BLOCKED

public static final int BLOCKED

application life cycle state

See Also:

Constant Field Values

LOCKED

public static final int LOCKED

application life cycle state

See Also:

Constant Field Values

SD_PRIV

public static final int SD_PRIV

application privilege: Security Domain

See Also:

Constant Field Values

SD_DAP_PRIV

public static final int SD_DAP_PRIV

application privilege: Security Domain with DAP verification

See Also:

Constant Field Values

SD_DELEGATE_PRIV

public static final int SD_DELEGATE_PRIV

application privilege: Security Domain with Delegated Managment

See Also:

Constant Field Values

CM_LOCK_PRIV

public static final int CM_LOCK_PRIV

application privilege: Card Manager Lock

See Also:

Constant Field Values

CARD_TERMINATE_PRIV

public static final int CARD_TERMINATE_PRIV

application privilege: Card Terminate

See Also:

Constant Field Values

IMP_SELECTABLE_PRIV

public static final int IMP_SELECTABLE_PRIV

application privilege: Implicit Selectable (default applet)

See Also:

Constant Field Values

PIN_CHANGE_PRIV

public static final int PIN_CHANGE_PRIV

application privilege: PIN Change

See Also:

Constant Field Values

MANDATED_DAP_PRIV

public static final int MANDATED_DAP_PRIV

application privilege: Mandated DAP verification

See Also:

Constant Field Values

NO_PRIVS

public static final int NO_PRIVS

application privilege: none

See Also:

Constant Field Values

SCP_UNDEFINED

public static final int SCP_UNDEFINED

secure channel protocol undefined

See Also:

Constant Field Values

SCP_01_05

public static final int SCP_01_05

secure channel protocol 01 option '05' (compatible with VOP 2.0.1')

See Also:

Constant Field Values

SCP_01_15

public static final int SCP_01_15

secure channel protocol 01 option '15'

See Also:

Constant Field Values

SCP_02_04

public static final int SCP_02_04

secure channel protocol 02 option '04'

See Also:

Constant Field Values

SCP_02_05

public static final int SCP_02_05

secure channel protocol 02 option '05'

See Also:

Constant Field Values

SCP_02_0A

public static final int SCP_02_0A

secure channel protocol 02 option '0A'

See Also:

Constant Field Values

SCP_02_0B

public static final int SCP_02_0B

secure channel protocol 02 option '0B'

See Also:

Constant Field Values

SCP_02_14

public static final int SCP_02_14

secure channel protocol 02 option '14'

See Also:

Constant Field Values

SCP_02_15

public static final int SCP_02_15

secure channel protocol 02 option '15'

See Also:

Constant Field Values

SCP_02_1A

public static final int SCP_02_1A

secure channel protocol 02 option '1A'

See Also:

Constant Field Values

SCP_02_1B

public static final int SCP_02_1B

secure channel protocol 02 option '1B'

See Also:

Constant Field Values

APDU_BIG_MAC

protected static final int APDU_BIG_MAC

Indicates MAC spanning multiple APDU - if APDU_MAC is on

See Also:

msgMode, Constant Field Values

APDU_MAC_START

protected static final int APDU_MAC_START

Indicates the first APDU. This bit is cleared after 1st APDU MACed under APDU_BIG_MAC.

See Also:

msgMode, Constant Field Values

APDU_CLR

public static final int APDU_CLR

Security level: No secure messaging

See Also:

getSecurityLevel(), Constant Field Values

APDU_MAC

public static final int APDU_MAC

Security level: C-MAC (command MACing)

See Also:

getSecurityLevel(), Constant Field Values

APDU_ENC

public static final int APDU_ENC

Security level: C-DECRYPTION and C-MAC (command MACing and encryption)

See Also:

getSecurityLevel(), Constant Field Values

APDU_RMAC

public static final int APDU_RMAC

Security level: R-MAC (response MACing). Applicable for SCP 02 only.

See Also:

getSecurityLevel(), Constant Field Values

APDU_CRMAC

public static final int APDU_CRMAC

Security level: C-MAC and R-MAC (command and response MACing) Applicable for SCP 02 only.

See Also:

getSecurityLevel(), Constant Field Values

APDU_CRMAC_ENC

public static final int APDU_CRMAC_ENC

Security level: C-DECRYPTION, C-MAC and R-MAC Applicable for SCP 02 only.

See Also:

getSecurityLevel(), Constant Field Values

APDU_SUPER_MAC

public static final int APDU_SUPER_MAC

Deprecated.

Security level: Indicates that C-MAC chaining starts

See Also:

Constant Field Values

NO_SESSION

public static final int NO_SESSION

Session state: No secure channel session established

See Also:

getSessionState(), Constant Field Values

SESSION_OK

public static final int SESSION_OK

Session state: Card authenticated (Initialize Update done)

See Also:

getSessionState(), Constant Field Values

SESSION_AUTH

public static final int SESSION_AUTH

Session state: Secure channel established (mutual authentication done)

See Also:

getSessionState(), Constant Field Values

CM_LCD

public static final byte CM_LCD

Accessing Card Manager life cycle data.

See Also:

Constant Field Values

APPLICATION_LCD

public static final byte APPLICATION_LCD

Accessing application/Security Domain life cycle data.

See Also:

Constant Field Values

LOAD_FILE_LCD

public static final byte LOAD_FILE_LCD

Accessing Executable Load File life cycle data.

See Also:

Constant Field Values

LOAD_FILE_MODULE_LCD

public static final byte LOAD_FILE_MODULE_LCD

Accessing Executable Load File and Executable Module life cycle data.

See Also:

Constant Field Values

GS_FIRST_ALL

public static final byte GS_FIRST_ALL

Get first or all occurence(s)

See Also:

Constant Field Values

GS_NEXT

public static final byte GS_NEXT

Get next occurence(s)

See Also:

Constant Field Values

GS_FORMAT_1

public static final byte GS_FORMAT_1

Response structured according Global Platform 2.1.1 table 9-22 and 9-24

See Also:

Constant Field Values

GS_FORMAT_2

public static final byte GS_FORMAT_2

Response structured according Global Platform 2.1.1 table 9-23

See Also:

Constant Field Values

macSize

public static final int macSize

Deprecated.

MAC size. If MACing is turned on then each APDU is send with a MAC of this size.

See Also:

Constant Field Values

MODIFY_KEYSET

public static final int MODIFY_KEYSET

PutKey mode: modify key set

See Also:

Constant Field Values

REPLACE_KEYSET

public static final int REPLACE_KEYSET

PutKey mode: replace key set

See Also:

Constant Field Values

ADD_NEW_KEYSET

public static final int ADD_NEW_KEYSET

PutKey mode: add new key set

See Also:

Constant Field Values

VOP_201

public static final int VOP_201

Open Platform 2.0.1' compatible session mode

See Also:

Constant Field Values

VOP_211

public static final int VOP_211

Global Platform 2.1.1 session mode

See Also:

Constant Field Values

VOP_NONE

public static final int VOP_NONE

No Global Platform session established

See Also:

Constant Field Values

sessionMode

protected int sessionMode

Global Platform session mode

scpMode

protected int scpMode

Secure Channel Protocol mode

icv

protected byte[] icv

Temp buffer for DES ICV. Used for C-MAC chaining

ricv

protected byte[] ricv

Temp buffer for DES ICV. Used for R-MAC chaining

rmbuf

protected byte[] rmbuf

Buffer for R-MAC calculation

msgMode

protected int msgMode

Secure messaging mode

K_m

protected byte[] K_m

Session key for C-MAC generation. This key is created during Initialize Update. If session key establishment uses a different algorithm subclasses may set the key directly.

See Also:

initializeUpdate(int, int)

K_ea

protected byte[] K_ea

Session key for encryption and authentication. This key is created during Initialize Update. If session key establishment uses a different algorithm subclasses may set the key directly.

See Also:

initializeUpdate(int, int)

K_rm

protected byte[] K_rm

Session key for R-MAC generation. This key is created during Initialize Update. If session key establishment uses a different algorithm subclasses may set the key directly. Applicable for Secure Messaging Protocol 02 only.

See Also:

initializeUpdate(int, int)

K_dek

protected byte[] K_dek

Session key for sensitive data encryption. This key is created during Initialize Update. If session key establishment uses a different algorithm subclasses may set the key directly. Applicable for Secure Messaging Protocol 02 only.

See Also:

initializeUpdate(int, int)

Kkek

protected OPKey Kkek

Static key encryption key of the key set version used during Initialize Update. Used for key encryption in case of an OpenPlatform PUT KEY command. Applicable for Secure Messaging Protocol 01 only.

See Also:

initializeUpdate(int, int)

Constructor Detail

OPApplet

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

Create the off-card representation of an OpenPlatform JavaCard applet.

Parameters:

card - the JavaCard on which this applet lives

aid - the buffer containing the AID of the applet

aidBeg - start offset for AID

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

state - the life cycle state of the applet.

privs - the privileges of the applet.

See Also:

JCApplet

OPApplet

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

Create the off-card representation of an OpenPlatform JavaCard applet.

Parameters:

card - the JavaCard on which this applet lives

aid - the buffer containing the AID of the applet

aidBeg - start offset for AID

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

See Also:

JCApplet

OPApplet

public OPApplet(JCApplet app)

Create the off-card representation of an OpenPlatform JavaCard applet.

Parameters:

app - JCApplet object.

See Also:

JCApplet

OPApplet

public OPApplet()

Method Detail

getState

public int getState()

Returns:

the applet life cycle state.

See Also:

NOT_AVAILABLE, LOGICALLY_DELETED, INSTALLED, SELECTABLE, PERSONALIZED, BLOCKED, LOCKED

getPrivileges

public int getPrivileges()

Returns:

the applet privileges.

See Also:

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

getMaxPayload

public int getMaxPayload()

Returns the maximum command APDU payload (Lc) length, which can currently be sent depending on the secuity level of the secure channel. This value depends on the secure messaging state.

Returns:

max. payload length

send

public byte[] send(byte[] data,
                   int beg,
                   int len)

Send some APDU via the applets secure channel. The data is examined and LC and LE are recovered. This recovery is ambigious because of LE. data[beg+4] is taken as LC and it is checked against len parameter. It must equal to len-5 (no LE present) or must match len-6 (last byte of data is LE). Command APDU with no LC but LE present are identified by len==5 and data[beg+4] not being zero. LC missing and LE=0 is not distinguishable from LC=0 and LE missing. APDUs with LE=0 must have an LC field. If no secure session exists (getSessionState() == NO_SESSION) and a SCP, which allows implicit session initiation has been set via setSCP(), then implicit session initiation takes place automatically.

Parameters:

data - APDU buffer

beg - where APDU starts

len - length of APDU

Throws:

JCException - if APDU format (e.g. LC and APDU length) is inconsistent.

sendAPDU

protected byte[] sendAPDU(int lc,
                          int le)

Send APDU via secure channel. Secure messaging is controlled by the variable msgMode. The maximum data length depends on the secure messaging parameters. If a MAC is is added or if padding happens because of encryption. If no secure session exists (getSessionState() == NO_SESSION) and a SCP, which allows implicit session initiation has been set via setSCP(), then implicit session initiation takes place automatically.

Parameters:

lc - length control value. If -1 then send only 4 byte APDU. The final LC value after possible MACing and possible encryption must hold: 0<=lc<=255.

le - Length of expected response. If -1 then no le is added to the APDU

Returns:

response APDU

Throws:

JCException - if the session state is illegal or lc is invalid.

See Also:

msgMode

setSecurityLevel

public void setSecurityLevel(int level)

Deprecated.

Set security level for secure channel.

See Also:

APDU_CLR, APDU_MAC, APDU_ENC, APDU_RMAC, APDU_CRMAC, APDU_CRMAC_ENC

getSecurityLevel

public int getSecurityLevel()

Returns the security level of the current secure channel session.

Returns:

Current security level.

See Also:

APDU_CLR, APDU_MAC, APDU_ENC, APDU_RMAC, APDU_CRMAC, APDU_CRMAC_ENC

getSessionState

public int getSessionState()

Returns:

current session state (with on-card counterpart)

See Also:

NO_SESSION, SESSION_OK, SESSION_AUTH

getSessionMode

public int getSessionMode()

Returns:

Current Global Platform session mode.

See Also:

VOP_NONE, VOP_201, VOP_211

getSCP

public int getSCP()

Returns current secure channel protocol version.

Returns:

Current Global Platform secure channel protocol identifier.

See Also:

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

setSCP

public void setSCP(int scp)

Allows defining the secure channel protocol to be used in subsequent implicit channel setup.

Parameters:

scp - Desired secure channel protocol

Throws:

JCException - if parameters are invalid.

See Also:

SCP_02_0A, SCP_02_0B, SCP_02_1A, SCP_02_1B

getData

public byte[] getData(int p1,
                      int p2)

Global Platform GET DATA command. Used to retrieve a signle data object.

Parameters:

p1 - high byte of the tag indicating which data object to be retrieved.

p2 - low byte of the tag indicating which data object to be retrieved.

Returns:

response APDU

Throws:

JCException - if response status is not equals 0x9000 or the format of the response is not TLV.

putData

public void putData(int p1,
                    int p2,
                    byte[] data,
                    int beg,
                    int len)

Visa Open Platform PUT DATA command. Used to put different types of data.

Parameters:

p1 - high byte of the data tag indicating which data to be put.

p2 - low byte of the data tag indicating which data to be put.

data - array holding the data to be put.

beg - offset in the data array.

len - length of the data.

Throws:

JCException - if response status is not equals 0x9000

storeData

public void storeData(byte[] data,
                      int beg,
                      int len,
                      int blockNumber,
                      boolean last)

Global Platform STORE DATA command. Used to transfer data to an application or Security Domain.

Parameters:

data - array holding the data to be stored.

beg - offset in the data array.

len - length of the data.

blockNumber - block number 0x00-0xFF.

last - true if this is the last block, false otherwise.

Throws:

JCException - if response status is not equals 0x9000

setStatus

public void setStatus(byte p1,
                      int p2,
                      byte[] id)

Global Platform SET STATUS command. Used to modify the life cycle state of the Card Manager or an Application/Security Domain. If an applet supports this command it can only attempt to transition its own life cycle state, attempt to lock the Card Manager or to terminate the card. However, the card manager can modify its own state as well as that of an application.

Parameters:

p1 - defines whether card manager or application state is to be modified (APPLICATION_LCD, CM_LCD)

p2 - the state to transition to (e.g. PERSONALIZED).

id - AID of the target (AID of this applet if null)

Throws:

JCException - if response status is not equals 0x9000

See Also:

CM_LCD, APPLICATION_LCD, INSTALLED, SELECTABLE, PERSONALIZED, BLOCKED, LOCKED, CardManager

getStatus

public byte[] getStatus(byte p1)

Deprecated.

Open Platform GET STATUS command. Used to retrieve card manager, load file (package) and application/security domain life cycle data. If an applet supports this command it can only report about its own life cycle state but not its privileges. However, the card manager can respond with information related to its own life cycle as well as package and application life cycles and their privileges.

Parameters:

p1 - defines whether card manager, application or load file life cycle data is to be retrieved (APPLICATION_LCD, CM_LCD or LOAD_FILE_LCD)

Returns:

response APDU.

Throws:

JCException - if response status is not equals 0x9000

See Also:

CM_LCD, APPLICATION_LCD, LOAD_FILE_LCD

getStatus

public byte[] getStatus(byte p1,
                        byte p2,
                        byte[] qualifier,
                        int off,
                        int len)

Global Platform GET STATUS command. Used to retrieve Card Manager, Executable Load File (package), Executable Module (applet in package) and application/Security Domain (instance) life cycle data. If an applet supports this command it can only report about its own life cycle state but not its privileges. However, the card manager can respond with information related to its own life cycle as well as package and application life cycles and their privileges.

Parameters:

p1 - defines whether Card Manager (CM_LCD), application/Security Domain (APPLICATION_LCD), Executable Load file (LOAD_FILE_LCD) or Executable Load file and Executable Module (LOAD_FILE_MODULE_LCD) life cycle data is to be retrieved.

p2 - controls the number of consecutive GET STATUS commands and indicates the format of the response message. Must be a combination of the following flags: GS_FIRST_ALL, GS_NEXT, GS_FORMAT_1, GS_FORMAT_2.

qualifier - TLV coded serach qualifier(s). If null, search criteria 0x4F00 is used meaning that all occurences match.

off - offset where the seach qualifier(s) start.

len - length of the seach qualifier(s).

Returns:

response APDU.

Throws:

JCException - if response status is not equals 0x9000

See Also:

CM_LCD, APPLICATION_LCD, LOAD_FILE_LCD, LOAD_FILE_MODULE_LCD, GS_FIRST_ALL, GS_NEXT, GS_FORMAT_1, GS_FORMAT_2

getKey

public OPKey getKey(int keySet,
                    int keyId)

Looks for a key in the off-card repository.

Parameters:

keySet - the key set version of the key to look for.

keyId - the ID of the key to look for.

Returns:

off-card key.

Throws:

JCException - if the requested key is not present.

getKeys

public OPKey[] getKeys()

Returns the off-card key repository. Returned array is sparsely populated and might contain null pointers. It's shared with this instance - don't modify it.

Returns:

all off-card keys.

deleteKey

public OPKey deleteKey(int keySet,
                       int keyId)

Delete specified key from key set.

Parameters:

keySet - the key set version of the key to delete.

keyId - the ID of the key to delete.

Returns:

the deleted key or null if the key did not exist.

setKey

public OPKey setKey(OPKey key)

Add some key to the applets off-card repository. Note that the key is only added to the off-card representation and no PUT KEY command sent to actually upload the key to the card.

If such a key already exists the new key replaces the existing one.

Parameters:

key - the key object to add.

See Also:

putKey(int, com.ibm.jc.OPKey[], int)

flush

public void flush()

Flush secure channel parametes and reset the session state.

Overrides:

flush in class JCApplet

select

public byte[] select()

Select applet.

Overrides:

select in class JCApplet

Returns:

response APDU.

Throws:

if - status of R-APDU is neither JCStatus.NOERROR (9000) nor JCStatus.APPLET_INVALIDATED (6283).

initializeUpdate

public void initializeUpdate(int keySet,
                             int keyId)

Deprecated. use initializeUpdate(int keySet, int keyId, int scp)

Global Platform INITIALIZE UPDATE command. Used to initiate the setting up of a secure channel according to Global Platform 2.0.1.

Parameters:

keySet - Key Set Version to be used for session key generation. If set to zero the on-card counterpart dictates which key set to be used.

keyId - Key ID. This parameter is usually ignored and shall be set to zero.

Throws:

JCException - If response data or keys are invalid.

initializeUpdate

public void initializeUpdate(int keySet,
                             int keyId,
                             int scp)

Global Platform INITIALIZE UPDATE command. Used to initiate (explicit) the setting up of a secure channel according to Global Platform 2.1.1.

Parameters:

keySet - Key Set Version to be used for session key generation. If set to zero the on-card counterpart dictates which key set to be used.

keyId - Key ID. This parameter is usually ignored and shall be set to zero.

scp - Desired secure channel protocol. If this parameter is SCP_UNDEFINED, SCP_02_15 is used if the card indicates SCP 02 in the INITIALIZE UPDATE response APDU, SCP_01_05 is used otherwise.

Throws:

JCException - If response data, keys or parameters are invalid.

See Also:

SCP_UNDEFINED, SCP_01_05, SCP_01_15, SCP_02_04, SCP_02_05, SCP_02_14, SCP_02_15

externalAuthenticate

public void externalAuthenticate(int secLevel)

Global Platform EXTERNAL AUTHENTICATE command. Used by the card to authentication the host and to determine the security level of the resulting secure messaging channel. The method initializeUpdate() must have been executed successfully beforehand.

Parameters:

secLevel - the desired level of security required for all subsequent APDUs.

Throws:

JCException - If authentication failed or invalid session state.

See Also:

APDU_CLR, APDU_MAC, APDU_ENC, APDU_RMAC, APDU_CRMAC, APDU_CRMAC_ENC

beginRMACSession

public void beginRMACSession(int secLevel,
                             byte[] data,
                             int off,
                             int len)

Global Platform BEGIN R-MAC SESSION command. Used to initiate APDU response message integrity. This implementation does not allow to begin a R-MAC session outside of a secure channel. This means a channel (SCP 02) must be already established.

Parameters:

secLevel - the desired level of security required for all subsequent response APDUs.

data - Data to be included in the command. Might be null.

off - Offset where the data starts.

len - Length of the data.

Throws:

JCException - If parameteres are invalid, no secure channel is established or the the command failed for some reason.

See Also:

APDU_CLR, APDU_RMAC

endRMACSession

public void endRMACSession()

Global Platform END R-MAC SESSION command. Used to terminate APDU response message integrity.

Throws:

JCException - If no secure channel with R-MAC exists or the the command failed for some reason.

storePKDAPKey

public void storePKDAPKey(OPKey key)

Set DAP verification public key information via a Global Platform STORE DATA command. The public key is stored in key set version 0x73 at index 1.

Parameters:

key - the 1024 bits RSA public key to be stored.

Throws:

JCException - if the key is invalid or the STORE DATA command fails.

storeKeyset

public void storeKeyset(OPKey[] keys,
                        int rSet)

Set Secure Channel key information via a Global Platform STORE DATA command. Used to add or replace one complete key set verison (keys at index 1,2 and 3) via a STORE DATA command.

Parameters:

keys - array holding the three keys to be stored. All keys in this array must belong to the same key set version and they must be sorted (key with lowest index (1) at array position 0). Array elements must not be null.

rSet - the key set version to be replaced (value 0x01-0x6F). If a new key set version is to be added, this parameter must be zero.

Throws:

JCException - if parameters are invalid or the STORE DATA command fails.

putKey

public void putKey(int mode,
                   OPKey[] keys,
                   int rSet)

Global Platform PUT KEY command. Used to add/modify/replace one or more DES keys or to add one RSA public key. Note: The assumption is that all keys fit within one APDU. Chained PUT KEY commands spanning multiple APDUs as defined in Global Platform are not supported by this implementation.

Parameters:

mode - defines whether the key set to which the keys belong to is to be modified, replaced or added.

keys - array holding the keys to be put. All keys in this array must be in the same key set and they must be sorted (key with lowest index at array position 0). Array elements must not be null.

rSet - the key set which is to be replaced if the mode parameter is set to REPLACE_KEYSET. Otherwise this parameter is ignored and the target key set is always the key set the keys belong to.

Throws:

JCException - if the parameters or the card response (e.g. the key check values) are invalid.

See Also:

MODIFY_KEYSET, REPLACE_KEYSET, ADD_NEW_KEYSET