1.0 Overview
The Fortanix-Data-Security-Manager (DSM) can compute and verify Message Authentication Codes using symmetric keys.
2.0 Prerequisites
Computing and verifying MACs requires a Fortanix DSM account, a group with a symmetric key, and an application configured in that group. See the Fortanix DSM Getting Started Guide for more details.
3.0 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.
4.0 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.)
5.0 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();
6.0 Compute a MAC
6.1 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.MacGenerateRequest;
DigestRequest macRequest = new MacGenerateRequest().alg(DigestAlgorithm.<algorithm>).data(<data as byte[]>);
6.2 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();
7.0 Verify a MAC
7.1 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[]>);
7.2 Make the Verify 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();