Checksum (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.security
Class Checksum

    java.lang.Object
      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:

  - Initialize with `0xFFFF` via the `init()` method
  - One's complement the result.
  Algorithm specifics:
  - The input data is not reversed (reflected)
  - The ISO 3309 algorithm is used with the polynomial value `0x1021`
  - The resulting 16 bit FCS is not reversed (reflected)
  - The 16 bit FCS is xor'd with `OxFFFF`. This is the CRC16 result.

  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:

  - Initialize with `0xFFFFFFFF` via the `init()` method
  Algorithm specifics:
  - The input data is reversed (reflected)
  - The ISO 3309 algorithm is used with the polynomial value `0x04C11DB7`
  - The resulting 32 bit FCS is reversed (reflected)
  - The reversed 32 bit FCS is xor'd with OxFFFFFFFF. This is the CRC32 result.

  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:

  - The ALG_ISO3309_CRC16 algorithm expects 2 bytes of parameter information in `bArray` representing the initial checksum value.
  - The ALG_ISO3309_CRC32 algorithm expects 4 bytes of parameter information in `bArray` representing the initial checksum value.

  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 `ALG_ISO3309_CRC16` and `ALG_ISO3309_CRC32` algorithms reset the initial checksum value to 0. The initial checksum value can be re-initialized using the `init(byte[], short, short)` method.

  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:

  - If `inLength` is 0 this method does nothing.

  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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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