Package uicc.usim.gba_u

Class GBAUCipher

java.lang.Object

uicc.usim.gba_u.GBAUCipher

Direct Known Subclasses:

GBAUCipher.OneShot

public abstract class GBAUCipher
extends Object

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

Ks_int_NAF keys, internal keys generated during GBA_U process (see 3GPP TS 31.102 and 3GPP TS 33.220), are the only ones used in this class.
Ks_int_NAF keys are 256 bits symmetric keys then all asymmetric key algorithms are not supported.

A tear or card reset event resets an initialized GBAUCipher 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, AES, and Korean SEED the GBAUCipher object key becomes uninitialized on clear events associated with the key with the appropriate NAF ID (the Ks_int_NAF key) used to initialize the GBAUCipher 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, Korean SEED and SM4 algorithms in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init() methods.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	GBAUCipher.OneShot	The OneShot class is a specialization of the GBAUCipher class intended to support efficient one-shot ciphering and deciphering operations that may avoid persistent memory writes entirely.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	GBAUCipher()	Protected constructor

Method Summary

Modifier and Type	Method	Description
abstract short	doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)	Generates encrypted/decrypted output from all/last input data using Ks_int_NAF linked to NAF ID given in init().
abstract byte	getAlgorithm()	Gets the cipher algorithm.
abstract byte	getCipherAlgorithm()	Gets the raw cipher algorithm.
static GBAUCipher	getInstance(byte algorithm, boolean externalAccess)	Create an instance of the GBAUCipher class with the selected cipher algorithm and padding algorithm.
static GBAUCipher	getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)	Create an instance of the GBAUCipher class.
abstract byte	getPaddingAlgorithm()	Gets the padding algorithm.
abstract void	init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen)	Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF key).
abstract void	init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen)	Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF key) and algorithm specific parameters.
abstract void	init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength)	Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF key) and algorithm specific parameters.
abstract void	init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength)	Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF key).
abstract short	update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)	Continues a multiple-part encryption or decryption operation, processing additional input data using Ks_int_NAF linked to NAF ID given in init().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

GBAUCipher

protected GBAUCipher()

Protected constructor

Method Details

getInstance

public static GBAUCipher getInstance(byte algorithm,
 boolean externalAccess)
                              throws javacard.security.CryptoException

Create an instance of the GBAUCipher class with the selected cipher algorithm and padding algorithm.
Ks_int_NAF keys, internal keys generated during GBA_U process (see 3GPP TS 31.102 and 3GPP TS 33.220), are the only ones used in this class.
Ks_int_NAF keys are 256 bits symmetric keys then all asymmetric key algorithms are not supported.

Parameters:

algorithm - the desired algorithm. Valid codes listed in ALG_* constants in this class or Cipher class from javacardx.crypto package e.g. ALG_AES_BLOCK_256_CBC_NOPAD.

externalAccess - true indicates that the instance will be shared among multiple applet instances and that the GBAUCipher instance will also be accessed (via a Shareable interface) when the owner of the GBAUCipher instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

Returns:

GBAUCipher object of the requested algorithm;

Throws:

javacard.security.CryptoException - with the following reason codes:

• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported.

See Also:

• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAcces)
• getAlgorithm()

getInstance

public static GBAUCipher getInstance(byte cipherAlgorithm,
 byte paddingAlgorithm,
 boolean externalAccess)
                              throws javacard.security.CryptoException

Create an instance of the GBAUCipher class.

Parameters:

cipherAlgorithm - the desired cipher algorithm. Valid codes listed in CIPHER_* constants in this class or Cipher class from javacardx.crypto package e.g. CIPHER_AES_CBC.

paddingAlgorithm - the desired padding algorithm. Valid codes listed in PAD_* constants in this class or Cipher class from javacardx.crypto package e.g. PAD_NULL.

externalAccess - true indicates that the instance will be shared among multiple applet instances and that the GBAUCipher instance will also be accessed (via a Shareable interface) when the owner of the GBAUCipher instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

Returns:

GBAUCipher object of the requested algorithm;

Throws:

javacard.security.CryptoException - with the following reason codes:

• CryptoException.NO_SUCH_ALGORITHM if the at least one requested algorithm is not supported.

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getCipherAlgorithm()
• getPaddingAlgorithm()

init

public abstract void init(byte theMode,
 byte[] adfAID,
 short adfAIDOff,
 short adfAIDLen,
 byte[] nafID,
 short nafIDOff,
 short nafIDLen)
                   throws GBAUException,
