Package javacardx.crypto

Class Cipher

  • Direct Known Subclasses:
    AEADCipher, Cipher.OneShot
    public abstract class Cipher
extends Object
    The Cipher class is the abstract base class for Cipher algorithms. Implementations of Cipher algorithms must extend this class and implement all the abstract methods.

    The term "pad" is used in the public key cipher algorithms below to refer to all the operations specified in the referenced scheme to transform the message block into the cipher block size.

    The asymmetric key algorithms encrypt using either a public key (to cipher) or a private key (to sign). In addition they decrypt using the either a private key (to decipher) or a public key (to verify). However, usage of some padding schemes, such as PKCS#1-OAEP, is intended for encryption or decryption operations only, and therefore should be limited to their intended purpose.

    Even if a transaction is in progress, update of intermediate result state in the implementation instance shall not participate in the transaction.

    A tear or card reset event resets an initialized Cipher object to a state where:

    • the key and the mode are the same as when previously initialized via a call to init(Key, byte) or init(Key, byte, byte[], short, short).
    • other initial values are the same default values as after a call to init(Key, byte). For example:
      • AES, DES, triple DES, Korean SEED and SM4 algorithms used in modes requiring an initial vector (like CBC, CFB, CTR, XTS modes) will use 0 for initial vector(IV).
      • RSA algorithm used with the PKCS#1-OAEP scheme, will use default values for the message digest algorithm of the scheme and the message digest algorithm for MGF1 as specified in the description of the related constants.
    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.

    Notes:

    • The byte array containing algorithm specific initialization information can be re-initialized using the init(Key, byte, byte[], short, short) method.
    • For algorithms which support keys with transient key data sets, e.g AES, the Cipher object key becomes uninitialized on clear events associated with the Key object used to initialize the Cipher object.

    • Field Detail

      • ALG_DES_CBC_NOPAD

        public static final byte ALG_DES_CBC_NOPAD
        Cipher algorithm ALG_DES_CBC_NOPAD provides a cipher using DES in CBC mode or triple DES in outer CBC mode, and does not pad input data. If the input data is not (8-byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_CBC, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_CBC_ISO9797_M1

        public static final byte ALG_DES_CBC_ISO9797_M1
        Cipher algorithm ALG_DES_CBC_ISO9797_M1 provides a cipher using DES in CBC mode or triple DES in outer CBC mode, and pads input data according to the ISO 9797 method 1 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_CBC, PAD_ISO9797_M1 constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_CBC_ISO9797_M2

        public static final byte ALG_DES_CBC_ISO9797_M2
        Cipher algorithm ALG_DES_CBC_ISO9797_M2 provides a cipher using DES in CBC mode or triple DES in outer CBC mode, and pads input data according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_CBC, PAD_ISO9797_M2 constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_CBC_PKCS5

        public static final byte ALG_DES_CBC_PKCS5
        Cipher algorithm ALG_DES_CBC_PKCS5 provides a cipher using DES in CBC mode or triple DES in outer CBC mode, and pads input data according to the PKCS#5 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_CBC, PAD_PKCS5 constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_ECB_NOPAD

        public static final byte ALG_DES_ECB_NOPAD
        Cipher algorithm ALG_DES_ECB_NOPAD provides a cipher using DES in ECB mode, and does not pad input data. If the input data is not (8-byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_ECB, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_ECB_ISO9797_M1

        public static final byte ALG_DES_ECB_ISO9797_M1
        Cipher algorithm ALG_DES_ECB_ISO9797_M1 provides a cipher using DES in ECB mode, and pads input data according to the ISO 9797 method 1 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_ECB, PAD_ISO9797_M1 constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_ECB_ISO9797_M2

        public static final byte ALG_DES_ECB_ISO9797_M2
        Cipher algorithm ALG_DES_ECB_ISO9797_M2 provides a cipher using DES in ECB mode, and pads input data according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_ECB, PAD_ISO9797_M2 constants respectively.

        See Also:
        Constant Field Values

      • ALG_DES_ECB_PKCS5

        public static final byte ALG_DES_ECB_PKCS5
        Cipher algorithm ALG_DES_ECB_PKCS5 provides a cipher using DES in ECB mode, and pads input data according to the PKCS#5 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_DES_ECB, PAD_PKCS5 constants respectively.

        See Also:
        Constant Field Values

      • ALG_RSA_ISO14888

        @Deprecated
public static final byte ALG_RSA_ISO14888
        Deprecated.
        This Cipher algorithm ALG_RSA_ISO14888 should not be used. The ISO 14888 algorithms are intended for signatures.
        See Also:
        Constant Field Values

      • ALG_RSA_PKCS1

        public static final byte ALG_RSA_PKCS1
        Cipher algorithm ALG_RSA_PKCS1 provides a cipher using RSA, and pads input data according to the PKCS#1 (v1.5) scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_RSA, PAD_PKCS1 constants respectively.

        Note:

        • This algorithm is only suitable for messages of limited length. The total number of input bytes processed during encryption may not be more than k-11, where k is the RSA key's modulus size in bytes.
        • The encryption block(EB) during encryption with a Public key is built as follows:
            EB = 00 || 02 || PS || 00 || M
                :: M (input bytes) is the plaintext message
                :: PS is an octet string of length k-3-||M|| of pseudo random nonzero octets. The length of PS must be at least 8 octets.
                :: k is the RSA modulus size.
        • The encryption block(EB) during encryption with a Private key (used to compute signatures when the message digest is computed off-card) is built as follows:
            EB = 00 || 01 || PS || 00 || D
                :: D (input bytes) is the DER encoding of the hash computed elsewhere with an algorithm ID prepended if appropriate
                :: PS is an octet string of length k-3-||D|| with value FF. The length of PS must be at least 8 octets.
                :: k is the RSA modulus size.

        See Also:
        Constant Field Values

      • ALG_RSA_ISO9796

        @Deprecated
public static final byte ALG_RSA_ISO9796
        Deprecated.
        This Cipher algorithm ALG_RSA_ISO9796 should not be used. The ISO 9796-1 algorithm was withdrawn by ISO in July 2000.
        See Also:
        Constant Field Values

      • ALG_RSA_NOPAD

        public static final byte ALG_RSA_NOPAD
        Cipher algorithm ALG_RSA_NOPAD provides a cipher using RSA and does not pad input data. If the input data is bounded by incorrect padding bytes while using RSAPrivateCrtKey, incorrect output may result. If the input data is not block aligned or greater than or equal to the modulus, it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_RSA, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_BLOCK_128_CBC_NOPAD

        public static final byte ALG_AES_BLOCK_128_CBC_NOPAD
        Cipher algorithm ALG_AES_BLOCK_128_CBC_NOPAD provides a cipher using AES with block size 128 in CBC mode and does not pad input data. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_CBC, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_BLOCK_128_ECB_NOPAD

        public static final byte ALG_AES_BLOCK_128_ECB_NOPAD
        Cipher algorithm ALG_AES_BLOCK_128_ECB_NOPAD provides a cipher using AES with block size 128 in ECB mode and does not pad input data. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_ECB, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_RSA_PKCS1_OAEP

        public static final byte ALG_RSA_PKCS1_OAEP
        Cipher algorithm ALG_RSA_PKCS1_OAEP provides a cipher using RSA, and pads input data according to the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA-1 as default message digest algorithm for both the scheme and MGF1.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_RSA, PAD_PKCS1_OAEP constants respectively.

        See Also:
        Constant Field Values

      • ALG_KOREAN_SEED_ECB_NOPAD

        public static final byte ALG_KOREAN_SEED_ECB_NOPAD
        Cipher algorithm ALG_KOREAN_SEED_ECB_NOPAD provides a cipher using the Korean SEED algorithm specified in the Korean SEED Algorithm specification provided by KISA, Korea Information Security Agency in ECB mode and does not pad input data. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_KOREAN_SEED_ECB, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_KOREAN_SEED_CBC_NOPAD

        public static final byte ALG_KOREAN_SEED_CBC_NOPAD
        Cipher algorithm ALG_KOREAN_SEED_CBC_NOPAD provides a cipher using the Korean SEED algorithm specified in the Korean SEED Algorithm specification provided by KISA, Korea Information Security Agency in CBC mode and does not pad input data. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_KOREAN_SEED_CBC, PAD_NOPAD constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_BLOCK_192_CBC_NOPAD

        @Deprecated
public static final byte ALG_AES_BLOCK_192_CBC_NOPAD
        Deprecated.
        This Cipher algorithm ALG_AES_BLOCK_192_CBC_NOPAD should not be used. AES algorithms as defined by NIST in the FIPS PUB 197 standard only support a block size of 128 bits.
        See Also:
        Constant Field Values

      • ALG_AES_BLOCK_192_ECB_NOPAD

        @Deprecated
public static final byte ALG_AES_BLOCK_192_ECB_NOPAD
        Deprecated.
        This Cipher algorithm ALG_AES_BLOCK_192_ECB_NOPAD should not be used. AES algorithms as defined by NIST in the FIPS PUB 197 standard only support a block size of 128 bits.
        See Also:
        Constant Field Values

      • ALG_AES_BLOCK_256_CBC_NOPAD

        @Deprecated
public static final byte ALG_AES_BLOCK_256_CBC_NOPAD
        Deprecated.
        This Cipher algorithm ALG_AES_BLOCK_256_CBC_NOPAD should not be used. AES algorithms as defined by NIST in the FIPS PUB 197 standard only support a block size of 128 bits.
        See Also:
        Constant Field Values

      • ALG_AES_BLOCK_256_ECB_NOPAD

        @Deprecated
public static final byte ALG_AES_BLOCK_256_ECB_NOPAD
        Deprecated.
        This Cipher algorithm ALG_AES_BLOCK_256_ECB_NOPAD should not be used. AES algorithms as defined by NIST in the FIPS PUB 197 standard only support a block size of 128 bits.
        See Also:
        Constant Field Values

      • ALG_AES_CBC_ISO9797_M1

        public static final byte ALG_AES_CBC_ISO9797_M1
        Cipher algorithm ALG_AES_CBC_ISO9797_M1 provides a cipher using AES with block size 128 in CBC mode, and pads input data according to the ISO 9797 method 1 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_CBC, PAD_ISO9797_M1 constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_CBC_ISO9797_M2

        public static final byte ALG_AES_CBC_ISO9797_M2
        Cipher algorithm ALG_AES_CBC_ISO9797_M2 provides a cipher using AES with block size 128 in CBC mode, and pads input data according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_CBC, PAD_ISO9797_M2 constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_CBC_PKCS5

        public static final byte ALG_AES_CBC_PKCS5
        Cipher algorithm ALG_AES_CBC_PKCS5 provides a cipher using AES with block size 128 in CBC mode, and pads input data according to the PKCS#5 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_CBC, PAD_PKCS5 constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_ECB_ISO9797_M1

        public static final byte ALG_AES_ECB_ISO9797_M1
        Cipher algorithm ALG_AES_ECB_ISO9797_M1 provides a cipher using AES with block size 128 in ECB mode, and pads input data according to the ISO 9797 method 1 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_ECB, PAD_ISO9797_M1 constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_ECB_ISO9797_M2

        public static final byte ALG_AES_ECB_ISO9797_M2
        Cipher algorithm ALG_AES_ECB_ISO9797_M2 provides a cipher using AES with block size 128 in ECB mode, and pads input data according to the ISO 9797 method 2 (ISO 7816-4, EMV'96) scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_ECB, PAD_ISO9797_M2 constants respectively.

        See Also:
        Constant Field Values

      • ALG_AES_ECB_PKCS5

        public static final byte ALG_AES_ECB_PKCS5
        Cipher algorithm ALG_AES_ECB_PKCS5 provides a cipher using AES with block size 128 in ECB mode, and pads input data according to the PKCS#5 scheme.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_ECB, PAD_PKCS5 constants respectively.

        See Also:
        Constant Field Values

      • CIPHER_AES_CBC

        public static final byte CIPHER_AES_CBC
        Cipher algorithm CIPHER_AES_CBC choice for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method. The cipher algorithm provides a cipher using AES with block size 128 in CBC mode.
        See Also:
        Constant Field Values

      • CIPHER_AES_ECB

        public static final byte CIPHER_AES_ECB
        Cipher algorithm CIPHER_AES_ECB choice for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method. The cipher algorithm provides a cipher using AES with block size 128 in ECB mode.
        See Also:
        Constant Field Values

      • CIPHER_DES_CBC

        public static final byte CIPHER_DES_CBC
        Cipher algorithm CIPHER_DES_CBC choice for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method. The cipher algorithm provides a cipher using DES in CBC mode.
        See Also:
        Constant Field Values

      • CIPHER_DES_ECB

        public static final byte CIPHER_DES_ECB
        Cipher algorithm CIPHER_DES_ECB choice for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method. The cipher algorithm provides a cipher using DES in ECB mode.
        See Also:
        Constant Field Values

      • CIPHER_KOREAN_SEED_CBC

        public static final byte CIPHER_KOREAN_SEED_CBC
        Cipher algorithm CIPHER_KOREAN_SEED_CBC choice for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method. The cipher algorithm provides a cipher using KOREAN_SEED in CBC mode.
        See Also:
        Constant Field Values

      • CIPHER_KOREAN_SEED_ECB

        public static final byte CIPHER_KOREAN_SEED_ECB
        Cipher algorithm CIPHER_KOREAN_SEED_ECB choice for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method. The cipher algorithm provides a cipher using KOREAN_SEED in ECB mode.
        See Also:
        Constant Field Values

      • CIPHER_AES_CTR

        public static final byte CIPHER_AES_CTR
        The CIPHER_AES_CTR constant represents a cipher using AES in counter (CTR) mode.

        It is used for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method and can only be associated with the PAD_NULL padding.

        Since:
        3.1
        See Also:
        Constant Field Values

      • CIPHER_AES_CFB

        public static final byte CIPHER_AES_CFB
        The CIPHER_AES_CFB constant represents a cipher using AES in Cipher Feedback (CFB) mode.

        It is used for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method and can only be associated with the PAD_NULL padding.

        Since:
        3.1
        See Also:
        Constant Field Values

      • CIPHER_AES_XTS

        public static final byte CIPHER_AES_XTS
        The CIPHER_AES_XTS constant represents a cipher using AES in XEX Tweakable Block Cipher with Ciphertext Stealing (XTS) mode as defined in IEEE Std 1619.

        It is used for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method and can only be associated with the PAD_NULL padding.

        Note:

        • The AES-XTS is parsing the provided key as a concatenation of two fields of equal size Key1 and Key2 such that Key = Key1 | Key2.

        Since:
        3.1
        See Also:
        Constant Field Values

      • CIPHER_SM4_ECB

        public static final byte CIPHER_SM4_ECB
        The CIPHER_SM4_ECB constant represents a cipher using SM4 block cipher algorithm in CBC mode with 128-bit input blocks.

        It is used for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method.

        Since:
        3.1
        See Also:
        Constant Field Values

      • CIPHER_SM4_CBC

        public static final byte CIPHER_SM4_CBC
        The CIPHER_SM4_CBC constant represents a cipher using SM4 block cipher algorithm in CBC mode with 128-bit input blocks.

        It is used for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method.

        Since:
        3.1
        See Also:
        Constant Field Values

      • CIPHER_SM2

        public static final byte CIPHER_SM2
        The CIPHER_SM2 constant represents a cipher using SM2 encryption as defined in GM/T 0003.4-2012 (Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 4: Public Key Encryption Algorithm).

        It is used for the cipherAlgorithm parameter of the getInstance(byte, byte, boolean) method and can only be associated with the PAD_NULL padding.

        This constant does not allow for update(byte[], short, short, byte[], short) operations. A CryptoException must be thrown with the value CryptoException.ILLEGAL_USE if the method is invoked.

        Since:
        3.1
        See Also:
        Constant Field Values

      • PAD_ISO9797_1_M1_ALG3

        public static final byte PAD_ISO9797_1_M1_ALG3
        Padding algorithm PAD_ISO9797_1_M1_ALG3 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method. This padding algorithm choice requests padding based on the ISO9797-1 MAC algorithm 3 with method 1.
        See Also:
        Constant Field Values

      • PAD_ISO9797_1_M2_ALG3

        public static final byte PAD_ISO9797_1_M2_ALG3
        Padding algorithm PAD_ISO9797_1_M2_ALG3 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method. This padding algorithm choice requests padding based on the ISO9797-1 MAC algorithm 3 with method 2 (also EMV'96, EMV'2000).
        See Also:
        Constant Field Values

      • PAD_PKCS1_PSS

        public static final byte PAD_PKCS1_PSS
        Padding algorithm PAD_PKCS1_PSS choice for the paddingAlgorithm parameter the Signature.getInstance(byte, byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-PSS scheme (IEEE 1363-2000) with a default salt length equal to the length of the message digest and with the message digest algorithm of MGF1 being the same as the one of the parameter messageDigestAlgorithm. The salt length can be changed when calling Signature.init(Key, byte, byte[], short, short) with a two-byte parameter value.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP

        public static final byte PAD_PKCS1_OAEP
        Padding algorithm PAD_PKCS1_OAEP choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA-1 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA224

        public static final byte PAD_PKCS1_OAEP_SHA224
        Padding algorithm PAD_PKCS1_OAEP_SHA224 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA-224 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA256

        public static final byte PAD_PKCS1_OAEP_SHA256
        Padding algorithm PAD_PKCS1_OAEP_SHA256 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA-256 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA384

        public static final byte PAD_PKCS1_OAEP_SHA384
        Padding algorithm PAD_PKCS1_OAEP_SHA384 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA-384 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA512

        public static final byte PAD_PKCS1_OAEP_SHA512
        Padding algorithm PAD_PKCS1_OAEP_SHA512 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA-512 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA3_224

        public static final byte PAD_PKCS1_OAEP_SHA3_224
        Padding algorithm PAD_PKCS1_OAEP_SHA3_224 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA3-224 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA3_256

        public static final byte PAD_PKCS1_OAEP_SHA3_256
        Padding algorithm PAD_PKCS1_OAEP_SHA3_256 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA3-256 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA3_384

        public static final byte PAD_PKCS1_OAEP_SHA3_384
        Padding algorithm PAD_PKCS1_OAEP_SHA3_384 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA3-384 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_SHA3_512

        public static final byte PAD_PKCS1_OAEP_SHA3_512
        Padding algorithm PAD_PKCS1_OAEP_SHA3_512 choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000) with SHA3-512 as default message digest algorithm for both the scheme and MGF1.
        See Also:
        Constant Field Values

      • PAD_ISO9796

        public static final byte PAD_ISO9796
        Padding algorithm PAD_ISO9796 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a Signature object instance. This padding algorithm choice requests padding based on the ISO/IEC 9796-2 signature scheme 1, signature production function B.6 with a trailer field option 1 and as specified in EMV 3.0 and EMV 4.0
        See Also:
        Constant Field Values

      • PAD_ISO9796_MR

        public static final byte PAD_ISO9796_MR
        Padding algorithm PAD_ISO9796_MR choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a SignatureMessageRecovery object instance. This padding algorithm choice requests padding specified by ISO/IEC 9796-2 for signature scheme 1, signature production function B.6 and giving message recovery with a trailer field option 1 - (also EMV 3.0, EMV 4.0).
        See Also:
        Constant Field Values

      • PAD_ISO9796_MR_SCHEME_2

        public static final byte PAD_ISO9796_MR_SCHEME_2
        Padding algorithm PAD_ISO9796_MR_SCHEME_2 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a SignatureMessageRecovery object instance. This padding algorithm choice requests padding specified by ISO/IEC 9796-2 for signature scheme 2, signature production function B.6 and giving message recovery with a trailer field option 1.
        Since:
        3.1
        See Also:
        Constant Field Values

      • PAD_ISO9796_MR_SCHEME_3

        public static final byte PAD_ISO9796_MR_SCHEME_3
        Padding algorithm PAD_ISO9796_MR_SCHEME_3 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a SignatureMessageRecovery object instance. This padding algorithm choice requests padding specified by ISO/IEC 9796-2 for signature scheme 3, signature production function B.6 and giving message recovery with a trailer field option 1.
        Since:
        3.1
        See Also:
        Constant Field Values

      • PAD_PKCS1_PSS_EXT_PARAMETERS

        public static final byte PAD_PKCS1_PSS_EXT_PARAMETERS
        Padding algorithm PAD_PKCS1_PSS_EXT_PARAMETERS choice for the paddingAlgorithm parameter the Signature.getInstance(byte, byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-PSS scheme (IEEE 1363-2000) with a default salt length equal to the length of the message digest and with a default message digest algorithm for MGF1 being the same as the one of the parameter messageDigestAlgorithm. The salt length and the MGF1 specific digest algorithm parameters can be changed when calling Signature.init(Key, byte, byte[], short, short) with a three-byte parameter value.
        Since:
        3.2
        See Also:
        Constant Field Values

      • PAD_PKCS1_OAEP_EXT_PARAMETERS

        public static final byte PAD_PKCS1_OAEP_EXT_PARAMETERS
        Padding algorithm PAD_PKCS1_OAEP_EXT_PARAMETERS choice for the paddingAlgorithm parameter of the getInstance(byte, byte, boolean) method. This padding algorithm choice requests padding based on the PKCS#1-OAEP scheme (IEEE 1363-2000)) with SHA-1 as default message digest algorithm for both the scheme and MGF1. The digest algorithm of the scheme and the digest algorithm of MGF1 can be changed when calling init(Key, byte, byte[], short, short) with a two-byte parameter value.
        Since:
        3.2
        See Also:
        Constant Field Values

      • PAD_ISO9796_MR_SCHEME_1_OPT_2

        public static final byte PAD_ISO9796_MR_SCHEME_1_OPT_2
        Padding algorithm PAD_ISO9796_MR_SCHEME_1_OPT_2 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a SignatureMessageRecovery object instance. This padding algorithm choice requests padding specified by ISO/IEC 9796-2 for signature scheme 1, signature production function B.6 and giving message recovery with a trailer field option 2.
        Since:
        3.2
        See Also:
        Constant Field Values

      • PAD_ISO9796_MR_SCHEME_2_OPT_2

        public static final byte PAD_ISO9796_MR_SCHEME_2_OPT_2
        Padding algorithm PAD_ISO9796_MR_SCHEME_2_OPT_2 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a SignatureMessageRecovery object instance. This padding algorithm choice requests padding specified by ISO/IEC 9796-2 for signature scheme 2, signature production function B.6 giving message recovery with a trailer field option 2.
        Since:
        3.2
        See Also:
        Constant Field Values

      • PAD_ISO9796_MR_SCHEME_3_OPT_2

        public static final byte PAD_ISO9796_MR_SCHEME_3_OPT_2
        Padding algorithm PAD_ISO9796_MR_SCHEME_3_OPT_2 choice for the paddingAlgorithm parameter of the Signature.getInstance(byte, byte, byte, boolean) method to create a SignatureMessageRecovery object instance. This padding algorithm choice requests padding specified by ISO/IEC 9796-2 for signature scheme 3, signature production function B.6 giving message recovery with a trailer field option 2.
        Since:
        3.2
        See Also:
        Constant Field Values

      • MODE_DECRYPT

        public static final byte MODE_DECRYPT
        Used in init() methods to indicate decryption mode.
        See Also:
        Constant Field Values

      • MODE_ENCRYPT

        public static final byte MODE_ENCRYPT
        Used in init() methods to indicate encryption mode.
        See Also:
        Constant Field Values

      • ALG_AES_CTR

        public static final byte ALG_AES_CTR
        Cipher algorithm ALG_AES_CTR provides a cipher using AES in counter (CTR) mode.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_CTR, PAD_NULL constants respectively.

        Since:
        3.0.5
        See Also:
        Constant Field Values

      • ALG_AES_CFB

        public static final byte ALG_AES_CFB
        Cipher Algorithm ALG_AES_CFB provides a cipher using AES in Cipher Feedback (CFB) mode.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_CFB, PAD_NULL constants respectively.

        Since:
        3.1
        See Also:
        Constant Field Values

      • ALG_AES_XTS

        public static final byte ALG_AES_XTS
        Cipher Algorithm ALG_AES_XTS provides a cipher using AES in XEX Tweakable Block Cipher with Ciphertext Stealing (XTS) mode as defined in IEEE Std 1619.

        To request this algorithm using the getInstance(byte, byte, boolean) method use the CIPHER_AES_XTS, PAD_NULL constants respectively.

        Note:

        • The AES-XTS is parsing the provided key as a concatenation of two fields of equal size Key1 and Key2 such that Key = Key1 | Key2.

        Since:
        3.1
        See Also:
        Constant Field Values

    • Constructor Detail

      • Cipher

        protected Cipher()
        Protected constructor.

    • Method Detail

      • getInstance

        public static final Cipher getInstance​(byte algorithm,
                                       boolean externalAccess)
                                throws CryptoException
        Creates a Cipher object instance of the selected algorithm.
        Parameters:
        algorithm - the desired Cipher algorithm. Valid codes listed in ALG_* constants above, for example, ALG_DES_CBC_NOPAD.
        externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Cipher instance will also be accessed (via a Shareable interface) when the owner of the Cipher instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
        Returns:
        the Cipher object instance of the requested algorithm
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported or shared access mode is not supported.
        See Also:
        getInstance(byte, byte, boolean), getAlgorithm()

      • getInstance

        public static final Cipher getInstance​(byte cipherAlgorithm,
                                       byte paddingAlgorithm,
                                       boolean externalAccess)
                                throws CryptoException
        Creates a Cipher object instance with the selected of the selected raw cipher algorithm and padding algorithm.

        Note:

        • When the padding algorithm is built into the cipher algorithm use the PAD_NULL choice for the padding algorithm.

        Parameters:
        cipherAlgorithm - the desired cipher algorithm. Valid codes listed in CIPHER_* constants in this class e.g. CIPHER_AES_CBC.
        paddingAlgorithm - the desired padding algorithm. Valid codes listed in PAD_* constants in this class e.g. PAD_NULL.
        externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Cipher instance will also be accessed (via a Shareable interface) when the owner of the Cipher instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
        Returns:
        the Cipher object instance of the requested algorithm
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if cipher algorithm or padding algorithm or their combination or the requested shared access mode is not supported.
        Since:
        3.0.4
        See Also:
        getInstance(byte, boolean), getCipherAlgorithm(), getPaddingAlgorithm()

      • 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, Korean SEED and SM4 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.

        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.

      • 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. The 128-bit tweak in XTS mode is an unsigned value with Big-Endian byte order which may contain leading zeroes.
        • Korean SEED algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
        • SM4 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, SM4 in ECB mode, DSA and SM2 algorithms throw CryptoException.ILLEGAL_VALUE.
        • For RSA:
          • Algorithms using the padding scheme PAD_PKCS1_OAEP_EXT_PARAMETERS expect a two-byte parameter value (b1 b2)in bArray where the first byte parameter b1 represents the message digest algorithm of the scheme and the second byte parameter b2 represents the message digest algorithm of MGF1. In both cases, valid codes are listed in ALG_* constants in the MessageDigest class or 0xFF. Notes:
            • if b1 is equal to 0xFF, the digest algorithm of the OAEP scheme must fall back to the default value i.e SHA1
            • if b2 is equal to 0xFF, the MGF1 digest algorithm must fall back to the default value i.e SHA1
          • All other algorithms throw CryptoException.ILLEGAL_VALUE

        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.NO_SUCH_ALGORITHM if the specified algorithm parameters are not supported that is when the specified digest algorithm for the OAEP scheme and/or the specified digest algorithm for MGF1 is/are not supported in case of RSA algorithms with the padding scheme PAD_PKCS1_OAEP_EXT_PARAMETERS.
        • 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.

      • getAlgorithm

        public abstract byte getAlgorithm()
        Gets the Cipher algorithm.
        Returns:
        the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        See Also:
        getInstance(byte, boolean)

      • getCipherAlgorithm

        public abstract byte getCipherAlgorithm()
        Gets the raw cipher algorithm. Pre-defined codes listed in CIPHER_* constants in this class e.g. CIPHER_AES_CBC.
        Returns:
        the raw cipher algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Since:
        3.0.5

      • getPaddingAlgorithm

        public abstract byte getPaddingAlgorithm()
        Gets the padding algorithm. Pre-defined codes listed in PAD_* constants in this class e.g. PAD_NULL.
        Returns:
        the padding algorithm code defined in the Cipher class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        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 a state where:

        • the key and the mode are the same as when previously initialized via a call to init(Key, byte) or init(Key, byte, byte[], short, short).
        • other initial values are the same default values as after a call to init(Key, byte). For example:
          • AES, DES, triple DES, Korean SEED and SM4 algorithms used in modes requiring an initial vector (like CBC, CFB, CTR, XTS modes) will use 0 for initial vector(IV).
          • RSA algorithm used with the PKCS#1-OAEP scheme, will use default values for the message digest algorithm of the scheme and the message digest algorithm for MGF1 as specified in the description of the related constants.
        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. The byte array containing algorithm specific initialization information can be re-initialized using the init(Key, byte, byte[], short, short) method.

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

        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:
        • CryptoException.UNINITIALIZED_KEY if key not initialized.
        • CryptoException.INVALID_INIT if this Cipher object is not initialized.
        • CryptoException.ILLEGAL_USE if one of the following conditions is met:
          • This Cipher algorithm does not pad the message and the message is not block aligned.
          • This Cipher algorithm does not pad the message and no input data has been provided in inBuff or via the update() method.
          • The input message length is not supported or the message value is greater than or equal to the modulus.
          • The decrypted data is not bounded by appropriate padding bytes.

      • 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. The doFinal() method must be invoked to complete processing of any remaining input data buffered by one or more calls to the update() method.

        For symmetric operations, 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 as shown in the following examples:

        • For operations based on stream cipher algorithms (e.g ALG_AES_CTR, CIPHER_AES_CTR, ALG_AES_CFB and CIPHER_AES_CFB), 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.
        • For block aligned algorithms without padding (e.g ALG_AES_BLOCK_128_ECB_NOPAD and ALG_AES_BLOCK_128_CBC_NOPAD), update() must write as much output blocks as can be generated from accumulated and additional input data. Partial input data block must be stored in internal storage until a complete block is accumulated.
        • For block aligned algorithms with padding (e.g ALG_AES_CBC_PKCS5, ALG_AES_CBC_ISO9797_M2), update() must write as much output blocks as can be generated from accumulated and additional input data. Partial input data block must be stored in internal storage until a complete block is accumulated. Besides, on decryption, padding bytes are not written in the output buffer.
        • For AES algorithm in XTS mode (ALG_AES_XTS, CIPHER_AES_XTS), update() must write as much output blocks as can be generated from accumulated and additional input data. Partial input data block must be stored in internal storage until a complete block is accumulated. This algorithm requires the first two blocks before starting generating output data.

        For asymmetric operations, this method only accumulates input data and always returns 0. Accumulated data will only be processed by a call to doFinal. For RSA, accumulated data length cannot exceed the length of the modulus.

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

        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:
        • CryptoException.UNINITIALIZED_KEY if key not initialized.
        • CryptoException.INVALID_INIT if this Cipher object is not initialized.
        • CryptoException.ILLEGAL_USE if the input message length is not supported or, for RSA algorithm, if the accumulated message value is greater than or equal to the modulus.