Package uicc.usim.gba_u

Class GBAUSignature

java.lang.Object

uicc.usim.gba_u.GBAUSignature

Direct Known Subclasses:

GBAUSignature.OneShot

public abstract class GBAUSignature
extends Object

The GBAUSignature class is the base class for Signature algorithms. Implementations of Signature algorithms must extend this class and implement all the abstract methods.

The term "pad" is used in the public key signature algorithms below to refer to all the operations specified in the referenced scheme to transform the message digest into the encryption 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. Those keys are 256 bits symmetric keys then all asymmetric key algorithms are not supported.

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 Signature object to the state it was in when previously initialized via a call to init() methods. For algorithms which support keys with transient key data sets, such as AES, Korean SEED and SM3 the GBAUSignature object key becomes uninitialized on clear events associated with the key associated to the appropriate NAF ID (Ks_int_NAF Key) used to initialize the GBAUSignature 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 SM3 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	GBAUSignature.OneShot	The OneShot class is a specialization of the GBAUSignature class intended to support efficient one-shot ciphering and deciphering operations that may avoid persistent memory writes entirely.

Field Summary

Fields

Modifier and Type	Field	Description
static final byte	ALG_HMAC_SM3	HMAC message authentication algorithm ALG_HMAC_SM3 This algorithm generates an HMAC following the steps found in RFC: 2104 using SM3 as the hashing algorithm.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	GBAUSignature()	protected constructor

Method Summary

Modifier and Type	Method	Description
abstract byte	getAlgorithm()	Gets the Signature algorithm.
abstract byte	getCipherAlgorithm()	Gets the cipher algorithm.
static GBAUSignature	getInstance(byte algorithm, boolean externalAccess)	Create an instance of the GBAUSignature class.
static GBAUSignature	getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)	Create an instance of the GBAUSignature with the selected message digest algorithm, cipher algorithm and padding algorithm.
abstract short	getLength()	Returns the short length of the signature data.
abstract byte	getMessageDigestAlgorithm()	Gets the message digest algorithm.
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 GBAUSignature 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 GBAUSignature 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 GBAUSignature 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 GBAUSignature object with the appropriate NAF ID (then Ks_int_NAF Key).
abstract void	setInitialDigest(byte[] initialDigestBuf, short initialDigestOffset, short initialDigestLength, byte[] digestedMsgLenBuf, short digestedMsgLenOffset, short digestedMsgLenLength)	This method initializes the starting hash value in place of the default value used by the GBAUSignature class.
abstract short	sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)	Generates the signature of all/last input data using Ks_int_NAF linked to NAF ID used in init().
abstract short	signPreComputedHash(byte[] hashBuff, short hashOffset, short hashLength, byte[] sigBuff, short sigOffset)	Generates the signature of the precomputed hash data.
abstract void	update(byte[] inBuff, short inOffset, short inLength)	Accumulates a signature of the input data using Ks_int_NAF linked to NAF ID used in init().
abstract boolean	verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)	Verifies the signature of all/last input data against the passed in signature using Ks_int_NAF linked to NAF ID used in init().
abstract boolean	verifyPreComputedHash(byte[] hashBuff, short hashOffset, short hashLength, byte[] sigBuff, short sigOffset, short sigLength)	Verifies the signature of precomputed hash data.

Methods inherited from class java.lang.Object

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

Field Details

ALG_HMAC_SM3

public static final byte ALG_HMAC_SM3

HMAC message authentication algorithm ALG_HMAC_SM3 This algorithm generates an HMAC following the steps found in RFC: 2104 using SM3 as the hashing algorithm. This algorithm does not pad input data. If the input data is not (16 bytes) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

See Also:

• Constant Field Values

Constructor Details

GBAUSignature

protected GBAUSignature()

protected constructor

Method Details

getInstance

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

Create an instance of the GBAUSignature class.
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 Signature class from javacardx.crypto package e.g. ALG_AES_MAC_256_NOPAD.

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

Returns:

the GBAUSignature object instance 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 messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• getAlgorithm()

getInstance

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

Create an instance of the GBAUSignature with the selected message digest algorithm, 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:

messageDigestAlgorithm - the desired message digest algorithm. Valid codes listed in ALG_* constants in the MessageDigest class from javacard.security e.g. ALG_NULL.

cipherAlgorithm - the desired cipher algorithm. Valid codes listed in SIG_CIPHER_* constants in this class or Signature class from javacard.security e.g. SIG_CIPHER_DES_MAC4.

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

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

