QR Code

It is possible to perform identification on the iDFace device through previously registered QR Codes. QR Codes are stored as objects and must be created and modified following the same premises as other objects via API.

The QR Codes identification can be performed through the Control iD's QR Code readers, being them the USB model and the Wiegand model. Furthermore, for the iDFace facial device, the identification can be performed through the device's cameras, but if you choose to use external readers, these also are supported by the device.

Operation mode

QR Code recognition can be used in three modes.

In Numeric Only Mode (Standard) the QR Code content must be 64 bits numeric and, in addition, the QR Code will be saved as an object of type cards.

In Hexadecimal Numeric Mode the QR Code content must be 64 bits hexadecimal numeric and its value will be interpreted by the device as decimal numeric. In addition, the QR Code will be saved as an object of type cards.

In Alphanumeric Mode alphanumeric characters are accepted in the representation of the QR Code and the object used for storage will be of type qrcodes. This mode is only supported by Access Line V5 devices (devices with 13-digit serial numbers) using an external USB QR Code Reader, or by the iDFace, using the device's cameras. The iDFace is also compatible with an external USB QR Code Reader. Wiegand QR Code Readers are not supported in this mode.

To change the operating mode, you must first change the module according to the equipment used. Access Line V5 devices use the barras module, while the iDFace (Access Line V6) uses the face_id module. After this configuration you must change the value of the parameter qrcode_legacy_mode_enabled parameter. If it's set to "0", the Alphanumeric Mode will be enabled, if its value is "1", Numeric Only Mode will be enable, and if its value is "2", Hexadecimal Numeric Mode will be used.

Request example for iDFace (Access Line V6)

Changes the QR Code's operating mode:

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        "face_id": {
            "qrcode_legacy_mode_enabled": "0"
        }
    })
});

Request example for Access Line V5 devices

Changes the QR Code's operating mode:

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        "barras": {
            "qrcode_legacy_mode_enabled": "0"
        }
    })
});

Dynamic QR Code

Access control devices are able to perform dynamic QR Code identification based on TOTP - timed one-time password logic.

TOTP

The TOTP concept represents the generation of temporary and periodically changed codes which can only be used once.

It is an extension of OTP one-time password logic, in which code renewal is time based and, thus, the validity of each code is restricted to a time interval called time-step window.

To be valid for TOTP, OTP access codes are generated through two components: an access key, representing a user or an access credential, and the time-step window in which the code is generated.

To develop a correct TOTP application, it is recommended for any interested integrator to make use of a TOTP library which follows the specification described in RFC6238.

Device's TOTP settings

The following parameters should be set in order to enable the usage of dynamic QR Codes.

totp_enabled: enables TOTP for temporary code validation. It can be set to either 0 (disabled) or 1 (enabled).
totp_window_size: time interval for TOTP's time-step window in seconds applied to code renewal.
totp_window_num: number of time-step windows to be used in code validations attempts.
totp_single_use: determines if the card_value can be used only once or if it will be kept valid for multiple usage. Values are 1 (single usage) or 0 (multiple usage).
totp_tz_offset: value representing local time zone offset in seconds.

Attention: the value set to totp_single_use affects only the enrolled card_value, which is a component in the QR Code. The time component, which references the current window's OTP code, will always be for single use. The QR Code content composition is better explained below.

Attention: the value configured in totp_tz_offset exists to compensate synchronization problems between the device and the server due to time zone settings. If no problem regarding synchronization happens, it can be left in its default value 0.

Generating a dynamic QR Code

In order to use dynamic QR Codes in our devices, it should be set to use Numeric Only Mode, as explained in the section in the beginning of this page.

User access credentials are based in two values:

card_value: numeric code to identify the user, equivalent to an access card number. This code must not be greater than 40 bits (5 bytes).
secret: hash code to be generated by the access control system and can be used as an identifier of the current access or of the system itself.

Both values should be enrolled to the user in the table cards, as a regular access card.

The request below enrolls ficticial credentials for a user with id 1:

$.ajax({
  url: "/create_objects.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({
    object: "cards",
    values: [
        {
            value: 819876543210,
            user_id: 1,
            secret: '8ae30f'
        }
    ]
  })
});

After the credentials enrollment, the parameter secret should be used as the key for generating an OTP temporary through the TOTP library. This code must be no longer than 24 bits (3 bytes).

The access QR Code's data is a 64 bit string concatenating two values. The first 24 bits contain the temporary OTP code of the current window and the last 40 bits contain the card value enrolled for the user.

After the emission of the QR, the user will be able to use it during a limited time interval, based on the time-step window size which must be equally configured between the device and the server.

Based on the enrolled credentials, the device will identify the user and then validate the code OTP received through the QR Code generating its own OTP code using the current window and the same secret value.

The exact duration of the validity interval for an OTP code depends on both the window duration (totp_window_size) and the number of windows configured (totp_window_num).

Example: if the number of windows used for validation has the value 5, the device will try to validate the received OTP code comparing it to values generated using the current window, two windows before and two windows after it. By doing this, we intend to avoid validation errors caused by small synchronization differences between the server and the device.