Strona główna

Vicomp Ltd, All rights reserved VicompHighapi

Pobieranie 285.29 Kb.
Rozmiar285.29 Kb.
  1   2   3   4
Copyright 2014-2016 Vicomp Ltd, All rights reserved



Document is still under development

If you don't want to spend time reading this guide but want writing your code as quickly as possible fly directly to VicompApiBase.h and a Visual Studio C#.NET programming sample available at the Vicomp web site (Downloads page). In case of problems and/or questions get in touch with our software staff:

Programming Guide

Download and install Vicomp High Engine software package from our web site (instVicompHighEngine.exe installation utility). Also, it is suggested to download and install two applications: Vicomp Reader Soft Center (instVicompReaderSoftCenter.exe) and Vicomp Security Gateway (instVicompSecurityGateway.exe). To run the applications successfully the core component VicompHighEngine must be installed as a first step. If you have one of our readers, check that everything is OK reading some ICAO documents by means of the mentioned applications. The shortcuts to applications will be placed on your desktop. There will be no any desktop icon related to the VicompHighEngine itself that is installed somewhere in the system.

Find the API folder in VicompHighEngine installation directory and take a look at its contents.

Actually, there are two different application programming interfaces (APIs) included in the VicompHighAPI:
1) VicompNativeAPI (also known as VicompLowAPI)

2) VicompHighAPI itself

VicompNativeAPI (aka VicompLowAPI) is a low-level programming interface you have to use when implementing Bluetooth reader in your application. It is a kind of PC/SC like driver for Bluetooth reader with one of the most important PC/SC communication function SCardTransmit. We have to supply this interface free of charge as you don't know hardware details of low-level communication with our Bluetooth reader. All the high-level procedures (e.g. RFID session cryptography) you have to develop and implement yourself. It is your problem to build and interprete APDUs properly.
VicompHighAPI on the other hand is able to do all the difficult work for you. However, it is not distributed freely. Ask for details if interested in using VicompHighAPI.



// VicompNativeAPI -------------------------------------------------------------

#define VICOMP_LOW_BAUD 9600

#define VICOMP_MID_BAUD 115200

#define VICOMP_HIGH_BAUD 460800


// VicompNativeAPI messages
#define VICOMP_MSG_NATIVE_API_BASE WM_APP //native messages up to WM_APP+4999



// majorParam = number of characters (bytes)

// minorParam = pointer to the raw MRZ contents (incl. STX/ETX & CR/LF)


// VICOMP_NOTIFY, minorParam = seconds left for RFID being active



// majorParam = VICOMP_CHIP_ENTER, minorParam = ptr to VICOMP_CHIP_NATIVE_INFO

// structure

// VICOMP_CHIP_EXIT, minorParam=0 (not used for native BT reader)


// the message is sent continuously while reading large elementary files (more

// than 2KB=2048bytes) by means of vicomp_native_ReadFileFast() API function

// majorParam = data group identifier (2,3,4), minorParam=% of reading completion

// Address of the following structure is returned

// in minorParam of the VICOMP_MSG_RFID_CHIP callback message



BYTE SerialNumber[64];

INT SerialNumberLen;

INT MaxHardFrameSize; // 256 bytes is expected for modern rfid chips

INT MaxPlainDataSize; // 245 bytes ...

INT MaxCryptDataSize; // 223 bytes ...

INT MaxAirBaudRate; // 424 or 848 Kbps ...


// majorParam for VICOMP_MSG_..._MONITOR messages


#define VICOMP_START 1



// majorParam for VICOMP_MSG_RFID_CHIP message


#define VICOMP_CHIP_EXIT 0 // not used for native BT reader

// The first API function to be called at startup of the user app

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_Open( CHAR *com_port_name,

VICOMP_CALLBACK api_callback,

DWORD com_port_baud_rate = VICOMP_HIGH_BAUD );

// com_port_name: Bluetooth virtual COM port name (e.g. "COM7", "com23"):

// INCOMING for VPR451e and its ancestors,

// OUTGOING for VPR460e and its successors

// or

// USB virtual COM port name for USB readers

// com_port_baud_rate: VICOMP_HIGH_BAUD for all Bluetooth and USB >= VPR620e


// api_callback: A routine implemented by the user that will be called by the API.

// return: VICOMP_SUCCESS or VICOMP_ERROR. If specified port is already opened

// VICOMP_ERROR will be returned (could not open already opened port).

// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// This is very important function that should be called at startup and then,

// immediately, after completion of every RFID session performed by the user.

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_StartMonitor( INT chip_wait_time = VICOMP_CHIP_WAIT_TIME_NATIVE_DEFAULT );

// chip_wait_time: Time to wait for a chip after each swipe (reading MRZ data).

// After starting the monitor, OCR module is activated first,

// waiting for a swipe. After MRZ arrival, OCR module is turned

// off and RFID one started for chip_wait_time seconds.

// After the chip is detected RFID module is turned off and you

// get exclusive control over the communication.

// After you complete the work do not forget to use this function

// to restart monitoring process.

// If a chip is not detected during this time RFID module is

// turned off and OCR module activated automatically.

// If set to 0, only OCR input will be monitored and RFID module will

// not be activated after MRZ arrival. OCR monitor will be active

// all time and you don't have to restart it yourself.


// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// A general-purpose, PC/SC-like data transfer function. By means of this only

// function you can implement all the required communication. However, take a

// look at the next two routines that may be easier to use for simple, basic

// tasks.

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_SCardTransmit( BYTE *capdu,

DWORD capdu_len,

BYTE *rapdu,

DWORD *rapdu_len );

// capdu: Command APDU, a byte array to be send to the card as it is, without

// any additional formatting by the API. It is user responsibility to

// create appropriate CAPDUs for different purposes. Particularly, in

// case of protected documents (Secure Messaging protocol) you have to

// encrypt the command using some external cryptographic tools.

// capdu_len: Actual, total length (in bytes) of CAPDU

// rapdu: Response APDU, a byte array sent back by the card as a response for

// CAPDU. It is user responsibility to interprete this response properly.

// Particularly, in case of handling protected documents and performing

// Secure Messaging protocol you have to dencrypt and verify encrypted

// response using some external cryptographic tools.

// rapdu_len: Actual, total length (in bytes) of RAPDU. RAPDU should not be

// shorter than two bytes (Status Word SW = [SW1][SW2], usually

// SW1=0x90 SW2=0x00 in case of successfull processing).

// return: VICOMP_SUCCESS or VICOMP_ERROR. The API does not analyse SW1/SW2

// status word, it is your task. In other words, for example, you will

// get VICOMP_SUCCESS function return code while SW1=0x69 SW=0x82 that



// IMPORTANT NOTE: It is allowed for the length of capdu data block to be of any

// size (larger than single transfer data size). In this case the API internally

// performs so called command chaining, according to ISO.

// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// This is the first function to call after the chip is detected. You may not

// be able to select and read elementary files (data groups) without previous

// selection of the ICAO MRTD (ePassport) application.

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_SelectIcaoMrtdApp( VOID );


// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// Obviously, any file from the chip may be successfully read by using universal

// vicomp_native_SCardTransmit function (see above). However it is strongly

// suggested to use our special method that performs reading several times

// faster (some special Vicomp native boosting secrets). Note, there is no

// offset and/or byte count arguments, entire file is read by this routine.

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_ReadFileFast( BYTE *file_id,

BYTE *buf = NULL,

BYTE *ssc = NULL,

BYTE *k_enc = NULL,

BYTE *k_mac = NULL );

// file_id: Elementary file identifier (0x011F for EF.COM, 0x0101 for EF.DG1 etc.)

// buf: Memory buffer to receive data, if you supply NULL pointer you will get

// size in bytes of currently selected file on return. This may be useful

// to know the size of memory to allocate for data buffer.

// ssc, k_enc, k_mac: 8, 16, 16 bytes length memory buffers respectively.

// Cryptographic parameters to be used when executing

// Secure Messaging protocol (SM) for protected chips.

// You will get them after performing BAC/PACE/CA protocols.

// It is your responsibility to use appropriate external

// cryptographic tools for this purpose.

// Set them all to NULL to execute plain (not protected)

// transfers.

// return: VICOMP_SUCCESS or VICOMP_ERROR. However, there is a special case when

// you set buf to NULL. In this case the function returns total number

// of bytes contained in selected file (file size) or VICOMP_ERROR

// in case of failure.


// IMPORTANT NOTE: On return cryptographic parameters contain updated (current)

// values that you can use for successive calls.

// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// You CAN call this function anytime you want to stop monitor manually (rare

// cases in normal operation) but you HAVE to call it before calling

