Challenges

A challenge can be generated and used by the user to prove to the sample service that he/she possesses a particular sample file. The answer to this challenge will be the challenge token and must be used in the request when adding a sample submission. A challenge can only be used once – if you want to submit multiple sample submissions a challenge must be created and answered for each submission.

Generating a challenge

To generate a challenge, the challenge endpoint must be used with a POST operation along with the sample ID. The response body will be JSON formatted and contain the challenge itself.

curl -X POST -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/sample/<sample sha256 hash>/challenge

Tip

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

This request can return three different responses, depending on whether the sample file exists and its file size. For how to handle each scenario, see the Solving a challenge section below.

Solving a challenge

Generating a challenge might return three different kinds of responses in the form of HTTP status code 404, 422, or 200.

404 Not Found

This means that the sample file does not exist in the system. In this case, you need to upload the sample file using the sample-upload endpoint. See the Sample for how to do this.

When the upload is finished, the JSON response will contain an object challenge with an id and sha256.

This is then the solution to a challenge and can be used in the request when adding a submission.

422 Unprocessable Entity

This means that the sample file is so small that a challenge cannot be generated. Instead, a full upload of the sample file must be done.

When the upload is finished, the JSON response will contain an objectchallenge with an id and sha256. This is then the solution to a challenge and can be used in the request when adding a submission.

200 OK

The response will in this case contain a JSON object with three fields inside the object data: id, offset, and length:

id

The ID of the challenge itself. This must be submitted along with the solution to the challenge

offset

Represents an offset (in bytes) into the sample file

length

Represents the number of bytes starting from offset in the sample file

The solution to the challenge will be the sha256 hash of length bytes, starting from the given offset into the sample file.

Below is an example of how to solve the challenge for an arbitrary sample file in bash:

$ curl -X POST -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/sample/36621fe568d2bea6c98fb388d1e36a696bbc1885ad7a72e83b86c279e14e4177/challenge
{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": {
    "id": "4e8341a0-ba36-4eaa-8c0a-ce70ea92879b",
    "offset": 1239,
    "length": 1024
  },
  "size": 0
}
$ dd if=sample-file bs=1 skip=1239 count=1024 | shasum -a 256
1024+0 records in
1024+0 records out
1024 bytes transferred in 0.004667 secs (219411 bytes/sec)
7d97adb3783d3e136eba8542a1bb388eb70a291fdbde9bd63bc06f66a3ef7460 -

The solution is 7d97adb3783d3e136eba8542a1bb388eb70a291fdbde9bd63bc06f66a3ef7460, and must be submitted along with the challenge id 4e8341a0-ba36-4eaa-8c0a-ce70ea92879b when adding a submission.