public static final class InitializedMessageDigest.OneShot extends InitializedMessageDigest
OneShot
class is a specialization of the
InitializedMessageDigest
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
InitializedMessageDigest
-implementing class configured for one-shot
use.
Note:
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.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.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.
OneShot
must be bound to the initial calling context
(owner context) as to preclude use/calls on that instance from other
contexts.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.
... InitializedMessageDigest.OneShot dig = null; try { dig = InitializedMessageDigest.OneShot.open(MessageDigest.ALG_SHA); dig.setInitialDigest(initialDigData, (short) 2, (short) initialDigData.length, initialDigData, (short) 0, (short) 2); dig.doFinal(someInData, (short) 0, (short) someInData.length, digData, (short) 0); } catch (CryptoException ce) { // Handle exception } finally { if (dig != null) { dig.close(); dig = null; } } ...
InitializedMessageDigest.OneShot
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
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 InitializedMessageDigest.OneShot |
open(byte algorithm)
Closes and 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 |
setInitialDigest(byte[] initialDigestBuf,
short initialDigestOffset,
short initialDigestLength,
byte[] digestedMsgLenBuf,
short digestedMsgLenOffset,
short digestedMsgLenLength)
This method initializes the starting hash value in place of the default
value used by the
MessageDigest superclass. |
void |
update(byte[] inBuff,
short inOffset,
short inLength)
Always throws a
CryptoException .This method is not supported by
OneShot . |
getInitializedMessageDigestInstance, getInstance
public static final InitializedMessageDigest.OneShot open(byte algorithm) throws CryptoException
OneShot
with the selected algorithm.algorithm
- the desired message digest algorithm. Valid codes listed
in ALG_*
constants above, for example, ALG_SHA
.InitializedMessageDigest
object instance of the
requested algorithm.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.public void close()
OneShot
object for reuse. If this method is
called again this method does nothing.SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public void setInitialDigest(byte[] initialDigestBuf, short initialDigestOffset, short initialDigestLength, byte[] digestedMsgLenBuf, short digestedMsgLenOffset, short digestedMsgLenLength) throws CryptoException
MessageDigest
superclass. The starting
hash value represents the previously computed hash (using the same
algorithm) of the first part of the message. The remaining bytes of the
message must be presented to this InitializedMessageDigest
object via the update
and doFinal
methods
to generate the final message digest.
Note:
setInitialDigest
in class InitializedMessageDigest
initialDigestBuf
- input buffer containing the starting hash value representing
the previously computed hash (using the same algorithm) of
first part of the messageinitialDigestOffset
- offset into initialDigestBuf
array where the
starting digest value data beginsinitialDigestLength
- the length of data in initialDigestBuf
array.digestedMsgLenBuf
- the byte array containing the number of bytes in the first
part of the message that has previously been hashed to obtain
the specified starting digest valuedigestedMsgLenOffset
- the offset within digestedMsgLenBuf
where the
digested length begins(the bytes starting at this offset for
digestedMsgLenLength
bytes are concatenated to
form the actual digested message length value)digestedMsgLenLength
- byte length of the digested lengthSecurityException
- 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_VALUE
if the
parameter initialDigestLength
is not equal
to the intermediate hash value size of the algorithm
or if the number of bytes
in the first part of the message that has previously been
hashed is 0 or not a multiple of the algorithm's block
size or greater than the maximum length supported by the
algorithm (see ALG_*
algorithm descriptions
ALG_SHA
).
public byte getAlgorithm()
getAlgorithm
in class MessageDigest
SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public byte getLength()
getLength
in class MessageDigest
SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public short doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws CryptoException
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 ashort
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.doFinal
in class MessageDigest
inBuff
- the input buffer of data to be hashedinOffset
- the offset into the input buffer at which to begin hash
generationinLength
- the byte length to hashoutBuff
- the output buffer, may be the same as the input bufferoutOffset
- the offset into the output buffer where the resulting hash
value beginsoutBuff
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.
public void reset()
MessageDigest
object to the initial state for
further use.reset
in class MessageDigest
SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public void update(byte[] inBuff, short inOffset, short inLength) throws CryptoException
CryptoException
.This method is not supported by
OneShot
.update
in class MessageDigest
inBuff
- the input buffer of data to be hashedinOffset
- the offset into the input buffer at which to begin hash
generationinLength
- the byte length to hashCryptoException
- with the following reason codes:
CryptoException.ILLEGAL_USE
always.doFinal
Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms