com.licel.jcardsim.crypto

Class AuthenticatedSymmetricCipherImpl

java.lang.Object

javacardx.crypto.Cipher

javacardx.crypto.AEADCipher

com.licel.jcardsim.crypto.AuthenticatedSymmetricCipherImpl

public class AuthenticatedSymmetricCipherImpl
extends javacardx.crypto.AEADCipher

Nested Class Summary

Nested classes/interfaces inherited from class javacardx.crypto.Cipher

javacardx.crypto.Cipher.OneShot

Field Summary

Fields inherited from class javacardx.crypto.AEADCipher

ALG_AES_CCM, ALG_AES_GCM, CIPHER_AES_CCM, CIPHER_AES_GCM

Fields inherited from class javacardx.crypto.Cipher

ALG_AES_BLOCK_128_CBC_NOPAD, ALG_AES_BLOCK_128_ECB_NOPAD, ALG_AES_BLOCK_192_CBC_NOPAD, ALG_AES_BLOCK_192_ECB_NOPAD, ALG_AES_BLOCK_256_CBC_NOPAD, ALG_AES_BLOCK_256_ECB_NOPAD, ALG_AES_CBC_ISO9797_M1, ALG_AES_CBC_ISO9797_M2, ALG_AES_CBC_PKCS5, ALG_AES_CTR, ALG_AES_ECB_ISO9797_M1, ALG_AES_ECB_ISO9797_M2, ALG_AES_ECB_PKCS5, ALG_DES_CBC_ISO9797_M1, ALG_DES_CBC_ISO9797_M2, ALG_DES_CBC_NOPAD, ALG_DES_CBC_PKCS5, ALG_DES_ECB_ISO9797_M1, ALG_DES_ECB_ISO9797_M2, ALG_DES_ECB_NOPAD, ALG_DES_ECB_PKCS5, ALG_KOREAN_SEED_CBC_NOPAD, ALG_KOREAN_SEED_ECB_NOPAD, ALG_RSA_ISO14888, ALG_RSA_ISO9796, ALG_RSA_NOPAD, ALG_RSA_PKCS1, ALG_RSA_PKCS1_OAEP, CIPHER_AES_CBC, CIPHER_AES_ECB, CIPHER_DES_CBC, CIPHER_DES_ECB, CIPHER_KOREAN_SEED_CBC, CIPHER_KOREAN_SEED_ECB, CIPHER_RSA, MODE_DECRYPT, MODE_ENCRYPT, PAD_ISO9796, PAD_ISO9796_MR, PAD_ISO9797_1_M1_ALG3, PAD_ISO9797_1_M2_ALG3, PAD_ISO9797_M1, PAD_ISO9797_M2, PAD_NOPAD, PAD_NULL, PAD_PKCS1, PAD_PKCS1_OAEP, PAD_PKCS1_OAEP_SHA224, PAD_PKCS1_OAEP_SHA256, PAD_PKCS1_OAEP_SHA3_224, PAD_PKCS1_OAEP_SHA3_256, PAD_PKCS1_OAEP_SHA3_384, PAD_PKCS1_OAEP_SHA3_512, PAD_PKCS1_OAEP_SHA384, PAD_PKCS1_OAEP_SHA512, PAD_PKCS1_PSS, PAD_PKCS5, PAD_RFC2409

Constructor Summary

Constructors

Constructor and Description
AuthenticatedSymmetricCipherImpl(byte algorithm)

Method Summary

Modifier and Type	Method and Description
short	doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) Generates encrypted/decrypted output from all/last input data.
byte	getAlgorithm() Gets the Cipher algorithm.
byte	getCipherAlgorithm() Gets the raw cipher algorithm.
byte	getPaddingAlgorithm() Gets the padding algorithm.
void	init(javacard.security.Key theKey, byte theMode) Initializes the Cipher object with the appropriate Key.
void	init(javacard.security.Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) Initializes the Cipher object with the appropriate Key and algorithm specific parameters.
void	init(javacard.security.Key theKey, byte theMode, byte[] nonceBuf, short nonceOff, short nonceLen, short adataLen, short messageLen, short tagSize) Initializes this Cipher instance to encrypt or decrypt a with the given key, nonce, AAD size and message size.
short	retrieveTag(byte[] tagBuf, short tagOff, short tagLen) Retrieves tagLen bytes from the calculated authentication tag.
short	update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) Generates encrypted/decrypted output from input data.
void	updateAAD(byte[] aadBuf, short aadOff, short aadLen) Continues a multi-part update of the Additional Associated Data (AAD) that will be verified by the authentication tag.
boolean	verifyTag(byte[] receivedTagBuf, short receivedTagOff, short receivedTagLen, short requiredTagLen) Verifies the authentication tag using the number of bits set in requiredTagLen bits.

