Skip to content

API Reference

Jump to bottom
typelogic edited this page Dec 31, 2020 · 14 revisions

API

Classes

idpass_lite_add_certificates

Adds intermediate certificates into the calling context. Cards created, thereafter, shall attach these certificates into the issued QR code ID. Intermediate certificates can only be added into the calling context after it is initialized with root certificates.

int idpass_lite_add_certificates(
    void* self,
    unsigned char* certs_buf,
    int certs_buf_len
);

Params:

  • self : The calling context.
  • certs_buf : The list of intermediate certificates.
  • certs_buf_len : The bytes length of certs_buf.

Return:

Returns 0 on success.

idpass_lite_add_revoked_key

Generate an intermediate certificate with the provided secret key of signer and public key of the intermediate certificate.

int idpass_lite_add_revoked_key(
    unsigned char* pubkey,
    int pubkey_len
);

Params:

  • pubkey : The public key to be revoked.
  • pubkey_len : Length in bytes of pubkey.

Return:

Returns 0 on success.

idpass_lite_card_decrypt

Symmetric decryption of the fullcard QR code ID.

int idpass_lite_card_decrypt(
    void* self,
    unsigned char* ecard_buf,
    int* ecard_buf_len,
    unsigned char* key,
    int key_len
);

Params:

  • self : The calling context.
  • ecard_buf : The fullcard bytes.
  • ecard_buf_len : Length in bytes of ecard_buf.
  • key : The AEAD symmetric decryption key.
  • key_len : Length in bytes of key.

Return:

Returns 0 on success. The decrypted content is stored in ecard_buf.

idpass_lite_compare_face_photo

Computes Euclidean difference between two facial photo images (jpeg or bmp) loaded in face1 and face2 byte arrays designated by corresponding array lengths face1_len and face2_len respectively. The computed difference is stored in the fdiff parameter if the function returns 0 which means success. Otherwise, the function returns no-zero and nothing is stored in fdiff parameter. This error happens when either face1 or face2 has no recognizable human face detected or it has more than one recognizable human faces detected.

int idpass_lite_compare_face_photo(
    void* self,
    char* face1,
    int face1_len,
    char* face2,
    int face2_len,
    float* fdiff
);

Params:

  • self : The calling context.
  • face1: The first facial photo bytes array.
  • face1_len: Bytes array length.
  • face2 : The second facial photo bytes array.
  • face2_len : Bytes array length.
  • fdiff : Array of floats Euclidean difference of the two faces.

Return:

Returns 0 in Eucledian difference is successfully computed. Otherwise, non-zero.

idpass_lite_compare_face_template

Substracts two faces face1 and face2 and stores the result into fdiff.

int idpass_lite_compare_face_template(
    unsigned char* face1,
    int face1_len,
    unsigned char* face2,
    int face2_len,
    float* fdiff
);

Params:

  • self : The calling context.
  • face1 : The first face input.
  • face1_len : Length in bytes of face1.
  • face2 : The second face input.
  • face2_len : Length in bytes of face2.
  • fdiff : Where to store the computation result.

Return:

Returns 0 on success.

idpass_lite_compute_hash

Computes hash of data.

int idpass_lite_compute_hash(
    unsigned char* data,
    int data_len,
    unsigned char* hash,
    int hash_len
);

Params:

  • data: Any arbitrary blob of data.
  • data_len: The data length.
  • hash: Stores the computed hash of data
  • hash_len: Describes the required hash length.

Return:

Returns 0 when the hash is successfuly computed.

idpass_lite_create_card_with_face

Returns a QR code ID of a registered identity.

unsigned char* idpass_lite_create_card_with_face(
    void* self,
    int* outlen,
    unsigned char* ident_buf,
    int ident_buf_len
);

Params:

  • self : The calling context.
  • outlen : Bytes length of returned bytes.
  • ident_buf : The personal details of the registered identity.
  • ident_buf_len : Bytes length of ident_buf.

Return:

Returns an encrypted QR code ID.

idpass_lite_decrypt_with_card

Asymmetric decryption of a ciphertext using a provided secret key.

unsigned char* idpass_lite_decrypt_with_card(
    void* self,
    int* outlen,
    unsigned char* fullcard,
    int fullcard_len,
    unsigned char* encrypted,
    int encrypted_len
);

Params:

  • self : The calling context.
  • outlen : The bytes length of decrypted text.
  • fullcard : The QR code ID content.
  • fullcard_len : The bytes length of fullcard.
  • encrypted : The encrypted data.
  • encrypted_len : The bytes length of encrypted.

