# Bulk Signing Capability

## Introduction

The Trust1Connector provides different ways of applying a digital signature on a hash. The hash can come from a dematerialised document, a transaction or any other content hash. Upon applying the signature, a PIN is requested from the user (something the user 'knows', besides something the user 'has/owns'). Applying the PIN can be done in several ways:

* **using a pin-pad reader** (user interaction in the context of the reader)
* **entering the pin in an OS owned pin dialog** (user interaction in the context of the operating system)
* **entering the pin in the web application** (user interaction in the context of the web application)

The above mentioned use cases, have a different level of security implication, ordered from ‘most’ secure to 'less’ secure. In order to avoid PIN visibility in the browser, additional functionalities (not in this scope) provide a mean for PIN encryption (which only make sense entering the PIN in the web application).

> Bulk signing comes in the picture, when a user is acting in a use case with multiple hashes (documents, transactions, …). This requires the user to enter his pin ('the user interaction for applying a digital signature') multiple times.

This can annoy users, therefor the T1C provides a mean to persist temporary the PIN in a stateful way on the stateless API interface. This is done by sharing the PIN, in a safe way, between one or more use cases. As the use case is defined by the consuming application, the consuming application is responsible to SET or RESET the pin throughout the different use cases.

{% hint style="info" %}
Bulk signing applies only on the digital signature request. The verify-pin or authenticate does not support bulk application of a user PIN.
{% endhint %}

## How-To

### Start a Bulk Signature Request

To trigger a bulk-sign operation, add the query-parameter 'bulk' with a value of 'true' to the request:

```
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="
}'
```

In the example above, no PIN is provided, this means that the fallback procedure will be triggered. The fallback in this scenario is the operating system PIN dialog which will be triggered. 

![os Dialog when no PIN is provided in request](https://1926565183-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M7HCvAhXTAbT3Blaa86%2F-MaTPQXbKoeqaid9yVnj%2F-MaTR3pc0E6Yc7MkEjzC%2FScreenshot%202021-05-24%20at%2014.53.45.png?alt=media\&token=3e7cb5ea-3c4f-46c3-8941-e1d6c4e2f37b)

After entering the PIN in the os Dialog, the PIN will be persisted in the volatile part of the device's memory. 

{% hint style="info" %}
More information on PIN handling can be found on the following link: [PIN Handling](https://app.gitbook.com/@t1t/s/t1c-api/~/drafts/-MaTPlG7V1ypYdbEI-Xs/v/v3.5.0/concepts/pin-handling)
{% endhint %}

For each subsequent request, with the availability of the 'bulk' query-parameter with value 'true', the user will not need to enter its PIN code over and over again. 

### Clear the Cache

The cache (or volatile memory) is cleared when the following occurs:

#### Bulk is explicitly set to false

When the query-parameter 'bulk' is set to 'false', the pin will be ignored from the cache. The cache will be additionally cleared, and the memory freed.

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

#### Sign Request contains a new PIN value

When the upcoming signature request contains a 'pin' property, the cache will be implicitly cleared, and the cached PIN will become unavailable. The new provided PIN (encrypted off course), will be decrypted and used upon applying the signature.

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

#### Explicit Reset Cache

A web/native application can explicitly clear the cache. The cache will free up the allocated volatile memory, and will clear the cache state.

```
curl --location --request GET 'https://t1c.t1t.io:51883/v3/modules/beid/apps/token/reset-bulk-pin' \
--header 'X-CSRF-Token: t1c-js' \
--data-raw ''
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://t1t.gitbook.io/t1c-api/concepts/bulk-signing-capability.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.