Returns:

the GBAUSignature object instance 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 algorithm, boolean externalAccess)
• getMessageDigestAlgorithm()
• getCipherAlgorithm()
• getPaddingAlgorithm()

init

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

Initializes the GBAUSignature 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 GBAUSignature 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(), sign() and verify() methods is unspecified.

init() must be used to update the GBAUSignature 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(), sign() and verify() 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 GBAUCipher.MODE_SIGN or GBAUCipher.MODE_VERIFY, see Javacard.security.Signature

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

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 messageDigestAlgorithm, 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)
• update(byte[] inBuff, short inOffset, short inLength)
• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)
• verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)

init

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

Initializes the GBAUSignature 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 GBAUSignature 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(), sign() and verify() methods is unspecified.

init() must be used to update the GBAUSignature 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(), sign() and verify() 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 GBAUCipher.MODE_SIGN or GBAUCipher.MODE_VERIFY, see Javacard.security.Signature

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

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 messageDigestAlgorithm, 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)
• update(byte[] inBuff, short inOffset, short inLength)
• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)
• verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)

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

Initializes the GBAUSignature object with the appropriate NAF ID (then Ks_int_NAF Key) and algorithm specific parameters.

init() must be used to update the GBAUSignature 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(), sign() and verify() 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 GBAUCipher.MODE_SIGN or GBAUCipher.MODE_VERIFY, see Javacard.security.Signature

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

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 messageDigestAlgorithm, 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)
• update(byte[] inBuff, short inOffset, short inLength)
• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)
• verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)

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

Initializes the GBAUSignature object with the appropriate NAF ID (then Ks_int_NAF Key) and algorithm specific parameters.

init() must be used to update the GBAUSignature 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(), sign() and verify() 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 GBAUCipher.MODE_SIGN or GBAUCipher.MODE_VERIFY, see Javacard.security.Signature

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

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 messageDigestAlgorithm, 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)
• update(byte[] inBuff, short inOffset, short inLength)
• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)
• verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)

update

public abstract void update(byte[] inBuff,
 short inOffset,
 short inLength)
                     throws GBAUException

Accumulates a signature of the input data using Ks_int_NAF linked to NAF ID used 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 signing/verifying is not available in one byte array. If all the input data required for the signing/verifying is located in a single byte array, use of the sign() or verify() is recommended. The sign() or verify() method must be invoked to complete processing of any remaining input data buffered by one or more calls to the update() method.

Note:

• 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

Throws:

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

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized.
• CryptoException.ILLEGAL_USE if the message value is not supported by the GBAUSignature algorithm or if a message value consistency check failed.

NullPointerException - if inBuff is null

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

GBAUException

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte messageDigestAlgorithm, 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)
• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)
• verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)

sign

public abstract short sign(byte[] inBuff,
 short inOffset,
 short inLength,
 byte[] sigBuff,
 short sigOffset)
                    throws GBAUException

Generates the signature of all/last input data using Ks_int_NAF linked to NAF ID used in init().

A call to this method also resets this GBAUSignature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another message. In addition, note that the initial vector(IV) used in AES in CBC mode will be reset to 0.

Note:

• AES, Korean SEED and SM3 algorithms in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init() method.

The input and output buffer data may overlap.
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 javacardx.security.SensitiveResult class, if supported by the platform.

Parameters:

inBuff - the input buffer of data to be signed

inOffset - the offset into the input buffer at which to begin signature generation

inLength - the byte length to sign

sigBuff - the output buffer to store signature data

sigOffset - the offset into sigBuff at which to begin signature data

Returns:

number of bytes of signature output in sigBuff.

Throws:

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

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized.
• CryptoException.ILLEGAL_USE if the message value is not supported by the GBAUSignature algorithm or if a message value consistency check failed.

NullPointerException - if inBuff or sigBuff 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 sigOffset would cause access of data outside sigBuff array bounds

GBAUException

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte messageDigestAlgorithm, 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)
• update(byte[] inBuff, short inOffset, short inLength)
• verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength)

verify

public abstract boolean verify(byte[] inBuff,
 short inOffset,
 short inLength,
 byte[] sigBuff,
 short sigOffset,
 short sigLength)
                        throws GBAUException

Verifies the signature of all/last input data against the passed in signature using Ks_int_NAF linked to NAF ID used in init().