Return:

Returns the decrypted text.

idpass_lite_encrypt_with_card

Encrypt data with user's QR code ID.

unsigned char* idpass_lite_encrypt_with_card(
    void* self,
    int* outlen,
    unsigned char* encrypted_card,
    int encrypted_card_len,
    unsigned char* data,
    int data_len
);

Params:

  • self : The calling context.
  • outlen : Bytes length of encrypted data.
  • encrypted_card : User's QR code ID.
  • encrypted_card_len : Bytes length of encrypted_card.
  • data : The input data to be encrypted.
  • data_len : Bytes length of data.

Return:

Returns the encrypted data.

idpass_lite_face128d

Computes full facial dimension of a face.

int idpass_lite_face128d(
    void* self,
    char* photo,
    int photo_len,
    float* facearray
);

Params:

  • self : The calling context.
  • photo : The face photo.
  • photo_len : Bytes length of photo.
  • facearray : A float[128] array with 4 bytes per float.

Return:

Returns the count of detected faces in photo.

idpass_lite_face128dbuf

Computes full facial dimension of a face.

int idpass_lite_face128dbuf(
    void* self,
    char* photo,
    int photo_len,
    unsigned char* buf
);

Params:

  • self : The calling context.
  • photo : The face photo.
  • photo_len : Bytes length in photo.
  • buf : The facial dimension float[128] as bytes.

Return:

Returns the count of detected faces in photo.

idpass_lite_face64d

Computes half facial dimension of a face.

int idpass_lite_face64d(
    void* self,
    char* photo,
    int photo_len,
    float* facearray
);

Params:

  • self : The calling context.
  • photo : The face photo.
  • photo_len : Bytes length of photo.
  • facearray : The float[64] with 2 bytes per float.

Return:

Returns the count of detected faces in photo.

idpass_lite_face64dbuf

Computes half facial dimension of a face.

int idpass_lite_face64dbuf(
    void* self,
    char* photo,
    int photo_len,
    unsigned char* buf
);

Params:

  • self : The calling context.
  • photo : The face photo.
  • photo_len : Bytes length of photo.
  • facearray : The float[64] with 2 bytes per float in byte array format.

Return:

Returns the count of detected faces in photo.

idpass_lite_freemem

Explicitely frees up memory blocks returned by context.

void idpass_lite_freemem(
    void* self,
    void* buf
);

Params:

  • self : The calling context.
  • buf : Memory address returned by context.

idpass_lite_generate_child_certificate

Generate an intermediate certificate with the provided secret key of signer and public key of the intermediate certificate.

unsigned char* idpass_lite_generate_child_certificate(
    const unsigned char* parent_skpk,
    int parent_skpk_len,
    const unsigned char* child_pubkey,
    int child_pubkey_len,
    int* outlen
);

Params:

  • self : The calling context.
  • parent_skpk : The private key of the signer.
  • parent_skpk_len : The length in bytes of parent_skpk.
  • child_pubkey : The public key of to-be-signed certificate.
  • child_pubkey_len : The length in bytes of child_pubkey.
  • outlen : The length in bytes of returned signed intermediate certificate.

Return:

Returns a signed intermediate certificate.

idpass_lite_generate_encryption_key

Generates an AEAD symmetric encryption key.

int idpass_lite_generate_encryption_key(
    unsigned char* key,
    int key_len
);

Params:

  • self : The calling context.
  • key : The generated encryption key.
  • key_len : The length in bytes of the generated encryption key.

Return:

Returns 0 on success.

idpass_lite_generate_root_certificate

Generate a self-signed certificate with the provided secret key.

unsigned char* idpass_lite_generate_root_certificate(
    unsigned char* skpk,
    int skpk_len,
    int* outlen
);

Params:

  • skpk : The certificates private key.
  • skpk_len : The bytes length of skpk.
  • outlen : The bytes length of returned self-signed certificate.

Return:

Returns a self-sign certificate with the provided private key.

idpass_lite_generate_secret_signature_keypair

Generate an ED25519 key.

int idpass_lite_generate_secret_signature_keypair(
    unsigned char* pk,
    int pklen,
    unsigned char* sk,
    int sklen
);

Params:

  • pk: The generated public key.
  • pklen: The generated public key length.
  • sk: The generated secret key.
  • sklen: The generated secret key length.

Return:

Returns 0 on success.

idpass_lite_init

The main initilizationfunction of the library.

