T1C-API
Search…
PIN Handling
Implementation logic for PIN handling in the Trust1Connector API

Introduction

For the user to sign, authenticate and verify transactions/documents, besides having a valid credential ('what you have'), an additional PIN entry is needed ('what you know').
A user can enter his PIN in differents contexts. Depending on the security policy enforced from the web/native application, some context can be forced to use.

PIN Context - Application level

Using a PIN dialog from the application level is considered less secure. This is because a PIN is normally send out to a service in clear text, on the operating device. For the Trust1Connector, to make the transaction more secure, the PIN is encrypted using the public key of the device.
The Trust1Connector secures the exchange of PIN between the browser and the local service
The application is responsible to provide the PIN information in the body of a request.

PIN Context - Operating system level

Using the native dialogs from the underlying operating system, the PIN entry is completely separated from the browser or application context. This is considered more secure as the PIN is entered on a separate thread on the system level. The web or native application demands for a use case where a PIN must be entered, but the user enters the PIN in a sandboxed and system level dialog.
The Trust1Connector separates PIN input from the browser or application context

PIN Context - Reader level

Not all readers have pin-pad capabilities. A reader with pin-pad capabilities can be detected by the underlying sandbox. The sandbox implement a reader API, mini driver or other hardware interfaces. When the reader is determined to be a pin-pad reader, the user can enter the pin using the pin entry methods on the hardware device. Typically this is a number pad, with an LCD window.
The Trust1Connector implements reader specific capabilities, depending on the reader, one of them is the ability to change the language on the reader upon PIN entry or other transactions.
Entering the PIN on a pin-pad reader is considered the most secure, as the PIN on the pin-pad reader lives only on the hardware device for the lifetime of the transaction. The pin-pad reader context is NOT shared with the operating system or the browser, web application or native application.
Trust1Connector support PIN entry on pin-pad readers besides custom communication commands

Use Cases

The following use cases allow for a PIN property:
    Sign hash
    Bulk sign hash
    Verify PIN
    Authenticate using PIN

Bulk Use cases

The only use case where bulk transactions are supported is the sign request for transactions or documents. A bulk transaction is a transaction where you want to avoid the user entering multiple times it's PIN. Independent of the the described use cases, and only for the sign request, the application can instruct the Trust1Connector to enable bulk sign.
On behalf of the application, the Trust1Connector will persist in volatile memory, and for a short time, the PIN provided by the application, or the PIN received from the OS dialog.
A pin-pad reader does not support the bulk sign use case. When using a pin-pad enabled reader, you MUST ask the user to enter his PIN for EACH transaction
To enable the bulk property for a sign request, a query-parameter 'bulk' must be provided.
1
curl --location --request POST 'https://t1c.t1t.io:51883/v3/modules/beid/apps/token/readers/9b28267029efca80/sign?bulk=true' \
2
--header 'X-CSRF-Token: t1c-js' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"algorithm": "sha256",
6
"data": "Vc1GgP6EWiZ4BszrolrVvN+YfQCKWhbNFhcTyWxjL3A="
7
}'
Copied!

Overview

Use Case
Description
Authenticate using pin-pad
User enters PIN on pin-pad for authentication
Authenticate using web application dialog
User enters PIN in the web application dialog (external to the T1C)
Authenticate using OS dialog
User enters PIN in the OS triggered input dialog
Sign a hash using pin-pad
User enters PIN on pin-pad for signing a hash
Sign a hash using web application dialog
User enters PIN in the web application dialog for signing a hash (external to the T1C)
Sign multiple hashes using web application dialog
User enters PIN in the web application dialog to start signing multiple hashes (external to T1C, T1C managed the PIN cache)
Sign a hash using OS dialog
User enters PIN in the OS triggered input dialog for signing a hash
Sign multiple hashes using the OS dialog
User enters PIN in the OS triggered input dialog for signing multiple hashes (owned by T1C, OS dialog in different context than the web application)
Verify PIN using pin-pad
User enters PIN on pin-pad for verification
Verify PIN using web application dialog
User enters PIN in the web application dialog (external to the T1C)
Verify PIN using OS dialog
User enters PIN in the OS triggered input dialog

Rules

Rule Set

General rule of Thumb

    when the application is not providing a PIN
      force use of pin-pad capabilities
      fallback on system dialog for PIN entry
      only for sign request - reuse cached value if enabled by the application
    when the application provides a PIN
      takes precedence on system dialog (even when set, PIN from request will be used)
      clears implicitly the cache
      pin-pad is still forced (even when PIN is provided, user must enter PIN on pin-pad)

Derived from the basic principles

    If reader is a pin-pad
      force use the of pin-pad capabilities of the reader
    If reader is NOT a pin-pad
      Check if the body of the use case has a PIN value
        YES =>
          Decrypt PIN
          Implicit reset cached PIN or IF bulk sign is set → set new value
          Sign using decrypted PIN provided in request (takes precedent on the cached PIN)
        NO => Is bulk sign enabled (check if PIN is cached):
          YES => Use cached PIN
          NO =>
            Show OS Dialog (except when explicitly set on false)
            If bulk sign is set → set value in cache if not → reset the cache implicitly

Flow Diagram

Note that when a PIN is provided, but the decryption fails, the T1C will try to fallback on the OS dialog, except when explicitly set to 'false'
Last modified 4mo ago