public static final class Cipher.OneShot extends Cipher
OneShot
class is a specialization of the Cipher
class intended to support efficient one-shot ciphering and deciphering
operations that may avoid persistent memory writes entirely. The
OneShot
class uses a delegation model where calls are delegated
to an instance of a Cipher
-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.
... Cipher.OneShot enc = null; try { enc = Cipher.OneShot.open(Cipher.CIPHER_RSA, Cipher.PAD_PKCS1); enc.init(someRSAKey, Cipher.MODE_ENCRYPT); enc.doFinal(someInData, (short) 0, (short) someInData.length, encData, (short) 0); } catch (CryptoException ce) { // Handle exception } finally { if (enc != null) { enc.close(); enc = null; } } ...
Cipher.OneShot
ALG_AES_BLOCK_128_CBC_NOPAD, ALG_AES_BLOCK_128_ECB_NOPAD, ALG_AES_BLOCK_192_CBC_NOPAD, ALG_AES_BLOCK_192_ECB_NOPAD, ALG_AES_BLOCK_256_CBC_NOPAD, ALG_AES_BLOCK_256_ECB_NOPAD, ALG_AES_CBC_ISO9797_M1, ALG_AES_CBC_ISO9797_M2, ALG_AES_CBC_PKCS5, ALG_AES_CTR, ALG_AES_ECB_ISO9797_M1, ALG_AES_ECB_ISO9797_M2, ALG_AES_ECB_PKCS5, ALG_DES_CBC_ISO9797_M1, ALG_DES_CBC_ISO9797_M2, ALG_DES_CBC_NOPAD, ALG_DES_CBC_PKCS5, ALG_DES_ECB_ISO9797_M1, ALG_DES_ECB_ISO9797_M2, ALG_DES_ECB_NOPAD, ALG_DES_ECB_PKCS5, ALG_KOREAN_SEED_CBC_NOPAD, ALG_KOREAN_SEED_ECB_NOPAD, ALG_RSA_ISO14888, ALG_RSA_ISO9796, ALG_RSA_NOPAD, ALG_RSA_PKCS1, ALG_RSA_PKCS1_OAEP, CIPHER_AES_CBC, CIPHER_AES_ECB, CIPHER_DES_CBC, CIPHER_DES_ECB, CIPHER_KOREAN_SEED_CBC, CIPHER_KOREAN_SEED_ECB, CIPHER_RSA, MODE_DECRYPT, MODE_ENCRYPT, PAD_ISO9796, PAD_ISO9796_MR, PAD_ISO9797_1_M1_ALG3, PAD_ISO9797_1_M2_ALG3, PAD_ISO9797_M1, PAD_ISO9797_M2, PAD_NOPAD, PAD_NULL, PAD_PKCS1, PAD_PKCS1_OAEP, PAD_PKCS1_OAEP_SHA224, PAD_PKCS1_OAEP_SHA256, PAD_PKCS1_OAEP_SHA3_224, PAD_PKCS1_OAEP_SHA3_256, PAD_PKCS1_OAEP_SHA3_384, PAD_PKCS1_OAEP_SHA3_512, PAD_PKCS1_OAEP_SHA384, PAD_PKCS1_OAEP_SHA512, PAD_PKCS1_PSS, PAD_PKCS5, PAD_RFC2409
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 encrypted/decrypted output from all/last input data.
|
byte |
getAlgorithm()
Gets the Cipher algorithm.
|
byte |
getCipherAlgorithm()
Gets the raw cipher algorithm.
|
byte |
getPaddingAlgorithm()
Gets the padding algorithm.
|
void |
init(Key theKey,
byte theMode)
Initializes the
Cipher object with the appropriate
Key . |
void |
init(Key theKey,
byte theMode,
byte[] bArray,
short bOff,
short bLen)
Initializes the
Cipher object with the appropriate Key and
algorithm specific parameters. |
static Cipher.OneShot |
open(byte cipherAlgorithm,
byte paddingAlgorithm)
Opens/acquires a JCRE owned temporary Entry Point Object instance of
OneShot with the selected cipher algorithm and padding
algorithm. |
short |
update(byte[] inBuff,
short inOffset,
short inLength,
byte[] outBuff,
short outOffset)
Always throws a
CryptoException . |
getInstance, getInstance
public static final Cipher.OneShot open(byte cipherAlgorithm, byte paddingAlgorithm) throws CryptoException
OneShot
with the selected cipher algorithm and padding
algorithm.
Note:
PAD_NULL
choice for the padding algorithm.
cipherAlgorithm
- the desired cipher algorithm. Valid codes listed
in CIPHER_*
constants in this class.g.
CIPHER_AES_CBC
.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 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 short update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws CryptoException
CryptoException
. This method is not supported by
OneShot
.update
in class Cipher
inBuff
- the input buffer of data to be encrypted/decryptedinOffset
- the offset into the input buffer at which to begin
encryption/decryptioninLength
- the byte length to be encrypted/decryptedoutBuff
- the output buffer, may be the same as the input bufferoutOffset
- the offset into the output buffer where the resulting
ciphertext/plaintext beginsoutBuff
CryptoException
- with the following reason codes:
CryptoException.ILLEGAL_USE
always.public void init(Key theKey, byte theMode) throws CryptoException
Cipher
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 Cipher
object with a new key. If the Key
object is modified after
invoking the init()
method, the behavior of the
update()
and doFinal()
methods is
unspecified.
The Key
is checked for consistency with the Cipher
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 Cipher
theKey
- the key object to use for encrypting or decryptingtheMode
- one of MODE_DECRYPT
or
MODE_ENCRYPT
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 the
Cipher
implementation.
CryptoException.UNINITIALIZED_KEY
if
theKey
instance is uninitialized.
public void init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) throws CryptoException
Cipher
object with the appropriate Key and
algorithm specific parameters.
init()
must be used to update the Cipher
object with a new key. If the Key
object is modified after
invoking the init()
method, the behavior of the
update()
and doFinal()
methods is
unspecified.
The Key
is checked for consistency with the Cipher
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
.
theKey
parameter is a transient key,
the implementation should, whenever possible, use transient space for internal storage.
init
in class Cipher
theKey
- the key object to use for encrypting or decrypting.theMode
- one of MODE_DECRYPT
or
MODE_ENCRYPT
bArray
- byte array containing algorithm specific initialization infobOff
- 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 the
Cipher
implementation.
CryptoException.UNINITIALIZED_KEY
if
theKey
instance is uninitialized.
public byte getAlgorithm()
getAlgorithm
in class Cipher
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.Cipher.getInstance(byte, boolean)
public byte getCipherAlgorithm()
CIPHER_*
constants in this class e.g.
CIPHER_AES_CBC
.getCipherAlgorithm
in class Cipher
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 this class e.g.
PAD_NULL
.getPaddingAlgorithm
in class Cipher
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 doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws CryptoException
update()
method as well as input data supplied in the
inBuff
parameter.
A call to this method also resets this Cipher
object to
the state it was in when previously initialized via a call to
init()
. That is, the object is reset and available to
encrypt or decrypt (depending on the operation mode that was specified in
the call to init()
) more data. In addition, note that the
initial vector(IV) used in AES, DES and Korean SEED algorithms will be
reset to 0.
Notes:
inBuff
and the output buffer,
outBuff
are the same array, then the output data area must not partially overlap the input data area such that
the input data is modified before it is used;
if inBuff==outBuff
andinOffset < outOffset < inOffset+inLength
,
incorrect output may result.
inBuff==outBuff
andoutOffset < inOffset+inLength
,
incorrect output may result.
init(Key, byte, byte[], short, short)
method.
outBuff
.
outBuff
may be larger or smaller than inLength
or even 0.
ArrayIndexOutOfBoundsException
,
outBuff
may be partially modified.
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.doFinal
in class Cipher
inBuff
- the input buffer of data to be encrypted/decryptedinOffset
- the offset into the input buffer at which to begin
encryption/decryptioninLength
- the byte length to be encrypted/decryptedoutBuff
- the output buffer, may be the same as the input bufferoutOffset
- the offset into the output buffer where the resulting output
data 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.UNINITIALIZED_KEY
if
key not initialized.
CryptoException.INVALID_INIT
if this
Cipher
object is not initialized.
CryptoException.ILLEGAL_USE
if one of
the following conditions is met:
Cipher
algorithm does not pad the
message and the message is not block aligned.
Cipher
algorithm does not pad the
message and no input data has been provided in
inBuff
or via the update()
method.
Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms