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.
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'
Last updated
Was this helpful?