Add documentation, in particular for running the tests against emulated Gnuk.

card-functionality/README.md

@@ -3,26 +3,149 @@ SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name>
 SPDX-License-Identifier: MIT OR Apache-2.0
 -->
 
-These tests rely mainly on the card-app abstraction layer in
-openpgp-card. However, for crypto-operations, higher level APIs and
-Sequoia PGP are used.
-
 The main purpose of this test suite is to be able to test the behavior
 of different OpenPGP card implementation.
 
+These tests rely partly on the card-app abstraction layer in
+openpgp-card. For crypto-operations, the higher level API 
+openpgp-card-sequoia (which relies on Sequoia PGP) is also used.
+
+
+# Building / Dependencies
+
+To build this crate on Debian 11, you need to install 
+
+`apt install rustc libpcsclite-dev pkg-config nettle-dev clang libclang-dev`
+
+Fedora 34:
+`dnf install rustc cargo pcsc-lite-devel pkg-config nettle-devel clang clang-devel`
+
+# Purpose
+
 These tests assert (and fail) in cases where a certain behavior is
 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.
+it's not ok for us to just fail and reject the card's output,
-Even when it contradicts the OpenPGP card spec.
+even when it 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.
 
-e.g.: the Yubikey 5 fails to handle the VERIFY command with empty data
+## Example for card-specific behavior
+
+Yubikey 5 fails to handle the VERIFY command with empty data
 (see OpenPGP card spec, 7.2.2: "If the command is called
 without data, the actual access status of the addressed password is
 returned or the access status is set to 'not verified'").
 
 The Yubikey 5 erroneously returns Status 0x6a80 ("Incorrect parameters in
 the command data field").
+
+
+# Running
+
+To access a card via pcsc, we need to install and start `pcscd`.
+
+```
+apt install pcscd
+systemctl enable pcscd
+systemctl start pcscd
+```
+
+(Alternatively, you could use the experimental scdaemon backend)
+
+
+# Running tests against an emulated Gnuk via PC/SC
+
+Install additional dependencies (Debian 11: `# apt install make usbip`,
+Fedora 34: `# dnf install make usbip`)
+
+We'll use the stable 1.2 branch of Gnuk, with the latest patches for 
+chopstx (which are necessary for emulated Gnuk to work with PC/SC).
+
+Get the Gnuk source code:
+
+```
+git clone https://git.gniibe.org/cgit/gnuk/gnuk.git/
+cd gnuk
+git checkout STABLE-BRANCH-1-2
+git submodule update --init
+cd chopstx
+git checkout master
+cd ../src
+```
+
+## Build the emulated Gnuk
+
+We aren't using KDF in our tests, so we disable Gnuk's default behavior 
+(by default, emulated Gnuk considers KDF "required") with the 
+"kdf_do=optional" variable.
+
+```
+kdf_do=optional ./configure --target=GNU_LINUX --enable-factory-reset
+make
+```
+
+## Run the emulated Gnuk
+
+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 
+to a running emulated Gnuk instance.
+
+First, we start the emulated Gnuk from a non-root account:
+
+```
+./build/gnuk --vidpid=234b:0000
+```
+
+Then, as root, we attach to the emulated Gnuk device:
+
+```
+# modprobe vhci_hcd
+# usbip attach -r 127.0.0.1 -b 1-1
+```
+
+Afterwards, emulated Gnuk is connected to the system.
+We can now talk to it, e.g. we can look it up with `pcsc_scan`:
+
+```
+$ pcsc_scan
+Using reader plug'n play mechanism
+Scanning present readers...
+[..]
+2: Free Software Initiative of Japan Gnuk (FSIJ-1.2.18-EMULATED) 00 00
+[..]
+```
+
+## Run the card-functionality tests against the emulated Gnuk
+
+Determine the ident of connected OpenPGP cards (and specifically of our 
+emulated Gnuk instance):
+
+```
+$ cargo run --bin list-cards
+[...]
+
+The following OpenPGP cards are connected to your system:
+ FFFE:F1420A7A
+```
+
+Edit the test config file in `config/test-cards.toml` to use this emulated 
+Gnuk, e.g. like this:
+
+```
+[card.gnuk_emu]
+backend.pcsc = "FFFE:F1420A7A"
+config.keygen = ["RSA2k/32", "Curve25519"]
+config.import = ["data/rsa2k.sec", "data/rsa4k.sec", "data/25519.sec"]
+```
+
+Running the import and key generation tests:
+
+```
+$ cargo run --bin import
+[...]
+
+$ cargo run --bin keygen
+[...]
+```