public abstract class AsconCipherSpi extends CipherSpi
The interface provides a buffered and a streaming mode of operation.
The buffered approach calls engineDoFinal(byte[], int, int)
directly with all input data at once.
The streaming mode enables updating the cipher in chunks of data (see engineUpdate(byte[], int, int)
).
While the streaming mode provides more efficiency since the input and output data are processed step-by-step,
it is important to notice that decrypted plaintext data might be output before the authentication tag is verified.
Therefore, using the streaming mode requires handling potentially unauthenticated plaintext appropriately until the full ciphertext is authenticated.
Constructor and Description |
---|
AsconCipherSpi() |
Modifier and Type | Method and Description |
---|---|
protected byte[] |
engineDoFinal(byte[] input,
int inputOffset,
int inputLen)
Returns the result of the last step of a multistep en/decryption operation
or the result of a single-step en/decryption operation by processing the
given input data and any remaining buffered data.
|
protected int |
engineDoFinal(byte[] input,
int inputOffset,
int inputLen,
byte[] output,
int outputOffset)
Performs the last step of a multistep en/decryption operation or a
single-step en/decryption operation by processing the given input data and
any remaining buffered data.
|
protected int |
engineGetBlockSize()
Returns the rate corresponding to the variant of this cipher.
|
protected byte[] |
engineGetIV()
Returns a byte array containing the initialization vector (IV).
|
protected int |
engineGetOutputSize(int inputLen)
Returns the output buffer size necessary for capturing the data resulting
from the next
update or doFinal operation including any data currently being buffered. |
protected AlgorithmParameters |
engineGetParameters()
Returns the parameters used with this cipher.
|
protected void |
engineInit(int opmode,
Key key,
AlgorithmParameterSpec params,
SecureRandom random)
Initializes this cipher object with proper key and algorithm parameters,
and some random seed.
|
protected void |
engineInit(int opmode,
Key key,
AlgorithmParameters algorithmParameters,
SecureRandom secureRandom)
Initializes this cipher with a key, a set of algorithm parameters, and a
source of randomness.
|
protected void |
engineInit(int opmode,
Key key,
SecureRandom secureRandom)
Initializes this cipher object with a proper key and some random seed.
|
protected void |
engineSetMode(String mode)
Sets the mode of this cipher.
|
protected void |
engineSetPadding(String padding)
Sets the padding scheme of this cipher.
|
protected byte[] |
engineUpdate(byte[] input,
int off,
int len)
Returns the result of the next step of a multistep en/decryption
operation.
|
protected int |
engineUpdate(byte[] input,
int inputOffset,
int inputLen,
byte[] output,
int outputOffset)
Performs the next step of a multistep en/decryption operation.
|
protected void |
engineUpdateAAD(byte[] input,
int off,
int len)
Continues a multipart update of the Additional Authentication Data (AAD), using a subset of the provided buffer.
|
protected void |
engineUpdateAAD(ByteBuffer src)
Continues a multipart update of the Additional Authentication Data (AAD).
|
protected abstract int |
getKeySize()
return the key size: Ascon-128: 16 bytes, Ascon-128a: 16 bytes, Ascon-80pq: 20 bytes
|
protected abstract int |
getRate()
return the rate: Ascon-128: 8 bytes, Ascon-128a: 16 bytes, Ascon-80pq: 8 bytes
|
protected abstract String |
getVariant()
returns the variant with which the cipher is called (Ascon-128, Ascon-128a, Ascon-80pq)
|
engineDoFinal, engineGetKeySize, engineUnwrap, engineUpdate, engineWrap
protected abstract String getVariant()
protected abstract int getRate()
protected abstract int getKeySize()
protected void engineSetMode(String mode) throws NoSuchAlgorithmException
For the Ascon cipher has solely one default mode.
Therefore, the parameter mode is either "NONE" or null
.
Cipher.getInstance(...)
without specifying a particular cipher
mode, engineSetMode
is also supplied with the default mode.engineSetMode
in class CipherSpi
mode
- the cipher modeNoSuchAlgorithmException
- if this cipher mode is not supported (any other input different to "NONE")protected void engineSetPadding(String padding) throws NoSuchPaddingException
The Ascon cipher does not support an external padding.
Therefore, the parameter mode is either "NoPadding" or null
.
Cipher.getInstance(...)
without specifying a particular
padding scheme, engineSetMode
is also supplied with the default
"NoPadding" scheme.engineSetPadding
in class CipherSpi
padding
- the padding schemeNoSuchPaddingException
- if this padding scheme is not supported (any other input different to "NoPadding")protected int engineGetBlockSize()
engineGetBlockSize
in class CipherSpi
protected int engineGetOutputSize(int inputLen)
update
or doFinal
operation including any data currently being buffered.
The actual output length of the next update or doFinal call may be smaller than the length returned by this method.engineGetOutputSize
in class CipherSpi
inputLen
- the number of bytes to processprotected byte[] engineGetIV()
engineGetIV
in class CipherSpi
null
otherwise.protected AlgorithmParameters engineGetParameters()
The returned parameters may be the same that were used to initialize this cipher or a set of randomly generated parameters.
engineGetParameters
in class CipherSpi
protected void engineInit(int opmode, Key key, SecureRandom secureRandom) throws InvalidKeyException
opmode
parameter (either ENCRYPT_MODE or
DECCRYPT_MODE).
e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key, random_seed);
The Cipher init
will call the proper CipherSpi
engineInit
method.
engineInit
in class CipherSpi
opmode
- the operation mode for which this cipher is used (ENCRYPT_MODE or
DECRYPT_MODE)key
- the keysecureRandom
- the random seedInvalidKeyException
- if the given key cannot be used for initializing this cipherprotected void engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
Initializes this cipher object with proper key and algorithm parameters,
and some random seed. Before a cipher object is ready for data processing,
it has to be initialized according to the desired cryptographic operation,
which is specified by the opmode
parameter (either
ENCRYPT_MODE or DECCRYPT_MODE).
e.g.
cipher_obj.init(Cipher.ENCRYPT_MODE, key, alg_params, random_seed);
The Cipher init
will call the proper CipherSpi
engineInit
method.
engineInit
in class CipherSpi
opmode
- the operation mode for which this cipher is used (ENCRYPT_MODE or
DECRYPT_MODE)key
- the keyparams
- the algorithm parametersrandom
- the random seedInvalidKeyException
- if the given key cannot be used for initializing this cipherInvalidAlgorithmParameterException
- if the given algorithm parameters don't match to this cipherprotected void engineInit(int opmode, Key key, AlgorithmParameters algorithmParameters, SecureRandom secureRandom) throws InvalidKeyException, InvalidAlgorithmParameterException
The cipher is initialized for encryption or decryption, depending on the value of opmode. If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from random. Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.
engineInit
in class CipherSpi
opmode
- the operation mode of this cipher (this is either ENCRYPT_MODE or
DECRYPT_MODE)key
- the encryption keyalgorithmParameters
- the algorithm parameterssecureRandom
- the source of randomnessInvalidKeyException
- if the given key is inappropriate for initializing thiscipherInvalidAlgorithmParameterException
- if the given algorithm parameters are inappropriate for this
cipherprotected byte[] engineUpdate(byte[] input, int off, int len)
inputOffset
, only the first inputLen
bytes are en/decrypted. The result is returned as a byte array.engineUpdate
in class CipherSpi
input
- the byte array holding the data to be processedoff
- the offset indicating the start position within the input byte
arraylen
- the number of bytes to be processedprotected int engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) throws ShortBufferException
inputOffset
, only the first inputLen
bytes are
en/decrypted. The result is stored in the given output byte array,
beginning at outputOffset
. The number of bytes stored in this
output byte array are returned.engineUpdate
in class CipherSpi
input
- the byte array holding the data to be processedinputOffset
- the offset indicating the start position within the input byte
arrayinputLen
- the number of bytes to be processedoutput
- the byte array for holding the resultoutputOffset
- the offset indicating the start position within the output byte
array to which the en/decrypted data is writtenShortBufferException
- if the given output buffer is too small for holding the resultprotected byte[] engineDoFinal(byte[] input, int inputOffset, int inputLen) throws BadPaddingException
The data to be processed is given in an input byte array. Beginning at
inputOffset
, only the first inputLen
bytes are
en/decrypted, including any buffered bytes of a previous
update
operation. The result is returned as a output byte array.
engineDoFinal
in class CipherSpi
input
- the byte array holding the data to be processedinputOffset
- the offset indicating the start position within the input byte
arrayinputLen
- the number of bytes to be processedBadPaddingException
- if the decrypted data is not bounded by the proper padding
bytes after data decryption including (un)paddingCipher.doFinal()
protected int engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) throws ShortBufferException, BadPaddingException
The data to be processed is given in an input byte array. Beginning at
inputOffset
, only the first inputLen
bytes are
en/decrypted, including any buffered bytes of a previous
update
operation. The
result is stored in the given output byte array, beginning at
outputOffset
. The number of bytes stored in this byte array
are returned.
engineDoFinal
in class CipherSpi
input
- the byte array holding the data to be processedinputOffset
- the offset indicating the start position within the input byte
arrayinputLen
- the number of bytes to be processedoutput
- the byte array for holding the resultoutputOffset
- the offset indicating the start position within the output byte
array to which the en/decrypted data is writtenShortBufferException
- if the given output buffer is too small for holding the resultBadPaddingException
- if the decrypted data is not bounded by the proper padding
bytes after data decryption including (un)paddingprotected void engineUpdateAAD(byte[] input, int off, int len)
Calls to this method provide AAD to the cipher.
All AAD must be supplied before beginning operations on the ciphertext (via the update and doFinal methods).engineUpdateAAD
in class CipherSpi
input
- the buffer containing the AADoff
- the offset in src
where the AAD input startslen
- the number of AAD bytesprotected void engineUpdateAAD(ByteBuffer src)
Calls to this method provide AAD to the cipher. All AAD must be supplied before beginning operations on the ciphertext (via the update and doFinal methods).
All src.remaining() bytes starting at src.position() are processed. Upon return, the input buffer's position will be equal to its limit; its limit will not have changed.engineUpdateAAD
in class CipherSpi
src
- the buffer containing the AADCopyright © 2022–2023 Stiftung SIC. All rights reserved.