javacard.security
Class Checksum

java.lang.Object
  extended by javacard.security.Checksum

@TransactionType(value=SUPPORTS)
public abstract class Checksum
extends Object

The Checksum class is the base class for CRC (cyclic redundancy check) checksum algorithms. Implementations of Checksum algorithms must extend this class and implement all the abstract methods.

A tear or card reset event resets a Checksum object to the initial state (state upon construction).

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

Since:
Java Card 2.x, Java Card 3.0

Field Summary
static byte ALG_ISO3309_CRC16
          ISO/IEC 3309 compliant 16 bit CRC algorithm.
static byte ALG_ISO3309_CRC32
          ISO/IEC 3309 compliant 32 bit CRC algorithm.
static String SERVICE_NAME
          This cryptographic service name, as used to lookup implemented algorithms.
 
Constructor Summary
protected Checksum()
          Protected Constructor
 
Method Summary
abstract  short doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)
          Generates a CRC checksum of all/last input data.
abstract  byte getAlgorithm()
          Gets the Checksum algorithm.
abstract  String getAlgorithmName()
          Gets the Checksum algorithm name.
static Checksum getInstance(byte algorithm, boolean externalAccess)
          Creates a Checksum object instance of the selected algorithm.
static Checksum getInstance(String algorithm, boolean externalAccess)
          Creates a Checksum object instance of the selected algorithm.
static Checksum getInstance(String algorithm, String provider, boolean externalAccess)
          Creates a Checksum object instance of the selected algorithm.
abstract  void init(byte[] bArray, short bOff, short bLen)
          Resets and initializes the Checksum object with the algorithm specific parameters.
abstract  void update(byte[] inBuff, short inOffset, short inLength)
          Accumulates a partial checksum of the input data.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SERVICE_NAME

public static final String SERVICE_NAME
This cryptographic service name, as used to lookup implemented algorithms.

Since:
Java Card 3.0
See Also:
Constant Field Values

ALG_ISO3309_CRC16

public static final byte ALG_ISO3309_CRC16
ISO/IEC 3309 compliant 16 bit CRC algorithm. This algorithm uses the generator polynomial : x^16+x^12+x^5+1. The default initial checksum value used by this algorithm is 0. This algorithm is also compliant with the frame checking sequence as specified in section 4.2.5.2 of the ISO/IEC 13239 specification.

To obtain the commonly used CCITT behavior:

Algorithm specifics:

The String name equivalent to this algorithm type to use as parameter to the getInstance(String algorithm, ...) method is "ISO3309_CRC16"

See Also:
Constant Field Values

ALG_ISO3309_CRC32

public static final byte ALG_ISO3309_CRC32
ISO/IEC 3309 compliant 32 bit CRC algorithm. This algorithm uses the generator polynomial : X^32 +X^26 +X^23 +X^22 +X^16 +X^12 +X^11 +X^10 +X^8 +X^7 +X^5 +X^4 +X^2 +X +1. The default initial checksum value used by this algorithm is 0. This algorithm is also compliant with the frame checking sequence as specified in section 4.2.5.3 of the ISO/IEC 13239 specification.

To obtain the PKZIP (also JDKTM java.util.zip.CRC32 class) behavior:

Algorithm specifics:

The String name equivalent to this algorithm type to use as parameter to the getInstance(String algorithm, ...) method is "ISO3309_CRC32"

See Also:
Constant Field Values
Constructor Detail

Checksum

protected Checksum()
Protected Constructor

Method Detail

getInstance

public static final Checksum getInstance(byte algorithm,
                                         boolean externalAccess)
                                  throws CryptoException
Creates a Checksum object instance of the selected algorithm.

This method returns an instance of the specified algorithm supported by the most preferred provider of this cryptographic service. Note that the list of installed providers may be retrieved via the CryptoServices.getProviders() method.

A call to this method is equivalent to a call to getInstance(java.lang.String, boolean) with the algorithm parameter set to the equivalent String algorithm name - as listed in the ALG_* constants above.

Parameters:
algorithm - the desired checksum algorithm. Valid codes listed in ALG_* constants above, for example, ALG_ISO3309_CRC16.
externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Checksum instance will also be accessed (via a Shareable. interface) when the owner of the Checksum instance is not the currently selected applet. If true or if called from a web application the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
Returns:
the Checksum object instance of the requested algorithm.
Throws:
CryptoException - with the following reason codes:
  • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm or shared access mode is not supported.
