javacardx.crypto

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 the ALG_AES_GCM and ALG_AES_CCM algorithm constants. The returned Cipher instance should then be cast to AEADCipher.

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 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.

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_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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AEADCipher() Avoid instantiation, compatible with protected constructor of Cipher.

Method Summary

Methods

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.

Methods inherited from class javacardx.crypto.Cipher

getAlgorithm, getCipherAlgorithm, getInstance, getInstance, getPaddingAlgorithm

Methods inherited from class java.lang.Object

equals

Field Detail

CIPHER_AES_GCM

public static final 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. 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.

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 the 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.

Since:

3.0.5

See Also:

Constant Field Values

ALG_AES_GCM

public static final 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. To use the AEAD properties of the instance returned by Cipher.getInstance(byte, boolean), it is required to cast the instance to AEADCipher

Since:

3.0.5

See Also:

Constant Field Values

ALG_AES_CCM

public static final 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. To use the AEAD properties of the instance returned by Cipher.getInstance(byte, boolean), it is required to cast the instance to AEADCipher

Since:

3.0.5

See Also:

Constant Field Values

Constructor Detail

AEADCipher

protected AEADCipher()

Avoid instantiation, compatible with protected constructor of Cipher.

Method Detail

init

public abstract void init(Key theKey,
        byte theMode)
                   throws CryptoException

Initializes the 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:

• AES, DES, triple DES and Korean SEED algorithms in CBC mode will use 0 for initial vector(IV) if this method is used.
• For optimal performance, when the theKey parameter is a transient key, the implementation should, whenever possible, use transient space for internal storage.

• AEADCipher in GCM mode will use 0 for initial vector(IV) if this method is used.

Specified by:

init in class Cipher

Parameters:

theKey - the key object to use for encrypting or decrypting

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

Throws:

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 encryption

Since:

3.0.5

init

public abstract void init(Key theKey,
        byte theMode,
        byte[] bArray,
        short bOff,
        short bLen)
                   throws CryptoException

Initializes the 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:

• DES and triple DES algorithms in CBC mode expect an 8-byte parameter value for the initial vector(IV) in bArray.
• AES algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
• Korean SEED algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
• AES algorithms in ECB mode, DES algorithms in ECB mode, Korean SEED algorithm in ECB mode, RSA and DSA algorithms throw CryptoException.ILLEGAL_VALUE.
• For optimal performance, when the theKey parameter is a transient key, the implementation should, whenever possible, use transient space for internal storage.

Specified by:

init in class Cipher

Parameters:

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 info

bOff - offset within bArray where the algorithm specific data begins

bLen - byte length of algorithm specific parameter data

Throws:

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.
• 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[] nonceBuf,
        short nonceOff,
        short nonceLen,
        short adataLen,
        short messageLen,
        short tagSize)
                   throws CryptoException

Initializes this 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.

Parameters:

theKey - the key object to use for encrypting or decrypting

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

adataLen - the length of the authenticated data as presented in the updateAAD method

nonceBuf - a buffer holding the nonce

nonceOff - the offset in the buffer of the nonce

nonceLen - the length in the buffer of the nonce

messageLen - the length of the message as presented in the update and doFinal methods

tagSize - 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 range
• CryptoException.UNINITIALIZED_KEY if theKey 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 data

aadOff - the offset of the AAD data in the buffer

aadLen - 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 cipher
• ILLEGAL_VALUE for CCM if the AAD size is different from 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

Generates encrypted/decrypted output from input data. This method is intended for multiple-part encryption/decryption operations.

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:

• When using block-aligned data (multiple of block size), if the input buffer, 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 and
  inOffset < 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; if inBuff==outBuff and
  outOffset < inOffset+inLength, incorrect output may result.
• On decryption operations(except when ISO 9797 method 1 padding is used), the padding bytes are not written to outBuff.
• On encryption and decryption operations, block alignment considerations may require that the number of bytes output into outBuff be larger or smaller than inLength 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 the SensitiveResult class, if supported by the platform.

Specified by:

update in class Cipher

Parameters:

inBuff - the input buffer of data to be encrypted/decrypted

inOffset - the offset into the input buffer at which to begin encryption/decryption

inLength - the byte length to be encrypted/decrypted

outBuff - the output buffer, may be the same as the input buffer

outOffset - 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 this Cipher 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

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 the 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:

• When using block-aligned data (multiple of block size), if the input buffer, 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 and
  inOffset < 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; if inBuff==outBuff and
  outOffset < inOffset+inLength, incorrect output may result.
• AES, DES, triple DES and Korean SEED algorithms in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init(Key, byte, byte[], short, short) method.
• On decryption operations (except when ISO 9797 method 1 padding is used), the padding bytes are not written to outBuff.
• On encryption and decryption operations, the number of bytes output into outBuff may be larger or smaller than inLength 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 the SensitiveResult class, if supported by the platform.

Specified by:

doFinal in class Cipher

Parameters:

inBuff - the input buffer of data to be encrypted/decrypted

inOffset - the offset into the input buffer at which to begin encryption/decryption

inLength - the byte length to be encrypted/decrypted

outBuff - the output buffer, may be the same as the input buffer

outOffset - 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 this Cipher 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 the init method

Since:

3.0.5

retrieveTag

public abstract short retrieveTag(byte[] tagBuf,
                short tagOff,
                short tagLen)
                           throws CryptoException

Retrieves tagLen 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 after doFinal 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 the SensitiveResult class, if supported by the platform.

Parameters:

tagBuf - the buffer that will contain the authentication tag

tagOff - the offset of the authentication tag in the buffer

tagLen - 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 codes

• ILLEGAL_USE if doFinal has not been called
• ILLEGAL_VALUE if the tag length is not supported

Since:

3.0.5

verifyTag

public abstract boolean verifyTag(byte[] receivedTagBuf,
                short receivedTagOff,
                short receivedTagLen,
                short requiredTagLen)
                           throws CryptoException

Verifies the authentication tag using the number of bits set in 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:

• This method may only be called for MODE_DECRYPT after doFinal has been called.

In addition to returning a 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.

Parameters:

receivedTagBuf - the buffer that will contain the received authentication tag

receivedTagOff - the offset of the received authentication tag in the buffer

receivedTagLen - the length in bytes of the received authentication tag in the buffer

requiredTagLen - the required length in bytes of the received authentication tag, usually a constant value

Throws:

CryptoException - with the following reason codes:

• ILLEGAL_USE if doFinal has not been called
• ILLEGAL_VALUE if the tag length is not supported

Since:

3.0.5