Notes on user interaction with OpenPGP cards
This commit is contained in:
Heiko Schaefer
commit
cc690f7b21
|
|
@ -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.
|
||||
Loading…
Reference in New Issue