javacard.security.CryptoException

Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF 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 GBAUCipher object with a new key / NAF ID. If the Ks_int_NAF key is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified.

If init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen) is used, the key length is implicitly selected:

• AES will use the Ks_int_NAF on 256 bits.
• Korean SEED will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.
• SM4 will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.

Use init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength) for different key length.

Parameters:

theMode - one of javacardx.crypto.Cipher.MODE_DECRYPT or javacardx.crypto.Cipher.MODE_ENCRYPT

adfAID - byte array containing the value of complete ADF AID to use (e.g. USIM, ISIM), partial AID is not supported

adfAIDOff - offset within adfAID where the ADF AID value begins

adfAIDLen - byte length of ADF AID value

nafID - byte array containing the value of NAF ID

nafIDOff - offset within nafID where the NAF ID value begins

nafIDLen - byte length of NAF ID value

Throws:

GBAUException - with the following reason codes:

• GBA_U_BOOTSTRAP_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U Bootstrap procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_NAF_DERIVATION_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U NAF derivation procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_UNALLOWED_ACCESS if applet is not allowed to use API, see 3GPP TS 31.130 for detail on access condition required
• GBA_U_INCORRECT_NAF_ID if applet provides a NAF ID (through nafID, nafIDOff and nafIDLen) which is not defined in its access condition, see 3GPP TS 31.130 for detail on access condition and NAF ID association
• GBA_U_INCORRECT_ADF_AID if applet provides a ADF AID (through adfAID, adfAIDOff and adfAIDLen) which does not supported GBA_U computation

javacard.security.CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if theMode option is an undefined value.
  • if key size is incompatible with algorithm defined in getInstance().

NullPointerException - if adfAID or nafID is null

ArrayIndexOutOfBoundsException - if the check operation on adfAIDOff or adfAIDLen would cause access of data outside adfAID array bounds

ArrayIndexOutOfBoundsException - if the check operation on nafIDOff or nafIDLen would cause access of data outside nafID array bounds

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength)

init

public abstract void init(byte theMode,
 byte[] adfAID,
 short adfAIDOff,
 short adfAIDLen,
 byte[] nafID,
 short nafIDOff,
 short nafIDLen,
 short keyLength)
                   throws GBAUException,
javacard.security.CryptoException

Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF 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 GBAUCipher object with a new key / NAF ID. If the Ks_int_NAF key is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified.

Depending on keyLength parameter the key is retrieved from Ks_int_NAF as follows:

• LENGTH_AES_128 will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.
• LENGTH_AES_192 will use the 192 left most significant bits of the Ks_int_NAF 256 bits key.
• LENGTH_AES_256 will use all the 256 bits of the Ks_int_NAF 256 bits key.
• LENGTH_KOREAN_SEED_128 Korean SEED will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.
• LENGTH_SM4 will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.

Parameters:

theMode - one of javacardx.crypto.Cipher.MODE_DECRYPT or javacardx.crypto.Cipher.MODE_ENCRYPT

adfAID - byte array containing the value of complete ADF AID to use (e.g. USIM, ISIM), partial AID is not supported

adfAIDOff - offset within adfAID where the ADF AID value begins

adfAIDLen - byte length of ADF AID value

nafID - byte array containing the value of NAF ID

nafIDOff - offset within nafID where the NAF ID value begins

nafIDLen - byte length of NAF ID value

keyLength - the key size in bits. The valid key bit length is key type dependent. Some common key lengths are listed in LENGTH_* constants in the KeyBuilder class from javacard.security e.g. LENGTH_AES_128.

Throws:

GBAUException - with the following reason codes:

• GBA_U_BOOTSTRAP_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U Bootstrap procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_NAF_DERIVATION_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U NAF derivation procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_UNALLOWED_ACCESS if applet is not allowed to use API, see 3GPP TS 31.130 for detail on access condition required
• GBA_U_INCORRECT_NAF_ID if applet provides a NAF ID (through nafID, nafIDOff and nafIDLen) which is not defined in its access condition, see 3GPP TS 31.130 for detail on access condition and NAF ID association
• GBA_U_INCORRECT_ADF_AID if applet provides a ADF AID (through adfAID, adfAIDOff and adfAIDLen) which does not supported GBA_U computation

javacard.security.CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if theMode option is an undefined value.
  • if keyLength is incompatible with algorithm defined in getInstance().

NullPointerException - if adfAID or nafID is null

ArrayIndexOutOfBoundsException - if the check operation on adfAIDOff or adfAIDLen would cause access of data outside adfAID array bounds