Methods inherited from class javacardx.crypto.Cipher

getInstance, getInstance

Methods inherited from class java.lang.Object

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

Constructor Detail

AuthenticatedSymmetricCipherImpl

public AuthenticatedSymmetricCipherImpl(byte algorithm)

Method Detail

getAlgorithm

public byte getAlgorithm()

Gets the Cipher algorithm.

Specified by:

getAlgorithm in class javacardx.crypto.Cipher

Returns:

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

getCipherAlgorithm

public byte getCipherAlgorithm()

Gets the raw cipher algorithm. Pre-defined codes listed in CIPHER_* constants in this class e.g. CIPHER_AES_CBC.

Specified by:

getCipherAlgorithm in class javacardx.crypto.Cipher

Returns:

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

getPaddingAlgorithm

public byte getPaddingAlgorithm()

Gets the padding algorithm. Pre-defined codes listed in PAD_* constants in this class e.g. PAD_NULL.

Specified by:

getPaddingAlgorithm in class javacardx.crypto.Cipher

Returns:

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

init

public void init(javacard.security.Key theKey,
                 byte theMode)
          throws javacard.security.CryptoException

Initializes the Cipher object with the appropriate Key. This method should be used for algorithms which do not need initialization parameters or use default parameter values. init() must be used to update the Cipher object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified. The Key is checked for consistency with the Cipher algorithm. For example, the key type must be matched. For elliptic curve algorithms, the key must represent a valid point on the curve's domain parameters. Additional key component/domain parameter strength checks are implementation specific. Note:

• AES, DES, triple DES and Korean SEED algorithms in CBC mode will use 0 for initial vector(IV) if this method is used.
• For optimal performance, when the theKey parameter is a transient key, the implementation should, whenever possible, use transient space for internal storage.
• AEADCipher in GCM mode will use 0 for initial vector(IV) if this method is used.

Specified by:

init in class javacardx.crypto.AEADCipher

Parameters:

theKey - the key object to use for encrypting or decrypting

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

Throws:

javacard.security.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.
• CryptoException.INVALID_INIT if this method is called for an offline mode of encryption

init

public void init(javacard.security.Key theKey,
                 byte theMode,
                 byte[] bArray,
                 short bOff,
                 short bLen)
          throws javacard.security.CryptoException

Initializes the Cipher object with the appropriate Key and algorithm specific parameters. init() must be used to update the Cipher object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified. The Key is checked for consistency with the Cipher algorithm. For example, the key type must be matched. For elliptic curve algorithms, the key must represent a valid point on the curve's domain parameters. Additional key component/domain parameter strength checks are implementation specific. Note:

• DES and triple DES algorithms in CBC mode expect an 8-byte parameter value for the initial vector(IV) in bArray.
• AES algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
• Korean SEED algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
• AES algorithms in ECB mode, DES algorithms in ECB mode, Korean SEED algorithm in ECB mode, RSA and DSA algorithms throw CryptoException.ILLEGAL_VALUE.
• For optimal performance, when the theKey parameter is a transient key, the implementation should, whenever possible, use transient space for internal storage.

Specified by:

init in class javacardx.crypto.AEADCipher

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:

javacard.security.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.
• CryptoException.INVALID_INIT if this method is called for an offline mode of encryption

init

public void init(javacard.security.Key theKey,
                 byte theMode,
                 byte[] nonceBuf,
                 short nonceOff,
                 short nonceLen,
                 short adataLen,
                 short messageLen,
                 short tagSize)
          throws javacard.security.CryptoException

Initializes this Cipher instance to encrypt or decrypt a with the given key, nonce, AAD size and message size. This method should only be called for offline cipher mode encryption such as Cipher#ALG_AES_CCM. In offline cipher mode encryption the length of the authentication data, message size and authentication tag must be known in advance.

Specified by:

init in class javacardx.crypto.AEADCipher

Parameters:

theKey - the key object to use for encrypting or decrypting

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

nonceBuf - a buffer holding the nonce

nonceOff - the offset in the buffer of the nonce

nonceLen - the length in the buffer of the nonce

