Notes on user interaction with OpenPGP cards

card/openpgp-card-interactions.md

@@ -0,0 +1,124 @@
+# 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.