Message Authentication Codes

Updated: August 9, 2017

SmartKey can compute and verify Message Authentication Codes using symmetric keys.

Prerequisites

Computing and verifying MACs requires an SmartKey account, a group with a symmetric key, and an application configured in that group. See the SmartKey Developer’s Guide for more details.

Required Operations

The symmetric key must have the MacGenerate operation enabled for generating a MAC and the MacVerify operation enabled for verifying a MAC. In addition, the key must be enabled.

Authorization and Configuration

You must first authenticate and optionally configure a default API client as described in Configure API Client and Client Authentication. Creating or verifying a MAC requires authenticating as an app with an API key or a client certificate. (User accounts cannot compute or verify MACs.)

Create a DigestApi Object

Computing and verifying MACs is performed using a DigestApi object.

import com.fortanix.sdkms.v1.api.DigestApi();

DigestApi digestApi = new DigestApi();

Compute a MAC

Create a MAC Generate Request.

The MAC request object encodes the request parameters. alg (algorithm) specifies the hash algorithm to use, and data specifies the data that the MAC is being calculated for. data should be binary data passed as a byte array.

import com.fortanix.sdkms.v1.model.MacGenerate;

DigestRequest macRequest = new MacGenerateRequest().alg(DigestAlgorithm.<algorithm>).data(<data as byte[]>);

Make the Compute MAC Call

The MAC is calculated with the computeMac() method of the DigestApi object. The MAC is returned as a byte array in the digest property of a MacGenerateResponse object.

import com.fortanix.sdkms.v1.model.MacGenerateResponse;

MacGenerateResponse macResponse = digestApi.computeMac(<key UUID>, macRequest);
byte[] mac = macResponse.getDigest();

Verify a MAC

Create a MAC Verify Request

The MAC verify request object encodes the request parameters. alg (digest algorithm) specifies the hash algorithm to use. data specifies the data that is being verified, and should be passed as a byte array. digest specifies the computed MAC, and should also be passed as a byte array.

import com.fortanix.sdkms.v1.model.DigestAlgorithm;
import com.fortanix.sdkms.v1.model.MacVerifyRequest;

MacVerifyRequest verifyRequest = new MacVerifyRequest().alg(DigestAlgorithm.<algorithm>).data(<data as byte[]>).digest(<digest as byte[]>);

Make the Verfiy MAC Call

The MAC is verified with the verifyMac() method of the DigestApi object. The result property of the returned MacVerifyResponse object will be true if the MAC was successfully verified, and false if it did not verify.

import com.fortanix.sdkms.v1.model.MacVerifyResponse;

MacVerifyResponse verifyResponse = digestApi.verifyMac(<key UUID>, verifyRequest);
bool verified = verifyResponse.getResult();