void* idpass_lite_init(
    unsigned char* keyset_buf,
    int keyset_buf_len,
    unsigned char* rootcerts_buf,
    int rootcerts_buf_len
);

Params:

  • keyset_buf : The cryptographic key settings for the context.
  • keyset_buf_len : Length in bytes of keyset_buf.
  • rootcerts_buf : The root certificates for the context.
  • rootcerts_buf_len : The length in bytes of rootcerts_buf.

Return:

void* Returns the library context.

idpass_lite_ioctl

A generic function to adjust settings of the calling context. It consist of a sub-command prefix by IOCTL_* followed by command-specific parameters.

void* idpass_lite_ioctl(
    void* self,
    int* outlen,
    unsigned char* iobuf,
    int iobuf_len
);

Params:

  • self : The calling context.
  • outlen : The count of bytes returned.
  • iobuf : The input/output command buffer.
  • iobuf_len : The bytes length of iobuf parameter.

Return:

void* Command-specific returned data buffer.

idpass_lite_qrpixel

Returns the QR code bitmap of data.

unsigned char* idpass_lite_qrpixel(
    void* self,
    const unsigned char* data,
    int data_len,
    int* qrsize
);

Params:

  • self : The calling context.
  • data : The input data.
  • data_len : Bytes length of data.
  • qrsize : The square side dimension of QR code.

Return:

The bitmap representation of data.

idpass_lite_qrpixel2

Returns the QR code bitmap of data.

unsigned char* idpass_lite_qrpixel2(
    void* self,
    int* outlen,
    const unsigned char* data,
    int data_len,
    int* qrsize
);

Params:

  • self : The calling context.
  • outlen : The bytes length of returned data.
  • data : The input data.
  • data_len : Bytes length of data.
  • qrsize : The square side dimension of QR code.

Return:

The bitmap representation of data.

idpass_lite_saveToBitmap

Saves the QR code data into a bitmap file.

int idpass_lite_saveToBitmap(
    void* self,
    unsigned char* data,
    int data_len,
    const char* bitmapfile
);

Params:

  • self : The calling context.
  • data : The QR code content data.
  • data_len : Bytes length of data.
  • bitmapfile : The output filename.

Return:

Returns 0 on successful file save.

idpass_lite_sign_with_card

Signs data with user's QR code ID.

int idpass_lite_sign_with_card(
    void* self,
    unsigned char* sig,
    int sig_len,
    unsigned char* encrypted_card,
    int encrypted_card_len,
    unsigned char* data,
    int data_len
);

Params:

  • self : The calling context.
  • outlen : Bytes length of returned signature.
  • encrypted_card : User's QR code ID.
  • encrypted_card_len : Bytes length of encrypted_card.
  • data : The input data to be signed.
  • data_len : Bytes length of data.

Return:

Returns the signature.

