Package javacardx.crypto

Class 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

    • 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 used in modes requiring an initial vector (like CBC, CFB, CTR, XTS modes) 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 expect a 16-byte parameter value in bArray for the initial vector(IV) in CBC, CFB, CTR mode or for the value of the 128-bit tweak in XTS mode.
        • 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, DSA and SM2 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.
        • AEADCipher in GCM mode will use barray 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
        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 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:
        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 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
        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 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: 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.
          Example: 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:

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

        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
        Returns:
        true if successfully verified, false otherwise
        Throws:
        CryptoException - with the following reason codes:
        Since:
        3.0.5