Retrieve Images of Stored Identities

Easy Method

The easiest way to retrieve face images of a stored identity is by doing the following:

This method works for cloud and locally hosted systems for images with and without application-level encryption applied to them. It is not, however, as efficient as other methods. For more information, see the Efficient method section.

For Local Host

curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd"
"http://localhost:8086/person/<personId>/face"'

For SAFR Cloud

curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd"
"https://cvos.real.com/person/<personId>/face"

Example:

curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd"
"https://cvos.real.com/person/60046fb9-5b5d-4d2b-a3aa-6345e43da53d/face"

Efficient Method

For a highly efficient and the most direct method of retrieval of images stored for identities, use the identity image URL. The stored identity image URL is returned by GET /people and GET /rootpeople requests in the imageURI property. The image referenced is used to represent the identity.

Note: Use unmergedImageURIis if the image that is different from the one referenced by imageURI exists for the identity and can be used to retrieve the image of the specific face modality (for example, a facial image with sunglasses) associated with a matching personId.

For a locally hosted system

For a locally hosted system, the provided URI will be of the following form: cvos://obj/<image-guid>

Retrieve the image by issuing the following http:// request to the Object Server (CVOS) API endpoint:

curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION: userid:pwd"
"http://localhost:8086/obj/<imageguid>"

For a cloud hosted system

The decryption is described in the next section.

Decrypt Application-Level Encrypted Images

Images referenced via the https:// scheme (applicable to cloud accounts only when efficient image retrieval method is used) must be decrypted after being downloaded before they can be viewed. The encrypted image data can be downloaded by using the https:// protocol scheme with the same path provided in the https:// URL: https://<path>

To decrypt the downloaded image:

  1. Retrieve the account-specific decryption key using the following API request:

    curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd""https://covi.real.com/obj/imagekey"

    The response contains a JSON formatted base64 form of the key: { "key": "<base64_encoded_key>"}

    Example:

    { "key": "yJgLFSH/Ypsb1wycx2TzZnvTwCob4KZHrcIYgqZxrz0=" }

  2. To decrypt the image, extract the 16-byte IV prefix from the encrypted image data and the rest of the data decrypted using the IV and the decryption key.

    • IV = first_16_bytes_of_encrypted_image_data
    • Key = base64Decode(base64_encoded_key)
    • EncryptedImageBody = encrypted_image_data_starting_with_byte_17
    • DecryptedImage = getCipher(AES/CBC/PKCSPadding).decode(IV, Key, EncryptedImageBody)

    Example:

    openssl dec -aes-256-cbc -in EncryptedImageBody.enc -out ImageBody.jpg -K $Key -iv $IV

See Also