Home

Introduction

This library, together with some Python or Java wrapping, is used to create and issue a biometrically binding QR code identity cards. The generated QR code ID is binded to its owner via face recognition. Other persons using this QR code ID will not verify.

The shared library libidpasslite.so (or idpasslite.dll in Windows) is a combination of existing opensource components. It is a single shared library and self-contained. This library is a fusion of two categories of functions. They are:

• facial biometric functions
• cryptographic functions

It also embeds some information to track the library's build from its sources version. For example,

strings libidpasslite.so | grep DXTRACKER
DXTRACKER 8b3fb1d1788ad52eb25a3d69f54f7877f5ef708e

points to the repository's commit hash from which the library was built.

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 an api::KeySet structure or object to show the usual patterns when using protobuf.

#include "idpass.h"
#include "proto/api/api.pb.h"
#include "proto/idpasslite/idpasslite.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* context = idpass_lite_init(keysetbuf.data(), keysetbuf.size(), nullptr, 0);
}

Create an IDPASSLITE 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 IDPASSLITE 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 details
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 IDPASSLITE card for ident
int idcard_len;
unsigned char* idcard = idpass_lite_create_card_with_face(context, 
    &idcard_len, identbuf.data(), identbuf.size());

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

Using the issued IDPASSLITE card for secure transaction

The issued IDPASSLITE QR code ID can be later used by the card owner for secure transactions. The ID card owner's facial biometric template (this is not his photo) is securely stored inside his QR code ID and forms a bind between the QR code ID and its owner. Another person carrying this ID should not be able to perform a transaction using the ID.

Each issued IDPASSLITE QR code ID card contains a unique ED25519 key. The contents of the QR code ID is protected with an AEAD symmetric encryption and digitally signed.

In addition, the library can be initialized with a list of root certificates and each created card can be supplied with a list of intermediate certificates.