---
description: >-
  Web application security transmitting PIN and how the device keys are
  managemed
---

# PIN Encryption and Device Key Management

## Introduction

When a web application is sending the PIN to the T1C-API, the PIN is by default encrypted using the public key of the running instance of the local API service.

The public key is generated upon installation or prior to any PIN related used case; this is done in the key-store of the local operating system or persisted on a safe location on disk. We can store the key-pair in the local folder, even for a shared environment, as the PIN encryption merely protects the communication between the browser and the local service (T1C-API).

The same certificate is used in a key-exchange algorithm with the DS. This is done in the use case for registration of new devices. It’s a use case where each installation registeres on the DS in order to be ‘known’ in the T1C ecosystem. Mainly for security and/or billing purpose.

## Considerations

* Entering a PIN using a pin-pad enabled card readers is not encrypted as the PIN is entered directly on the pin-pad device. Technically, a web application can send the PIN along with any verify-pin, authentication or signing request targeting a pin-pad reader. If this is not the case, the **t1c-sdk-js** is required to encrypt any PIN transfer
* The CCID/pin-pad enabled reader properties are correctly managed and responded to the web application; The pin-pad reader **ALWAYS** takes precedence (see [PIN Handling](https://app.gitbook.com/@t1t/s/t1c-api/~/drafts/-MaSs7bv4LO6M072TYpa/v/v3.5.0/concepts/pin-handling))
* Entering a PIN using the operating system dialog is not encrypted through the Trust1Connector, as the PIN is entered in a different context, and separately from the web/native application

## Approach

In the context of the **Trust1Connector**, the browser context is **UNTRUSTED** and thus the PIN entry through a 3rd Party web application should be protected. To do so, the local service is starting up, verifying if a keys-pair has been created for the local service. We refer to this as the **'device key-pair'**.

* on startup, the service verifies if the keys have been created; if NOT, a new key-pair is created
* the application can ask for a key-rotation, when so, the device will initialise the key-pair by re-issuing a new key-pair for the local device
* when requesting the device-key, if no keys are present, new keys will be generated **implicitly**; if the keys are present, the public key is responded with

The T1C-Rust-API exposes an /encrypt endpoint, which should only be used for testing purpose. The T1C-Rust-API can be started in DEBUG mode, when this is the case, the /decrypt endpoint can be used as well. To start the T1C-Rust-API in development/debug:

```
$ ./trust1connector-api -d
```

### Sequence Diagram - PIN Encryption through Web Application

&#x20;

![](https://3092524840-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M7HCvAhXTAbT3Blaa86%2F-MaNr48LzXarRUbwpDLl%2F-MaTNqmT68Jqde9DnGDd%2FPIN%20Encryption%20browser-api.jpg?alt=media\&token=37138082-d487-4f38-9e9e-1515c7e96aaa)