`idpass_lite_uio

Experimential test of length-prefixed returned blob.

unsigned char* idpass_lite_uio(
    void* self,
    int typ
);

Params:

  • self : The calling context.
  • typ : Generic type parameter.

Return:

Returns a 4 bytes length-prefix byte array.

idpass_lite_verify_card_signature

Check if the card's signature verifies to its corresponding public key, and that this public key is within the configured trusted keys initialized in the library.

If skipcheckcert is 0 then in addition to the above check, the card's certificate chain's root anchor is verified to the configured root certificate initialized in the library.

int idpass_lite_verify_card_signature(
    void* self,
    unsigned char* fullcard,
    int fullcard_len,
    int skipcheckcert
);

Params:

  • self: Library instance context.
  • fullcard: A serialized byte array of idpass::IDPassCards.
  • fullcard_len: Byte array length.
  • skipcheckcert: Flag (0 or 1) wither to skip checking of card's certificate.

Return:

Returns 0 if the card is successfully verified.

idpass_lite_verify_card_with_face

Verify user's QR code ID against a matching photo.

unsigned char* idpass_lite_verify_card_with_face(
    void* self,
    int* outlen,
    unsigned char* encrypted_card,
    int encrypted_card_len,
    char* photo,
    int photo_len
);

Params:

  • self : The calling context.
  • outlen : Bytes length of returned bytes.
  • encrypted_card : The user's QR code ID.
  • encrypted_card_len : Bytes length of encrypted_card.
  • photo : The ID owner's photo capture.
  • photo_len : Length in bytes of photo.

Return:

Returns the user's CardDetails if there is facial match.

idpass_lite_verify_card_with_pin

Verify user's QR code ID against a matching pin.

unsigned char* idpass_lite_verify_card_with_pin(
    void* self,
    int* outlen,
    unsigned char* encrypted_card,
    int encrypted_card_len,
    const char* pin
);

Params:

  • self : The calling context.
  • outlen : Bytes length of returned bytes.
  • encrypted_card : The user's QR code ID.
  • encrypted_card_len : Bytes length of encrypted_card.
  • pin : The ID owner's secret pin code.

Return:

Returns the user's CardDetails if there is pin match.

idpass_lite_verify_certificate

Verifies the fullcard's attached certificate against the root certificate configured in the context.

int idpass_lite_verify_certificate(
    void* self,
    unsigned char* fullcard,
    int fullcard_len
);

Params:

  • self : The calling context.
  • certs_buf : The fullcard bytes content.
  • certs_buf_len : The bytes length of certs_buf.

Return:

Returns 0 if the card has no attached certificates. Returns greater than 0 if the attached certificates is validated against a root certificate. Returns -1 if the attached certificates fails to validate.

idpass_lite_verify_with_card

Verify the signature of msg using pubkey.

int idpass_lite_verify_with_card(
    void* self,
    unsigned char* msg,
    int msg_len,
    unsigned char* signature,
    int signature_len,
    unsigned char* pubkey,
    int pubkey_len
);

Params:

  • self : The calling context.
  • msg : The message.
  • msg_len : Length in bytes of message.
  • signature : Signature of message.
  • signature_len : The length in bytes of signature.
  • pubkey : Public key that generated the signature.
  • pubkey_len : Length in bytes of pubkey.

Return:

Returns 0 if pubkey verifies signature of message.

api::byteArray

An API level protobuf message used to send/receive any blob as a bytes array

Enums:

  • Typ: Descriptor of the bytes array.

Properties:

  • <Typ> typ: Descriptor of the blob.
  • <bytes> val: The blob as a bytes array.

Methods:

Getter/setter methods to get/set the blob and its type.

api::byteArrays

A list of blob.

Properties:

List of blob in vals.

  • <byteArray[]> vals

Methods:

Standard getter/setter methods.

api::Certificates

List of certificate.

Properties:

List of certificate where each certificate has public key, issuer key and signature.

Methods:

Standard getter/setter to get/set public key, signature and issuer key.

api::Ident

An API level protobuf message used to send/received identity details.

Properties:

  • <string> surName: Identity surname.
  • <string> givenName: Identity given name.
  • <string> placeOfBirth: Identity place of birth.
  • <string> pin: Identity card's secret pin code.
  • <idpass::Date> dateOfBirth: Identity birthday.
  • <byteArrays> photos: Identity's list of facial photos.
  • <bytes> photo: Identity's main facial photo.
  • <idpass::Pair[]> privExtra: Identity private information as a key/value pair.
  • <idpass::Pair[]> pubExtra: Identity public information as a key/value pair.
  • <string> UIN: Identity UIN identifier.
  • <string> fullName: Identity full name.
  • <int32> gender : 1 = Female, 2 = Male, 3 = Diverse: Identity's gender as int.
  • <idpass::PostalAddress> postalAddress: Identity postal address.

Methods:

Standard protobuf getter/setter to get/set member fields.

api::Idents

API level protobuf message to pack and send list of identities.

Properties:

Methods:

Standard protobuf getter/setter methods.

api::KeySet

API level protobuf message to pack and send initialization cryptographic keys.

Properties:

  • <bytes> encryptionKey: Symmetric encryption key.
  • <bytes> signatureKey: Asymmetric signature key pair.
  • <byteArray[]> verificationKeys: Trusted list of public signature keys.

Methods:

Standard getter/setter to set member fields.

idpass::CardAccess

Data structure that contains biometric captures.

Enums:

  • FingerType
  • EyeType

Properties:

  • <FingerType> finger: One of the 10 finger identifier.
  • <bytes> fingerprint: Finger print biometric capture result.
  • <EyeType> eye: Either of left or right eye.
  • <bytes> iris: Eye biometric capture result.
  • <bytes> face: Facial dimension biometric capture.
  • <string> pin: Secret pin code to encrypt information.

Methods:

Standard protobuf getter/setter

idpass::CardDetails

The protobuf data structure that holds the identity fields details.

Properties:

  • <string> UIN: MOSIP assigned identifier.
  • <string> fullName: Identity fullname.
  • <string> surName: Identity surname.
  • <string> givenName: Identity given name.
  • <string> placeOfBirth: Identity place of birth.
  • <idpass::Date> dateOfBirth: Identity date of birth.
  • <int32> gender: Identity gender.
  • <idpass::PostalAddress> postalAddress: Identity postal address.
  • <idpass::Pair[]> extra: Identity extra key/value pieces of information.
  • <int64> createdAt: Unix epoch seconds timestamp of id generation.

Methods:

Standard protobuf getter/setter provided methods.

idpass::Certificate

Protobuf data structure that holds the certificate stamp of generated card.

Properties:

  • <bytes> pubkey: Public key
  • <bytes> issuerkey: Issuer key
  • <bytes> signature: Digital signature.

Methods:

Standard protobuf getter/setter methods.

idpass::Date

Protobuf structure for a date.

Properties:

  • <int32> year : Year of date. Must be from 1 to 9999, or 0 if specifying a date without a year.
  • <int32> month : Month of year. Must be from 1 to 12, or 0 if specifying a year without a month and day.
  • <int32> day : Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a year by itself or a year and month where the day is not significant.

Methods:

Standard protobuf getter/setter for the fields.

idpass::Dictionary

Protobuf data structure that holds a list of key/value pairs.

Properties:

Methods:

Standard protobuf getter/setter methods.

idpass::IDPassCard

Protobuf data structure that holds the access, details and encryption key. The access field provides the access conditions for authentication. The details field holds the hidden private details of the owner, and shall only become publicly visible upon authentication.

Properties:

  • <idpass::CardAccess> access: See CardAccess description.
  • <idpass::CardDetails> details: See CardDetails description.
  • <bytes> encryptionKey: Symmetric encryption key that encrypts the card contents.

Methods:

Standard protobuf getter/setter methods.

idpass::IDPassCards

The main protobuf data structure that is returned from the API call create_card_with_face. It contains the publicly visible, the private hidden, signature, signer key and certificates of the issue ID.

Properties:

Standard protobuf getter/setter provided.

  • <idpass::PublicSignedIDPassCard> publicCard: The publicly visible details.
  • <bytes> encryptedCard: The hidden private details.
  • <bytes> signature: The signature of the card.
  • <bytes> signerPublicKey: The signing public key of the signature.
  • <idpass::Certificate[]> certificates: List of certificate chain for the signature.

Methods:

Standard protobuf getter/setter methods.

idpass::Pair

Protobuf data structure for a key and a value pair.

Properties:

  • <string> key: The key
  • <string> value: The value

Methods:

Standard protobuf getter/setter.

idpass::PostalAddress

Represents a postal address, e.g. for postal delivery or payments addresses. Given a postal address, a postal service can deliver items to a premise, P.O. Box or similar.

Original source: https://github.com/protobuf-net/protobuf-net/blob/main/src/protogen.site/wwwroot/protoc/google/type/postal_address.proto

Properties:

  • <int32> revision : The schema revision of the PostalAddress. All new revisions must be backward compatible with old revisions.
  • <string> region_code : CLDR region code of the country/region of the address. This is never inferred and it is up to the user to ensure the value is correct. See http://cldr.unicode.org/ and http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html for details. Example: "CH" for Switzerland.
  • <string> language_code : BCP-47 language code of the contents of this address.
  • <string> postal_code : Postal code of the address.
  • <string> sorting_code : Additional, country-specific, sorting code. This is not used in most regions. Where it is used, the value is either a string like "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number alone, representing the "sector code" (Jamaica), "delivery area indicator" (Malawi) or "post office indicator" (e.g. Côte d'Ivoire).
  • <string> administrative_area : Highest administrative subdivision which is used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture.
  • <string> locality : Generally refers to the city/town portion of the address. Examples: US city, IT comune, UK post town.
  • <string> sublocality : Sublocality of the address. For example, this can be neighborhoods, boroughs, districts.
  • <string[]> address_lines : Unstructured address lines describing the lower levels of an address.
  • <string[]> recipients : The recipient at the address.
  • <string> organization : The name of the organization at the address.

Methods:

Standard protobuf getter/settter.

idpass::PublicSignedIDPassCard

An outer envelop of the publicly visible identity details.

Properties:

Standard protobuf getter/setter.

Methods:

Standard protobuf provided getter/setter.

idpass::SignedIDPassCard

An unused data structure that has been supercedded by the newer IDPassCards.

Properties:

Methods:

Standard protobuf getter/setter.

Clone this wiki locally