// vicomp_native_Close (next routine) on application shutdown if monitor is active.

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_StopMonitor( VOID );


// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// The last API function to be called before shutdown of the user app.

extern "C" int DLL_EXPORT __stdcall

vicomp_nativeapi_Close( VOID );

// return: VICOMP_SUCCESS or VICOMP_ERROR. If the port is already closed

// VICOMP_ERROR will be returned (could not close already closed port).

// -----------------------------------------------------------------------------

// ------------------------------------------------------------- VicompNativeAPI


Installing and Getting Ready to Use VicompHighAPI
VicompHighAPI (Vicomp High-Level Application Programming Interface) actually consists of two components:
1) VicompHighEngine (the core run-time worker that has to be installed in the system)

2) VicompHighSDK (a programming interface to access and control VicompHighEngine)

You have to get VicompHighEngine installation utility (instVicompHighEngine.exe) to arrange all necessary components on the developer or end user machine. If you are going to work with a general purpose version of the API just download the installation file from our web site (Downloads page). However, if you are going to use a special release (with some customer specific features) that is not available in public, you are suppose to get your private installation CD.
Regardless of the way you get the stuff, launch instVicompHighAPI.exe as an administrator of the machine and let the program run its default way. After successful completion take a look at the folder C:\Vicomp\HighEngine\API.

Note that all the VicompHighEngine executables (exes and DLLs) were located somewhere in the system (exact location is not important for you and may be changed in the future) while in the API folder you have just programming interface. Most important for you now are probably VicompApiBase.h and VicompHighAPI.pdf files.

Start your programming experience on the basis of appropriate sample code available at our site for Delphi/Pascal, VB/NET and C#/NET environments.

Of course, before you start experimenting with your application, it is assumed that the required Vicomp's reader is already installed in the system (get drivers and installation instructions from our web site).

VicompHighAPI Licensing Scheme

There are following six licensing levels that the API may be configured to execute:


This is the demonstration level that you get when downloading the API from our web site. It is fully functional. However, there are VicompHighAPI logo inserted into electronic images retrieved from the chip.


The API is limited to perform Basic Access Control and retrieve data available after BAC (DG1 and DG2). There is no any Vicomp logo inserted in face image (DG2).


The API is limited to perform Basic Access Control as well as Supplemental Access Control and retrieve data available after BAC/SAC (DG1 and DG2). There is no any Vicomp logo inserted in face image (DG2).


The API is limited to perform Basic Access Control and Extended Access Control version 1 and retrieve data available after BAC/EAC (DG1 and DG2 and DG3). There are no Vicomp logo inserted in face and fingerprint images (DG2, DG3).


The API is limited to perform Basic Access Control and Supplemental Access Control and Extended Access Control version 1 and retrieve data available after BAC/SAC/EAC (DG1 and DG2 and DG3). There are no Vicomp logo inserted in face and fingerprint images (DG2, DG3).

LEVEL3: VICOMP_LICENSE_EAC2 (RFU - Not yet fully implemented)

The API is not limited at all. It is able to perform Basic Access Control and Supplemental Access Control and Extended Access Control version 1 and Extended Access Control version 2 and retrieve data available after BAC/SAC/EAC1/EAC2 (DG1 and DG2 and DG3). There are no Vicomp logo inserted in face and fingerprint images (DG2, DG3).

As it was already mentioned, after downloading the API from our web site repository you get the license level DEMO with logo in images. If you want to upgrade your API configuration to some higher licensing level you have to send a special request to Vicomp Ltd. Find VicompLicenseRequest.bin file created after each usage of the API. Send it to Vicomp asking for the license key of the level you want. After an agreement concerning payment you will get a VicompLicenseKey.bin file dedicated only to the machine on which the request was generated. Copy this file to the API installation folder and you are done.
In case of buying a bundle of many licenses it is possible we can prepare a special API installation utility avoiding the need to supply individual requests for each user machine.

General Note About ICAO MRTD APP Data Groups
In general there may be sixteen data groups present in a chip containing ICAO MRTD Application (DG1-DG16). Not all of them are usually implemented. Most important data groups (elementary files) that you can find in modern eDocuments are following:
EF_DG1: electronic copy of optical MRZ

EF_DG2: document holder digital photograph (JPEG or JPEG-2000 image)

EF_DG3: document holder fingerprints (JPEG, JPEG-2000 or WSQ images)

EF_DG4: document holder iris (JPEG or JPEG-2000 image)

