Class Cipher.OneShot

java.lang.Object
javacardx.crypto.Cipher
javacardx.crypto.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 Details

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

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

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

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

      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.