public static final class Signature.OneShot extends Signature
OneShot
class is a specialization of the
Signature
class intended to support efficient one-shot signing and
verification operations that may avoid persistent memory writes entirely.
The OneShot
class uses a delegation model where calls are
delegated to an instance of a Signature
-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.
... Signature.OneShot sig = null; try { sig = Signature.OneShot.open(MessageDigest.ALG_SHA, Signature.SIG_CIPHER_RSA, Cipher.PAD_PKCS1); sig.init(someRSAKey, Signature.MODE_SIGN); sig.sign(someInData, (short) 0, (short) someInData.length, sigData, (short) 0); } catch (CryptoException ce) { // Handle exception } finally { if (sig != null) { sig.close(); sig = null; } } ...
Signature.OneShot
ALG_AES_CMAC_128, ALG_AES_MAC_128_NOPAD, ALG_AES_MAC_192_NOPAD, ALG_AES_MAC_256_NOPAD, ALG_DES_MAC4_ISO9797_1_M1_ALG3, ALG_DES_MAC4_ISO9797_1_M2_ALG3, ALG_DES_MAC4_ISO9797_M1, ALG_DES_MAC4_ISO9797_M2, ALG_DES_MAC4_NOPAD, ALG_DES_MAC4_PKCS5, ALG_DES_MAC8_ISO9797_1_M1_ALG3, ALG_DES_MAC8_ISO9797_1_M2_ALG3, ALG_DES_MAC8_ISO9797_M1, ALG_DES_MAC8_ISO9797_M2, ALG_DES_MAC8_NOPAD, ALG_DES_MAC8_PKCS5, ALG_DSA_SHA, ALG_ECDSA_SHA, ALG_ECDSA_SHA_224, ALG_ECDSA_SHA_256, ALG_ECDSA_SHA_384, ALG_ECDSA_SHA_512, ALG_HMAC_MD5, ALG_HMAC_RIPEMD160, ALG_HMAC_SHA_256, ALG_HMAC_SHA_384, ALG_HMAC_SHA_512, ALG_HMAC_SHA1, ALG_KOREAN_SEED_MAC_NOPAD, ALG_RSA_MD5_PKCS1, ALG_RSA_MD5_PKCS1_PSS, ALG_RSA_MD5_RFC2409, ALG_RSA_RIPEMD160_ISO9796, ALG_RSA_RIPEMD160_ISO9796_MR, ALG_RSA_RIPEMD160_PKCS1, ALG_RSA_RIPEMD160_PKCS1_PSS, ALG_RSA_SHA_224_PKCS1, ALG_RSA_SHA_224_PKCS1_PSS, ALG_RSA_SHA_256_PKCS1, ALG_RSA_SHA_256_PKCS1_PSS, ALG_RSA_SHA_384_PKCS1, ALG_RSA_SHA_384_PKCS1_PSS, ALG_RSA_SHA_512_PKCS1, ALG_RSA_SHA_512_PKCS1_PSS, ALG_RSA_SHA_ISO9796, ALG_RSA_SHA_ISO9796_MR, ALG_RSA_SHA_PKCS1, ALG_RSA_SHA_PKCS1_PSS, ALG_RSA_SHA_RFC2409, MODE_SIGN, MODE_VERIFY, SIG_CIPHER_AES_CMAC128, SIG_CIPHER_AES_MAC128, SIG_CIPHER_DES_MAC4, SIG_CIPHER_DES_MAC8, SIG_CIPHER_DSA, SIG_CIPHER_ECDSA, SIG_CIPHER_ECDSA_PLAIN, SIG_CIPHER_HMAC, SIG_CIPHER_KOREAN_SEED_MAC, SIG_CIPHER_RSA
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes and releases this JCRE owned temporary instance of the
OneShot
object for reuse. |
byte |
getAlgorithm()
Gets the Signature algorithm.
|
byte |
getCipherAlgorithm()
Gets the cipher algorithm.
|
short |
getLength()
Returns the byte length of the signature data.
|
byte |
getMessageDigestAlgorithm()
Gets the message digest algorithm.
|
byte |
getPaddingAlgorithm()
Gets the padding algorithm.
|
void |
init(Key theKey,
byte theMode)
Initializes the
Signature object with the appropriate
Key . |
void |
init(Key theKey,
byte theMode,
byte[] bArray,
short bOff,
short bLen)
Initializes the
Signature object with the appropriate
Key and algorithm specific parameters. |
static Signature.OneShot |
open(byte messageDigestAlgorithm,
byte cipherAlgorithm,
byte paddingAlgorithm)
Opens/acquires a JCRE owned temporary Entry Point Object instance of
OneShot with the selected message digest algorithm, cipher
algorithm and padding algorithm. |
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
Signature class. |
short |
sign(byte[] inBuff,
short inOffset,
short inLength,
byte[] sigBuff,
short sigOffset)
Generates the signature of all/last input data.
|
short |
signPreComputedHash(byte[] hashBuff,
short hashOff,
short hashLength,
byte[] sigBuff,
short sigOffset)
Generates the signature of the precomputed hash data.
|
void |
update(byte[] inBuff,
short inOffset,
short inLength)
Always throws a
CryptoException .This method is not supported by
OneShot . |
boolean |
verify(byte[] inBuff,
short inOffset,
short inLength,
byte[] sigBuff,
short sigOffset,
short sigLength)
Verifies the signature of all/last input data against the passed in
signature.
|
boolean |
verifyPreComputedHash(byte[] hashBuff,
short hashOff,
short hashLength,
byte[] sigBuff,
short sigOffset,
short sigLength)
Verifies the signature of precomputed hash data.
|
getInstance, getInstance
public static final Signature.OneShot open(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm) throws CryptoException
OneShot
with the selected message digest algorithm, cipher
algorithm and padding algorithm.
Note:
DSA
.
MessageDigest.ALG_NULL
choice for the message digest
algorithm.
PAD_NULL
choice for the padding algorithm.
messageDigestAlgorithm
- the desired message digest algorithm. Valid
codes listed in ALG_*
constants in the MessageDigest class e.g.
ALG_NULL
.cipherAlgorithm
- the desired cipher algorithm. Valid codes listed
in SIG_CIPHER_*
constants in the Signature class e.g.
Signature.SIG_CIPHER_DES_MAC4
.paddingAlgorithm
- the desired padding algorithm. Valid codes listed
in PAD_*
constants in the Cipher class e.g.
PAD_NULL
.OneShot
object instance of the requested
algorithm.CryptoException
- with the following reason codes:
CryptoException.NO_SUCH_ALGORITHM
if the requested message
digest algorithm or cipher algorithm or padding algorithm or their
combination 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 final void update(byte[] inBuff, short inOffset, short inLength) throws CryptoException
CryptoException
.This method is not supported by
OneShot
.update
in class Signature
inBuff
- the input buffer of data to be signed/verified.inOffset
- the offset into the input buffer where input data begins.inLength
- the byte length to sign/verify.CryptoException
- with the following reason codes:
CryptoException.ILLEGAL_USE
always.sign(byte[], short,
short, byte[], short)
,
verify(byte[],
short, short, byte[], short, short)
public void init(Key theKey, byte theMode) throws CryptoException
Signature
object with the appropriate
Key
. This method should be used for algorithms which do
not need initialization parameters or use default parameter values.
init()
must be used to update the Signature
object with a new key. If the Key
object is modified after
invoking the init()
method, the behavior of the
update()
, sign()
, and
verify()
methods is unspecified.
The Key
is checked for consistency with the Signature
algorithm. For example, the key type must be matched.
For elliptic curve algorithms, the key must represent a valid point on the
curve's domain parameters. Additional key component/domain parameter
strength checks are implementation specific.
Note:
theKey
parameter is a transient key,
the implementation should, whenever possible, use transient space for internal storage.
init
in class Signature
theKey
- the key object to use for signing or verifyingtheMode
- one of MODE_SIGN
or MODE_VERIFY
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_VALUE
if
theMode
option is an undefined value or if
the Key
is inconsistent with
theMode
or with the Signature
implementation.
CryptoException.UNINITIALIZED_KEY
if
theKey
instance is uninitialized.
public void init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) throws CryptoException
Signature
object with the appropriate
Key
and algorithm specific parameters.
init()
must be used to update the Signature
object with a new key. If the Key
object is modified after
invoking the init()
method, the behavior of the
update()
, sign()
, and
verify()
methods is unspecified.
The Key
is checked for consistency with the Signature
algorithm. For example, the key type must be matched.
For elliptic curve algorithms, the key must represent a valid point on the
curve's domain parameters. Additional key component/domain parameter
strength checks are implementation specific.
Note:
bArray
.
bArray
.
bArray
.
CryptoException.ILLEGAL_VALUE
.
For RSA algorithms using the padding scheme PKCS1_PSS expect a two-byte parameter value (b1 b2)
for the salt length in bArray
. This two-byte parameter represents a short value
where b1 is the first byte (high order byte) and b2 is the second byte (low order byte).
For all other RSA algorithms CryptoException.ILLEGAL_VALUE is thrown.
theKey
parameter is a transient key,
the implementation should, whenever possible, use transient space for internal storage.
init
in class Signature
theKey
- the key object to use for signingtheMode
- one of MODE_SIGN
or MODE_VERIFY
bArray
- byte array containing algorithm specific initialization
informationbOff
- offset within bArray
where the algorithm
specific data beginsbLen
- byte length of algorithm specific parameter dataSecurityException
- 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
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
theMode
or with the Signature
implementation.
CryptoException.UNINITIALIZED_KEY
if
theKey
instance is uninitialized.
public void setInitialDigest(byte[] initialDigestBuf, short initialDigestOffset, short initialDigestLength, byte[] digestedMsgLenBuf, short digestedMsgLenOffset, short digestedMsgLenLength) throws CryptoException
Signature
class. 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 Signature
object via the update
and sign
or
verify
methods
to generate or verify the signature.
Note:
setInitialDigest
in class Signature
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
MessageDigest.ALG_SHA
).
CryptoException.ILLEGAL_USE
if the
Signature algorithm does not compute a distinct message
digest value prior to applying cryptographic primitives or
if this Signature
algorithm includes message
recovery functionality.
public byte getAlgorithm()
ALG_*
constants above, for example, Signature.ALG_DES_MAC4_NOPAD
.getAlgorithm
in class Signature
0
is returned.SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public byte getMessageDigestAlgorithm()
ALG_*
constants in the MessageDigest class e.g.
ALG_NULL
.getMessageDigestAlgorithm
in class Signature
MessageDigest
class; if the algorithm is not one of the pre-defined
algorithms, 0
is returned.SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public byte getCipherAlgorithm()
SIG_CIPHER_*
constants in this class e.g.
SIG_CIPHER_DES_MAC4
.getCipherAlgorithm
in class Signature
0
is returned.SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public byte getPaddingAlgorithm()
PAD_*
constants in the Cipher
class e.g.
PAD_NULL
.getPaddingAlgorithm
in class Signature
Cipher
class; if
the algorithm is not one of the pre-defined algorithms, 0
is
returned.SecurityException
- if this JCRE owned temporary instance of the
OneShot
object was opened in a context different from that of the caller.public short getLength() throws CryptoException
getLength
in class Signature
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.INVALID_INIT
if this
Signature
object is not initialized.
CryptoException.UNINITIALIZED_KEY
if
key not initialized.
public short sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset) throws CryptoException
A call to this method also resets this Signature
object to
the state it was in when previously initialized via a call to
init()
. That is, the object is reset and available to
sign another message. In addition, note that the initial vector(IV) used
in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.
Note:
init(Key, byte, byte[], short, short)
method.
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.sign
in class Signature
inBuff
- the input buffer of data to be signedinOffset
- the offset into the input buffer at which to begin signature
generationinLength
- the byte length to signsigBuff
- the output buffer to store signature datasigOffset
- the offset into sigBuff at which to begin signature dataSecurityException
- 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.UNINITIALIZED_KEY
if
key not initialized.
CryptoException.INVALID_INIT
if this
Signature
object is not initialized or
initialized for signature verify mode.
CryptoException.ILLEGAL_USE
if one of
the following conditions is met:
Signature
algorithm does not
pad the message and the message is not block aligned.
Signature
algorithm does not
pad the message and no input data has been provided in
inBuff
or via the update()
method.
Signature
algorithm
or if a message value consistency check failed.
Signature
algorithm includes
message recovery functionality.
public short signPreComputedHash(byte[] hashBuff, short hashOff, short hashLength, byte[] sigBuff, short sigOffset) throws CryptoException
A call to this method also resets this Signature
object to
the state it was in when previously initialized via a call to
init()
. That is, the object is reset and available to
sign another precomputed hash.
Note:
update
method are discarded.
The hash 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.signPreComputedHash
in class Signature
hashBuff
- the input buffer of precomputed hash to be signedhashOff
- the offset into the buffer where the hash beginshashLength
- the byte length of the hashsigBuff
- the output buffer to store signature datasigOffset
- the offset into sigBuff at which to begin signature dataSecurityException
- 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.UNINITIALIZED_KEY
if
key not initialized.
CryptoException.INVALID_INIT
if this
Signature
object is not initialized or
initialized for signature verify mode.
CryptoException.ILLEGAL_USE
if one of
the following conditions is met:
hashLength
value is not equal
to the length of the algorithm's message digest length.
Signature
algorithm includes
message recovery functionality.
public boolean verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength) throws CryptoException
Signature
object to
the state it was in when previously initialized via a call to
init()
. That is, the object is reset and available to
verify another message. In addition, note that the initial vector(IV)
used in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.
Note:
init(Key, byte, byte[], short, short)
method.
boolean
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.verify
in class Signature
inBuff
- the input buffer of data to be verifiedinOffset
- the offset into the input buffer at which to begin signature
generationinLength
- the byte length to signsigBuff
- the input buffer containing signature datasigOffset
- the offset into sigBuff
where signature data
beginssigLength
- the byte length of the signature datatrue
if the signature verifies, false
otherwise. Note, if sigLength
is inconsistent with
this Signature
algorithm, false
is
returned.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.UNINITIALIZED_KEY
if
key not initialized.
CryptoException.INVALID_INIT
if this
Signature
object is not initialized or
initialized for signature sign mode.
CryptoException.ILLEGAL_USE
if one of
the following conditions is met:
Signature
algorithm does not
pad the message and the message is not block aligned.
Signature
algorithm does not
pad the message and no input data has been provided in
inBuff
or via the update()
method.
Signature
algorithm
or if a message value consistency check failed.
Signature
algorithm includes
message recovery functionality.
public boolean verifyPreComputedHash(byte[] hashBuff, short hashOff, short hashLength, byte[] sigBuff, short sigOffset, short sigLength) throws CryptoException
A call to this method also resets this Signature
object to
the state it was in when previously initialized via a call to
init()
. That is, the object is reset and available to
verify another precomputed hash. In addition, note that the initial vector(IV)
used in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.
Note:
update
method are discarded.
The hash and output buffer data may overlap.
In addition to returning aboolean
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.verifyPreComputedHash
in class Signature
hashBuff
- the input buffer of precomputed hash to be verifiedhashOff
- the offset into the buffer where the hash beginshashLength
- the byte length of the hashsigBuff
- the input buffer containing signature datasigOffset
- the offset into sigBuff
where signature data
beginssigLength
- the byte length of the signature datatrue
if the signature verifies, false
otherwise. Note, if sigLength
is inconsistent with
this Signature
algorithm, false
is
returned.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.UNINITIALIZED_KEY
if
key not initialized.
CryptoException.INVALID_INIT
if this
Signature
object is not initialized or
initialized for signature sign mode.
CryptoException.ILLEGAL_USE
if one of
the following conditions is met:
hashLength
value is not equal
to the length of the algorithm's message digest length.
Signature
algorithm includes
message recovery functionality.
Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms