Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacardx.crypto
Class Cipher

    java.lang.Object
      javacardx.crypto.Cipher

Direct Known Subclasses:
  AssymetricCipherImpl, SymmetricCipherImpl

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

A tear or card reset event resets an initialized `Cipher` object to the state it was in when previously initialized via a call to `init()`. For algorithms which support keys with transient key data sets, such as DES, triple DES and AES, the `Cipher` object key becomes uninitialized on clear events associated with the `Key` object used to initialize the `Cipher` object.

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

Note:

- On a tear or card reset event, the AES, DES, and triple DES 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.

Field Summary
`static 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.
`static 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.
`static 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.
`static 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.
`static 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.
`static 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.
`static 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.
`static 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.
`static 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.
`static 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.
`static byte` | `ALG_RSA_ISO14888` Cipher algorithm `ALG_RSA_ISO14888` provides a cipher using RSA, and pads input data according to the ISO 14888 scheme.
`static byte` | `ALG_RSA_ISO9796` This Cipher algorithm `ALG_RSA_ISO9796` should not be used.
`static byte` | `ALG_RSA_NOPAD` Cipher algorithm `ALG_RSA_NOPAD` provides a cipher using RSA and does not pad input data.
`static 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.
`static 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).
`static byte` | `MODE_DECRYPT` Used in `init()` methods to indicate decryption mode.
`static byte` | `MODE_ENCRYPT` Used in `init()` methods to indicate encryption mode.

Constructor Summary
`protected` | `Cipher()` Protected constructor.

Method Summary
`abstract short` | `doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)` Generates encrypted/decrypted output from all/last input data.
`abstract byte` | `getAlgorithm()` Gets the Cipher algorithm.
`static Cipher` | `getInstance(byte algorithm, boolean externalAccess)` Creates a `Cipher` object instance of the selected algorithm.
`abstract void` | `init(Key theKey, byte theMode)` Initializes the `Cipher` object with the appropriate `Key`.
`abstract void` | `init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen)` Initializes the `Cipher` object with the appropriate Key and algorithm specific parameters.
`abstract short` | `update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)` Generates encrypted/decrypted output from input data.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

  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.

  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.

  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.

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

  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.

  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.

  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.

  See Also:
    Constant Field Values

### ALG_RSA_ISO14888

    public static final byte ALG_RSA_ISO14888

  Cipher algorithm `ALG_RSA_ISO14888` provides a cipher using RSA, and pads input data according to the ISO 14888 scheme.

  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.

  Note:

  - This algorithm is only suitable for messages of limited length. The total number of input bytes processed 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

    public static final byte ALG_RSA_ISO9796

  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 it throws `CryptoException` with the reason code `ILLEGAL_USE`.

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

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

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

  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

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

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

  Note:

  - AES, DES, and triple DES algorithms in CBC mode 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.

  Note:

  - DES and triple DES algorithms in CBC mode expect an 8-byte parameter value for the initial vector(IV) in `bArray`.
  - AES algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in `bArray`.
  - AES algorithms in ECB mode, DES algorithms in ECB mode, RSA and DSA 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.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

### 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 and DES algorithms will be reset to 0.

  Notes:

  - When using block-aligned data (multiple of block size), if the input buffer, `inBuff` and the output buffer, `outBuff` are the same array, then the output data area must not partially overlap the input data area such that the input data is modified before it is used; if `inBuff==outBuff` and
    `inOffset < outOffset < inOffset+inLength`, incorrect output may result.
  - When non-block aligned data is presented as input data, no amount of input and output buffer data overlap is allowed; if `inBuff==outBuff` and
    `outOffset < inOffset+inLength`, incorrect output may result.
  - AES, DES, and triple DES 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 `ArrayIndexOutOfBoundException`, `outBuff` may be partially modified.

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

  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.

  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/decryptedv
    `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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD