No description
Find a file
2023-03-08 14:31:38 -05:00
.github/workflows add nix support 2023-03-08 12:16:38 -05:00
.reuse Set CC0-1.0 license for debian packaging artifacts 2022-07-16 12:27:21 +02:00
card-functionality Fix clippy lints: directly use variables in format! strings 2023-02-02 09:09:47 +01:00
LICENSES Initial commit 2021-06-30 22:29:23 +02:00
openpgp-card Don't print application ID twice. 2023-02-24 00:49:26 +01:00
openpgp-card-examples remove "use sequoia_openpgp as openpgp;" pattern 2022-11-03 14:43:28 +01:00
openpgp-card-sequoia Release openpgp-card-sequoia 0.1.1 2023-02-14 17:52:34 +01:00
pcsc Fix clippy lints: directly use variables in format! strings 2023-02-02 09:09:47 +01:00
scdc Fix clippy lints: directly use variables in format! strings 2023-02-02 09:09:47 +01:00
tools Adjust README and subplot test to fix previously wrong application ID format. 2023-03-06 14:41:54 +01:00
.envrc add nix support 2023-03-08 12:16:38 -05:00
.gitignore add nix support 2023-03-08 12:16:38 -05:00
.gitlab-ci.yml CI: Install cargo-udeps in a more straightforward way 2023-02-14 16:22:07 +01:00
Cargo.lock add Cargo.lock 2023-03-08 11:45:39 -05:00
Cargo.toml Rename openpgp-card-apps into openpgp-card-examples 2021-10-29 22:38:01 +02:00
default.nix add nix support 2023-03-08 12:16:38 -05:00
deny.toml deny.toml: allow the Subplot license 2022-10-24 19:05:24 +03:00
flake.lock more attempts 2023-03-08 13:50:15 -05:00
flake.nix more attempts 2023-03-08 14:31:38 -05:00
LICENSE Add LICENSE 2022-05-25 15:29:33 +00:00
README.md Adjust paths for move to gitlab group 'openpgp-card'. 2022-06-11 21:46:32 +02:00
rustfmt.toml rustfmt: enable format_code_in_doc_comments 2022-11-03 14:43:28 +01:00
shell.nix add nix support 2023-03-08 12:16:38 -05:00

This project implements client software for the OpenPGP card standard, in Rust.

Architecture

This project consists of the following library crates:

This is how the libraries relate to each other (and to applications):

graph BT
    OP["openpgp-card-pcsc <br/> (pcsclite backend)"] --> OC
    OS["openpgp-card-scdc <br/> (scdaemon backend)"] --> OC["openpgp-card <br/> (low level API)"]
    OC --> OCS["openpgp-card-sequoia <br/> (high level Sequoia PGP-based API)"]
    OC -.-> U1[Applications based on low level API]
    OCS -.-> U2[Sequoia PGP-based applications]

classDef userApp fill:#f8f8f8,stroke-dasharray: 5 5;
class U1,U2 userApp;

Additionally, there are the following non-library crates that are built on top of the libraries described above:

  • openpgp-card-tools, a CLI tool to inspect, manage and use OpenPGP cards, aimed at end users.
  • openpgp-card-tests, a test-suite that runs OpenPGP card operations on smartcards.
  • openpgp-card-examples, small example applications that demonstrate how you can use these libraries in your own projects to access OpenPGP card functionality.

The openpgp-card crate

Implements the functionality described in the OpenPGP card specification, offering an API at roughly the level of abstraction of that specification, using Rust data structures. (However, this crate may work around some minor quirks of specific card models, in order to offer clients a somewhat uniform view)

This crate and its API do not depend or rely on any particular OpenPGP implementation.

Backends

Typically, openpgp-card will be used with the openpgp-card-pcsc backend, which uses the standard pcsclite library to communicate with cards.

However, alternative backends can be used and may be useful.
The experimental, alternative openpgp-card-scdc backend uses scdaemon from the GnuPG project as a low-level transport layer to interact with OpenPGP cards.

Backends implement:

  1. functionality to find and connect to a card (these operations may vary significantly between different backends),

  2. transaction management (where applicable), by implementing the CardBackend trait, and

  3. simple communication primitives, by implementing the CardTransaction trait, to send individual APDU commands and receive responses.

All higher level and/or OpenPGP card-specific logic (including command chaining) is handled in the openpgp-card layer.

The openpgp-card-sequoia crate

Offers a higher level interface, based around Sequoia PGP datastructures.

Most client projects will probably want to use only this crate, and ignore the lower level crates as implementation details.

Testing

The subcrate openpgp-card-tests (in the directory card-functionality) contains the beginnings of a framework that tests the openpgp-card library against OpenPGP cards.

However, OpenPGP cards are, usually, physical devices that you plug into your computer, e.g. as USB sticks, or Smart cards (this is, of course, the usual point of these cards: they are independent devices, which are only loosely coupled with your regular computing environment. However, for automated testing, such as CI, this can be a complication.)

There are at least two approaches for running tests against software-based OpenPGP cards:

Virtual JavaCards

It's possible to run simulated JavaCard applets on a host computer, and make those available via the PCSC lite framework.

To simplify testing against such simulated cards, the https://gitlab.com/openpgp-card/virtual-cards repository provides Container images for the "SmartPGP" and "YubiKey NEO" OpenPGP card implementations.

These images are used to run card-functionality tests on gitlab's CI. See the GitLab CI config openpgp-card/openpgp-card:.gitlab-ci.yml and the Dockerfiles and run script: openpgp-card/openpgp-card:card-functionality/docker/.

Emulated Gnuk

Gnuk is a free implementation of the OpenPGP card spec by Gniibe, see: http://www.fsij.org/doc-gnuk/.

Gnuk normally runs on STM32-based hardware tokens. However, it's also possible to compile the Gnuk code to run on your host machine. This is useful for testing purposes.

Emulated Gnuk is connected to the system via http://usbip.sourceforge.net/. This means that to use an emulated Gnuk, you need to have both root privileges and be able to load a kernel module (so running an emulated Gnuk is not currently possible in GitLab CI).

See the README of the card-functionality project for more information on this.

Acknowledgements

This project is based on the OpenPGP card spec, version 3.4.1.

Other helpful resources included: