javacard.security

Class MessageDigest.OneShot

java.lang.Object

javacard.security.MessageDigest

javacard.security.MessageDigest.OneShot

Enclosing class:

MessageDigest

public static final class MessageDigest.OneShot
extends MessageDigest

The OneShot class is a specialization of the MessageDigest class intended to support efficient one-shot hash operations that may avoid persistent memory writes entirely. The OneShot class uses a delegation model where calls are delegated to an instance of a MessageDigest-implementing class configured for one-shot use.

Note:

• Instances of OneShot are JCRE owned temporary Entry Point Object instances and references to these temporary objects cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
• The platform must support at least one instance of OneShot. Support for several OneShot instances is platform dependent. To guarantee application code portability, acquiring/opening and then releasing/closing OneShot instances should be performed within tight try-catch-finally blocks (as illustrated in the code sample below) in order to avoid unnecessarily keeping hold of instances and to prevent interleaving invocations - hence enforcing the One-Shot usage pattern. Additionally, any local variable holding a reference to a OneShot instance should be set to null once the instance is closed in order to prevent further use attempts.
• Upon return from any Applet entry point method, back to the JCRE, and on tear or card reset events any OneShot instances in use are released back to the JCRE.
• The internal state associated with an instance of OneShot must be bound to the initial calling context (owner context) as to preclude use/calls on that instance from other contexts.
• Unless otherwise specified, after an instance of OneShot is released back to the JCRE, calls to any of the instance methods of the OneShot class results in an CryptoException being thrown with reason code CryptoException.ILLEGAL_USE.

The following code shows a typical usage pattern for the OneShot class.

 ...
 MessageDigest.OneShot dig = null;
 try {
     dig = MessageDigest.OneShot.open(MessageDigest.ALG_SHA);
     dig.doFinal(someInData, (short) 0, (short) someInData.length, digData, (short) 0);
 } catch (CryptoException ce) {
     // Handle exception
 } finally {
     if (dig != null) {
        dig.close();
        dig = null;
     }
 }
 ...
 

Since:

3.0.5

Nested Class Summary

Nested classes/interfaces inherited from class javacard.security.MessageDigest

MessageDigest.OneShot

Field Summary

Fields inherited from class javacard.security.MessageDigest

ALG_MD5, ALG_NULL, ALG_RIPEMD160, ALG_SHA, ALG_SHA_224, ALG_SHA_256, ALG_SHA_384, ALG_SHA_512, ALG_SHA3_224, ALG_SHA3_256, ALG_SHA3_384, ALG_SHA3_512, LENGTH_MD5, LENGTH_RIPEMD160, LENGTH_SHA, LENGTH_SHA_224, LENGTH_SHA_256, LENGTH_SHA_384, LENGTH_SHA_512, LENGTH_SHA3_224, LENGTH_SHA3_256, LENGTH_SHA3_384, LENGTH_SHA3_512

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes and releases this JCRE owned temporary instance of the OneShot object for reuse.
short	doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) Generates a hash of all/last input data.
byte	getAlgorithm() Gets the Message digest algorithm.
byte	getLength() Returns the byte length of the hash.
static MessageDigest.OneShot	open(byte algorithm) Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected algorithm.
void	reset() Resets the MessageDigest object to the initial state for further use.
void	update(byte[] inBuff, short inOffset, short inLength) Always throws a CryptoException.This method is not supported by OneShot.

Methods inherited from class javacard.security.MessageDigest

getInitializedMessageDigestInstance, getInstance

Methods inherited from class java.lang.Object

equals

Method Detail

open

public static final MessageDigest.OneShot open(byte algorithm)
                                        throws CryptoException

Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected algorithm.

Parameters:

algorithm - the desired message digest algorithm. Valid codes listed in ALG_* constants above, for example, ALG_SHA.

Returns:

the MessageDigest 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.

SystemException - with the following reason codes:

• SystemException.NO_RESOURCE if sufficient resources are not available.

close

public void close()

Closes and releases this JCRE owned temporary instance of the OneShot object for reuse. If this method is called again this method does nothing.

Throws:

SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

getAlgorithm

public byte getAlgorithm()

Gets the Message digest algorithm.

Specified by:

getAlgorithm in class MessageDigest

Returns:

the algorithm code defined above

Throws:

SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

getLength

public byte getLength()

Returns the byte length of the hash.

Specified by:

getLength in class MessageDigest

Returns:

hash length

Throws:

SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

doFinal

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

Generates a hash of all/last input data. Completes and returns the hash computation after performing final operations such as padding. The MessageDigest object is reset to the initial state after this call is made. The data format is big-endian.

The input and output buffer data may overlap.

In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

Specified by:

doFinal in class MessageDigest

Parameters:

inBuff - the input buffer of data to be hashed

inOffset - the offset into the input buffer at which to begin hash generation

inLength - the byte length to hash

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 of hash output in outBuff

Throws:

SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_USE if the accumulated message length is greater than the maximum length supported by the algorithm.

update

public void update(byte[] inBuff,
          short inOffset,
          short inLength)
            throws CryptoException

Always throws a CryptoException.This method is not supported by OneShot.

Specified by:

update in class MessageDigest

Parameters:

inBuff - the input buffer of data to be hashed

inOffset - the offset into the input buffer at which to begin hash generation

inLength - the byte length to hash

Throws:

CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_USE always.

See Also:

doFinal

reset

public void reset()

Resets the MessageDigest object to the initial state for further use.

Specified by:

reset in class MessageDigest

Throws:

SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.