# Notes on OpenPGP card user interactions

This document discusses user interactions with OpenPGP card devices, with focus
on use of OpenPGP card devices in the context of the sequoia-keystore.

There are three common mechanisms for user interaction with cards:

- PIN entry:
  - via the host computer
  - via a numerical keypad on a card reader
- Touch confirmation on OpenPGP card devices


# OpenPGP card PINs

The OpenPGP card specification (version 3.4.1) describes two main PINs:

> The OpenPGP application uses two local passwords for user verification,
> called PW. PW1 is also called user-password and PW3 admin-password.
> PW1 (user) is the password used for signing and decryption operations,
> PW3 (admin) is the security officers password.

In addition, many cards support a third password, the `resetting code`:

> To reset PW1 in the case of a blocked error counter, a special Resetting
> Code (RC) is introduced. The issuer should give the RC to the user together
> with his password.

In this document, we will only deal with one of these three passwords: `PW1`.
Only `PW1` is relevant for the operations that the keystore supports.

We will refer to `PW1` as the `User PIN`.


## Presenting the User PIN to the card

The User PIN needs to be presented to the card before performing operations
that use the secret key material.

Cards distinguish two different modes of presenting the User PIN:
- Presenting the User PIN for signing (`PW1 with P2 = 81`)
- Presenting the User PIN for other functions (`PW1 with P2 = 82`)

### User PIN for signing

Presenting the User PIN for signing can either enable
- exactly one signing operation, or
- unlimited signing operations.

Users can choose between these two modes in `PW status Bytes`, byte 1.

### User PIN for other functions

Presenting the User PIN for 'other functions' enables unlimited use of
the decryption key slot and unlimited use of the authentication key slot.

## Presenting the User PIN via the host computer

It's always possible to present the User PIN to cards directly from the host
computer. An application can ask the user to enter the User PIN on the host
computer, and present the User PIN to the card.

This has the downside that on an untrusted computer, that computer learns the
User PIN.

## Presenting the User PIN via a PIN pad on the card reader

When the user uses an OpenPGP card in a card reader that has a physical
PIN pad, an application can choose to use the PIN pad to present the User PIN
to the OpenPGP card application, instead of asking the user to enter the PIN
on the host computer.

This has the benefit that a potentially untrustworthy computer doesn't get
access to the User PIN. It has the downside that the application is not able
to cache the User PIN on behalf of the user.

Card readers will typically signal the need for PIN entry with a beep.
However applications should probably display information to the user
explaining which PIN is needed, and why it is needed.

Applications will typically explicitly trigger PIN entry, so it's clear in
the control flow, when a notification is needed.

# Touch confirmation

See 'User Interaction' in the OpenPGP card spec for some details (and
https://gitlab.com/openpgp-card/openpgp-card/-/tree/main/tools#set-touch-policy
for documentation of the user perspective).

Some OpenPGP card devices (including Gnuk, and the Yubikey 4 and 5) can
make cryptographic operations contingent on a 'User Interaction'.
This interaction typically consists of touching a button. (There are other
possibilities, e.g. some Gnuk hardware implements user interaction with
a sensor that detects a magnetic field).

In this document we'll ignore implementation details of the input method,
and refer to this user interaction as 'touch confirmation'.

Different cards offer different levels of support for touch confirmation.
Typically, touch confirmation can be configured per key slot. The user can
configure the card to either require, or not require, touch confirmation
for cryptographic operations. Some cards additionally support a 'cached'
mode, where one touch is valid for a number of cryptographic operations
within a short window of time (Yubikey specifies 15 seconds).

The need for touch confirmation is often hard to notice, for users.
Yubikey devices have an LED that blinks, when touch is required. However,
this is easy to miss, even for advanced users.

Applications should signal to users when and why touch confirmation is needed.

*Unlike PIN entry (which applications trigger explicitly, before running a
cryptographic operation on the card), when touch confirmation is enabled, it
is required implicitly by cards, when applications use cryptographic
operations.*

# Implementing notifications for PIN pad entry and touch confirmation with `openpgp-card-sequoia`

The `openpgp-card-sequoia` library accepts (separate) callback functions as
parameters for PIN pad entry and for touch confirmation.

By supplying these callback functions, applications can implement
notifications to show the user when, how, and why they need to interact
with a card.