Class AEADCipher
- java.lang.Object
-
- javacardx.crypto.Cipher
-
- javacardx.crypto.AEADCipher
-
public abstract class AEADCipher extends Cipher
The AEADCipher class is the abstract base class for Authenticated Encryption with Associated Data (AEAD) ciphers.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 theALG_AES_GCM
andALG_AES_CCM
algorithm constants. The returnedCipher
instance should then be cast toAEADCipher
.A tear or card reset event resets an initialized
AEADCipher
object to a state where:- the key and the mode are the same as when previously initialized via a call to init().
- Other initial values passed within init() methods e.g tagSize, messageLen, IV, nonce are reset to 0.
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. It is recommended to provide new initial values, not full of zeroes, with a new call to init().
Note: For algorithms which support keys with transient key data sets, e.g AES, the AEADCipher object key becomes uninitialized on clear events associated with the Key object used to initialize the AEADCipher object.
- Since:
- 3.0.5
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class javacardx.crypto.Cipher
Cipher.OneShot
-
-
Field Summary
Fields Modifier and Type Field Description static byte
ALG_AES_CCM
Cipher algorithmALG_AES_CCM
provides a cipher using AES in Counter with CBC-MAC mode as specified in RFC 3610.static byte
ALG_AES_GCM
Cipher algorithmALG_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 theCipher.getInstance(byte, byte, boolean)
method; the paddingAlgorithm must be set toPAD_NULL
.static byte
CIPHER_AES_GCM
Cipher algorithm CIPHER_AES_GCM choice for the cipherAlgorithm parameter of theCipher.getInstance(byte, byte, boolean)
method; the paddingAlgorithm must be set toPAD_NULL
.-
Fields inherited from class javacardx.crypto.Cipher
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_CFB, ALG_AES_CTR, ALG_AES_ECB_ISO9797_M1, ALG_AES_ECB_ISO9797_M2, ALG_AES_ECB_PKCS5, ALG_AES_XTS, 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_CFB, CIPHER_AES_CTR, CIPHER_AES_ECB, CIPHER_AES_XTS, CIPHER_DES_CBC, CIPHER_DES_ECB, CIPHER_KOREAN_SEED_CBC, CIPHER_KOREAN_SEED_ECB, CIPHER_RSA, CIPHER_SM2, CIPHER_SM4_CBC, CIPHER_SM4_ECB, MODE_DECRYPT, MODE_ENCRYPT, PAD_ISO9796, PAD_ISO9796_MR, PAD_ISO9796_MR_SCHEME_1_OPT_2, PAD_ISO9796_MR_SCHEME_2, PAD_ISO9796_MR_SCHEME_2_OPT_2, PAD_ISO9796_MR_SCHEME_3, PAD_ISO9796_MR_SCHEME_3_OPT_2, 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_EXT_PARAMETERS, 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_PKCS1_PSS_EXT_PARAMETERS, PAD_PKCS5, PAD_RFC2409
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
AEADCipher()
Avoid instantiation, compatible with protected constructor of Cipher.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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 theAEADCipher
object with the appropriateKey
.abstract void
init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen)
Initializes theAEADCipher
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 thisAEADCipher
instance to encrypt or decrypt with the given key, nonce, AAD size and message size.abstract short
retrieveTag(byte[] tagBuf, short tagOff, short tagLen)
RetrievestagLen
bytes from the calculated authentication tag.abstract short
update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)
Continues a multiple-part encryption or decryption operation, processing additional 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 bytes set inrequiredTagLen
bytes.-
Methods inherited from class javacardx.crypto.Cipher
getAlgorithm, getCipherAlgorithm, getInstance, getInstance, getPaddingAlgorithm
-
-
-
-
Field Detail
-
CIPHER_AES_GCM
public static final byte CIPHER_AES_GCM
Cipher algorithm CIPHER_AES_GCM choice for the cipherAlgorithm parameter of theCipher.getInstance(byte, byte, boolean)
method; the paddingAlgorithm must be set toPAD_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 toAEADCipher
.- Since:
- 3.0.5
- See Also:
- Constant Field Values
-
CIPHER_AES_CCM
public static final byte CIPHER_AES_CCM
Cipher algorithm CIPHER_AES_CCM choice for the cipherAlgorithm parameter of theCipher.getInstance(byte, byte, boolean)
method; the paddingAlgorithm must be set toPAD_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 toAEADCipher
.- Since:
- 3.0.5
- See Also:
- Constant Field Values
-
ALG_AES_GCM
public static final byte ALG_AES_GCM
Cipher algorithmALG_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 byCipher.getInstance(byte, boolean)
, it is required to cast the instance toAEADCipher
- Since:
- 3.0.5
- See Also:
- Constant Field Values
-
ALG_AES_CCM
public static final byte ALG_AES_CCM
Cipher algorithmALG_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 byCipher.getInstance(byte, boolean)
, it is required to cast the instance toAEADCipher
- Since:
- 3.0.5
- See Also:
- Constant Field Values
-
-
Method Detail
-
init
public abstract void init(Key theKey, byte theMode) throws CryptoException
Initializes theAEADCipher
object with the appropriateKey
. This method should be used for algorithms which do not need initialization parameters or use default parameter values.init()
must be used to update theAEADCipher
object with a new key. If theKey
object is modified after invoking theinit()
method, the behavior of theupdate()
anddoFinal()
methods is unspecified.The
Key
is checked for consistency with theCipher
algorithm. For example, the key type must be matched. Additional key componentdomain parameter strength checks are implementation specific.Note:
- AEADCipher in GCM mode will use a 12 bytes length buffer full of 0 for initial vector(IV) if this method is used.
- Specified by:
init
in classCipher
- Parameters:
theKey
- the key object to use for encrypting or decryptingtheMode
- one ofMODE_DECRYPT
orMODE_ENCRYPT
- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
iftheMode
option is an undefined value or if theKey
is inconsistent with theAEADCipher
implementation.CryptoException.UNINITIALIZED_KEY
iftheKey
instance is uninitialized.CryptoException.INVALID_INIT
if this method is called for an offline mode of encryption
- Since:
- 3.0.5
-
init
public abstract void init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) throws CryptoException
Initializes theAEADCipher
object with the appropriate Key and algorithm specific parameters.init()
must be used to update theAEADCipher
object with a new key. If theKey
object is modified after invoking theinit()
method, the behavior of theupdate()
anddoFinal()
methods is unspecified.The
Key
is checked for consistency with theCipher
algorithm. For example, the key type must be matched. Additional key component parameter strength checks are implementation specific.Note:
- AEADCipher in GCM mode will use
barray
for initial vector(IV) if this method is used.
- Specified by:
init
in classCipher
- Parameters:
theKey
- the key object to use for encrypting or decrypting.theMode
- one ofMODE_DECRYPT
orMODE_ENCRYPT
bArray
- byte array containing algorithm specific initialization infobOff
- offset within bArray where the algorithm specific data beginsbLen
- byte length of algorithm specific parameter data- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
iftheMode
option is an undefined value or if a byte array parameter option is not supported by the algorithm or if thebLen
is an incorrect byte length for the algorithm specific data or if theKey
is inconsistent with theAEADCipher
implementation.CryptoException.UNINITIALIZED_KEY
iftheKey
instance is uninitialized.CryptoException.INVALID_INIT
if this method is called for an offline mode of encryption
- Since:
- 3.0.5
- AEADCipher in GCM mode will use
-
init
public abstract void init(Key theKey, byte theMode, byte[] nonceBuf, short nonceOff, short nonceLen, short adataLen, short messageLen, short tagSize) throws CryptoException
Initializes thisAEADCipher
instance to encrypt or decrypt with the given key, nonce, AAD size and message size.This method should only be called for offline cipher mode encryption such as
ALG_AES_CCM
. In offline cipher mode encryption the length of the authentication data, message size and authentication tag must be known in advance.- Parameters:
theKey
- the key object to use for encrypting or decryptingtheMode
- one ofMODE_DECRYPT
orMODE_ENCRYPT
adataLen
- the length of the authenticated data as presented in theupdateAAD
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 theupdate
anddoFinal
methodstagSize
- the size in in bytes of the authentication tag- Throws:
CryptoException
- with the following reason codes:ILLEGAL_VALUE
if any of the values are outside the accepted rangeCryptoException.UNINITIALIZED_KEY
iftheKey
instance is uninitialized.CryptoException.INVALID_INIT
if this method is called for an online mode of encryption
- Since:
- 3.0.5
-
updateAAD
public abstract void updateAAD(byte[] aadBuf, short aadOff, short aadLen) throws CryptoException
Continues a multi-part update of the Additional Associated Data (AAD) that will be verified by the authentication tag. The data is not included with the ciphertext by this method.- Parameters:
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 buffer- Throws:
CryptoException
- 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 total AAD size provided, in all calls to this method, exceeds the AAD size given in the initial block used as IV
- Since:
- 3.0.5
-
update
public abstract short update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws CryptoException
Continues a multiple-part encryption or decryption operation, processing additional input data.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. ThedoFinal()
method must be invoked to complete processing of any remaining input data buffered by one or more calls to theupdate()
method.This method must write as much output as can be generated from the input data received so far. The output data length depends on the algorithm, the padding and the mode.
For operations based on stream cipher algorithms (
ALG_AES_CCM
,CIPHER_AES_CCM
,ALG_AES_GCM
andCIPHER_AES_GCM
), update() must process all bytes from input buffer and write the corresponding result. In this case, n input bytes generate n bytes of output data.Notes:
- When using block-aligned data (multiple of block size),
if the input buffer,
inBuff
and the output buffer,outBuff
refer to the same array, or if any of these arguments refer to an array view sharing components with the other argument, then the output data area must not partially overlap the input data area such that the input data is modified before it is used.
Example: ifinBuff==outBuff
andinOffset < outOffset < inOffset+inLength
, incorrect output may result. - When non-block aligned data is presented as input data, no amount of input
and output buffer data overlap is allowed.
Example: ifinBuff==outBuff
andoutOffset < inOffset+inLength
, incorrect output may result. - On encryption and decryption operations,
block alignment considerations may require that
the number of bytes output into
outBuff
be larger or smaller thaninLength
or even 0. - If
inLength
is 0 this method does nothing.
In addition to returning a
short
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Specified by:
update
in classCipher
- Parameters:
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 begins- Returns:
- number of bytes output in
outBuff
- Throws:
CryptoException
- with the following reason codes:INVALID_INIT
if thisAEADCipher
object is not initialized.CryptoException.UNINITIALIZED_KEY
if key not initialized.ILLEGAL_USE
- for CCM if AAD is not provided while it is indicated in the initial block used as IV
- for CCM if the payload exceeds the payload size given in the initial block used as IV
- Since:
- 3.0.5
- When using block-aligned data (multiple of block size),
if the input buffer,
-
doFinal
public abstract short doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws CryptoException
Generates encrypted/decrypted output from all/last input data. This method must be invoked to complete a cipher operation. This method processes any remaining input data buffered by one or more calls to theupdate()
method as well as input data supplied in theinBuff
parameter.A call to this method also resets this AEADCipher object to a state where:
- the key and the mode are the same as when previously initialized via a call to init().
- other initial values passed within init() methods e.g tagSize, messageLen, IV, nonce are reset to 0 except tagSize required for subsequent calls to retrieveTag and verifyTag.
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. It is recommended to provide new initial values, not full of zeroes, with a new call to init().
Notes:
- When using block-aligned data (multiple of block size),
if the input buffer,
inBuff
and the output buffer,outBuff
refer to the same array, or if any of these arguments refer to an array view sharing components with the other argument, then the output data area must not partially overlap the input data area such that the input data is modified before it is used.
Example: ifinBuff==outBuff
andinOffset < outOffset < inOffset+inLength
, incorrect output may result. - When non-block aligned data is presented as input data, no amount of input
and output buffer data overlap is allowed.
Example: ifinBuff==outBuff
andoutOffset < inOffset+inLength
, incorrect output may result. - On encryption and decryption operations, the number of bytes output into
outBuff
may be larger or smaller thaninLength
or even 0. - On decryption operations resulting in an
ArrayIndexOutOfBoundsException
,outBuff
may be partially modified.
In addition to returning a
short
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Specified by:
doFinal
in classCipher
- Parameters:
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 begins- Returns:
- number of bytes output in
outBuff
- Throws:
CryptoException
- with the following reason codes:INVALID_INIT
if thisAEADCipher
object is not initialized.UNINITIALIZED_KEY
if key not initialized.ILLEGAL_USE
- for CCM if all Additional Authenticated Data (AAD) was not provided
- for CCM if the total message size provided is not identical to the
messageLen
parameter given in theinit
method
- Since:
- 3.0.5
-
retrieveTag
public abstract short retrieveTag(byte[] tagBuf, short tagOff, short tagLen) throws CryptoException
RetrievestagLen
bytes from the calculated authentication tag. Depending on the algorithm, only certain tag lengths may be supported.Note:
- This method may only be called for
MODE_ENCRYPT
afterdoFinal
has been called.
In addition to returning a
short
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Parameters:
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 buffer- Returns:
- the tag length, as given by tagLen (for convenience)
- Throws:
CryptoException
- with the following reason codesILLEGAL_USE
ifdoFinal
has not been called or the mode is notMODE_ENCRYPT
ILLEGAL_VALUE
if the tag length is not equal to the generated tag length e.g the length passed ininit(Key, byte, byte[], short, short, short, short, short)
for ALG_AES_CCM
- Since:
- 3.0.5
- This method may only be called for
-
verifyTag
public abstract boolean verifyTag(byte[] receivedTagBuf, short receivedTagOff, short receivedTagLen, short requiredTagLen) throws CryptoException
Verifies the authentication tag using the number of bytes set inrequiredTagLen
bytes. Depending on the algorithm, only certain tag lengths may be supported. For all algorithms the tag length must be a multiple of 8 bits.Notes:
- This method may only be called for
MODE_DECRYPT
afterdoFinal
has been called. - If recievedTagLen and requiredTagLen are valid values and recievedTagLen < requiredTagLen, the method returns false.
In addition to returning a
boolean
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Parameters:
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 value- Returns:
true
if successfully verified,false
otherwise- Throws:
CryptoException
- with the following reason codes:ILLEGAL_USE
ifdoFinal
has not been called or the mode is notMODE_DECRYPT
ILLEGAL_VALUE
if the tag length is not supported
- Since:
- 3.0.5
- This method may only be called for
-
-