javacardx.crypto
Class Cipher

The Cipher class is the abstract base class for Cipher algorithms. 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.

The asymmetric key algorithms encrypt using either a public key (to cipher) or a private key (to sign).
In addition they decrypt using the either a private key (to decipher) or a public key (to verify).

A tear or card reset event resets an initialized
Cipher object to the state it was in when previously initialized
via a call to init(). For algorithms which support keys with transient
key data sets, such as DES, triple DES and AES,
the Cipher object key becomes
uninitialized on clear events associated with the Key
object used to initialize the Cipher object.

Even if a transaction is in progress, update of intermediate result state in the implementation
instance shall not participate in the transaction.

Note:

On a tear or card reset event, the AES, DES, and triple DES algorithms in CBC mode
reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the
init(Key, byte, byte[], short, short) method.

Field Summary

static byte

ALG_AES_BLOCK_128_CBC_NOPAD
Cipher algorithm ALG_AES_BLOCK_128_CBC_NOPAD provides a cipher using AES with
block size 128 in CBC mode and
does not pad input data.

static byte

ALG_AES_BLOCK_128_ECB_NOPAD
Cipher algorithm ALG_AES_BLOCK_128_ECB_NOPAD provides a cipher using AES with
block size 128 in ECB mode and
does not pad input data.

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
or triple DES in outer CBC mode, and
does not pad input data. If the input data is not (8-byte) block
aligned it throws CryptoException with the reason code ILLEGAL_USE.

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,
and does not pad input data. If the input data is not (8-byte) block
aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_RSA_PKCS1

Cipher algorithm ALG_RSA_PKCS1 provides a cipher using RSA, and pads
input data 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.

The encryption block(EB) during encryption with a Public key
is built as follows:
EB = 00 || 02 || PS || 00 || M
:: M (input bytes) is the plaintext message
:: PS is an octet string of length k-3-||M|| of pseudo
random nonzero octets. The length of PS must be at least 8 octets.
:: k is the RSA modulus size.

The encryption block(EB) during encryption with a Private key
(used to compute signatures when the message digest is computed off-card)
is built as follows:
EB = 00 || 01 || PS || 00 || D
:: D (input bytes) is the DER encoding of the
hash computed elsewhere with an algorithm ID
prepended if appropriate
:: PS is an octet string of length k-3-||D|| with value
FF. The length of PS must be at least 8 octets.
:: k is the RSA modulus size.

ALG_RSA_ISO9796

ALG_RSA_NOPAD

public static final byte ALG_RSA_NOPAD

Cipher algorithm ALG_RSA_NOPAD provides a cipher using RSA and
does not pad input data. If the input data is bounded by incorrect
padding bytes while using RSAPrivateCrtKey, incorrect output may result.
If the input data is not block aligned it throws CryptoException with
the reason code ILLEGAL_USE.

ALG_AES_BLOCK_128_CBC_NOPAD

public static final byte ALG_AES_BLOCK_128_CBC_NOPAD

Cipher algorithm ALG_AES_BLOCK_128_CBC_NOPAD provides a cipher using AES with
block size 128 in CBC mode and
does not pad input data. If the input data is not block
aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_AES_BLOCK_128_ECB_NOPAD

public static final byte ALG_AES_BLOCK_128_ECB_NOPAD

Cipher algorithm ALG_AES_BLOCK_128_ECB_NOPAD provides a cipher using AES with
block size 128 in ECB mode and
does not pad input data. If the input data is not block
aligned it throws CryptoException with the reason code ILLEGAL_USE.

externalAccess - 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.
If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

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.

CryptoException.UNINITIALIZED_KEY if theKey instance is uninitialized.

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. This method must be invoked
to complete a cipher operation. This method processes any remaining input data buffered by
one or more calls to the update() method as well as input data supplied in the
inBuff parameter.

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.
In addition, note that the initial vector(IV) used in AES and DES algorithms will be reset to 0.

Notes:

When using block-aligned data (multiple of block size),
if the input buffer, inBuff and the output buffer,
outBuff
are the same array, then the output data area must not partially overlap the input data area such that
the input data is modified before it is used;
if inBuff==outBuff andinOffset < outOffset < inOffset+inLength,
incorrect output may result.

When non-block aligned data is presented as input data, no amount of input
and output buffer data overlap is allowed;
if inBuff==outBuff andoutOffset < inOffset+inLength,
incorrect output may result.

AES, DES, and triple DES algorithms in CBC mode reset the initial vector(IV)
to 0. The initial vector(IV) can be re-initialized using the
init(Key, byte, byte[], short, short) method.

On decryption operations (except when ISO 9797 method 1 padding is used),
the padding bytes are not written to outBuff.

On encryption and decryption operations, the number of bytes output into outBuff
may be larger or smaller than inLength or even 0.

On decryption operations resulting in an ArrayIndexOutOfBoundException,
outBuff may be partially modified.

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 output data begins

This method requires temporary storage of
intermediate results. In addition, if the input data length is not block aligned
(multiple of block size)
then additional internal storage may be allocated at this time to store a partial
input data block.
This may result in additional resource consumption and/or slow performance.

This method should only be used if all the input data required for the cipher
is not available in one byte array. If all the input data required for the cipher
is located in a single byte array, use of the doFinal() method to
process all of the input data is recommended. The doFinal() method
must be invoked to complete processing of any remaining input data buffered by one or more calls
to the update() method.

Notes:

When using block-aligned data (multiple of block size),
if the input buffer, inBuff and the output buffer,
outBuff
are the same array, then the output data area must not partially overlap the input data area such that
the input data is modified before it is used;
if inBuff==outBuff andinOffset < outOffset < inOffset+inLength,
incorrect output may result.

When non-block aligned data is presented as input data, no amount of input
and output buffer data overlap is allowed;
if inBuff==outBuff andoutOffset < inOffset+inLength,
incorrect output may result.

On decryption operations(except when ISO 9797 method 1 padding is used),
the padding bytes are not written to outBuff.

On encryption and decryption operations,
block alignment considerations may require that
the number of bytes output into outBuff be larger or smaller than
inLength or even 0.

If inLength is 0 this method does nothing.

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/decryptedv

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

outOffset - the offset into the output buffer where the resulting ciphertext/plaintext begins