EF_DG7: document holder signature (JPEG, JPEG-2000 or WSQ image)

EF_DG11: additional (optional) data

EF_DG13: additional (optional) data

EF_DG14: Chip Authentication (CA) supporting file

EF_DG15: Active Authentication (AA) supporting file
There are also four important control files:
EF_CARDACCESS: PACE/SAC supporting file

EF_COM: The list of data groups present in a chip (chip contents)

EF_SOD: Passive Authentication (PA) supporting file

EF_CVCA: Terminal Authentication (TA) supporting file

Generally, when executing RFID reading session you will get all above data groups and control files in appropriate callbacks of the form:

1stParam = size of the EF_XXX in bytes

2ndParam = a pointer to memory buffer containing EF_XXX contents
where XXX denotes DG1, DG2, ... , CARDACCESS, COM, SOD and CVCA respectively.

However, there are some restrictions to above general scheme:

1) You will not get any image raw data group (DG2, DG3, DG4) when running the API with VICOMP_LICENSE_DEMO level (LEVEL0).
2) You will not get any sensitive image raw data group (DG3, DG4) when running the API below VICOMP_LICENSE_BAC_EAC1 level (LEVEL1e).
3) You will get all raw data groups (including DG3 and DG4) when running the API license level equal or above VICOMP_LICENSE_SAC_EAC1 (LEVEL2).

The basic concept of the API is an API-declared (and user-defined) callback function. The API executes this function to signal different events and exchange information and data with the application. See programming samples to learn how to implement the callback in different programming environments.
typedef INT ( __stdcall *VICOMP_CALLBACK ) (

UINT message,

UINT 1stParam,

INT 2ndParam );
As a general rule, with several exceptions, become accustomed to return following integer constants from your implementation of the message handler:
VICOMP_SUCCESS if a message was handled successfully

VICOMP_ERROR if any problem occurred to complete the handler successfully

VICOMP_SKIP if a message is not interesting for you and not handled at all
Again, as a general rule, with several exceptions, become accustomed that the first parameter is used to hold an integer value while the second one is usually used as a pointer indicating some memory location that you can read and/or write to. Do not be afraid, every time the memory buffer will be sufficient enough to gather the stuff API expects to get from you.

API Core Functions
Besides implementing and handling the very important callback mentioned above, there are only three core API functions you have to use each time you use the API. They are following:
extern "C" INT DLL_EXPORT __stdcall

vicomp_highapi_Start (

VICOMP_CALLBACK callback_func,

WORD reader_type,

CHAR *reader_com_name,

DWORD reader_com_baud = VICOMP_HIGH_BAUD,


WORD chip_wait_time = VICOMP_CHIP_WAIT_TIME_DEF );
This function must be called as the first step to activate the API engine and to be able to perform any further activity.
 Specify reader_type = VICOMP_PCSC_READER for our USB devices. Also, for USB readers, specify reader_com_baud = VICOMP_LOW_BAUD for VPR610e (and lower models) but VICOMP_HIGH_BAUD for all new models, starting from VPR620e. Set chip_wait_time to 0.
 Specify reader_type = VICOMP_NATIVE_READER for our Bluetooth devices. Also, for all Bluetooth readers, specify reader_com_baud = VICOMP_HIGH_BAUD. Set chip_wait_time to default 5 (seconds) to start with.
 Specify reader_type = VICOMP_FULLPAGE_READER for our USB PC/SC Full-Page scanner. Specify NULL (0) for reader_com_name.
Possible return values and their meaning:

retVal = -1: VicompHighEngine already started, must be stopped first to be started again

retVal = -2 : Required callback function address was not supplied (is NULL)

retVal = -3 : Invalid/unknown reader type specified

retVal = -5 : Problem opening OCR transmission channel

retVal = -6 : Problem starting OCR monitor

retVal = -7 : Problem opening RFID transmission channel

retVal = -8 : Problem starting RFID monitor

Additionally, on successful completion of the function, after the engine is started, you will get two callbacks with following arguments



2ndParam = pointer to memory buffer containing 5 bytes of engine version
byte 0: MajorVersion

byte 1: MinorVersion

byte 2: BuildNumber

byte 3: RevisionNumber

byte 4: SpecialRelease
If the pointer is 0 (NULL) there was a problem to retrieve version information from the API.

And the second callback:

  1   2   3   4

© 2016
wyślij wiadomość