A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to verify another message. In addition, note that the initial vector(IV) used in AES in CBC mode will be reset to 0.

Note:

• AES in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init() method.

In addition to returning a boolean 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 verified

inOffset - the offset into the input buffer at which to begin signature generation

inLength - the byte length to sign

sigBuff - the input buffer containing signature data

sigOffset - the offset into sigBuff where signature data begins

sigLength - the byte length of the signature data

Returns:

true if the signature verifies, false otherwise. Note if sigLength is inconsistent with this Signature algorithm, false is returned.

Throws:

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

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized.
• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if this GBAUSignature algorithm does not pad the message and the message is not block aligned.
  • if this GBAUSignature algorithm does not pad the message and no input data has been provided in inBuff or via the update() method.
  • if the message value is not supported by the GBAUSignature algorithm or if a message value consistency check failed.
  • if this GBAUSignature algorithm includes message recovery functionality.

NullPointerException - if inBuff or sigBuff 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 sigOffset or sigLength would cause access of data outside sigBuff array bounds

GBAUException

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte messageDigestAlgorithm, 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)
• update(byte[] inBuff, short inOffset, short inLength)
• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)

getAlgorithm

public abstract byte getAlgorithm()

Gets the Signature algorithm. Pre-defined codes listed in ALG_* constants from javacard.security.Signature class e.g. ALG_DES_MAC4_NOPAD.

Returns:

the algorithm code defined itn the javacard.security.Signature class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.

See Also:

• getInstance(byte algorithm, boolean externalAccess)

getCipherAlgorithm

public abstract byte getCipherAlgorithm()

Gets the cipher algorithm. Pre-defined codes listed in SIG_CIPHER_* constants from javacard.security.Signature class e.g. SIG_CIPHER_DES_MAC4.

Returns:

the cipher algorithm code defined in the javacard.security.Signature class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.

See Also:

• getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)

getLength

public abstract short getLength()
                         throws javacard.security.CryptoException

Returns the short length of the signature data.

Returns:

Returns the short length of the signature data.

Throws:

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

• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized.
• CryptoException.UNINITIALIZED_KEY if key not initialized.

See Also:

• sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)

getMessageDigestAlgorithm

public abstract byte getMessageDigestAlgorithm()

Gets the message digest algorithm. Pre-defined codes listed in ALG_* constants from javacard.security.MessageDigest class e.g. ALG_NULL.

Returns:

the message digest algorithm code defined in the javacard.security.MessageDigest class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.

See Also:

• getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)

getPaddingAlgorithm

public abstract byte getPaddingAlgorithm()

Gets the padding algorithm. Pre-defined codes listed in PAD_* constants from javacardx.crypto.Cipher class e.g. PAD_NULL.

Returns:

the padding algorithm code defined in the javacardx.crypto.Cipher class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.

See Also:

• getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)

setInitialDigest

public abstract void setInitialDigest(byte[] initialDigestBuf,
 short initialDigestOffset,
 short initialDigestLength,
 byte[] digestedMsgLenBuf,
 short digestedMsgLenOffset,
 short digestedMsgLenLength)
                               throws javacard.security.CryptoException

This method initializes the starting hash value in place of the default value used by the GBAUSignature class. The starting hash value represents the previously computed hash (using the same algorithm) of the first part of the message. The remaining bytes of the message must be presented to this GBAUSignature object via the update( and sign() or verify() methods to generate or verify the signature.

Note:

• The maximum allowed value of the byte length of the first part of the message is algorithm specific.
• This method throws an exception if the underlying signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives. These algorithms throw exception - DES, triple DES, AES, HMAC and KOREAN SEED.

Parameters:

initialDigestBuf - input buffer containing the starting hash value representing the previously computed hash (using the same algorithm) of first part of the message

initialDigestOffset - offset into initialDigestBuf array where the starting digest value data begins

initialDigestLength - the length of data in initialDigestBuf array

digestedMsgLenBuf - the byte array containing the number of bytes in the first part of the message that has previously been hashed to obtain the specified starting digest value

digestedMsgLenOffset - the offset within digestedMsgLenBuf where the digested length begins(the bytes starting at this offset for digestedMsgLenLength bytes are concatenated to form the actual digested message length value)

digestedMsgLenLength - byte length of the digested length

Throws:

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

• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized.
• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.ILLEGAL_VALUE if the parameter initialDigestLength is not equal to the intermediate hash value size of the algorithm or if the number of bytes in the first part of the message that has previously been hashed is 0 or not a multiple of the algorithm's block size or greater than the maximum length supported by the algorithm (see ALG_* algorithm descriptions javacard.security.MessageDigest.ALG_SHA).
• CryptoException.ILLEGAL_USE if the Signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives or if this Signature algorithm includes message recovery functionality.

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafOff, short nafLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafOff, short nafLen, 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)
• signPreComputedHash(byte[] hashBuff, short hashOffset, short hashLength, byte[] sigBuff, short sigOffset)
• verifyPreComputedHash(byte[] hashBuff, short hashOffset, short hashLength, byte[] sigBuff, short sigOffset, short sigLength)

