Package javacardx.crypto

Class Cipher.OneShot

  • Enclosing class:
    Cipher
    public static final class Cipher.OneShot
extends Cipher
    The OneShot class is a specialization of the Cipher class intended to support efficient one-shot ciphering and deciphering operations that may avoid persistent memory writes entirely. The OneShot class uses a delegation model where calls are delegated to an instance of a Cipher-implementing class configured for one-shot use.

    Note:

    • Instances of OneShot are JCRE owned temporary Entry Point Object instances and references to these temporary objects cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
    • The platform must support at least one instance of OneShot. Support for several OneShot instances is platform dependent. To guarantee application code portability, acquiring/opening and then releasing/closing OneShot instances should be performed within tight try-catch-finally blocks (as illustrated in the code sample below) in order to avoid unnecessarily keeping hold of instances and to prevent interleaving invocations - hence enforcing the One-Shot usage pattern. Additionally, any local variable holding a reference to a OneShot instance should be set to null once the instance is closed in order to prevent further use attempts.
    • Upon return from any Applet entry point method, back to the JCRE, and on tear or card reset events any OneShot instances in use are released back to the JCRE.
    • The internal state associated with an instance of OneShot must be bound to the initial calling context (owner context) as to preclude use/calls on that instance from other contexts.
    • Unless otherwise specified, after an instance of OneShot is released back to the JCRE, calls to any of the instance methods of the OneShot class results in an CryptoException being thrown with reason code CryptoException.ILLEGAL_USE.

    The following code shows a typical usage pattern for the OneShot class. 

     ...
 Cipher.OneShot enc = null;
 try {
     enc = Cipher.OneShot.open(Cipher.CIPHER_RSA, Cipher.PAD_PKCS1);
     enc.init(someRSAKey, Cipher.MODE_ENCRYPT);
     enc.doFinal(someInData, (short) 0, (short) someInData.length, encData, (short) 0);
 } catch (CryptoException ce) {
     // Handle exception
 } finally {
     if (enc != null) {
         enc.close();
         enc = null;
     }
 }
 ...

    Since:
    3.0.5

    • Method Detail

      • open

        public static final Cipher.OneShot open​(byte cipherAlgorithm,
                                        byte paddingAlgorithm)
                                 throws CryptoException
        Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected 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 the Cipher class e.g. PAD_NULL.
        Returns:
        the OneShot object instance of the requested algorithm.
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested cipher algorithm or padding algorithm or their combination is not supported.
        SystemException - with the following reason codes:
        • SystemException.NO_RESOURCE if sufficient resources are not available.

      • close

        public void close()
        Closes and releases this JCRE owned temporary instance of the OneShot object for reuse. If this method is called again this method does nothing.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • update

        public short update​(byte[] inBuff,
                    short inOffset,
                    short inLength,
                    byte[] outBuff,
                    short outOffset)
             throws CryptoException
        Always throws a CryptoException. This method is not supported by OneShot.
        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:
        • CryptoException.ILLEGAL_USE always.

      • init

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

        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:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        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 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.

        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:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        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.

      • getAlgorithm

        public byte getAlgorithm()
        Gets the Cipher algorithm.
        Specified by:
        getAlgorithm in class Cipher
        Returns:
        the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        See Also:
        Cipher.getInstance(byte, boolean)

      • getCipherAlgorithm

        public byte getCipherAlgorithm()
        Gets the raw cipher algorithm. Pre-defined codes listed in CIPHER_* constants in this class e.g. CIPHER_AES_CBC.
        Specified by:
        getCipherAlgorithm in class Cipher
        Returns:
        the raw cipher algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getPaddingAlgorithm

        public byte getPaddingAlgorithm()
        Gets the padding algorithm. Pre-defined codes listed in PAD_* constants in this class e.g. PAD_NULL.
        Specified by:
        getPaddingAlgorithm in class Cipher
        Returns:
        the padding algorithm code defined in the Cipher class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • doFinal

        public 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:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        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.