adataLen - the length of the authenticated data as presented in the updateAAD method

messageLen - the length of the message as presented in the update and doFinal methods

tagSize - the size in bytes of the authentication tag

Throws:

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

• CryptoException.ILLEGAL_VALUE if any of the values are outside the accepted range
• CryptoException.UNINITIALIZED_KEY if theKey instance is uninitialized.
• CryptoException.INVALID_INIT if this method is called for an online mode of encryption

See Also:

AEADCipher.init(Key, byte, byte[], short, short, short, short, short)

updateAAD

public void updateAAD(byte[] aadBuf,
                      short aadOff,
                      short aadLen)
               throws javacard.security.CryptoException

Continues a multi-part update of the Additional Associated Data (AAD) that will be verified by the authentication tag. The data is not included with the ciphertext by this method.

Specified by:

updateAAD in class javacardx.crypto.AEADCipher

Parameters:

aadBuf - the buffer containing the AAD data

aadOff - the offset of the AAD data in the buffer

aadLen - the length in bytes of the AAD data in the buffer

Throws:

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

• ILLEGAL_USE if updating the AAD value is conflicting with the state of this cipher
• ILLEGAL_VALUE for CCM if the AAD size is different from the AAD size given in the initial block used as IV

update

public short update(byte[] inBuff,
                    short inOffset,
                    short inLength,
                    byte[] outBuff,
                    short outOffset)
             throws javacard.security.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. SensitiveResult class, if supported by the platform.

Specified by:

update in class javacardx.crypto.AEADCipher

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.INVALID_INIT if this Cipher object is not initialized.
• CryptoException.UNINITIALIZED_KEY if key not initialized.
• CryptoException.ILLEGAL_USE
• for CCM if AAD is not provided while it is indicated in the initial block used as IV
• for CCM if the payload exceeds the payload size given in the initial block used as IV

doFinal

public 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. This method must be invoked to complete a cipher operation. This method processes any remaining input data buffered by one or more calls to the update() method as well as input data supplied in the inBuff parameter. A call to this method also resets this Cipher object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to encrypt or decrypt (depending on the operation mode that was specified in the call to init()) more data. In addition, note that the initial vector(IV) used in AES, DES and Korean SEED algorithms will be reset to 0.

Specified by:

doFinal in class javacardx.crypto.AEADCipher

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:

• INVALID_INIT if this Cipher object is not initialized.
• UNINITIALIZED_KEY if key not initialized.
• ILLEGAL_USE
• for CCM if all Additional Authenticated Data (AAD) was not provided
• for CCM if the total message size provided is not identical to the messageLen parameter given in the init method

retrieveTag

public short retrieveTag(byte[] tagBuf,
                         short tagOff,
                         short tagLen)
                  throws javacard.security.CryptoException

Retrieves tagLen bytes from the calculated authentication tag. Depending on the algorithm, only certain tag lengths may be supported. Note: This method may only be called for MODE_ENCRYPT after doFinal has been called. In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

Specified by:

retrieveTag in class javacardx.crypto.AEADCipher

Parameters:

tagBuf - the buffer that will contain the authentication tag

tagOff - the offset of the authentication tag in the buffer

tagLen - the length in bytes of the authentication tag in the buffer

Returns:

the tag length, as given by tagLen (for convenience)

Throws:

javacard.security.CryptoException - with the following reason codes

• ILLEGAL_USE if doFinal has not been called
• ILLEGAL_VALUE if the tag length is not supported

verifyTag

public boolean verifyTag(byte[] receivedTagBuf,
                         short receivedTagOff,
                         short receivedTagLen,
                         short requiredTagLen)
                  throws javacard.security.CryptoException

Verifies the authentication tag using the number of bits set in requiredTagLen bits. Depending on the algorithm, only certain tag lengths may be supported. For all algorithms the tag length must be a multiple of 8 bits. Note:

• This method may only be called for MODE_DECRYPT after doFinal has been called.

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.

Specified by:

verifyTag in class javacardx.crypto.AEADCipher

Parameters:

receivedTagBuf - the buffer that will contain the received authentication tag

receivedTagOff - the offset of the received authentication tag in the buffer

receivedTagLen - the length in bytes of the received authentication tag in the buffer

requiredTagLen - the required length in bytes of the received authentication tag, usually a constant value

Returns:

Tag verification result

Throws:

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

• ILLEGAL_USE if doFinal has not been called
• ILLEGAL_VALUE if the tag length is not supported