Message Authentication Codes

In cryptography, a Message Authentication Code (MAC) is a short piece of information used to authenticate a message and to provide integrity and authenticity assurances on the message. Integrity assurances detect accidental and intentional message changes, while authenticity assurances affirm the message’s origin. libscapi currently provides only one implementation of message authentication codes: HMAC.

The Mac abstract class

This is the general class for Mac. Every class in this family must derive this class.

class Mac

Basic Mac and Verify Functionality

vector<byte> Mac::mac(const vector<byte>& msg, int offset, int msgLen)

Computes the mac operation on the given msg and return the calculated tag.

Parameters:
  • msg – the message to operate the mac on.
  • offset – the offset within the message vector to take the bytes from.
  • msgLen – the length of the message in bytes.
Returns:

vector<byte> the return tag from the mac operation.
bool Mac::verify(const vector<byte>& msg, int offset, int msgLength, vector<byte>& tag)

Verifies that the given tag is valid for the given message.

Parameters:
  • msg – the message to compute the mac on to verify the tag.
  • offset – the offset within the message array to take the bytes from.
  • msgLength – the length of the message in bytes.
  • tag – the tag to verify.
Returns:

true if the tag is the result of computing mac on the message. false, otherwise.

Calulcating the Mac when not all the message is known up front

void Mac::update(vector<byte>& msg, int offset, int msgLen)

Adds the byte array to the existing message to mac.

Parameters:
  • msg – the message to add.
  • offset – the offset within the message array to take the bytes from.
  • msgLen – the length of the message in bytes.
void Mac::doFinal(vector<byte>& msg, int offset, int msgLength, vector<byte>& tag_res)

Completes the mac computation and puts the result tag in the tag array.

Parameters:
  • msg – the end of the message to mac.
  • offset – the offset within the message array to take the bytes from.
  • msgLength – the length of the message in bytes.
Returns:

the result tag from the mac operation.

Key Handling

SecretKey Mac::generateKey(int keySize)

Generates a secret key to initialize this mac object.

Parameters keySize:
 is the required secret key size in bits.
Returns:the generated secret key.
SecretKey Mac::generateKey(AlgorithmParameterSpec& keyParams)

Generates a secret key to initialize this mac object.

Parameters keyParams:
 algorithmParameterSpec contains parameters for the key generation of this mac algorithm.
Returns:the generated secret key.
bool Mac::isKeySet()

An object trying to use an instance of mac needs to check if it has already been initialized.

Returns:true if the object was initialized by calling the function setKey.
void Mac::setMacKey(SecretKey& secretKey)

Sets the secret key for this mac. The key can be changed at any time.

Parameters secretKey:
 secret key

Mac Properties

int Mac::getMacSize()

Returns the input block size in bytes.

Returns:the input block size.

HMAC

We presented the same HMAC algorithm in the first layer of libscapi. However, there it was only presented as a PRF. In order to make HMAC become also a MAC and not just a PRF, all we have to do is to derive the Mac class. This means that now our HMAC needs to know how to mac and verify. HMAC is a mac that does not require knowing the length of the message in advance.

The Hmac class

Hmac is a Marker interface. Every class that implements it is signed as Hmac. Hmac has varying input length and thus implements the interface PrfVaryingInputLength. Currenty the BcHMAC class implements the Hmac interface.

Hmac : public virtual PrfVaryingInputLength, public virtual UniqueTagMac, public virtual UnlimitedTime

Basic Usage

Sender usage:

//Create an hmac object.
OpenSSLHMAC hmac("SHA-1");

//Generate a SecretKey
Hmac.generateKey(128);

//Set the secretKey.
hmac.setKey(secretKey);

//Get the message to mac and calculate the mac tag.
auto tag = hmac.mac(msg, offset, length);

//Send the msg and tag to the receiver.
...

Receiver usage:

//Get secretKey, msg and tag byte arrays.
...
//Create the same hmac object as the sender’s hmac object and set the key.
...
// receive the message and the tag
...
// Verify the tag with the given msg.
If (hmac.verify(tag, msg, offset, length)) { //Tag is valid.
    //Continue working...
} else return ERROR; //Tag is not valid.