mirror of
https://codeberg.org/openpgp/notes.git
synced 2024-11-26 01:22:06 +01:00
124 lines
5 KiB
Markdown
124 lines
5 KiB
Markdown
# 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.
|