turnkey/openpgp-card
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Some more edits for documentation.

Browse source
This commit is contained in:
Heiko Schaefer 2021-10-11 12:11:56 +02:00
parent 63576de817
commit f2b65e7880
1 changed files with 37 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
card-functionality/README.md
View file

@ -3,12 +3,15 @@ SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name>
SPDX-License-Identifier: MIT OR Apache-2.0 SPDX-License-Identifier: MIT OR Apache-2.0
--> -->
The main purpose of this test suite is to be able to test the behavior This test suite has two goals:
of different OpenPGP card implementation.
These tests rely partly on the card-app abstraction layer in 1) To test openpgp-card and its backends, as well as openpgp-card-sequoia.
openpgp-card. For crypto-operations, the higher level API 2) To be able to compare the behavior of different OpenPGP card
openpgp-card-sequoia (which relies on Sequoia PGP) is also used. implementations.
The tests are built mostly on top of the `card-app` abstraction layer in
`openpgp-card`. For crypto-operations, the higher level API
`openpgp-card-sequoia` (which relies on Sequoia PGP) is used.
# Building / Dependencies # Building / Dependencies
@ -24,14 +27,15 @@ Fedora 34:
These tests assert (and fail) in cases where a certain behavior is These tests assert (and fail) in cases where a certain behavior is
expected from all cards, and a card doesn't conform. expected from all cards, and a card doesn't conform.
However, in some aspects, card behavior is expected to diverge, and
it's not ok for us to just fail and reject the card's output, However, card behavior diverges from the spec in some cases.
even when it contradicts the OpenPGP card spec. It's not ok for us to just fail and reject the card's output, in some of
these cases, even when a card contradicts the OpenPGP card spec.
For such cases, these tests return a TestOutput (which is a For such cases, these tests return a TestOutput (which is a
Vec<TestResult>), to document the return values of the card in question. Vec<TestResult>), to document the return values of the card in question.
## Example for card-specific behavior ## Example for card-specific behavior that contradicts the spec
Yubikey 5 fails to handle the VERIFY command with empty data Yubikey 5 fails to handle the VERIFY command with empty data
(see OpenPGP card spec, 7.2.2: "If the command is called (see OpenPGP card spec, 7.2.2: "If the command is called
@ -55,7 +59,20 @@ systemctl start pcscd
(Alternatively, you could use the experimental scdaemon backend) (Alternatively, you could use the experimental scdaemon backend)
# Running tests against an emulated Gnuk via PC/SC # Running tests against emulated Gnuk via PC/SC
## About Gnuk
Gnuk is a free implementation of the OpenPGP card spec by
[Gniibe](https://www.gniibe.org/), see:
http://www.fsij.org/doc-gnuk/. (Gniibe also designs and produces open
hardware to run the Gnuk software on, see https://www.gniibe.org/tag/fst-01.html)
For our purposes, we will run the Gnuk code in "emulated" mode, meaning it
will run on our host, instead of on a USB-connected device (as one would
usually use Gnuk).
## Building Gnuk
Install additional dependencies (Debian 11: `# apt install make usbip`, Install additional dependencies (Debian 11: `# apt install make usbip`,
Fedora 34: `# dnf install make usbip`) Fedora 34: `# dnf install make usbip`)
@ -75,18 +92,19 @@ git checkout master
cd ../src cd ../src
``` ```
## Build the emulated Gnuk Now we can build the emulated Gnuk.
We aren't using KDF in our tests, so we disable Gnuk's default behavior We don't want to use KDF in our tests, so we disable Gnuk's default behavior
(by default, emulated Gnuk considers KDF "required") with the (by default, emulated Gnuk considers KDF "required") with the
"kdf_do=optional" variable. "kdf_do=optional" variable (I am not aware of any OpenPGP card that
requires KDF by default, so the tests currently don't use KDF).
``` ```
kdf_do=optional ./configure --target=GNU_LINUX --enable-factory-reset kdf_do=optional ./configure --target=GNU_LINUX --enable-factory-reset
make make
``` ```
## Run the emulated Gnuk ## Running the emulated Gnuk
Emulated Gnuk connects to the system via http://usbip.sourceforge.net/. Emulated Gnuk connects to the system via http://usbip.sourceforge.net/.
This means that we need to load the kernel module `vhci_hcd` to connect This means that we need to load the kernel module `vhci_hcd` to connect
@ -119,8 +137,8 @@ Scanning present readers...
## Run the card-functionality tests against the emulated Gnuk ## Run the card-functionality tests against the emulated Gnuk
Determine the ident of connected OpenPGP cards (and specifically of our First, we determine the ident of connected OpenPGP cards (and specifically of
emulated Gnuk instance): our emulated Gnuk instance):
``` ```
$ cargo run --bin list-cards $ cargo run --bin list-cards
@ -130,8 +148,8 @@ The following OpenPGP cards are connected to your system:
FFFE:F1420A7A FFFE:F1420A7A
``` ```
Edit the test config file in `config/test-cards.toml` to use this emulated The we edit the test config file in `config/test-cards.toml` to use this
Gnuk, e.g. like this: emulated Gnuk. The configuration should look like this:
``` ```
[card.gnuk_emu] [card.gnuk_emu]
@ -140,7 +158,7 @@ config.keygen = ["RSA2k/32", "Curve25519"]
config.import = ["data/rsa2k.sec", "data/rsa4k.sec", "data/25519.sec"] config.import = ["data/rsa2k.sec", "data/rsa4k.sec", "data/25519.sec"]
``` ```
Running the import and key generation tests: Now we can run the `card-functionality` tests, e.g. import and key generation:
``` ```
$ cargo run --bin import $ cargo run --bin import