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

Update/improve crate level documentation.

Browse source
This commit is contained in:
Heiko Schaefer 2022-02-24 14:21:38 +01:00
parent e9235164c8
commit 986094fac8
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
6 changed files with 35 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
openpgp-card/README.md
View file

@ -16,18 +16,14 @@ specification.
**Card access backends** **Card access backends**
This crate doesn't contain code to talk to cards, The trait `CardClient` This crate doesn't contain code to talk to cards. Implementations of the traits
needs to be implemented for access to cards. `CardBackend`/`CardTransaction` need to be provided for access to cards.
The crates The crates [openpgp-card-pcsc](https://crates.io/crates/openpgp-card-pcsc)
[openpgp-card-pcsc](https://crates.io/crates/openpgp-card-pcsc) and the experimental crate [openpgp-card-scdc](https://crates.io/crates/openpgp-card-scdc)
and the experimental crate provide implementations of these traits for use with this crate.
[openpgp-card-scdc](https://crates.io/crates/openpgp-card-scdc)
provide implementations of `CardClient` for use with this crate.
**Sequoia PGP wrapper** **Sequoia PGP wrapper**
See the companion crate See the companion crate [openpgp-card-sequoia](https://crates.io/crates/openpgp-card-sequoia)
[openpgp-card-sequoia](https://crates.io/crates/openpgp-card-sequoia) for a high level wrapper to use this library with [Sequoia PGP](https://sequoia-pgp.org/).
for a high level wrapper to use this library with
[Sequoia PGP](https://sequoia-pgp.org/).

2
openpgp-card/src/lib.rs
View file

@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name> // SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name>
// SPDX-License-Identifier: MIT OR Apache-2.0 // SPDX-License-Identifier: MIT OR Apache-2.0
//! Access library for //! Client library for
//! [OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card) //! [OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card)
//! devices (such as Gnuk, Yubikey, or Java smartcards running an OpenPGP //! devices (such as Gnuk, Yubikey, or Java smartcards running an OpenPGP
//! card application). //! card application).

23
pcsc/README.md
View file

@ -1,10 +1,25 @@
<!-- <!--
SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name> SPDX-FileCopyrightText: 2021-2022 Heiko Schaefer <heiko@schaefer.name>
SPDX-License-Identifier: MIT OR Apache-2.0 SPDX-License-Identifier: MIT OR Apache-2.0
--> -->
**pcsc client for the openpgp-card library** # PC/SC client for the openpgp-card library
This crate provides `PcscClient`, which is an implementation of the This crate provides `PcscBackend` and `PcscTransaction`, which are implementations of the
`CardClient` trait that uses [pcsc](https://crates.io/crates/pcsc) `CardBackend` and `CardTransactions` traits from the [`openpgp-card`](https://crates.io/crates/openpgp-card) crate.
This implementation uses the [pcsc](https://crates.io/crates/pcsc) Rust wrapper crate
to access OpenPGP cards. to access OpenPGP cards.
## Documentation
[PC/SC](https://en.wikipedia.org/wiki/PC/SC) is a standard for interaction with smartcards and readers.
The workgroup publishes an [overview]( https://pcscworkgroup.com/specifications/)
and a [set of documents](https://pcscworkgroup.com/specifications/download/) detailing the standard.
The [pcsc-lite](https://pcsclite.apdu.fr/ ) implementation is used on many free software systems
([API documentation for pcsc-lite](https://pcsclite.apdu.fr/api/group__API.html)).
Microsoft [documentation](https://docs.microsoft.com/en-us/windows/win32/api/winscard/)
about their implementation of PC/SC.

2
pcsc/src/lib.rs
View file

@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: 2021-2022 Heiko Schaefer <heiko@schaefer.name> // SPDX-FileCopyrightText: 2021-2022 Heiko Schaefer <heiko@schaefer.name>
// SPDX-License-Identifier: MIT OR Apache-2.0 // SPDX-License-Identifier: MIT OR Apache-2.0
//! This crate implements a `CardBackend`/`CardTransaction` backend for //! This crate implements the `CardBackend`/`CardTransaction` backend for
//! `openpgp-card`. It uses the PCSC middleware to access the OpenPGP //! `openpgp-card`. It uses the PCSC middleware to access the OpenPGP
//! application on smart cards. //! application on smart cards.

9
scdc/README.md
View file

@ -5,14 +5,14 @@ SPDX-License-Identifier: MIT OR Apache-2.0
**scdaemon client for the openpgp-card library** **scdaemon client for the openpgp-card library**
This crate provides `ScdClient`, which is an implementation of the This crate provides `ScdBackend`/`ScdTransaction`, which is an implementation of the
CardClient trait that uses an instance of GnuPG's `CardBackend`/`CardTransaction` traits that uses an instance of GnuPG's
[scdaemon](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-SCDAEMON.html) [scdaemon](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-SCDAEMON.html)
to access OpenPGP cards. to access OpenPGP cards.
**Known limitations** **Known limitations**
- Uploading RSA 4096 keys via scdaemon doesn't work with cards that don't - Uploading RSA 4096 keys via `scdaemon` doesn't work with cards that don't
support Command Chaining (e.g. the "Floss Shop OpenPGP Smart Card"). support Command Chaining (e.g. the "Floss Shop OpenPGP Smart Card").
This is caused by a size limitation for client requests via the This is caused by a size limitation for client requests via the
[Assuan](https://www.gnupg.org/documentation/manuals/assuan/) protocol. [Assuan](https://www.gnupg.org/documentation/manuals/assuan/) protocol.
@ -24,7 +24,7 @@ to access OpenPGP cards.
- When using `scdaemon` via pcsc (by configuring `scdaemon` with - When using `scdaemon` via pcsc (by configuring `scdaemon` with
`disable-ccid`), choosing a specific card of multiple plugged in OpenPGP `disable-ccid`), choosing a specific card of multiple plugged in OpenPGP
cards seems to be broken. cards seems to be broken.
So you probably want to plug in one OpenPGP card at a time when using So you probably want to plug in only one OpenPGP card at a time when using
`openpgp-card-scdc` combined with `disable-ccid`. `openpgp-card-scdc` combined with `disable-ccid`.
- When using `scdaemon` via its default `ccid` driver, choosing a - When using `scdaemon` via its default `ccid` driver, choosing a
@ -32,3 +32,4 @@ to access OpenPGP cards.
to 4 plugged in cards. to 4 plugged in cards.
So you probably want to plug in at most four OpenPGP cards at a time when So you probably want to plug in at most four OpenPGP cards at a time when
using `openpgp-card-scdc` with its ccid driver. using `openpgp-card-scdc` with its ccid driver.
(This limit has been raised in GnuPG 2.3.x)

2
scdc/src/lib.rs
View file

@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name> // SPDX-FileCopyrightText: 2021 Heiko Schaefer <heiko@schaefer.name>
// SPDX-License-Identifier: MIT OR Apache-2.0 // SPDX-License-Identifier: MIT OR Apache-2.0
//! This crate implements the experimental `ScdClient` backend for the //! This crate implements the experimental `ScdBackend`/`ScdTransaction` backend for the
//! `openpgp-card` crate. //! `openpgp-card` crate.
//! It uses GnuPG's scdaemon (via GnuPG Agent) to access OpenPGP cards. //! It uses GnuPG's scdaemon (via GnuPG Agent) to access OpenPGP cards.