Crate openpgp_card_sequoia

This crate offers ergonomic abstractions to use OpenPGP card devices. The central abstraction is the Card type, which offers access to all card operations.

A Card object is always in one of the possible States. The State determines which operations can be performed on the card.

This crate is a convenient higher-level wrapper around the openpgp-card crate (which exposes low level access to OpenPGP card functionality). sequoia-openpgp is used to perform OpenPGP operations.

Backends

To make use of this crate, you need to use a backend for communication with cards. The suggested default backend is card-backend-pcsc.

With card-backend-pcsc you can either open all available cards:

use card_backend_pcsc::PcscBackend;
use openpgp_card_sequoia::{state::Open, Card};

for backend in PcscBackend::cards(None)? {
    let mut card = Card::<Open>::new(backend?)?;
    let mut transaction = card.transaction()?;
    println!(
        "Found OpenPGP card with ident '{}'",
        transaction.application_identifier()?.ident()
    );
}

Or you can open one particular card, by ident:

use card_backend_pcsc::PcscBackend;
use openpgp_card_sequoia::{state::Open, Card};

let cards = PcscBackend::card_backends(None)?;
let mut card = Card::<Open>::open_by_ident(cards, "abcd:01234567")?;
let mut transaction = card.transaction()?;

Use for cryptographic operations

Decryption

To use a card for decryption, it needs to be opened, and user authorization needs to be available. A sequoia_openpgp::crypto::Decryptor implementation can then be obtained:

use card_backend_pcsc::PcscBackend;
use openpgp_card_sequoia::{state::Open, Card};

// Open card via PCSC
let cards = PcscBackend::card_backends(None)?;
let mut card = Card::<Open>::open_by_ident(cards, "abcd:01234567")?;
let mut transaction = card.transaction()?;

// Get user access to the card (and authorize with the user pin)
let mut user = transaction.to_user_card("123456")?;

// Get decryptor
let decryptor = user.decryptor(&|| println!("Touch confirmation needed for decryption"));

// Perform decryption operation(s)
// ..

Signing

To use a card for signing, it needs to be opened, and signing authorization needs to be available. A sequoia_openpgp::crypto::Signer implementation can then be obtained.

(Note that by default, some OpenPGP Cards will only allow one signing operation to be performed after the password has been presented for signing. Depending on the card’s configuration you need to present the user password before each signing operation!)

use card_backend_pcsc::PcscBackend;
use openpgp_card_sequoia::{state::Open, Card};

// Open card via PCSC
let cards = PcscBackend::card_backends(None)?;
let mut card = Card::<Open>::open_by_ident(cards, "abcd:01234567")?;
let mut transaction = card.transaction()?;

// Get signing access to the card (and authorize with the user pin)
let mut user = transaction.to_signing_card("123456")?;

// Get signer
let signer = user.signer(&|| println!("Touch confirmation needed for signing"));

// Perform signing operation(s)
// ..

Setting up and configuring a card

use card_backend_pcsc::PcscBackend;
use openpgp_card_sequoia::{state::Open, Card};

// Open card via PCSC
let cards = PcscBackend::card_backends(None)?;
let mut card = Card::<Open>::open_by_ident(cards, "abcd:01234567")?;
let mut transaction = card.transaction()?;

// Get admin access to the card (and authorize with the admin pin)
let mut admin = transaction.to_admin_card("12345678")?;

// Set the Name and URL fields on the card
admin.set_cardholder_name("Alice Adams")?;
admin.set_url("https://example.org/openpgp.asc")?;

Modules

• sq_util
  Simple wrappers for performing very specific tasks with Sequoia PGP.
• state
  States of a card are modeled by the types Open, Transaction, User, Sign, Admin.
• types
  Re-exports of openpgp-card types to enable standalone-use of openpgp-card-sequoia.
• util
  Odds and ends, will most likely be restructured.

Structs

• Card
  Representation of an OpenPGP card.
• OptionalPin
  Optional PIN, used as a parameter to Card<Transaction>::into_*_card.

Type Aliases

• PublicKey
  Shorthand for Sequoia public key data (a single public (sub)key)