Implementation logic for PIN handling in the Trust1Connector API
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
The following use cases allow for a PIN property:
Bulk sign hash
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'\