ArrayIndexOutOfBoundsException - if the check operation on nafIDOff or nafIDLen would cause access of data outside nafID array bounds

Since:

1.2

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength)

init

public abstract void init(byte theMode,
 byte[] adfAID,
 short adfAIDOff,
 short adfAIDLen,
 byte[] nafID,
 short nafIDOff,
 short nafIDLen,
 byte[] bArray,
 short bOff,
 short bLen)
                   throws GBAUException,
javacard.security.CryptoException

Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF key) and algorithm specific parameters.
init() must be used to update the GBAUCipher object with a new key / NAF ID. If the Ks_int_NAF key is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified.

If init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen) is used, the key length is implicitly selected:

• AES will use the Ks_int_NAF on 256 bits.
• Korean SEED will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.
• SM4 will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.

Use init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength) for different key length.

Parameters:

theMode - one of javacardx.crypto.Cipher.MODE_DECRYPT or javacardx.crypto.Cipher.MODE_ENCRYPT

adfAID - byte array containing the value of complete ADF AID to use (e.g. USIM, ISIM), partial AID is not supported

adfAIDOff - offset within adfAID where the ADF AID value begins

adfAIDLen - byte length of ADF AID value

nafID - byte array containing the value of NAF ID

nafIDOff - offset within nafID where the NAF ID value begins

nafIDLen - byte length of NAF ID value

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:

GBAUException - with the following reason codes:

• GBA_U_BOOTSTRAP_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U Bootstrap procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_NAF_DERIVATION_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U NAF derivation procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_UNALLOWED_ACCESS if applet is not allowed to use API, see 3GPP TS 31.130 for detail on access condition required
• GBA_U_INCORRECT_NAF_ID if applet provides a NAF ID (through nafID, nafIDOff and nafIDLen) which is not defined in its access condition, see 3GPP TS 31.130 for detail on access condition and NAF ID association
• GBA_U_INCORRECT_ADF_AID if applet provides a ADF AID (through adfAID, adfAIDOff and adfAIDLen) which does not supported GBA_U computation

javacard.security.CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if theMode option is an undefined value.
  • if key size is incompatible with algorithm defined in getInstance().

NullPointerException - if adfAID, nafID or bArray is null

ArrayIndexOutOfBoundsException - if the check operation on adfAIDOff or adfAIDLen would cause access of data outside adfAID array bounds

ArrayIndexOutOfBoundsException - if the check operation on nafIDOff or nafIDLen would cause access of data outside nafID array bounds

ArrayIndexOutOfBoundsException - if the check operation on bOff or bLen would cause access of data outside bArray array bounds

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength)

init

public abstract void init(byte theMode,
 byte[] adfAID,
 short adfAIDOff,
 short adfAIDLen,
 byte[] nafID,
 short nafIDOff,
 short nafIDLen,
 byte[] bArray,
 short bOff,
 short bLen,
 short keyLength)
                   throws GBAUException,
javacard.security.CryptoException

Initializes the GBAUCipher object with the appropriate NAF ID (then Ks_int_NAF key) and algorithm specific parameters.
init() must be used to update the GBAUCipher object with a new key / NAF ID. If the Ks_int_NAF key is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified.

Depending on keyLength parameter the key is retrieved from Ks_int_NAF as follows:

• LENGTH_AES_128 will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.
• LENGTH_AES_192 will use the 192 left most significant bits of the Ks_int_NAF 256 bits key.
• LENGTH_AES_256 will use all the 256 bits of the Ks_int_NAF 256 bits key.
• LENGTH_KOREAN_SEED_128 Korean SEED will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.
• LENGTH_SM4 will use the 128 left most significant bits of the Ks_int_NAF 256 bits key.

Parameters:

theMode - one of javacardx.crypto.Cipher.MODE_DECRYPT or javacardx.crypto.Cipher.MODE_ENCRYPT

adfAID - byte array containing the value of complete ADF AID to use (e.g. USIM, ISIM), partial AID is not supported

adfAIDOff - offset within adfAID where the ADF AID value begins

adfAIDLen - byte length of ADF AID value

nafID - byte array containing the value of NAF ID

nafIDOff - offset within nafID where the NAF ID value begins

nafIDLen - byte length of NAF ID value

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

keyLength - the key size in bits. The valid key bit length is key type dependent. Some common key lengths are listed in LENGTH_* constants in the KeyBuilder class from javacard.security e.g. LENGTH_AES_128.

Throws:

GBAUException - with the following reason codes:

