Additional JCOP on-card API: SEED API

Introduction

Certain versions of JCOP feature an applet programmer's interface (API) that is beyond the scope of the APIs described in the general specifications. When present, the API described in this document is providing access to a cryptographic block cipher defined by the Korean Institute for Standards (KISA), the SEED algorithm.

This document describes this SEED API. It is not of relevance for other purposes and should then be disregarded.

Package

The code for accessing the SEED algorithm is contained in the class

jz.framework.JZSystem

Any code that shall make use of this API has to import this class.

Constants

All constants to be used are bit masks controlling the operation of the crypto method:

• JZSystem.SEED: Indicator of the SEED algorithm (to be set in keyType parameter)
• JZSystem.ENCRYPT: Indicator to encrypt the given data
• JZSystem.DECRYPT: Indicator to decrypt the given data
• JZSystem.MAC: Run the algorithm in Message Authentication Mode using the ICV
• JZSystem.ZERO_ICV: Indicator to clear the specified ICV area before processing a MAC operation

Method

void JZSystem.crypto(short mode, short keyType, byte[] key, short keyBegin, byte[] icv, short icvBeg, byte[] buf, short bufBeg, short blocks)

The parameters have the following meaning:

• mode: Of the bit mask constants listed above, at least one of the mutually exclusive JZSystem.ENCRYPT, JZSystem.DECRYPT, or JZSystem.MAC must be set.
• keyType: JZSystem.SEED must be passed here to run the SEED algorithm.
• key: The byte array containing the key data.
• keyBeg: The start position of the key in the key parameter. The key length is 16 bytes for the SEED algorithm.
• icv: The byte array holding the initialization and continuation vector for MACing operations; this parameter must not be null when mode is set to JZSystem.MAC.
• icvBeg: The start position of the ICV vector in the icv parameter. The ICV length is 16 bytes for the SEED algorithm.
• buf: The buffer holding the input data and receiving the output data. In case of MACing (mode = JZSystem.MAC) this buffer is only read and the data may be in persistent memory. Otherwise, the data buffer must be in transient memory.
• bufBeg: The start position of the input/output data in the buf parameter.
• blocks: The number of 16 byte long blocks to be processed following the bufBeg parameter.

The method may throw a CryptoException if the wrong keyType was passed, no ICV byte array was provided, but a MAC operation was demanded, or simply if the card does not support the SEED algorithm, e.g., due to export control measures.

Sample Code

Sample code making use of this API is listed below:

import jz.framework.JZSystem;

[...]

byte[] buf = apdu.getBuffer();
byte[] key = JCSystem.makeTransientByteArray((short)16); // to hold key data (all 0 at the start)

apdu.setIncomingAndReceive(); // assume APDU buffer contains data to be encrypted

JZSystem.crypto(JZSystem.ENCRYPT, JZSystem.SEED, key, (short)0,
     null, (short)0, // No MACing done, no ICV required
     buf, ISO7816.OFFSET_CDATA, (short)1); // encrypt one block of command data

// send this block back
apdu.setOutgoingAndSend(ISO7816.OFFSET_CDATA, (short)16);


Caveats

It has to be noted that code written against this API will only run on JCOP cards supporting this API. It will not run on generic JavaCard/OpenPlatform compliant cards, and it will also not run on JCOP10 or JCOP20 cards without support for the SEED algorithm. The error condition reflecting this will be a failure to load the applet containing this code. This is due to a reference to the SEED crypto code in the Export File (cf. JavaCard Specifications for further explanations on this) which will be reflected in the CAP file generated.