About Thumbprints

Thumbprints are a required property contained within the request and response payloads of many Janus API calls. Thumbprints maintain system integrity in the measure lifecycle. The primary use of thumbprints is to ensure that Observation Item and Outcome Item data is encoded to the format specified by the ScalesItems file and that the data was not impaired in transit. A thumbprint must be generated whenever an Observation or Outcome Set is created or modified.

In order to ensure correctness of the data, the thumbprint should be generated twice in any given request process. Firstly, a thumbprint must be generated by the system creating/modifying the Observation or Outcome Set, creating a "signature" for the items. This may be done either by the Janus API or calling system, depending on the scenario. Then, the system receiving the Observation or Outcome Sets should also generate a thumbprint for each Set, checking the calculated value against the provided one. If the value has changed, the data may have been impaired in transit, and the Items should be considered compromised.

The following are scenarios where the Janus API will generate a thumbprint. It is strongly recommended that these thumbprints be checked for correctness by the calling application upon receiving the results, to verify the integrity of the data. These scenarios are:

1. The Janus API generates Observation Sets to be retrieved during the Data Gatherer process. In this case, the Janus API will generate a thumbprint attached to each Observation Set.
2. The Janus API generates Outcome Sets during the Evaluate process. The Janus API will generate and return a thumbprint attached to each Outcome Set.

The following are scenarios which require the caller to generate a thumbprint, which will be checked by the Janus API:

1. The caller provides Observation Sets during Data Gatherer set-up to pre-fill some demographic info into the assessment.
2. The caller has an agreement with MHS that allows for a custom Data Gatherer to be used. In this case, the Data Gatherer must correctly generate all thumbprints for Observation Sets before sending them to the Evaluate endpoint.
3. The caller modifies an Observation Set before passing it forward to the Evaluate endpoint. Note that ONLY demographic information should be modified this way - modifying the scored assessment items compromises the integrity of the assessment and renders it invalid.

Note that the calling application should never create/modify an Outcome Set. By generating a thumbprint on an Observation Set in any of the above scenarios, the API caller is attesting that:

1. The API user has collected the data and encoded it as specified by the measure.
2. The data has been encoded to the specification of the required format as defined by the InterpretAs key.
3. The API caller assumes sole responsibility for the accuracy of the encoding.
4. The Observation data was collected by an appropriately trained individual who is correctly certified or qualified to utilize the measure and to interpret the results that will be returned.

Technical Implementation

Thumbprints are generated using the Blake2b cryptographic keyed hash algorithm. The Blake2b algorithm is used because it effectively balances security, performance, and transparency. The implementation of this algorithm depends on the language and library used, but the following points must be considered:

• The hashing algorithm used must be Blake2b, not Blake or Blake2 or some other algorithm variation.
• The Thumbprint hash values are generated in Keyed mode.
• The key must be the interpretAs value for Observation Sets or outcomeSetID for Outcome Sets, which binds the hash to the specific origin or formatting of the source data.
• The encoding of the input should be set to use Unicode values
• The digest (output) size should be 16-bytes.
• The digest (output) should be encoded as a hex string.
• The Items must be fed into the hashing algorithm one value at a time; i.e. If the Items of an Observation Set is "Items": "0|1|0|0|1" what should be hashed is:
  • '0'
  • '1'
  • '0'
  • '0'
  • '1'

Code Samples

Sample code snippets for generating thumbprints are available in Python and C#.

Python:

import hashlib

#store data as an array, converting values to bytes-like objects
data = [b'-99', b'2', b'3', b'2', b'1', b'3', b'4', b'4', b'4', b'1', b'2', b'2', b'4', b'3', b'2', b'1'] 

#create hash with digest size of 16 and InterpretAs as key (as a bytes-like object)
h = hashlib.blake2b(digest_size=16, key=b'23b69174-2ff7-4e66-8b42-b2a525491f56')

#pass each value to the hash function
for item in data:
    h.update(item)

#results in a correct thumbprint: e509c6e993870168908c00fcecef97eb
print(h.hexdigest())

C#:

using Blake2Fast;
using System.Text;

// IntepretAs and Item setup
string KeyInterpretAs = "23b69174-2ff7-4e66-8b42-b2a525491f56";
string delimiter = "|";
string observationItems = "-99|2|3|2|1|3|4|4|4|1|2|2|4|3|2|1";

// Blake2B setup
const int DIGEST_LENGTH = 16;
string[] valueArray = observationItems.Split(delimiter);
IBlake2Incremental observationDataThumbprint = Blake2b.CreateIncrementalHasher(DIGEST_LENGTH, Encoding.UTF8.GetBytes(KeyInterpretAs));
StringBuilder observationData = new StringBuilder();

// Gather Observation Values
foreach (var value in valueArray)
{
    observationDataThumbprint.Update(Encoding.UTF8.GetBytes(value.ToString()));   // Where 'value' is the response for the Item
    observationData.Append(value.ToString());
    observationData.Append(delimiter);
}
observationData.Length--;  // Remove trailing delimiter

// Finish thumbprint
var observationDataThumbprintResult = observationDataThumbprint.Finish();
string hex = BitConverter.ToString(observationDataThumbprintResult);
string thumbprint = hex.Replace("-", "").ToLower();

// Print correct thumbprint: e509c6e993870168908c00fcecef97eb
Console.WriteLine(thumbprint);