public class CipherLite extends Object
Cipher
but provides only a subset of all the
interface methods of Cipher
. This class is intended to be used in
lieu of the underlying Cipher directly whenever applicable. For example, this
class makes it easy to generate an inverse cipher, or to create an
"auxiliary" cipher for use with get-range or multi-part upload operations. A
subclass may also support the mark and reset operations to enable parts of a
plaintext to be re-processed which is useful for error recovery typical when
network transmission is involved.
However a cipher lite, unlike a Cipher
, can only be used once, and
cannot be reused after the doFinal()
methods have been invoked. In
other words, it is NOT true that, upon finishing, the doFinal method will
reset the cipher lite object to the state it was in when first constructed.
GCMCipherLite
Modifier and Type | Field and Description |
---|---|
static CipherLite |
Null
A no-op implementation.
|
Modifier and Type | Method and Description |
---|---|
CipherLite |
createAuxiliary(long startingBytePos)
Returns an auxiliary
CipherLite for partial plaintext
re-encryption (or re-decryption) purposes. |
CipherLite |
createInverse()
Returns the inverse of the current
CipherLite . |
CipherLite |
createUsingIV(byte[] iv)
Creates a new instance of CipherLite from the current one, but using
the given IV.
|
byte[] |
doFinal()
Finishes a multiple-part encryption or decryption operation, depending on
how the underlying cipher was initialized.
|
byte[] |
doFinal(byte[] input)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
|
byte[] |
doFinal(byte[] input,
int inputOffset,
int inputLen)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
|
int |
getBlockSize()
Returns the block size (in bytes).
|
Cipher |
getCipher()
This method is provided only for testing purposes.
|
String |
getCipherAlgorithm()
Returns the algorithm name of the underlying cipher.
|
Provider |
getCipherProvider()
Returns the provider of the underlying cipher.
|
ContentCryptoScheme |
getContentCryptoScheme() |
byte[] |
getIV()
Returns the initialization vector (IV) in a new buffer.
|
String |
getSecretKeyAlgorithm()
Returns the standard algorithm name for the secret key.
|
long |
mark()
Marks the current position in this cipher lite.
|
boolean |
markSupported()
Tests if this cipher lite supports the
mark
and reset methods. |
CipherLite |
recreate()
Recreates a new instance of CipherLite from the current one.
|
void |
reset()
Repositions this cipher lite to the position at the time the
mark method was last called. |
byte[] |
update(byte[] input,
int inputOffset,
int inputLen)
Continues a multiple-part encryption or decryption operation (depending
on how the underlying cipher was initialized), processing another data
part.
|
public static final CipherLite Null
public CipherLite recreate()
public CipherLite createUsingIV(byte[] iv)
public CipherLite createAuxiliary(long startingBytePos) throws InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException, NoSuchPaddingException, InvalidAlgorithmParameterException
CipherLite
for partial plaintext
re-encryption (or re-decryption) purposes.startingBytePos
- the starting byte position of the plaintext. Must be a
multiple of the cipher block size.InvalidKeyException
NoSuchAlgorithmException
NoSuchProviderException
NoSuchPaddingException
InvalidAlgorithmParameterException
public CipherLite createInverse() throws InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException, NoSuchPaddingException, InvalidAlgorithmParameterException
CipherLite
.public byte[] doFinal() throws IllegalBlockSizeException, BadPaddingException
Input data that may have been buffered during a previous
update
operation is processed, with padding (if requested)
being applied. If an AEAD mode such as GCM/CCM is being used, the
authentication tag is appended in the case of encryption, or verified in
the case of decryption. The result is stored in a new buffer.
Note: if any exception is thrown, a new instance of this cipher lite object may need to be constructed before it can be used again. be reconstructed before it can be used again.
IllegalStateException
- if this cipher is in a wrong state (e.g., has not been
initialized)IllegalBlockSizeException
- if this cipher is a block cipher, no padding has been
requested (only in encryption mode), and the total input
length of the data processed by this cipher is not a
multiple of block size; or if this encryption algorithm is
unable to process the input data provided.BadPaddingException
- if this cipher is in decryption mode, and (un)padding has
been requested, but the decrypted data is not bounded by
the appropriate padding bytesAEADBadTagException
- if this cipher is decrypting in an AEAD mode (such as
GCM/CCM), and the received authentication tag does not
match the calculated valuepublic byte[] doFinal(byte[] input) throws IllegalBlockSizeException, BadPaddingException
The bytes in the input
buffer, and any input bytes that may
have been buffered during a previous update
operation, are
processed, with padding (if requested) being applied. If an AEAD mode
such as GCM/CCM is being used, the authentication tag is appended in the
case of encryption, or verified in the case of decryption. The result is
stored in a new buffer.
Note: if any exception is thrown, a new instance of this cipher lite object may need to be constructed before it can be used again.
input
- the input bufferIllegalStateException
- if this cipher is in a wrong state (e.g., has not been
initialized)IllegalBlockSizeException
- if this cipher is a block cipher, no padding has been
requested (only in encryption mode), and the total input
length of the data processed by this cipher is not a
multiple of block size; or if this encryption algorithm is
unable to process the input data provided.BadPaddingException
- if this cipher is in decryption mode, and (un)padding has
been requested, but the decrypted data is not bounded by
the appropriate padding bytes; or if this cipher is
decrypting in an AEAD mode (such as GCM/CCM), and the
received authentication tag does not match the calculated
valuepublic byte[] doFinal(byte[] input, int inputOffset, int inputLen) throws IllegalBlockSizeException, BadPaddingException
The first inputLen
bytes in the input
buffer,
starting at inputOffset
inclusive, and any input bytes that
may have been buffered during a previous update
operation,
are processed, with padding (if requested) being applied. If an AEAD mode
such as GCM/CCM is being used, the authentication tag is appended in the
case of encryption, or verified in the case of decryption. The result is
stored in a new buffer.
Note: if any exception is thrown, a new instance of this cipher lite object may need to be constructed before it can be used again.
input
- the input bufferinputOffset
- the offset in input
where the input startsinputLen
- the input lengthIllegalStateException
- if this cipher is in a wrong state (e.g., has not been
initialized)IllegalBlockSizeException
- if this cipher is a block cipher, no padding has been
requested (only in encryption mode), and the total input
length of the data processed by this cipher is not a
multiple of block size; or if this encryption algorithm is
unable to process the input data provided.BadPaddingException
- if this cipher is in decryption mode, and (un)padding has
been requested, but the decrypted data is not bounded by
the appropriate padding bytes; or if this cipher is
decrypting in an AEAD mode (such as GCM/CCM), and the
received authentication tag does not match the calculated
valuepublic byte[] update(byte[] input, int inputOffset, int inputLen)
The first inputLen
bytes in the input
buffer,
starting at inputOffset
inclusive, are processed, and the
result is stored in a new buffer.
If inputLen
is zero, this method returns null
.
input
- the input bufferinputOffset
- the offset in input
where the input startsinputLen
- the input lengthIllegalStateException
- if the underlying cipher is in a wrong state (e.g., has
not been initialized)public final String getCipherAlgorithm()
public final Provider getCipherProvider()
public final String getSecretKeyAlgorithm()
public final Cipher getCipher()
CipherLite
is intended to be used in lieu of the underlying Cipher.public final ContentCryptoScheme getContentCryptoScheme()
public final byte[] getIV()
This is useful in the case where a random IV was created, or in the context of password-based encryption or decryption, where the IV is derived from a user-supplied password.
public final int getBlockSize()
public boolean markSupported()
mark
and reset
methods. Returns false by default, but subclass
may override.public long mark()
reset
method repositions this cipher lite at the last marked
position so that subsequent crypto operations will be logically performed
in an idempotent manner as if the cipher has been rewinded back to the
marked position.
The general contract of mark
is that, if the method
markSupported
returns true
, the cipher lite
somehow remembers the internal state after the call to mark
and stands ready to restore to the internal state so that it would be
able to produce the same output given the same input again if and
whenever the method reset
is called.
public void reset()
mark
method was last called.
The general contract of reset
is:
markSupported
returns true
,
then the cipher lite is reset to the internal state since the most recent
call to mark
(or since the start of the input data, if
mark
has not been called), so that subsequent callers of the
udpate
or doFinal
method would produce the same
output given the same input data identical to the input data after the
mark
method was last called..markSupported
returns false
,
then the call to reset
may throw an
IllegalStateException
.