Working with Large Fingerprints

Fingerprints that are too large to be serialized as strings in request and response payloads are instead handled as files with dedicated endpoints for upload, removal, and retrieval, described below.

Warning
 Your implementation should not store fingerprint retrieval URLs, should not assume that they will be valid in the future, and should not derive meaning from them.

Format

Fingerprints submitted using the large fingerprint endpoint MUST be submitted as raw binary data. These fingerprints should not be transmitted in any format that does not meet the conventions for the fingerprint type.

Supported Large Fingerprint Types

Below is a list of fingerprints only supported via these endpoints. Fingerprint values for these types cannot be included in XML submission documents and are not included in query responses.

Name Key

Videntifier

VIDENTIFIER

TMK+PDQF

TMK_PDQF

SSVH+PDNA

SSVH_PDNA

SSVH+SaferHash

TMK_SAFER_HASH

Discovering Large Fingerprints

Due to their size, file-based fingerprints are not serialized in the response payload when querying for entries. Instead, the response includes a relative URL that can be appended to the application’s root URL to retrieve the fingerprint.

The response below is an example of how file-based fingerprints are presented when querying for entries.

Query Result
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<queryResult xmlns="https://hashsharing.ncmec.org/hashsharing/v2">
    <images count="2" maxTimestamp="2017-10-24T14:00:00Z">
        <image>
            <member id="42">Example Member</member>
            <timestamp>2017-10-24T14:00:00Z</timestamp>
            <id>image1</id>
            <classification>A1</classification>
            <fingerprints>
                <pdna>aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa...</pdna>
                <videntifier rel="self" href="/v2/image1VidentifierUrl" />
            </fingerprints>
        </image>
    </images>
    <videos count="1" maxTimestamp="2017-10-24T14:00:00Z">
        <video>
            <member id="42">Example Member</member>
            <timestamp>2017-10-24T14:00:00Z</timestamp>
            <id>video1</id>
            <classification>B1</classification>
            <fingerprints>
                <md5>0123456789abcdef0123456789abcdef</pdna>
                <tmk-pdqf rel="self" href="/v2/video1TmkPdqfUrl" />
                <videntifier rel="self" href="/v2/video1VidentifierUrl" />
                <ssvh-pdna rel="self" href="/v2/video1SsvhPdnaUrl" />
                <ssvh-safer-hash rel="self" href="/v2/video1SsvhSaferHashUrl" />
            </fingerprints>
        </video>
    </videos>
</queryResult>
Note
 That the relative fingerprint URLs in this response are illustrative and are not representative of real data. When interacting with the API, these URLs should be treated as opaque and are subject to change without notice.

Retrieving a Large Fingerprint

A large fingerprint can be retrieved with a GET request to the URL supplied in the query result resolved against the application root URL, i.e. {app-url-root}/{fingerprintUrl}. The response is the raw binary content of the fingerprint.

retrieve large fingerprint diagram

For example, to retrieve the TMK+PDQF fingerprint for the video in the query result from Discovering Large Fingerprints, make the following curl call.

curl --user {ex-creds} {ex-url-root}/v2/video1TmkPdqfUrl

Submitting and Updating a Large Fingerprint

In addition to being able to upload small fingerprints as binaries, one can also upload larger fingerprints. See [uploading-fingerprints-via-files].

Deleting a Large Fingerprint

A large fingerprint can be removed using a DELETE request to the endpoint {app-url-v2}/entries/{entryId}/fingerprints/{fingerprintType}, where {fingerprintType} is the key for a supported large fingerprint type.

The server will respond with a status of 204 No Content if a fingerprint existed and was deleted.

remove large fingerprint diagram

For example, to remove a TMK+PDQF fingerprint for an existing entry with Entry ID video1, make the following curl call.

curl --user {ex-creds} \
     --request DELETE \
     {ex-url-v2}/entries/video1/fingerprints/TMK_PDQF