Skip to main content

Secure MAC for Grades Journey

The MAC security mechanism is one of the options when you have enabled Secure REST API while configuring the approval workflow or a gradebook extract.

Generate and validate the MAC value

Validate that the value of the API Key is the value you expect, the validate the value of the MAC parameter:

  1. Order the API Key and other parameters alphabetically by parameter name.

  2. Concatenate the values of the parameters in that order in a single string.

  3. Add the Shared Secret value from the Grades Journey configuration screen to the string obtained from the previous step.

  4. Encrypt the string into a 16-byte string using the MD5 algorithm (see the following examples).

  5. Convert the 16-byte string to a 32-byte alphanumeric (hexadecimal) string for URL support.

  6. Compare your generated MAC with the generated MAC from Blackboard that was passed in the request.

Java Example

/**
* Calculates a secure MAC (message authentication code) from an array of strings and
shared secret.
* @param values – Parameters must first be sorted alphabetically by parameter name, then
the values of these sorted parameters passed to calculateSecureMac
* @param secret - the shared secret
* @return The calculated MAC
*/
private String calculateSecureMAC (final String[] values, final String secret) throws
NoSuchAlgorithmException
{
// concatenate param values
final int size = values.length;
String paramString = "";
for(int i=0; i<size; i++)
{
paramString += values[i];
}
// get md5 hash from ascii value and secret
final MessageDigest md = MessageDigest.getInstance("MD5");
final byte[] hashBytes = md.digest((paramString + secret).getBytes());
md.reset();
// convert to hex
String mac = "";
String hexByte;

for (int k=0; k<hashBytes.length; k++)
{
hexByte = Integer.toHexString(hashBytes[k] < 0 ? hashBytes[k] + 256 : hashBytes[k]);
mac += (hexByte.length()==1) ? "0" + hexByte : hexByte;
}
return mac;

PHP Example

/* Calculates a MAC (message authentication code) from an array of strings and a secret.
Sort request parameters alphabetically by parameter name first, then pass values of sorted
parameters and shared secret to calculateSecureMac */
function calculateSecureMac($params, $secret)
{
// concatenate param values
$data = implode('', $params);
// get md5 of concatenated param values and secret
$mac = md5($data . $secret);
return $mac;
}

Perl Example

use Digest::MD5;
# Calculates a MAC (message authentication code) from an array of strings and a secret. Sort request parameters alphabetically by parameter name first, then pass values of sorted parameters and shared secret to calculateSecureMac
sub calculateSecureMac
{
my @args = @_;
$secret = pop(@args);
# concatenate param values
$data = join("", @args);
# get md5 of concatenated param values and secret
$ctx = Digest::MD5->new;
$ctx->add($data . $secret);
$mac = $ctx->hexdigest;
return $mac;
}