Package javacard.security

Interface HMACKey

All Superinterfaces:

Key, SecretKey

public interface HMACKey
extends SecretKey

HMACKey contains a key for HMAC operations. This key can be of any length aligned on a multiple of 8 bits, but it is strongly recommended that the key is not shorter than the byte length of the hash output used in the HMAC implementation. Keys with length greater than the hash block length are first hashed with the hash algorithm used for the HMAC implementation.

Implementations must support an HMAC key length equal to the length of the supported hash algorithm block size (e.g 64 bytes for SHA-1)

When the key data is set, the key is initialized and ready for use.

Since:

2.2.2

See Also:

KeyBuilder, Signature, javacardx.crypto.Cipher, javacardx.crypto.KeyEncryption

Method Summary

Modifier and Type	Method	Description
byte	getKey(byte[] keyData, short kOff)	Returns the Key data in plain text.
void	setKey(byte[] keyData, short kOff, short kLen)	Sets the Key data.

Methods inherited from interface javacard.security.Key

clearKey, getSize, getType, isInitialized

Method Detail

setKey

void setKey(byte[] keyData,
            short kOff,
            short kLen)
     throws CryptoException,
            NullPointerException,
            ArrayIndexOutOfBoundsException

Sets the Key data. Input key data is copied into the internal representation.

Notes:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, keyData is decrypted using the Cipher object.
• The kLen parameter (expressed in bytes) is the length of the key initialization data and can be smaller or equal to the capacity of the key. The capacity of the key is the length returned by Key.getSize() (expressed in bits) which has been requested when calling KeyBuilder.buildKey(byte, short, boolean) or KeyBuilder.buildKey(byte, byte, short, boolean) methods. The klen parameter will be the length of the retrieved data when calling getKey(byte[], short).

Parameters:

keyData - byte array containing key initialization data

kOff - offset within keyData to start

kLen - the byte length of the key initialization data

Throws:

CryptoException - with the following reason code:

• CryptoException.ILLEGAL_VALUE if the kLen parameter is 0 or invalid or if the keyData parameter is inconsistent with the key length or if input data decryption is required and fails.

ArrayIndexOutOfBoundsException - if kOff is negative or the keyData array is too short

NullPointerException - if the keyData parameter is null

getKey

byte getKey(byte[] keyData,
            short kOff)

Returns the Key data in plain text.

Note:

• If the byte length of the key data exceeds 127, this method returns -1. The data is nevertheless placed in the keyData buffer if it fits.
• The length of the retrieved data is the same as the one which has been set by calling setKey(byte[], short, short). It can be smaller or equal to the capacity of the key. The capacity of the key is the length returned by Key.getSize() (expressed in bits) which has been requested when calling KeyBuilder.buildKey(byte, short, boolean) or KeyBuilder.buildKey(byte, byte, short, boolean) methods.

Parameters:

keyData - byte array to return key data

kOff - offset within keyData to start

Returns:

the byte length of the key data returned

Throws:

CryptoException - with the following reason code:

• CryptoException.UNINITIALIZED_KEY if the key data has not been successfully initialized since the time the initialized state of the key was set to false.

See Also:

Key