public abstract class AEADCipher extends Cipher
Examples of AEAD algorithms are the GCM and CCM modes of operation for AES.
AEAD ciphers can be created by the Cipher.getInstance
method using the
ALG_AES_GCM
and ALG_AES_CCM
algorithm constants.
The returned Cipher
instance should then be cast to AEADCipher
.
Cipher.OneShot
Modifier and Type | Field and Description |
---|---|
static byte |
ALG_AES_CCM
Cipher algorithm
ALG_AES_CCM provides a cipher using AES in Counter with CBC-MAC mode as
specified in RFC 3610. |
static byte |
ALG_AES_GCM
Cipher algorithm
ALG_AES_GCM provides a cipher using AES in Galois/Counter Mode as specified
in NIST SP 800-38D, November 2007. |
static byte |
CIPHER_AES_CCM
Cipher algorithm CIPHER_AES_CCM choice for the cipherAlgorithm parameter of the
Cipher.getInstance(byte, byte, boolean) method;
the paddingAlgorithm must be set to PAD_NULL . |
static byte |
CIPHER_AES_GCM
Cipher algorithm CIPHER_AES_GCM choice for the cipherAlgorithm parameter of the
Cipher.getInstance(byte, byte, boolean) method;
the paddingAlgorithm must be set to PAD_NULL . |
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 | Constructor and Description |
---|---|
protected |
AEADCipher()
Avoid instantiation, compatible with protected constructor of Cipher.
|
Modifier and Type | Method and Description |
---|---|
abstract short |
doFinal(byte[] inBuff,
short inOffset,
short inLength,
byte[] outBuff,
short outOffset)
Generates encrypted/decrypted output from all/last input data.
|
abstract void |
init(Key theKey,
byte theMode)
Initializes the
Cipher object with the appropriate
Key . |
abstract void |
init(Key theKey,
byte theMode,
byte[] bArray,
short bOff,
short bLen)
Initializes the
Cipher object with the appropriate Key and
algorithm specific parameters. |
abstract void |
init(Key theKey,
byte theMode,
byte[] nonceBuf,
short nonceOff,
short nonceLen,
short adataLen,
short messageLen,
short tagSize)
Initializes this
Cipher instance to encrypt or decrypt a with the given
key, nonce, AAD size and message size. |
abstract short |
retrieveTag(byte[] tagBuf,
short tagOff,
short tagLen)
Retrieves
tagLen bytes from the calculated authentication tag. |
abstract short |
update(byte[] inBuff,
short inOffset,
short inLength,
byte[] outBuff,
short outOffset)
Generates encrypted/decrypted output from input data.
|
abstract void |
updateAAD(byte[] aadBuf,
short aadOff,
short aadLen)
Continues a multi-part update of the Additional Associated Data (AAD) that will be verified by the authentication tag.
|
abstract boolean |
verifyTag(byte[] receivedTagBuf,
short receivedTagOff,
short receivedTagLen,
short requiredTagLen)
Verifies the authentication tag using the number of bits set in
requiredTagLen bits. |
getAlgorithm, getCipherAlgorithm, getInstance, getInstance, getPaddingAlgorithm
public static final byte CIPHER_AES_GCM
Cipher.getInstance(byte, byte, boolean)
method;
the paddingAlgorithm must be set to PAD_NULL
. The cipher algorithm provides a cipher using AES Galois/Counter Mode as specified
in NIST SP 800-38D, November 2007.
To use the AEAD properties of the instance returned it is required to cast the returned instance to AEADCipher
.public static final byte CIPHER_AES_CCM
Cipher.getInstance(byte, byte, boolean)
method;
the paddingAlgorithm must be set to PAD_NULL
. The cipher algorithm provides a cipher using AES in Counter with CBC-MAC mode
as specified in RFC 3610.
To use the AEAD properties of the instance returned it is required to cast the returned instance to AEADCipher
.public static final byte ALG_AES_GCM
ALG_AES_GCM
provides a cipher using AES in Galois/Counter Mode as specified
in NIST SP 800-38D, November 2007.
To use the AEAD properties of the instance returned by Cipher.getInstance(byte, boolean)
,
it is required to cast the instance to AEADCipher
public static final byte ALG_AES_CCM
ALG_AES_CCM
provides a cipher using AES in Counter with CBC-MAC mode as
specified in RFC 3610.
To use the AEAD properties of the instance returned by Cipher.getInstance(byte, boolean)
,
it is required to cast the instance to AEADCipher
protected AEADCipher()
public abstract 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
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.CryptoException.INVALID_INIT
if this method is called for an offline mode of encryptionpublic abstract 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 dataCryptoException
- 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.CryptoException.INVALID_INIT
if this method is called for an offline mode of encryptionpublic abstract void init(Key theKey, byte theMode, byte[] nonceBuf, short nonceOff, short nonceLen, short adataLen, short messageLen, short tagSize) throws CryptoException
Cipher
instance to encrypt or decrypt a with the given
key, nonce, AAD size and message size.
This method should only be called for offline cipher mode encryption such as Cipher#ALG_AES_CCM
.
In offline cipher mode encryption the length of the authentication data, message size and authentication tag
must be known in advance.
theKey
- the key object to use for encrypting or decryptingtheMode
- one of MODE_DECRYPT
or
MODE_ENCRYPT
adataLen
- the length of the authenticated data
as presented in the updateAAD
methodnonceBuf
- a buffer holding the noncenonceOff
- the offset in the buffer of the noncenonceLen
- the length in the buffer of the noncemessageLen
- the length of the message
as presented in the update
and doFinal
methodstagSize
- the size in in bytes of the authentication tagCryptoException
- with the following reason codes:
ILLEGAL_VALUE
if any of the values are outside the
accepted rangeCryptoException.UNINITIALIZED_KEY
if
theKey
instance is uninitialized.CryptoException.INVALID_INIT
if this method is called for an online mode of encryptionpublic abstract void updateAAD(byte[] aadBuf, short aadOff, short aadLen) throws CryptoException
aadBuf
- the buffer containing the AAD dataaadOff
- the offset of the AAD data in the bufferaadLen
- the length in bytes of the AAD data in the bufferCryptoException
- with the following reason codes:
ILLEGAL_USE
if updating the AAD value is conflicting with the
state of this cipherILLEGAL_VALUE
for CCM if the AAD size is different from the AAD size given in the initial block used as IVpublic abstract short update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws CryptoException
This method requires temporary storage of intermediate results. In addition, if the input data length is not block aligned (multiple of block size) then additional internal storage may be allocated at this time to store a partial input data block. This may result in additional resource consumption and/or slow performance.
This method should only be used if all the input data required for the
cipher is not available in one byte array. If all the input data required
for the cipher is located in a single byte array, use of the
doFinal()
method to process all of the input data is
recommended. The doFinal()
method must be invoked to
complete processing of any remaining input data buffered by one or more
calls to the update()
method.
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.
outBuff
.
outBuff
be larger or smaller than
inLength
or even 0.
inLength
is 0 this method does nothing.
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.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:
INVALID_INIT
if this Cipher
object is
not initialized.CryptoException.UNINITIALIZED_KEY
if key not initialized.ILLEGAL_USE
public abstract 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
CryptoException
- with the following reason codes:
INVALID_INIT
if this Cipher
object is
not initialized.UNINITIALIZED_KEY
if key not initialized.ILLEGAL_USE
messageLen
parameter
given in the init
methodpublic abstract short retrieveTag(byte[] tagBuf, short tagOff, short tagLen) throws CryptoException
tagLen
bytes from the calculated authentication tag. Depending
on the algorithm, only certain tag lengths may be supported.
Note:
MODE_ENCRYPT
after
doFinal
has been called.
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.tagBuf
- the buffer that will contain the authentication tagtagOff
- the offset of the authentication tag in the buffertagLen
- the length in bytes of the authentication tag in the bufferCryptoException
- with the following reason codes
ILLEGAL_USE
if
doFinal
has not been calledILLEGAL_VALUE
if the tag length is not supported
public abstract boolean verifyTag(byte[] receivedTagBuf, short receivedTagOff, short receivedTagLen, short requiredTagLen) throws CryptoException
requiredTagLen
bits. Depending on
the algorithm, only certain tag lengths
may be supported. For all algorithms the tag length must be a multiple of
8 bits.
Note:
MODE_DECRYPT
after
doFinal
has been called.
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.receivedTagBuf
- the buffer that will contain the received authentication tagreceivedTagOff
- the offset of the received authentication tag in the bufferreceivedTagLen
- the length in bytes of the received authentication tag in the bufferrequiredTagLen
- the required length in bytes of the received authentication tag,
usually a constant valueCryptoException
- with the following reason codes:
ILLEGAL_USE
if
doFinal
has not been calledILLEGAL_VALUE
if the tag length is not supported
Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms