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.

curl --location --request POST 'https://t1c.t1t.io:51883/v3/modules/beid/apps/token/readers/9b28267029efca80/sign?bulk=true' \
--header 'X-CSRF-Token: t1c-js' \
--header 'Content-Type: application/json' \
--data-raw '{
	"algorithm": "sha256",
	"data": "Vc1GgP6EWiZ4BszrolrVvN+YfQCKWhbNFhcTyWxjL3A="
}'

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'