commit cc690f7b211083bf22c5fd6f5b3a5728503e46bc Author: Heiko Schaefer Date: Thu Nov 9 13:50:52 2023 +0100 Notes on user interaction with OpenPGP cards diff --git a/card/openpgp-card-interactions.md b/card/openpgp-card-interactions.md new file mode 100644 index 0000000..3a59dbc --- /dev/null +++ b/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.