signPreComputedHash

public abstract short signPreComputedHash(byte[] hashBuff,
 short hashOffset,
 short hashLength,
 byte[] sigBuff,
 short sigOffset)
                                   throws javacard.security.CryptoException

Generates the signature of the precomputed hash data.
A call to this method also resets this GBAUSignature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another precomputed hash.

Note:

• This method throws an exception if the underlying signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives. These algorithms throw exception - DES, triple DES, AES, HMAC and KOREAN SEED.
• Any data previously accumulated from previous calls to the update method are discarded.

The hash and output buffer data may overlap.
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 javacardx.security.SensitiveResult class, if supported by the platform.

Parameters:

hashBuff - the input buffer of precomputed hash to be signed

hashOffset - the offset into the buffer where the hash begins

hashLength - the byte length of the hash

sigBuff - the output buffer to store signature data

sigOffset - the offset into sigBuff at which to begin signature data

Returns:

number of bytes of signature output in sigBuff

Throws:

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

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized.
• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if the hashLength value is not equal to the length of the algorithm's message digest length.
  • if this GBAUSignature algorithm includes message recovery functionality.
  • if the GBAUSignature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives.

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafOff, short nafLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafOff, short nafLen, 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)
• setInitialDigest(byte[] initialDigestBuf, short initialDigestOffset, short initialDigestLength, byte[] digestedMsgLenBuf, short digestedMsgLenOffset, short digestedMsgLenLength)
• verifyPreComputedHash(byte[] hashBuff, short hashOffset, short hashLength, byte[] sigBuff, short sigOffset, short sigLength)

verifyPreComputedHash

public abstract boolean verifyPreComputedHash(byte[] hashBuff,
 short hashOffset,
 short hashLength,
 byte[] sigBuff,
 short sigOffset,
 short sigLength)
                                       throws javacard.security.CryptoException

Verifies the signature of precomputed hash data. A call to this method also resets this GBAUSignature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to verify another precomputed hash. In addition, note that the initial vector(IV) used in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.

Note:

• This method throws an exception if the underlying signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives. These algorithms throw exception - DES, triple DES, AES, and KOREAN SEED.
• Any data previously accumulated from previous calls to the update method are discarded.

The hash and output buffer data may overlap.
In addition to returning a boolean 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:

hashBuff - the input buffer of precomputed hash to be verified

hashOffset - the offset into the buffer where the hash begins

hashLength - the byte length of the hash

sigBuff - the input buffer containing signature data

sigOffset - the offset into sigBuff where signature data begins

sigLength - the byte length of the signature data

Returns:

true if the signature verifies, false otherwise. Note, if sigLength is inconsistent with this GBAUSignature algorithm, false is returned.

Throws:

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

• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.INVALID_INIT if this GBAUSignature object is not initialized or initialized for signature sign mode.
• CryptoException.ILLEGAL_USE if one of the following conditions is met:
  • if the hashLength value is not equal to the length of the algorithm's message digest length.
  • if this GBAUSignature algorithm includes message recovery functionality.
  • if the GBAUSignature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives.

See Also:

• getInstance(byte algorithm, boolean externalAccess)
• getInstance(byte messageDigestAlgorithm, byte cipherAlgorithm, byte paddingAlgorithm, boolean externalAccess)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafOff, short nafLen)
• init(byte theMode, byte[] adfAID, short adfAIDOff, short adfAIDLen, byte[] nafID, short nafOff, short nafLen, 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)
• setInitialDigest(byte[] initialDigestBuf, short initialDigestOffset, short initialDigestLength, byte[] digestedMsgLenBuf, short digestedMsgLenOffset, short digestedMsgLenLength)
• signPreComputedHash(byte[] hashBuff, short hashOffset, short hashLength, byte[] sigBuff, short sigOffset)