From 4b201071973e9c2d08f2f382c38d5f6a02c18aad Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 26 Jul 2022 13:11:43 +0200 Subject: [PATCH] openpgp-card-tools documentation edits. - always show examples for interactive pin-entry first, as the default, - fix documentation error for 'pin set-admin', - misc minor edits. --- tools/README.md | 105 +++++++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 51 deletions(-) diff --git a/tools/README.md b/tools/README.md index e702ca8..227dcf4 100644 --- a/tools/README.md +++ b/tools/README.md @@ -293,12 +293,12 @@ used in a smartcard reader that has a pinpad. #### Set touch policy -Cards can require a type of confirmation before cryptographic operations are performed -(the feature is often implemented as a mechanical button on the card). +Cards can require confirmation by the user before cryptographic operations are performed +(this confirmation feature is often implemented as a mechanical button on the card). -Not all cards implement this feature. +However, not all cards implement this feature. -Rationale: when the card requires touch confirmation, an attacker who gains control of the user's host computer +Rationale: when a card requires touch confirmation, an attacker who gains control of the user's host computer cannot perform cryptographic operations on the card at will - even after they learn the user's PINs. This feature is configured per key slot. The user can choose to require (or not require) touch confirmation separately @@ -324,12 +324,6 @@ Some cards only support a subset of these. #### Set cardholder name -Set cardholder name, with pin file: - -``` -$ opgpcard admin -c ABCD:01234567 -P name "Alice Adams" -``` - Set cardholder name, with interactive PIN input (either on the host computer, or via a smartcard reader pinpad): @@ -337,28 +331,36 @@ Set cardholder name, with interactive PIN input $ opgpcard admin -c ABCD:01234567 name "Alice Adams" ``` +Set cardholder name, with a pin file, non-interactively: + +``` +$ opgpcard admin -c ABCD:01234567 -P name "Alice Adams" +``` + #### Set cardholder URL -``` -$ opgpcard admin -c ABCD:01234567 -P url "https://key.url.example" -``` - -or interactively - ``` $ opgpcard admin -c ABCD:01234567 url "https://key.url.example" ``` +or non-interactively: + +``` +$ opgpcard admin -c ABCD:01234567 -P url "https://key.url.example" +``` + ##### Using `keys.openpgp.org` for the URL -If you have uploaded (or plan to upload) your certificate to the `keys.openpgp.org` keyserver, you can set the URL -field on your card to point to that server: +If you have uploaded (or plan to upload) your certificate (your public key) to the `keys.openpgp.org` keyserver, +you can point the URL field on your card there: If the fingerprint of your certificate is `0123456789ABCDEF0123456789ABCDEF01234567`, then you can set the URL as follows: -`$ opgpcard admin -c FFFE:12345678 url "https://keys.openpgp.org/vks/v1/by-fingerprint/0123456789ABCDEF0123456789ABCDEF01234567"` +``` +$ opgpcard admin -c FFFE:12345678 url "https://keys.openpgp.org/vks/v1/by-fingerprint/0123456789ABCDEF0123456789ABCDEF01234567" +``` ##### Other URLs @@ -375,19 +377,19 @@ You can use any URL that serves your public key, including a link to your certif Import private key onto a card. This works if at most one (sub)key per role (sign, decrypt, auth) exists in `key.priv`: -``` -$ opgpcard admin -c ABCD:01234567 -P import key.priv -``` - -or interactively - ``` $ opgpcard admin -c ABCD:01234567 import key.priv ``` +or non-interactively + +``` +$ opgpcard admin -c ABCD:01234567 -P import key.priv +``` + Import private key onto a card while explicitly selecting subkeys. Explicitly specified fingerprints are necessary if more than one subkey exists -in `key.priv` for any role (note: spaces in fingerprints are ignored). +in `key.priv` for any role (spaces in fingerprints are ignored). ``` $ opgpcard admin -c ABCD:01234567 -P import key.priv \ @@ -406,16 +408,16 @@ Key generation needs both the Admin PIN and the User PIN (the User PIN is needed The User PIN can be provided with the `-p `, or interactively on the host computer or via the smartcard reader pinpad. -``` -$ opgpcard admin -c ABCD:01234567 -P generate -p -o 25519 -``` - -or interactively - ``` $ opgpcard admin -c ABCD:01234567 generate -o 25519 ``` +or non-interactively + +``` +$ opgpcard admin -c ABCD:01234567 -P generate -p -o 25519 +``` + Output will look like: ``` @@ -452,35 +454,35 @@ x3z8hDoRKAU= For now, this tool only supports creating detached signatures, like this (if no input file is set, stdin is read): -``` -$ opgpcard sign --detached -c ABCD:01234567 -p -``` - -or interactively - ``` $ opgpcard sign --detached -c ABCD:01234567 ``` +or non-interactively + +``` +$ opgpcard sign --detached -c ABCD:01234567 -p +``` + ### Decrypting Decryption using a card (if no input file is set, stdin is read): -``` -$ opgpcard decrypt -c ABCD:01234567 -p -``` - -or interactively - ``` $ opgpcard decrypt -c ABCD:01234567 ``` +or non-interactively + +``` +$ opgpcard decrypt -c ABCD:01234567 -p +``` + ### PIN management OpenPGP cards use PINs (numerical passwords) to verify that a user is allowed to perform an operation. -To use the cryptographic operations on a card (such as decryption or signing), the *User PIN* is required. +To use cryptographic operations on a card (such as decryption or signing), the *User PIN* is required. To configure a card (for example to import OpenPGP key material into the card's key slots), the *Admin PIN* is needed. @@ -536,13 +538,14 @@ $ opgpcard pin -c ABCD:01234567 set-admin For non-interactive PIN change: ``` -$ opgpcard pin -c ABCD:01234567 set-admin -p -q +$ opgpcard pin -c ABCD:01234567 set-admin -P -Q ``` #### Reset User PIN with Admin PIN The User PIN can be reset to a different (or the same) PIN by providing the Admin PIN. -This is possible at any time, including when a wrong User PIN has been entered too often, and the card refuses to accept the User PIN any more. +This is possible at any time, including when a wrong User PIN has been entered too often, +and the card refuses to accept the User PIN anymore. ``` $ opgpcard pin -c ABCD:01234567 reset-user @@ -607,7 +610,7 @@ When using a shell like , you can pass User- and/or Admin PINs via file-descriptors (instead of from a file on disk): ``` -$ opgpcard sign --detached -c ABCD:01234567 -p /dev/fd/3 -s 3<<<123456 +$ opgpcard sign --detached -c ABCD:01234567 -p /dev/fd/3 3<<<123456 ``` ``` @@ -630,7 +633,7 @@ This feature is available on YubiKey 5 devices with firmware version 5.2 or newe #### Attestation key/certificate -*"The YubiKey is pre-loaded with an attestation certificate and matching attestation key issued by the Yubico CA. +*"The YubiKey is preloaded with an attestation certificate and matching attestation key issued by the Yubico CA. The template and key are replaceable, which permits an individual or organization to issue attestations verifiable with their own CA if they prefer. If replaced, the Yubico template can never be restored."* @@ -657,12 +660,12 @@ It's not possible to generate attestation statements for key material that was i To generate an attestation statement, run: ``` -$ opgpcard attestation generate --key SIG -c 0006:12345678 +$ opgpcard attestation generate --key SIG -c 0006:01234567 ``` Supported values for `--key` are `SIG`, `DEC` and `AUT`. -Generation of an attestation requires the User PIN. By default it also requires touch confirmation +Generation of an attestation requires the User PIN. By default, it also requires touch confirmation (the touch policy configuration for the attestation key slot is set to `On` by default). #### Viewing an attestation statement