• GBA_U_BOOTSTRAP_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U Bootstrap procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_NAF_DERIVATION_NOT_DONE if Ks_int_NAF is not availaible linked to GBA_U NAF derivation procedure was not done (see 3GPP TS 31.102 and 3GPP TS 33.220)
• GBA_U_UNALLOWED_ACCESS if applet is not allowed to use API, see 3GPP TS 31.130 for detail on access condition required
• GBA_U_INCORRECT_NAF_ID if applet provides a NAF ID (through nafID, nafIDOff and nafIDLen) which is not defined in its access condition, see 3GPP TS 31.130 for detail on access condition and NAF ID association
• GBA_U_INCORRECT_ADF_AID if applet provides a ADF AID (through adfAID, adfAIDOff and adfAIDLen) which does not supported GBA_U computation

javacard.security.CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if theMode option is an undefined value.
  • if keyLength is incompatible with algorithm defined in getInstance().

NullPointerException - if adfAID, nafID or bArray is null

ArrayIndexOutOfBoundsException - if the check operation on adfAIDOff or adfAIDLen would cause access of data outside adfAID array bounds

ArrayIndexOutOfBoundsException - if the check operation on nafIDOff or nafIDLen would cause access of data outside nafID array bounds

ArrayIndexOutOfBoundsException - if the check operation on bOff or bLen would cause access of data outside bArray array bounds

Since:

1.2

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen)

update

public abstract short update(byte[] inBuff,
 short inOffset,
 short inLength,
 byte[] outBuff,
 short outOffset)
                      throws javacard.security.CryptoException

Continues a multiple-part encryption or decryption operation, processing additional input data using Ks_int_NAF linked to NAF ID given in init().

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.

Note:

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

javacard.security.CryptoException - with the following reason codes:

• CryptoException.UNINITIALIZED_KEY if the key (Ks_int_NAF key) is uninitialized.
• CryptoException.INVALID_INIT if this GBAUCipher object is not initialized.
• CryptoException.ILLEGAL_USE if the input message length is not supported or the message value is greater than or equal to the modulus.

NullPointerException - if inBuff or outBuff is null

ArrayIndexOutOfBoundsException - if the check operation on inOffset or inLength would cause access of data outside inBuff array bounds

ArrayIndexOutOfBoundsException - if the check operation on outOffset would cause access of data outside outBuff array bounds

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength)
• doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)

doFinal

public abstract short doFinal(byte[] inBuff,
 short inOffset,
 short inLength,
 byte[] outBuff,
 short outOffset)
                       throws javacard.security.CryptoException

Generates encrypted/decrypted output from all/last input data using Ks_int_NAF linked to NAF ID given in init(). 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() methods. 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() methods) more data. In addition, note that the initial vector(IV) used in AES, DES, Korean SEED and SM4 algorithms will be reset to 0.

Note:

• 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, triple DES, Korean SEED and SM4 algorithms in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init() methods.
• 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.

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:

javacard.security.CryptoException - with the following reason codes:

• CryptoException.UNINITIALIZED_KEY if the key (Ks_int_NAF key) is uninitialized.
• CryptoException.INVALID_INIT if this GBAUCipher object is not initialized.
• CryptoException.ILLEGAL_USE if one of the following conditions is met
  • This GBAUCipher algorithm does not pad the message and the message is not block aligned.
  • This GBAUCipher algorithm does not pad the message and no input data has been provided in inBuff or via the update() method.
  • The decrypted data is not bounded by appropriate padding bytes.

NullPointerException - if inBuff or outBuff is null

ArrayIndexOutOfBoundsException - if the check operation on inOffset or inLength would cause access of data outside inBuff array bounds

ArrayIndexOutOfBoundsException - if the check operation on outOffset would cause access of data outside outBuff array bounds

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, short keyLength)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafIDOff, short nafIDLen, byte[] bArray, short bOff, short bLen, short keyLength)
• update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)

getAlgorithm

public abstract byte getAlgorithm()

Gets the cipher algorithm. Pre-defined codes listed in ALG_* constants in javacardx.crypto.Cipher e.g. ALG_AES_BLOCK_128_CBC_NOPAD.

Returns:

the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAcces)

getCipherAlgorithm

public abstract byte getCipherAlgorithm()

Gets the raw cipher algorithm. Pre-defined codes listed in CIPHER_* constants in javacardx.crypto.Cipher 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.

See Also:

• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAcces)

getPaddingAlgorithm

public abstract byte getPaddingAlgorithm()

Gets the padding algorithm. Pre-defined codes listed in PAD_* constants in javacardx.crypto.Cipher 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.

See Also:

• getInstance(byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAcces)