javacardx.crypto
Class Cipher

java.lang.Object
  |
  +--javacardx.crypto.Cipher

public abstract class Cipher

extends Object

The Cipher class is the abstract base class for Cipher algorthims. Implementations of Cipher algorithms must extend this class and implement all the abstract methods.

The term "pad" is used in the public key cipher algorithms below to refer to all the operations specified in the referenced scheme to transform the message block into the cipher block size.

Field Summary

static byte	ALG_DES_CBC_ISO9797_M1 Cipher algorithm ALG_DES_CBC_ISO9797_M1 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.
static byte	ALG_DES_CBC_ISO9797_M2 Cipher algorithm ALG_DES_CBC_ISO9797_M2 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.
static byte	ALG_DES_CBC_NOPAD Cipher algorithm ALG_DES_CBC_NOPAD provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data.
static byte	ALG_DES_CBC_PKCS5 Cipher algorithm ALG_DES_CBC_PKCS5 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.
static byte	ALG_DES_ECB_ISO9797_M1 Cipher algorithm ALG_DES_ECB_ISO9797_M1 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 1 scheme.
static byte	ALG_DES_ECB_ISO9797_M2 Cipher algorithm ALG_DES_ECB_ISO9797_M2 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.
static byte	ALG_DES_ECB_NOPAD Cipher algorithm ALG_DES_ECB_NOPAD provides a cipher using DES in ECB mode. This algorithm does not pad input data.
static byte	ALG_DES_ECB_PKCS5 Cipher algorithm ALG_DES_ECB_PKCS5 provides a cipher using DES in ECB mode. Input data is padded according to the PKCS#5 scheme.
static byte	ALG_RSA_ISO14888 Cipher algorithm ALG_RSA_ISO14888 provides a cipher using RSA. Input data is padded according to the ISO 14888 scheme.
static byte	ALG_RSA_ISO9796 Cipher algorithm ALG_RSA_ISO9796 provides a cipher using RSA. Input data is padded according to the ISO 9796 (EMV'96) scheme.
static byte	ALG_RSA_PKCS1 Cipher algorithm ALG_RSA_PKCS1 provides a cipher using RSA. Input data is padded according to the PKCS#1 (v1.5) scheme.
static byte	MODE_DECRYPT Used in init() methods to indicate decryption mode.
static byte	MODE_ENCRYPT Used in init() methods to indicate encryption mode.

Constructor Summary

protected

Cipher() Protected Constructor

Method Summary

abstract short	doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) Generates encrypted/decrypted output from all/last input data.
abstract byte	getAlgorithm() Gets the Cipher algorithm.
static Cipher	getInstance(byte algorithm, boolean externalAccess) Creates a Cipher object instance of the selected algorithm.
abstract void	init(Key theKey, byte theMode) Initializes the Cipher object with the appropriate Key.
abstract void	init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) Initializes the Cipher object with the appropriate Key and algorithm specific parameters.
abstract short	update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) Generates encrypted/decrypted output from input data.

Methods inherited from class java.lang.Object

equals

Field Detail

ALG_DES_CBC_NOPAD

public static final byte ALG_DES_CBC_NOPAD

Cipher algorithm ALG_DES_CBC_NOPAD provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoExeption with the reason code ILLEGAL_USE.

ALG_DES_CBC_ISO9797_M1

public static final byte ALG_DES_CBC_ISO9797_M1

Cipher algorithm ALG_DES_CBC_ISO9797_M1 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.

ALG_DES_CBC_ISO9797_M2

public static final byte ALG_DES_CBC_ISO9797_M2

Cipher algorithm ALG_DES_CBC_ISO9797_M2 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.

ALG_DES_CBC_PKCS5

public static final byte ALG_DES_CBC_PKCS5

Cipher algorithm ALG_DES_CBC_PKCS5 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

ALG_DES_ECB_NOPAD

public static final byte ALG_DES_ECB_NOPAD

Cipher algorithm ALG_DES_ECB_NOPAD provides a cipher using DES in ECB mode. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoExeption with the reason code ILLEGAL_USE.

ALG_DES_ECB_ISO9797_M1

public static final byte ALG_DES_ECB_ISO9797_M1

Cipher algorithm ALG_DES_ECB_ISO9797_M1 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 1 scheme.

ALG_DES_ECB_ISO9797_M2

public static final byte ALG_DES_ECB_ISO9797_M2

Cipher algorithm ALG_DES_ECB_ISO9797_M2 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.

ALG_DES_ECB_PKCS5

public static final byte ALG_DES_ECB_PKCS5

Cipher algorithm ALG_DES_ECB_PKCS5 provides a cipher using DES in ECB mode. Input data is padded according to the PKCS#5 scheme.

ALG_RSA_ISO14888

public static final byte ALG_RSA_ISO14888

Cipher algorithm ALG_RSA_ISO14888 provides a cipher using RSA. Input data is padded according to the ISO 14888 scheme.

ALG_RSA_PKCS1

public static final byte ALG_RSA_PKCS1

Cipher algorithm ALG_RSA_PKCS1 provides a cipher using RSA. Input data is padded according to the PKCS#1 (v1.5) scheme.

Note:

• This algorithm is only suitable for messages of limited length. The total number of input bytes processed may not be more than k-11, where k is the RSA key's modulus size in bytes.

ALG_RSA_ISO9796

public static final byte ALG_RSA_ISO9796

Cipher algorithm ALG_RSA_ISO9796 provides a cipher using RSA. Input data is padded according to the ISO 9796 (EMV'96) scheme.

Note:

• This algorithm is only suitable for messages of limited length. The total number of input bytes processed may not be more than k/2, where k is the RSA key's modulus size in bytes.

MODE_DECRYPT

public static final byte MODE_DECRYPT

Used in init() methods to indicate decryption mode.

MODE_ENCRYPT

public static final byte MODE_ENCRYPT

Used in init() methods to indicate encryption mode.

Constructor Detail

Cipher

protected Cipher()

Protected Constructor

Method Detail

getInstance

public static final Cipher getInstance(byte algorithm,
                                       boolean externalAccess)
                                throws CryptoException

Creates a Cipher object instance of the selected algorithm.

Parameters:

algorithm - the desired Cipher algorithm. See above.

externalAccess - if true indicates that the instance will be shared among multiple applet instances and that the Cipher instance will also be accessed (via a Shareable interface) when the owner of the Cipher instance is not the currently selected applet.

Returns:

the Cipher object instance of the requested algorithm.

Throws:

CryptoException - with the following reason codes:

• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported.

init

public abstract void init(Key theKey,
                          byte theMode)
                   throws CryptoException

Initializes the Cipher object with the appropriate Key. This method should be used for algorithms which do not need initialization parameters or use default parameter values.

Note:

• DES and triple DES algorithms in CBC mode will use 0 for initial vector(IV) if this method is used.

Parameters:

theKey - the key object to use for signing or verifying

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

Throws:

CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if the Key is inconsistent with the Cipher implementation.

init

public abstract void init(Key theKey,
                          byte theMode,
                          byte[] bArray,
                          short bOff,
                          short bLen)
                   throws CryptoException

Initializes the Cipher object with the appropriate Key and algorithm specific parameters.

Note:

• DES and triple DES algorithms in outer CBC mode expect an 8 byte parameter value for the initial vector(IV) in bArray.
• RSA and DSA algorithms throw CryptoException.ILLEGAL_VALUE.

Parameters:

theKey - the key object to use for signing

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

bArray - byte array containing algorithm specific initialization info.

bOff - offset withing bArray where the algorithm specific data begins.

bLen - byte length of algorithm specific parameter data

Throws:

CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if a byte array parameter option is not supported by the algorithm or if the bLen is an incorrect byte length for the algorithm specific data or if the Key is inconsistent with the Cipher implementation.

getAlgorithm

public abstract byte getAlgorithm()

Gets the Cipher algorithm.

Returns:

the algorithm code defined above.

doFinal

public abstract short doFinal(byte[] inBuff,
                              short inOffset,
                              short inLength,
                              byte[] outBuff,
                              short outOffset)
                       throws CryptoException

Generates encrypted/decrypted output from all/last input data. A call to this method also resets this Cipher object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to encrypt or decrypt (depending on the operation mode that was specified in the call to init()) more data.

The input and output buffer data may overlap.

Notes:

• On decryption operations (except when ISO 9797 method 1 padding is used), the padding bytes are not written to outBuff.
• On encryption operations, the number of bytes output into outBuff may be larger than inLength.

Parameters:

inBuff - the input buffer of data to be encrypted/decrypted.

inOffset - the offset into the input buffer at which to begin encryption/decryption.

inLength - the byte length to be encrypted/decrypted.

outBuff - the output buffer, may be the same as the input buffer

outOffset - the offset into the output buffer where the resulting hash value begins

Returns:

number of bytes output in outBuff

Throws:

CryptoException - with the following reason codes:

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this Cipher object is not initialized.
• CryptoException.ILLEGAL_USE if this Cipher algorithm does not pad the message and the message is not block aligned or if the input message length is not supported.

update

public abstract short update(byte[] inBuff,
                             short inOffset,
                             short inLength,
                             byte[] outBuff,
                             short outOffset)
                      throws CryptoException

Generates encrypted/decrypted output from input data. When this method is used temporary storage of intermediate results is required. This method should only be used if all the input data required for the cipher is not available in one byte array. The doFinal() method is recommended whenever possible.

The input and output buffer data may overlap.

Notes:

• On decryption operations(except when ISO 9797 method 1 padding is used), the padding bytes are not written to outBuff.
• On encryption operations, the number of bytes output into outBuff may be larger than inLength.
• On encryption and decryption operations(except when ISO 9797 method 1 padding is used), block alignment considerations may require that the number of bytes output into outBuff be smaller than inLength or even 0.

Parameters:

inBuff - the input buffer of data to be encrypted/decrypted.

inOffset - the offset into the input buffer at which to begin encryption/decryption.

inLength - the byte length to be encrypted/decrypted.

outBuff - the output buffer, may be the same as the input buffer

outOffset - the offset into the output buffer where the resulting hash value begins

Returns:

number of bytes output in outBuff

Throws:

CryptoException - with the following reason codes:

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this Cipher object is not initialized.
• CryptoException.ILLEGAL_USE if the input message length is not supported.