SecurityException - if creating an instance of this cryptographic service is not granted.

getInstance

public static final Checksum getInstance(String algorithm,
                                         boolean externalAccess)
                                  throws CryptoException
Creates a Checksum object instance of the selected algorithm.

This method returns an instance of the specified algorithm supported by the most preferred provider of this cryptographic service. Note that the list of installed providers may be retrieved via the CryptoServices.getProviders() method.

Parameters:
algorithm - the desired checksum algorithm name. Valid names listed in ALG_* constants above, for example, ALG_ISO3309_CRC16.
externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Checksum instance will also be accessed (via a Shareable. interface) when the owner of the Checksum instance is not the currently selected applet. If true or if called from a web application the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
Returns:
the Checksum object instance of the requested algorithm.
Throws:
CryptoException - with the following reason codes:
  • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm or shared access mode is not supported.
NullPointerException - if algorithm is null.
SecurityException - if creating an instance of this cryptographic service is not granted.
Since:
Java Card 3.0

getInstance

public static final Checksum getInstance(String algorithm,
                                         String provider,
                                         boolean externalAccess)
                                  throws CryptoException
Creates a Checksum object instance of the selected algorithm.

Parameters:
algorithm - the desired checksum algorithm name. Valid names listed in ALG_* constants above, for example, ALG_ISO3309_CRC16.
provider - the desired message digest algorithm provider.
externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Checksum instance will also be accessed (via a Shareable. interface) when the owner of the Checksum instance is not the currently selected applet. If true or if called from a web application the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
Returns:
the Checksum object instance of the requested algorithm.
Throws:
CryptoException - with the following reason codes:
  • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm or shared access mode is not supported.
NullPointerException - if algorithm or provider is null.
SecurityException - if creating an instance of this cryptographic service is not granted.
Since:
Java Card 3.0

init

public abstract void init(byte[] bArray,
                          short bOff,
                          short bLen)
                   throws CryptoException
Resets and initializes the Checksum object with the algorithm specific parameters.

Note:

Parameters:
bArray - byte array containing algorithm specific initialization information
bOff - offset within 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 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.

getAlgorithm

public abstract byte getAlgorithm()
Gets the Checksum algorithm. Pre-defined codes listed in ALG_* constants above, for example, ALG_ISO3309_CRC16.

Returns:
the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.

getAlgorithmName

public abstract String getAlgorithmName()
Gets the Checksum algorithm name. Pre-defined codes listed for each of the ALG_* constants above, for example, ALG_ISO3309_CRC16.

New algorithms may be defined through the Extensible Cryptography Framework.

Returns:
the algorithm name.
Since:
Java Card 3.0

doFinal

public abstract short doFinal(byte[] inBuff,
                              short inOffset,
                              short inLength,
                              byte[] outBuff,
                              short outOffset)
Generates a CRC checksum of all/last input data. The CRC engine processes input data starting with the byte at offset inOffset and continuing on until the byte at (inOffset+inLength-1) of the inBuff array. Within each byte the processing proceeds from the least significant bit to the most.

Completes and returns the checksum computation. The Checksum object is reset to the initial state(state upon construction) when this method completes.

Note:

The input and output buffer data may overlap.

Parameters:
inBuff - the input buffer of data to be checksummed
inOffset - the offset into the input buffer at which to begin checksum generation
inLength - the byte length to checksum
outBuff - the output buffer, may be the same as the input buffer
outOffset - the offset into the output buffer where the resulting checksum value begins
Returns:
number of bytes of checksum output in outBuff

update

public abstract void update(byte[] inBuff,
                            short inOffset,
                            short inLength)
Accumulates a partial checksum of the input data. The CRC engine processes input data starting with the byte at offset inOffset and continuing on until the byte at (inOffset+inLength-1) of the inBuff array. Within each byte the processing proceeds from the least significant bit to the most.

This method requires temporary storage of intermediate results. 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 checksum is not available in one byte array. The doFinal(byte[], short, short, byte[], short) method is recommended whenever possible.

Note:

Parameters:
inBuff - the input buffer of data to be checksummed
inOffset - the offset into the input buffer at which to begin checksum generation
inLength - the byte length to checksum
See Also:
doFinal


Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.