Home

Introduction

The shared library libidpasslite.so or idpasslite.dll is a monolithic amalgamation of various existing opensource components. It is intentionally crafted to be singular and as much as possible self-contained. Generally speaking, the library is a fusion of two functions:

• face recognition function
• cryptography function

In the event of further requirements and integrations rendering the library's physical monolithic construct no longer appropriate, then the composite artifacts should be cryptographically binded.

The libidpasslite.so library shall be digitally signed to trace it back to the sources version it was built from. For example,

strings libidpasslite.so | grep DXTRACKER
DXTRACKER 8b3fb1d1788ad52eb25a3d69f54f7877f5ef708e

points to the repository's commit hash from which the library was built. The DX prefix was from Android where this library initially started.

Initialize the library

The API's design uses Google's protocol buffer serialization format version 3.12.3. For example, in the snippet below shows a C++ client side caller where a structure or object is created, initialized, serialized and de-serialized in certain complex API calls and return values.

#include "idpass.h"
#include "proto/api/api.pb.h"

void initialize_snippet() 
{
    unsigned char signaturekey[64];
    unsigned char encryptionkey[32];

    idpass_lite_generate_secret_signature_key(signaturekey, 64);
    idpass_lite_generate_encryption_key(encryptionkey, 32);

    // create api::KeySet object
    api::KeySet keyset;
 
    // initialize object member fields
    keyset.set_encryptionkey(encryptionkey, 32);
    keyset.set_signaturekey(signaturekey, 64);

    // serialize object into byte array 
    std::vector<unsigned char> keysetbuf(keyset.ByteSizeLong());
    keyset.SerializeToArray(keysetbuf.data(), keysetbuf.size());

    // call the library's main initialization API
    void* self = idpass_lite_init(keysetbuf.data(), keysetbuf.size(), nullptr, 0);
}

The deserialization part is not shown in the above snippet as it happens inside the idpass_lite_init function. The de-serialization part shall re-construct the exact api::KeySet object instance within the library.

The idpass.h header file exposes a C API. However, the internal implementation uses C++ due to the following:

• Google's protocol buffers is natively in C++
• Dlib is purely in C++

Create an IDPASS ID for a new user

After initializing the library, the snippet below shows how to setup the identity details for a user, call an API to create an IDPASS card, and then saving the issued identification card as a QR code image.

// prepare protobuf object
api::Ident ident;

// take photo of user
std::string filename = "userphoto.jpg";
std::ifstream photofile(filename, std::ios::binary);
std::vector<char> photo(std::istreambuf_iterator<char>{photofile}, {});

// initialize protobuf object with identity values
ident.set_surname("Doe");
ident.set_givenname("John");
ident.set_placeofbirth("Kibawe, Bukidnon");
ident.set_pin("12345");
ident.mutable_dateofbirth()->set_year(1978);
ident.mutable_dateofbirth()->set_month(12);
ident.mutable_dateofbirth()->set_day(17);
ident.set_photo(photo.data(), photo.size());

// serialize protobuf object into a byte array
std::vector<unsigned char> identbuf(ident.ByteSizeLong());
ident.SerializeToArray(identbuf.data(), identbuf.size());

// call API to create IDPASS card for ident
int idcard_len;
unsigned char* idcard = idpass_lite_create_card_with_face(self, 
    &idcard_len, identbuf.data(), identbuf.size());

// save idcard as a QR code image
idpass_lite_saveToBitmap(self, idcard, idcard_len, "qrcode_id.bmp");

Using the issued IDPASS card for secure transaction

The issued IDPASS QR code ID can be later used by the card owner for secure transaction.