vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2024-11-22 07:32:05 +01:00
Code Issues Projects Releases Packages Wiki Activity
openpgp-notes/card/openpgp-card-interactions.md
Heiko Schaefer cc690f7b21
Notes on user interaction with OpenPGP cards
2023-11-09 13:50:52 +01:00

5 KiB
Raw Blame History

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.